import type { CompletionRequest, ToolDefinition } from '../../types/messages.js';
import type { AgentMiddleware, AgentMiddlewareContext } from '../create-agent.js';
/** What a rule chooses tools from. */
export interface ToolSelectionContext extends AgentMiddlewareContext {
    /** The request about to be sent. */
    request: CompletionRequest;
    /** Every tool the request offers. */
    tools: readonly ToolDefinition[];
    /** What the turn is about: the text `query` returned. */
    query: string;
}
/** Options for `toolSelector()`. Give it `select`, `embed`, or both. */
export interface ToolSelectorOptions {
    /**
     * A rule: the names of the tools to send. With `embed` too, the rule narrows the candidates and
     * similarity ranks what is left.
     */
    select?: (context: ToolSelectionContext) => readonly string[] | Promise<readonly string[]>;
    /**
     * Embeds texts, for choosing by similarity: any embedding function, such as one from
     * `toEmbeddingFunction()`. Each tool is embedded once, from `describe`; the query once per turn.
     */
    embed?: (texts: string[]) => Promise<readonly (readonly number[])[]> | readonly (readonly number[])[];
    /** The most tools sent, `always` included. Defaults to 12. */
    maxTools?: number;
    /** The lowest similarity a tool needs to be sent, from -1 to 1. Defaults to none. */
    minScore?: number;
    /** Tools sent on every call, whatever the turn is about. */
    always?: readonly string[];
    /**
     * Keeps every tool the model already called this turn, so a tool it is halfway through using
     * never disappears from under it. Defaults to true.
     */
    keepUsed?: boolean;
    /** What the turn is about. Defaults to the latest user message. */
    query?: (context: AgentMiddlewareContext & {
        request: CompletionRequest;
    }) => string;
    /** The text a tool is embedded from. Defaults to its name and description. */
    describe?: (tool: ToolDefinition) => string;
    /** Called with each selection, for logs and for measuring what the selector saves. */
    onSelect?: (selection: ToolSelection) => void;
}
/** What `toolSelector()` sent for one call. */
export interface ToolSelection {
    /** The query the tools were chosen for. */
    query: string;
    /** The names of the tools sent. */
    selected: string[];
    /** How many tools the request offered. */
    offered: number;
    /** Each ranked tool's similarity to the query, when tools were chosen by similarity. */
    scores?: Record<string, number>;
}
/**
 * Sends a model only the tools relevant to the turn.
 *
 * An agent with 150 tools otherwise sends 150 schemas on every call: the tokens are paid each time,
 * the call is slower, and a model choosing among that many picks worse. A rule, embedding
 * similarity, or both choose a dozen; tools named in `always`, the tool a `toolChoice` forces, and
 * the tools the model already used this turn are always kept. The agent can still run every tool —
 * only what the model is offered changes.
 */
export declare function toolSelector(options: ToolSelectorOptions): AgentMiddleware;