/** * Progressive tool disclosure (Python parity: `tools/tool_search.py`, * `Agent(tool_search=...)`). * * A large tool list costs context on every single request, whether or not the * model uses any of it. With tool search on, deferrable tools are replaced in * the request by three bridge tools -- `tool_search`, `tool_describe`, * `tool_call` -- and the model discovers what it needs, when it needs it. * * The architecture invariants are Python's, and each one is load-bearing: * * 1. Core tools never defer ({@link PRAISONAI_CORE_TOOLS}). * 2. Unknown tools stay visible -- a tool is never silently dropped. * 3. The catalog is stateless: rebuilt from the current tool defs every turn. * 4. Bridge dispatch reads the PRE-assembly deferrable set. * 5. The catalog is scoped to this agent's own tools. * 6. `tool_call` is unwrapped BEFORE hooks, approval and events, so they see * the real tool name rather than the bridge. * 7. In `auto` mode tools defer only once their schemas cross * `thresholdPct` of the context window. * 8. BM25 is inlined -- no new dependency -- with a substring fallback. */ import { ToolSearchConfig } from '../../config'; /** An OpenAI function schema, as the Agent stores them. */ export type ToolDef = Record; /** Tools that never defer (Python `PRAISONAI_CORE_TOOLS`). */ export declare const PRAISONAI_CORE_TOOLS: ReadonlySet; /** The three bridge tool names. */ export declare const BRIDGE_TOOL_NAMES: ReadonlySet; /** Split tools into "never defer" and "may defer" (Python `classify_tools`). */ export declare function classifyTools(toolDefs: readonly ToolDef[], config: ToolSearchConfig): { core: ToolDef[]; deferrable: ToolDef[]; }; /** Rough schema cost (Python `estimate_tool_schema_tokens`: ~3.5 chars/token). */ export declare function estimateToolSchemaTokens(toolDefs: readonly ToolDef[]): number; /** Python `should_defer_tools`: the `auto` threshold rule. */ export declare function shouldDeferTools(deferrable: readonly ToolDef[], config: ToolSearchConfig, contextLength?: number): boolean; /** One catalog row the model can search. */ export interface CatalogEntry { name: string; description: string; } /** * BM25 over the tool catalog, inlined so tool search adds no dependency * (Python `BM25ToolSearcher`, same k1/b constants). */ export declare class BM25ToolSearcher { private readonly catalog; private readonly termFrequencies; private readonly docFrequencies; private readonly totalDocs; private readonly avgDocLength; constructor(catalog: readonly CatalogEntry[]); search(query: string, limit?: number): CatalogEntry[]; } /** Python `search_catalog`: BM25 for a substantial query, substring otherwise. */ export declare function searchCatalog(deferrable: readonly ToolDef[], query: string, limit?: number): CatalogEntry[]; /** The three bridge tool schemas (Python `bridge_tool_schemas`). */ export declare function bridgeToolSchemas(): ToolDef[]; /** What the turn needs to know once tools have been assembled. */ export interface ToolSearchAssembly { /** The tool list actually sent to the model. */ tools: ToolDef[]; /** Whether deferrable tools were replaced by the bridge. */ bridgeMode: boolean; /** Tools kept out of the request; the bridge resolves calls against these. */ deferrableTools: ToolDef[]; /** Name/description rows the model can search. */ catalog: CatalogEntry[]; config: ToolSearchConfig; } /** * Decide between bridge mode and pass-through, and build the tool list for * the request (Python `assemble_tool_defs`). */ export declare function assembleToolDefs(toolDefs: readonly ToolDef[] | undefined, config: ToolSearchConfig, contextLength?: number): ToolSearchAssembly; /** Python `dispatch_tool_search`. */ export declare function dispatchToolSearch(query: string, limit: number | undefined, deferrable: readonly ToolDef[], config: ToolSearchConfig): Record; /** Python `dispatch_tool_describe`. */ export declare function dispatchToolDescribe(toolName: string, deferrable: readonly ToolDef[]): Record; /** * Unwrap a `tool_call` bridge invocation into the real call * (Python `resolve_underlying_call`). Anything else is returned unchanged. */ export declare function resolveUnderlyingCall(toolName: string, toolArgs: Record): { name: string; args: Record; }; /** * Resolve the constructor option into a config, or `undefined` when tool * search is off. Mirrors `ToolSearchConfig.fromRaw` plus the `false` fast path. */ export declare function resolveToolSearch(input: boolean | string | Record | undefined | null): ToolSearchConfig | undefined;