import type { ToolExecuteContext } from './types.js';
/**
 * Cortex's canonical in-process tool contract.
 *
 * All tools registered with CortexAgent are normalized to this signature.
 * Cortex adapts this shape to pi-agent-core's execute signature at the
 * registration boundary.
 */
export interface CortexTool<TParams = unknown, TResult = unknown> {
    name: string;
    description: string;
    parameters: unknown;
    execute: (params: TParams, context?: ToolExecuteContext) => Promise<TResult>;
    /**
     * Marks this tool as eligible for deferred loading. When the agent has
     * `deferredTools.enabled = true`, deferred tools are NOT included in the
     * `tools` array sent to the model on every turn. Instead, only their names
     * appear in the `_available_tools` slot, and the model uses ToolSearch to
     * load full schemas on demand.
     *
     * MCP tools get `isMcp: true` set automatically by the MCP client and are
     * deferred when `deferredTools.deferMcp` is true (default). Built-in or
     * consumer-supplied tools can opt in via `shouldDefer: true`.
     */
    shouldDefer?: boolean;
    /**
     * Forces this tool to always be sent in the `tools` array, even if it
     * matches deferral criteria (e.g., an MCP tool the consumer wants always
     * available). Overrides `shouldDefer` and the `deferMcp` config.
     */
    alwaysLoad?: boolean;
    /**
     * Marker indicating this tool was wrapped from an MCP server. Set
     * automatically by the MCP client. Consumers should not set this manually.
     */
    isMcp?: boolean;
    /**
     * Optional pi-agent-core execution hint. Use "sequential" for tools that
     * must update shared agent state before later tool calls in the same batch.
     */
    executionMode?: 'sequential' | 'parallel';
}
/**
 * Raw pi-agent-core tool contract.
 *
 * Use fromPiAgentTool() to explicitly adapt a tool with this signature into
 * Cortex's canonical CortexTool shape.
 */
export interface PiAgentTool<TParams = unknown, TResult = unknown> {
    name: string;
    description: string;
    parameters: unknown;
    executionMode?: 'sequential' | 'parallel';
    execute: (toolCallId: string, params: TParams, signal?: AbortSignal, onUpdate?: (partialResult: unknown) => void) => Promise<TResult>;
}
/**
 * Explicitly adapt a pi-agent-core-style tool into Cortex's canonical tool contract.
 */
export declare function fromPiAgentTool<TParams = unknown, TResult = unknown>(tool: PiAgentTool<TParams, TResult>): CortexTool<TParams, TResult>;
/**
 * Validate that a tool matches Cortex's canonical execute signature.
 *
 * Cortex does not infer tool execution contracts from function arity. Tools
 * that already use pi-agent-core's raw execute signature must be adapted
 * explicitly with fromPiAgentTool().
 */
export declare function assertValidCortexTool(tool: CortexTool): CortexTool;
//# sourceMappingURL=tool-contract.d.ts.map