import type { Agent, AgentSession } from './agent.js';
/** The metadata describing a callable tool (name, description, parameter schema). */
export type FunctionToolInfoLike = {
    /** Tool name the model uses to invoke it. */
    name: string;
    /** Natural-language description shown to the model. */
    description?: string | null;
    /** JSON Schema for the tool's arguments. */
    parametersSchema?: object | null;
    /** Optional spoken filler phrase played while the tool runs (e.g. "one moment"). */
    filler?: string | null;
    /** Delay in milliseconds before the filler is spoken. */
    fillerGracePeriod?: number | null;
};
/** Concrete carrier for tool metadata; see {@link FunctionToolInfoLike}. */
export declare class FunctionToolInfo implements FunctionToolInfoLike {
    name: string;
    description?: string | null;
    parametersSchema?: object | null;
    filler?: string | null;
    fillerGracePeriod?: number | null;
    constructor(info: FunctionToolInfoLike);
}
/** Context object passed as the second argument to a tool's `execute` function. */
export type ToolContext = any;
/** Declarative definition of a tool, passed to {@link functionTool}. */
export type ToolDefinition<P = any> = {
    /** Tool name the model uses to invoke it. */
    name: string;
    /** Natural-language description shown to the model. */
    description?: string;
    /** A Zod schema for the arguments. Converted to JSON Schema; takes precedence over `parameters`. */
    input?: unknown;
    /** JSON Schema describing the tool's arguments. A Zod schema is also accepted and converted. */
    parameters?: object;
    /** Optional spoken filler phrase played while the tool runs. */
    filler?: string | null;
    /** Delay in milliseconds before the filler is spoken. */
    fillerGracePeriod?: number | null;
    /** Handler invoked with the parsed arguments (and optional {@link ToolContext}). */
    execute: (args: P, ctx?: ToolContext) => any | Promise<any>;
};
/**
 * A callable tool: a function that runs the tool, with its {@link FunctionToolInfoLike}
 * metadata attached as `_toolInfo`. Create one with {@link functionTool}.
 */
export type FunctionTool<P = any> = {
    (args: P, ctx?: ToolContext): any | Promise<any>;
    _toolInfo: FunctionToolInfoLike;
};
/**
 * Create a callable {@link FunctionTool} the agent can expose to its model.
 *
 * Pass a {@link ToolDefinition} describing the tool; `name` is required. The
 * argument schema can be a Zod schema (`input`, which takes precedence, or
 * `parameters` directly) or a plain JSON Schema (`parameters`); Zod schemas
 * are converted to JSON Schema.
 */
export declare function functionTool<P = any>(def: ToolDefinition<P>): FunctionTool<P>;
/** Type guard: whether `obj` is a {@link FunctionTool} (has valid `_toolInfo`). */
export declare function isFunctionTool(obj: any): obj is FunctionTool;
/** Return the {@link FunctionToolInfoLike} metadata attached to a tool. */
export declare function getToolInfo(tool: FunctionTool | any): FunctionToolInfoLike;
/** Convert a tool to the OpenAI function-calling schema. */
export declare function buildOpenaiSchema(tool: FunctionTool | any): {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: object;
    };
};
/** Convert a tool to the Nova Sonic schema (identical to OpenAI's). */
export declare function buildNovaSonicSchema(tool: FunctionTool | any): {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: object;
    };
};
/** Convert a tool to the Gemini function-declaration schema (simplified parameters). */
export declare function buildGeminiSchema(tool: FunctionTool | any): {
    name: string;
    description: string;
    parameters: object;
};
/**
 * Strip JSON-Schema keywords some providers reject (`additionalProperties`, `title`,
 * `$defs`, `definitions`), recursing into nested objects and arrays.
 */
export declare function simplifySchema(schema: any): any;
/** Live context handed to a tool's `execute` (as `{ ctx }`) and to functional lifecycle hooks. */
export type ToolRunContext = {
    /** The active session for the current call, or `null` before it starts. */
    session: AgentSession | null;
    /** The agent that owns the tool / lifecycle hook. */
    agent: Agent;
};
/** Build the second argument passed to a tool `execute`: `{ ctx: { session, agent } }`. */
export declare function makeToolRunContext(agent: Agent): {
    ctx: ToolRunContext;
};
/** Duck-typed check: is `x` a Zod schema? (has the Zod `parse` method and internal `_def`). */
export declare function isZodSchema(x: unknown): boolean;
/**
 * Convert a Zod schema to a plain JSON Schema object. Isolated here so the exact
 * Zod API (Zod 4's `z.toJSONSchema`) is the only thing that changes if it moves.
 */
export declare function zodToJsonSchema(schema: unknown): object;