/**
 * Tool loop state machine - CC query.ts aligned.
 *
 * Architecture:
 *   - Infinite while(true) loop with centralized State object (CC parity)
 *   - 7 labeled continue sites matching CC's query loop transitions
 *   - Error Withholding: 413 / max_output_tokens / media errors are
 *     withheld from callers during recovery attempts
 *   - Context Collapse drain: staged collapses committed on 413
 *     BEFORE falling through to reactive compact
 *   - Media error recovery: image/media errors -> reactive compact retry
 *   - Hermes delta suppression preserved
 *   - StreamingToolExecutor preserved
 *   - Sub-agent fork depth preserved
 *   - Skill learning evaluation preserved
 *
 * CC reference: src/query.ts queryLoop()
 *
 * Zero imports from express/pg/ioredis/ws.
 */
import type { AgentLogger, ChatMessage, ToolDefinition, ToolInvoker, TurnEvent, HookRegistry, LLMTransport } from "./types.js";
import type { ToolLoopRuntimePorts } from "../runtime/ports/index.js";
export interface ToolLoopParams {
    turnId: string;
    sessionId: string;
    messages: ChatMessage[];
    tools: ToolDefinition[];
    model: string;
    apiKey: string;
    temperature?: number;
    maxRounds?: number;
    /** Context window size in tokens (for turn-loop-guard budget checks) */
    contextWindowTokens?: number;
    /** Max output tokens for current model */
    maxOutputTokens?: number;
    /** Model's absolute max output tokens (escalation ceiling) */
    modelMaxOutputTokens?: number;
    /** Tool choice strategy (default "auto") */
    toolChoice?: "auto" | "none" | "required";
    /** Parent fork depth (0 = top-level) */
    parentDepth?: number;
    /** Tool eligibility context for policy-based filtering */
    toolEligibilityContext?: unknown;
    /** Hook registry for lifecycle events (optional, fire-and-forget) */
    hooks?: HookRegistry;
    /** Max turns (loop iterations). 0 = use maxRounds. */
    maxTurns?: number;
    /** Fallback model to switch to after repeated 529 errors (CC parity). */
    fallbackModel?: string;
    /** Query source for foreground/background retry distinction (CC parity). */
    querySource?: string;
    /** Token budget for this turn (>0 enables budget continuation). */
    tokenBudget?: number;
    /**
     * Refresh tools callback -called between turns (CC refreshTools parity).
     * Returns updated tool definitions if tools have changed (e.g. MCP reconnect),
     * or the same array reference if unchanged.
     */
    refreshTools?: () => ToolDefinition[];
    /**
     * Generate a human-readable summary label for a tool batch (CC generateToolUseSummary parity).
     * Fire-and-forget: called after tool execution, result yielded as tool_use_summary event
     * when the next LLM round starts streaming. ~30 chars, git-commit-subject style.
     */
    generateToolUseSummary?: (toolCalls: Array<{
        name: string;
        arguments: string;
        result?: string;
    }>) => Promise<string | null>;
    /**
     * Post-sampling hooks -fire-and-forget after LLM response completes (CC executePostSamplingHooks parity).
     * Cannot modify messages. Used for background tasks (memory extraction, skill learning, etc.).
     */
    postSamplingHooks?: Array<(context: {
        messages: unknown[];
        model: string;
        sessionId: string;
    }) => Promise<void> | void>;
    /** Max concurrent tool executions (0 = unlimited, CC parity: semantic concurrency control). */
    maxConcurrentTools?: number;
    /** Model requires streaming -disable non-streaming fallback. */
    streamRequired?: boolean;
    /** Reasoning effort for models that support it. */
    reasoning?: {
        effort: "minimal" | "low" | "medium" | "high" | "xhigh";
        includeEncryptedReasoning?: boolean;
    };
    /** Prompt cache bucketing key. */
    promptCacheKey?: string;
    /** Prompt cache retention policy. */
    promptCacheRetention?: "in_memory" | "24h";
    /** Service tier scheduling. */
    serviceTier?: "auto" | "default" | "flex" | "priority";
    /** OpenAI Responses API built-in tools. */
    openaiBuiltinTools?: Array<{
        type: "web_search_preview" | "file_search" | "code_interpreter" | "computer_use_preview";
        [key: string]: unknown;
    }>;
    /** Max builtin tool calls per turn. */
    maxToolCalls?: number;
    /** Disable parallel tool calling. */
    parallelToolCalls?: boolean;
    /** Text output verbosity hint. */
    textVerbosity?: "low" | "medium" | "high";
    /** Project root directory -used for skill pattern tracking at project level. */
    projectRoot?: string;
    runtimePorts: ToolLoopRuntimePorts;
    signal?: AbortSignal;
}
/**
 * Execute the tool loop -CC query.ts queryLoop() aligned.
 *
 * Yields TurnEvent stream. The caller (Agent class) wraps this with
 * start/end lifecycle and error handling.
 *
 * Architecture: infinite while(true) with centralized State + 7 continue
 * labels. Error withholding gates recoverable errors through collapse
 * drain ->reactive compact ->escalation ->recovery message pipeline
 * before surfacing to callers.
 */
export declare function executeToolLoop(params: ToolLoopParams, transport: LLMTransport, toolInvoker: ToolInvoker, log: AgentLogger): AsyncGenerator<TurnEvent>;
