/**
 * Shared types for the MCP tool provider.
 */
export interface CallApiContextParams {
    prompt?: {
        raw: string;
        label?: string;
    };
    vars?: Record<string, object | string>;
}
export interface ProviderOptions {
    config?: Record<string, unknown>;
    id?: string;
}
export interface ProviderResponse {
    cached?: boolean;
    cost?: number;
    error?: string;
    metadata?: Record<string, unknown>;
    output?: object | string;
    tokenUsage?: {
        total?: number;
        prompt?: number;
        completion?: number;
        cached?: number;
    };
}
export interface MCPTool {
    name: string;
    description?: string;
    inputSchema?: Record<string, unknown>;
}
export interface MCPClient {
    getAllTools: () => MCPTool[];
    callTool: (name: string, args: Record<string, unknown>) => Promise<{
        content: string;
        error?: string;
    }>;
    cleanup: () => Promise<void>;
}
export interface ToolCallEntry {
    name: string;
    input: unknown;
    output: string;
    /**
     * Error text when the call failed — either the MCP server's `isError`
     * content or a thrown transport/protocol error. Absent on success.
     * Structured assertions (`error-returned`) and telemetry read this
     * directly instead of parsing it back out of `output`.
     */
    error?: string;
    /**
     * Numeric JSON-RPC / MCP error code when the failure carried one
     * (e.g. `-32602` invalid params). Present only for thrown `McpError`s.
     */
    errorCode?: number;
    /**
     * True when the tool output was truncated before being fed back to the
     * model to keep the request within the model's context window. `output`
     * holds the truncated copy the model actually saw; `originalOutputLength`
     * records the pre-truncation size. Makes a degraded run distinguishable
     * from a clean one.
     */
    truncated?: boolean;
    /**
     * Original tool-output length in characters, before truncation. Present
     * only when `truncated` is true.
     */
    originalOutputLength?: number;
    /**
     * Wall-clock duration of this tool round-trip in milliseconds (D0088),
     * measured with `Date.now()` around the `callTool` invocation. Recorded for
     * both successful and errored calls; feeds the trace's `tool-call` timeline
     * spans. Optional so callers that don't time the call still satisfy the type.
     */
    durationMs?: number;
    /**
     * 0-based model round (turn) this call was issued in (D0088). Lets the trace
     * collector place the call's span after the matching `llm-turn` span in
     * execution order rather than packing all LLM spans first.
     */
    turnIndex?: number;
}
/**
 * Per-call timing the tool loops stamp onto a `ToolCallEntry` (D0088). Carried
 * as one value so the record helpers take a single optional argument rather
 * than two trailing positionals.
 */
export interface ToolCallTiming {
    /** Wall-clock duration of the tool round-trip in milliseconds. */
    durationMs: number;
    /** 0-based model round (turn) the call was issued in. */
    turnIndex: number;
}
/** Configuration passed from the provider to an LLM backend's tool loop */
export interface ToolLoopConfig {
    /** The user's prompt */
    prompt: string;
    /** MCP tools available (already filtered by capabilities) */
    tools: MCPTool[];
    /** Function to call an MCP tool by name */
    callTool: (name: string, args: Record<string, unknown>) => Promise<{
        content: string;
        error?: string;
    }>;
    /** Max rounds of tool calls before forcing a final answer */
    maxToolRounds: number;
    /** LLM model name (provider-specific, e.g., "claude-opus-4-6") */
    model: string;
    /** Sampling temperature */
    temperature: number;
    /** Max output tokens */
    maxTokens: number;
    /**
     * Max characters of a single tool result fed back to the model. Tool output
     * larger than this is truncated with a marker so the accumulated request
     * stays within the model's context window. Defaults to
     * `DEFAULT_MAX_TOOL_OUTPUT_CHARS` when unset.
     */
    maxToolOutputChars?: number;
    /** API key for the LLM provider */
    apiKey: string;
    /**
     * OpenAI API variant — determines which endpoint to call.
     * - `"chat"` → `/v1/chat/completions` (default)
     * - `"responses"` → `/v1/responses`
     *
     * Extracted from model ID: `openai:responses:gpt-5.4` → `"responses"`
     */
    apiVariant?: "chat" | "responses";
    /** Additional model-specific config passed through from the provider */
    providerConfig?: Record<string, unknown>;
}
/** Result returned from an LLM backend's tool loop */
export interface ToolLoopResult {
    /** The LLM's final text output */
    output: string;
    /** Log of all tool calls made during the loop */
    toolCallLog: ToolCallEntry[];
    /** Token usage stats */
    tokenUsage: {
        prompt: number;
        completion: number;
        total: number;
    };
    /** Number of tool rounds completed */
    toolRounds: number;
    /** Whether the loop exhausted maxToolRounds */
    exhaustedRounds?: boolean;
    /** Wall-clock duration in ms */
    latencyMs: number;
    /**
     * Per-turn LLM-call latency in milliseconds, in turn order (D0088). One
     * entry per model API round-trip. Feeds the trace's `llm-turn` timeline
     * spans. Optional so backends that don't yet record it (e.g. the OpenAI
     * loop) still satisfy the contract.
     */
    llmTimings?: number[];
}
/**
 * An LLM backend that can run a multi-turn tool loop.
 *
 * Each backend (Anthropic, OpenAI) implements this function signature.
 * The provider selects the appropriate backend based on the model ID prefix.
 */
export type RunToolLoop = (config: ToolLoopConfig) => Promise<ToolLoopResult>;
