/**
 * Direct tool calling support through agent.tool accessor.
 *
 * Enables method-style tool invocation without model inference:
 * ```typescript
 * const agent = new Agent({ tools: [myTool] })
 * const result = await agent.tool.calculator!.invoke({ a: 5, b: 3 })
 * ```
 */
import type { JSONValue } from '../types/json.js';
import type { ToolResultBlock } from '../types/messages.js';
import { Message } from '../types/messages.js';
import type { InvocationState } from '../types/agent.js';
import { ToolStreamEvent } from '../tools/tool.js';
import type { Agent } from './agent.js';
/**
 * Options for direct tool call execution.
 */
export interface DirectToolCallOptions {
    /**
     * Whether to record this tool call in the agent's message history.
     * Defaults to `true`. Set to `false` to execute the tool without
     * affecting conversation context.
     */
    recordDirectToolCall?: boolean;
}
/**
 * A handle to a specific tool, providing `.invoke()` and `.stream()` methods.
 *
 * Returned by the Proxy get trap when accessing `agent.tool.toolName`.
 * This aligns with the agent-level `agent.invoke()` / `agent.stream()` pattern.
 */
export interface ToolHandle {
    /**
     * Invoke the tool and return the final result.
     *
     * @param input - The input parameters for the tool
     * @param options - Optional configuration for this call
     * @returns The tool result
     */
    invoke: (input?: JSONValue, options?: DirectToolCallOptions) => Promise<ToolResultBlock>;
    /**
     * Stream the tool execution, yielding intermediate events and returning the final result.
     *
     * @param input - The input parameters for the tool
     * @param options - Optional configuration for this call
     * @returns Async generator that yields ToolStreamEvents and returns ToolResultBlock
     */
    stream: (input?: JSONValue, options?: DirectToolCallOptions) => AsyncGenerator<ToolStreamEvent, ToolResultBlock, undefined>;
}
/**
 * The public type of the tool caller proxy.
 * Provides dynamic property access where each property is a {@link ToolHandle}
 * with `.invoke()` and `.stream()` methods.
 */
export type ToolCallerProxy = Record<string, ToolHandle>;
/**
 * Helper passed in from Agent for appending messages and firing MessageAddedEvent hooks.
 *
 * Defined here (not in agent.ts) so that the message-mutation capability stays
 * encapsulated — only the Agent knows how to mutate messages safely, and it
 * passes a bound helper into ToolCaller. ToolCaller never gets direct access
 * to `agent.messages` or the hooks registry.
 */
export type AppendMessageFn = (message: Message, invocationState?: InvocationState) => Promise<void>;
/**
 * Provides direct tool calling through the agent.
 *
 * Enables programmatic tool invocation without model inference via
 * `agent.tool.toolName.invoke(input)` or `agent.tool.toolName.stream(input)`.
 * Tools are called directly, bypassing the model loop, and results are optionally
 * recorded in message history for context continuity.
 *
 * Supports underscore-to-hyphen and case-insensitive name normalization
 * via {@link ToolRegistry.resolve}.
 *
 * @example
 * ```typescript
 * const agent = new Agent({ tools: [calculatorTool] })
 *
 * // Invoke and get the result
 * const result = await agent.tool.calculator!.invoke({ operation: 'add', a: 5, b: 3 })
 * console.log(result.status) // 'success'
 *
 * // Stream intermediate events
 * for await (const event of agent.tool.calculator!.stream({ operation: 'add', a: 5, b: 3 })) {
 *   console.log('progress:', event)
 * }
 * ```
 *
 * @internal This class is not intended for direct instantiation by users.
 */
export declare class ToolCaller {
    private readonly _agent;
    private readonly _appendMessage;
    /**
     * Creates a ToolCaller proxy for the given agent.
     *
     * Encapsulates the Proxy cast so callers don't need to handle the
     * implementation detail that the constructor returns a Proxy, not
     * a plain ToolCaller instance.
     *
     * @param agent - The owning agent instance
     * @param appendMessage - Helper provided by the agent to append messages and fire hooks.
     *   Passed in (rather than calling a public agent method) so message mutation stays
     *   encapsulated within the agent.
     */
    static create(agent: Agent, appendMessage: AppendMessageFn): ToolCallerProxy;
    private constructor();
    /**
     * Creates a ToolHandle for the given tool name.
     */
    private _createToolHandle;
    /**
     * Executes a tool by name with the given input, consuming the full stream and returning the result.
     *
     * @param name - The tool name (supports underscore-to-hyphen and case-insensitive resolution)
     * @param input - The input parameters for the tool
     * @param options - Optional configuration for this call
     * @returns The tool result
     */
    private _callTool;
    /**
     * Streams a tool execution by name, yielding intermediate events.
     *
     * @param name - The tool name
     * @param input - The input parameters for the tool
     * @param options - Optional configuration for this call
     * @returns Async generator that yields ToolStreamEvents and returns ToolResultBlock
     */
    private _streamTool;
    /**
     * Executes a tool's stream generator, yielding events and returning the final result.
     */
    private _executeTool;
    /**
     * Records a tool execution in the agent's message history and fires MessageAddedEvent hooks.
     *
     * Creates a sequence of 3 messages that represent the tool execution:
     * 1. An assistant message with the ToolUseBlock (what was called and with what input)
     * 2. A user message with the ToolResultBlock (tool output)
     * 3. An assistant message acknowledging the result
     *
     * Each message fires a {@link MessageAddedEvent} so that hooks registered via
     * `agent.addHook(MessageAddedEvent, ...)` are notified of direct tool call messages.
     */
    private _recordToolExecution;
}
//# sourceMappingURL=tool-caller.d.ts.map