import { type BrandedFunctionalTool } from '../../ai-tool-ref.js';
import type { Passage } from '../../spi/retriever.js';
import type { AiToolCtx } from '../../spi/tool.js';
import type { TreeBudget } from './llm.js';
import type { NavigatedNode, NavigationStep, TreeNavigationRetriever } from './navigate.js';
export interface NavigateDocumentToolOptions {
    /** Tool name the model sees. Default `navigate_document`. */
    name?: string;
    description?: string;
    /**
     * The access filter for this call, from the tool context — e.g. `(ctx) => ({ tenant: ctx.actor.tenantRef })`.
     * Applied to the tree read, with the vector stores' semantics. Omit only for single-tenant corpora.
     */
    filter?: (ctx: AiToolCtx) => Record<string, unknown> | undefined;
    /** Per-call navigation budget (overrides the navigator's). */
    budget?: TreeBudget;
    /** Roles allowed to invoke. Omit to inherit the config's `defaultRoles`. */
    roles?: string[];
    /** Authz ability for an ability-aware `RolesPolicy`. */
    ability?: string;
}
export interface NavigateDocumentInput {
    documentId: string;
    question: string;
}
export interface NavigateDocumentOutput {
    documentId: string;
    /** `false` when the document has no tree (short documents don't get one) or the caller may not read it. */
    found: boolean;
    passages: Passage[];
    /** The sections chosen and the path to each. */
    nodes: NavigatedNode[];
    /** The walk, step by step, with the model's reasoning. */
    steps: NavigationStep[];
    stoppedBy?: string;
    note?: string;
}
/**
 * The agentic half of two-stage retrieval: `navigate_document(documentId, question)`, a `read`-kind
 * tool the model calls **after** a search put a long document among its hits — it walks that
 * document's table of contents to the sections that answer and returns their text, with the path and
 * reasoning (the citation surface: section titles and page ranges).
 *
 * `documentId` may also be a chunk id from a search result (`doc#12`); the chunk suffix is dropped.
 * A document with no tree answers `found: false` with a note, so the model falls back to the
 * passages it already has instead of retrying.
 *
 * Returns a {@link defineTool} tool: export it from an `app/agent_tools` module, or pass it to
 * `defineConfig({ tools })`.
 *
 * ```ts
 * export const navigateDocument = createNavigateDocumentTool(navigator, {
 *   filter: (ctx) => ({ tenant: ctx.actor.tenantRef }),
 * })
 * ```
 */
export declare function createNavigateDocumentTool(navigator: TreeNavigationRetriever, options?: NavigateDocumentToolOptions): BrandedFunctionalTool;
//# sourceMappingURL=navigate-tool.d.ts.map