qlogicagent 2.13.5 → 2.13.6

package/dist/agent/tool-loop.js

@@ -1,1017 +0,0 @@
-/**
- * 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 { accumulateToolCalls } from "../runtime/ports/index.js";
-import { fireHook } from "../contracts/fire-hook.js";
-import { advanceToolLoopState, applyToolChoicePolicy, buildAssistantToolCallMessage, buildToolResultMessage, recoverToolLoopStateFromChatConversation, settleToolLoopState, calculateTokenWarningState, resolveApiErrorRecovery, resolveOutputTokenEscalation, shouldAbortTurn, createTurnLoopGuardState, shouldAttemptReactiveCompact, createReactiveCompactState, classifyError, createCollapseStore, recoverContextCollapseFromOverflow, } from "../orchestration/index.js";
-import { DEFAULT_TEMPERATURE, MAX_CONSECUTIVE_FAILURES, MAX_IDENTICAL_CALL_REPEATS, DEFAULT_CONTEXT_WINDOW_TOKENS, RESPONSE_BUFFER_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODEL_MAX_OUTPUT_TOKENS, MAX_OUTPUT_TOKENS_RECOVERY_LIMIT, ESCALATED_MAX_OUTPUT_TOKENS, MAX_API_RETRIES, } from "./tunable-defaults.js";
-import { createToolMediaResultEvents, createToolResultEvent } from "./tool-loop/tool-result-events.js";
-import { createToolSidecarEvents } from "./tool-loop/artifact-events.js";
-import { findLastToolError, isEmptyToolResult, resolveToolLoopBudget, summarizeToolInput, synthesizeFallbackContent, } from "./tool-loop/loop-helpers.js";
-import { isMaxOutputTokensTruncation, isMediaSizeError, isPromptTooLongError, } from "./tool-loop/recovery-helpers.js";
-import { executeSingleLLMRound } from "./tool-loop/single-round.js";
-import { runCompressionPipeline } from "./tool-loop/compression-pipeline.js";
-import { handleStreamError } from "./tool-loop/stream-error-recovery.js";
-import { resolveCompletionActionPolicy } from "./tool-loop/completion-action-policy.js";
-import { resolveCompletionStopPolicy } from "./tool-loop/completion-stop-policy.js";
-import { resolveBudgetContinuationPolicy } from "./tool-loop/budget-continuation-policy.js";
-import { resolveToolUsageSkillInstruction } from "./tool-loop/skill-instruction-policy.js";
-import { newVariantFailureNudges, recordToolFailureResult, splitVariantToolCalls, variantBlockNudge, } from "./tool-loop/tool-failure-policy.js";
-// - Main tool loop -
-/**
- * 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 async function* executeToolLoop(params, transport, toolInvoker, log) {
-    const { turnId, sessionId, messages: inputMessages, tools, model, apiKey, temperature = DEFAULT_TEMPERATURE, hooks, signal, } = params;
-    const hookCtx = { sessionId, turnId };
-    const maxTurns = params.maxTurns ?? 0;
-    const querySource = params.querySource;
-    // - Tool eligibility filtering (allow/ask/deny + unified risk) -
-    const eligibility = params.runtimePorts.resolveToolEligibility(tools, params.toolEligibilityContext);
-    const effectiveTools = eligibility.eligibleTools;
-    // Emit blocked tool events
-    for (const blocked of eligibility.blockedTools) {
-        yield { type: "tool_blocked", turnId, callId: "", name: blocked.toolName, reason: "blocked-by-policy" };
-    }
-    // - No tools: single LLM call, no loop -
-    if (!effectiveTools.length) {
-        yield* executeSingleLLMRound(turnId, model, inputMessages, apiKey, temperature, signal, transport, log);
-        return;
-    }
-    // - Immutable setup -
-    const toolBudget = resolveToolLoopBudget(params.maxRounds);
-    // Turn-loop-guard config (CC-aligned)
-    const guardConfig = {
-        contextWindowTokens: params.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS,
-        responseBufferTokens: RESPONSE_BUFFER_TOKENS,
-        maxOutputTokens: params.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
-        abortSignal: signal,
-        reactiveCompactEnabled: true,
-        outputEscalationEnabled: true,
-    };
-    // Skill learning metrics (loop-local, not on State)
-    const distinctToolNames = new Set();
-    let totalToolCallCount = 0;
-    // Mutable tool list -refreshed between turns if refreshTools callback provided (CC parity)
-    let currentTools = effectiveTools;
-    // Pending tool use summary -fire-and-forget promise from previous turn (CC pendingToolUseSummary parity)
-    let pendingToolUseSummary;
-    let requiredToolChoiceSatisfied = false;
-    let requiredToolChoiceRetryCount = 0;
-    // - Mutable cross-iteration state (CC State parity) -
-    // The loop body destructures this at the top of each iteration.
-    // Continue sites write `state = { ...next }` instead of N separate assignments.
-    let state = {
-        messages: [...inputMessages],
-        maxOutputTokensRecoveryCount: 0,
-        hasAttemptedReactiveCompact: false,
-        maxOutputTokensOverride: undefined,
-        turnCount: 1,
-        transition: undefined,
-        guardState: createTurnLoopGuardState(guardConfig),
-        reactiveCompactState: createReactiveCompactState(),
-        toolLoopState: recoverToolLoopStateFromChatConversation({
-            maxRounds: toolBudget,
-            replayMessages: [...inputMessages],
-        }).state,
-        consecutiveFailedRounds: 0,
-        finalText: "",
-        totalUsage: { inputTokens: 0, outputTokens: 0 },
-        collapseStore: createCollapseStore(),
-        currentModel: model,
-        consecutive529Errors: 0,
-        consecutiveApiRetries: 0,
-        stopHookActive: undefined,
-        lastResponseId: undefined,
-        snipRemovedIds: new Set(),
-        contentReplacementState: params.runtimePorts.createContentReplacementState(),
-        budgetContinuationCount: 0,
-        lastBudgetDeltaTokens: 0,
-        lastBudgetGlobalTokens: 0,
-        identicalCallCounts: new Map(),
-        toolFailureCounts: new Map(),
-        fileReadCounts: new Map(),
-        recoveryTrace: new Map(),
-    };
-    // P0: hard iteration cap -safety net against infinite recovery loops.
-    // Unlike turnCount (only incremented on successful tool-call rounds),
-    // this counter increments on EVERY while-loop iteration including
-    // recovery retries. CC relies on bounded retry limits per recovery path;
-    // this provides a catch-all for any path that might loop unboundedly.
-    const MAX_TOTAL_ITERATIONS = Math.max(maxTurns * 5, 200);
-    let totalIterations = 0;
-    // Record + emit a recovery event. Centralizes the per-turn recovery trace so the
-    // path a turn took is observable (surfaced on the final `end` event). Named
-    // emitRecovery, not `recovery`, to avoid shadowing the local resolveApiErrorRecovery
-    // result inside the stream-error handler.
-    const emitRecovery = (action, detail) => {
-        state.recoveryTrace.set(action, (state.recoveryTrace.get(action) ?? 0) + 1);
-        return { type: "recovery", turnId, action, detail };
-    };
-    // Build the terminal `end` event, attaching the recovery trace when non-empty.
-    const endEvent = (content) => ({
-        type: "end",
-        turnId,
-        content,
-        usage: state.totalUsage,
-        model: state.currentModel,
-        ...(state.recoveryTrace.size > 0 ? { recoveryTrace: Object.fromEntries(state.recoveryTrace) } : {}),
-    });
-    // - Main loop (CC while(true) parity) -
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-        // P0: hard iteration cap -terminate if recovery loops go unbounded
-        totalIterations++;
-        if (totalIterations > MAX_TOTAL_ITERATIONS) {
-            log.info(`hard iteration cap reached (${MAX_TOTAL_ITERATIONS}), forcing completion`);
-            const endContent = state.finalText || synthesizeFallbackContent(state.messages, log);
-            yield endEvent(endContent);
-            return;
-        }
-        // Destructure state at the top of each iteration (CC pattern)
-        const { messages, maxOutputTokensRecoveryCount, maxOutputTokensOverride, turnCount, guardState, reactiveCompactState, collapseStore, } = state;
-        let { toolLoopState } = state;
-        // - Pre-round checks -
-        // Yield pending tool use summary from previous turn (CC pendingToolUseSummary parity)
-        if (pendingToolUseSummary) {
-            try {
-                const summary = await pendingToolUseSummary;
-                if (summary) {
-                    yield { type: "tool_use_summary", turnId, summary };
-                }
-            }
-            catch { /* non-blocking */ }
-            pendingToolUseSummary = undefined;
-        }
-        // Tool refresh between turns (CC refreshTools parity)
-        if (params.refreshTools && turnCount > 1) {
-            const refreshed = params.refreshTools();
-            if (refreshed !== currentTools) {
-                currentTools = refreshed;
-                log.debug(`tools refreshed: ${refreshed.length} tools`);
-            }
-        }
-        // Abort check
-        if (shouldAbortTurn(guardState, guardConfig)) {
-            log.info(`turn aborted by guard at turn ${turnCount}`);
-            yield { type: "error", turnId, error: "Turn aborted", code: "ABORTED", usage: state.totalUsage };
-            return;
-        }
-        // Token budget pre-check
-        const tokenWarning = calculateTokenWarningState(guardState, guardConfig);
-        if (tokenWarning.level === "blocking") {
-            if (tokenWarning.reason === "prompt_too_long" &&
-                shouldAttemptReactiveCompact(reactiveCompactState)) {
-                reactiveCompactState.attemptedThisTurn = true;
-                guardState.hasAttemptedReactiveCompact = true;
-                log.info(`token budget blocking (${tokenWarning.reason}), reactive compact needed`);
-                yield emitRecovery("reactive_compact", "token budget pre-check");
-            }
-            log.info(`token budget blocking (${tokenWarning.reason}), ending tool loop`);
-            break;
-        }
-        if (tokenWarning.level === "warning") {
-            log.info(`token budget warning: ${tokenWarning.usagePercent}% used, ${tokenWarning.remainingTokens} remaining`);
-        }
-        // - Context compression pipeline (CC query.ts parity) -
-        // tool-result-budget → snip → microcompact → collapse → autocompact → whitespace
-        // filter. Extracted to tool-loop/compression-pipeline.ts (see it for stage detail);
-        // no control-flow escape, so it is a clean `yield*` boundary.
-        let messagesForQuery = yield* runCompressionPipeline({
-            messages,
-            contentReplacementState: state.contentReplacementState,
-            snipRemovedIds: state.snipRemovedIds,
-            collapseStore,
-            guardState,
-            guardConfig,
-            runtimePorts: params.runtimePorts,
-            hooks,
-            hookCtx,
-            sessionId,
-            currentModel: state.currentModel,
-            log,
-            recovery: emitRecovery,
-            onAutocompact: () => { state.hasAttemptedReactiveCompact = false; },
-        });
-        // - Build tool loop request -
-        const roundToolChoice = params.toolChoice === "required" && requiredToolChoiceSatisfied
-            ? "auto"
-            : (params.toolChoice ?? "auto");
-        const toolChoiceResult = applyToolChoicePolicy({
-            tools: currentTools,
-            toolChoice: roundToolChoice,
-        });
-        const repaired = recoverToolLoopStateFromChatConversation({
-            maxRounds: toolBudget,
-            replayMessages: messagesForQuery,
-            lastStopReason: toolLoopState.lastStopReason,
-            options: { stopReason: toolLoopState.lastStopReason },
-        });
-        const requestMessages = toolChoiceResult.extraSystemPrompt
-            ? [
-                { role: "system", content: toolChoiceResult.extraSystemPrompt },
-                ...repaired.state.replayMessages,
-            ]
-            : repaired.state.replayMessages;
-        toolLoopState = repaired.state;
-        if (repaired.recoveryActions.length > 0) {
-            log.debug(`tool loop recovery: ${repaired.recoveryActions.map((a) => a.detail ?? a.kind).join("; ")}`);
-        }
-        log.debug(`turn ${turnCount}, messages: ${requestMessages.length}`);
-        // Hook: turn.before_inference
-        fireHook(hooks, "turn.before_inference", { ...hookCtx, model: state.currentModel }, log);
-        // - Streaming LLM round with Hermes delta suppression -
-        let hasToolCalls = false;
-        const textChunks = [];
-        const toolCallAccumulator = new Map();
-        let finishReason = "stop";
-        let roundUsage;
-        let streamError = null;
-        // Error Withholding: track whether the response is a recoverable error
-        let withheldError = false;
-        let sawTerminalChunk = false;
-        // Anthropic thinking blocks -accumulated for passback in subsequent requests
-        const thinkingChunks = [];
-        const thinkingBlocks = [];
-        try {
-            for await (const chunk of transport.stream({
-                model: state.currentModel,
-                messages: requestMessages,
-                tools: toolChoiceResult.tools,
-                toolChoice: toolChoiceResult.normalizedToolChoice ??
-                    "auto",
-                temperature,
-                maxTokens: (maxOutputTokensOverride ?? guardState.currentMaxOutputTokens) || undefined,
-                streamRequired: params.streamRequired,
-                previousResponseId: state.lastResponseId,
-                reasoning: params.reasoning,
-                promptCacheKey: params.promptCacheKey,
-                promptCacheRetention: params.promptCacheRetention,
-                serviceTier: params.serviceTier,
-                openaiBuiltinTools: params.openaiBuiltinTools,
-                maxToolCalls: params.maxToolCalls,
-                parallelToolCalls: params.parallelToolCalls,
-                textVerbosity: params.textVerbosity,
-            }, apiKey, signal)) {
-                switch (chunk.type) {
-                    case "delta":
-                        textChunks.push(chunk.text);
-                        break;
-                    case "tool_call_delta":
-                        hasToolCalls = true;
-                        accumulateToolCalls(toolCallAccumulator, chunk);
-                        break;
-                    case "reasoning_delta":
-                        thinkingChunks.push(chunk.text);
-                        break;
-                    case "reasoning_block_complete":
-                        // Finalize thinking block with accumulated text + signature.
-                        // CC parity (stripSignatureBlocks): only store blocks with
-                        // valid signatures. DeepSeek may not emit signature_delta,
-                        // leaving signature as "". Sending empty signatures back
-                        // to the API causes 400 errors.
-                        if (chunk.signature) {
-                            thinkingBlocks.push({
-                                thinking: thinkingChunks.join(""),
-                                signature: chunk.signature,
-                            });
-                        }
-                        thinkingChunks.length = 0;
-                        break;
-                    case "usage":
-                        roundUsage = {
-                            inputTokens: chunk.promptTokens,
-                            outputTokens: chunk.completionTokens,
-                            reasoningTokens: chunk.reasoningTokens,
-                            cacheRead: chunk.cacheReadTokens,
-                            cacheWrite: chunk.cacheCreationTokens,
-                        };
-                        break;
-                    case "response_id":
-                        // Capture for server-side context chain (previous_response_id)
-                        state.lastResponseId = chunk.id;
-                        break;
-                    case "annotations":
-                        // Forward citation annotations to UI
-                        yield { type: "annotations", turnId, annotations: chunk.annotations };
-                        break;
-                    case "builtin_tool_status":
-                        // Forward platform builtin tool progress as heartbeat
-                        yield { type: "heartbeat", turnId, message: `${chunk.toolType}: ${chunk.event}` };
-                        break;
-                    case "done":
-                        sawTerminalChunk = true;
-                        finishReason = chunk.finishReason;
-                        break;
-                }
-            }
-            // Hook: turn.after_inference (success path)
-            if (!hasToolCalls) {
-                fireHook(hooks, "turn.after_inference", { ...hookCtx, model: state.currentModel }, log);
-            }
-            // Post-sampling hooks -fire-and-forget (CC executePostSamplingHooks parity)
-            if (params.postSamplingHooks && params.postSamplingHooks.length > 0) {
-                const pshModel = state.currentModel;
-                for (const hook of params.postSamplingHooks) {
-                    try {
-                        void hook({ messages: [...messagesForQuery], model: pshModel, sessionId });
-                    }
-                    catch { /* non-blocking */ }
-                }
-            }
-        }
-        catch (err) {
-            // Stream-error recovery (FallbackTriggeredError / stale-connection / max_tokens
-            // overflow / 429·529 transient) is extracted to tool-loop/stream-error-recovery.ts.
-            // It yields any user-facing events and returns a control-flow decision the loop
-            // applies here — keeping the loop's densest branch behind one named boundary.
-            const decision = yield* handleStreamError(err, {
-                state,
-                guardState,
-                fallbackModel: params.fallbackModel,
-                signal,
-                querySource,
-                turnId,
-                log,
-                emitRecovery,
-            });
-            if (decision.kind === "return")
-                return;
-            if (decision.kind === "continue") {
-                state = { ...state, ...decision.patch };
-                continue;
-            }
-            streamError = decision.streamError;
-        }
-        if (!streamError && !sawTerminalChunk) {
-            const message = "LLM stream closed before a terminal event; the response was likely truncated upstream.";
-            fireHook(hooks, "stop.failure", { sessionId, reason: "RETRYABLE_TRANSIENT", error: message }, log);
-            yield { type: "error", turnId, error: message, code: "RETRYABLE_TRANSIENT", usage: state.totalUsage };
-            return;
-        }
-        // Hook: turn.after_inference (error path)
-        if (streamError) {
-            fireHook(hooks, "turn.after_inference", { ...hookCtx, model: state.currentModel, response: { error: streamError.message } }, log);
-        }
-        // - Handle LLM errors with Error Withholding (CC parity) -
-        if (streamError) {
-            // Check if this is a recoverable prompt-too-long error
-            if (isPromptTooLongError(streamError)) {
-                // Withhold the error -attempt recovery before surfacing
-                withheldError = true;
-                log.info(`withheld prompt_too_long error (status=${streamError.status})`);
-            }
-            else if (isMediaSizeError(streamError)) {
-                // P1: Media error withholding (CC ImageSizeError/ImageResizeError parity)
-                // Withhold for reactive compact strip-retry
-                withheldError = true;
-                log.info(`withheld media_size error (status=${streamError.status})`);
-            }
-            else {
-                // Non-recoverable errors: handle via turn-loop-guard
-                const recovery = resolveApiErrorRecovery({ status: streamError.status ?? 500, message: streamError.message }, guardState, guardConfig);
-                if (recovery.action === "reactive_compact" &&
-                    shouldAttemptReactiveCompact(reactiveCompactState)) {
-                    reactiveCompactState.attemptedThisTurn = true;
-                    guardState.hasAttemptedReactiveCompact = true;
-                    yield emitRecovery("reactive_compact", `API ${streamError.status ?? 500}: ${streamError.message}`);
-                }
-                if (recovery.action === "retry") {
-                    const nextRetries = (state.consecutiveApiRetries ?? 0) + 1;
-                    if (nextRetries > MAX_API_RETRIES) {
-                        log.info(`API retry limit reached (${MAX_API_RETRIES}), aborting`);
-                        const category = classifyError(streamError.status, streamError.message);
-                        yield { type: "error", turnId, error: streamError.message, code: category, usage: state.totalUsage };
-                        return;
-                    }
-                    yield emitRecovery("retry", recovery.reason);
-                    state = { ...state, consecutiveApiRetries: nextRetries, transition: undefined };
-                    continue;
-                }
-                // Unrecoverable
-                const category = classifyError(streamError.status, streamError.message);
-                fireHook(hooks, "stop.failure", { sessionId, reason: category, error: streamError.message }, log);
-                yield { type: "error", turnId, error: streamError.message, code: category, usage: state.totalUsage };
-                return;
-            }
-        }
-        // Accumulate usage
-        if (roundUsage) {
-            state.totalUsage.inputTokens += roundUsage.inputTokens;
-            state.totalUsage.outputTokens += roundUsage.outputTokens;
-            if (roundUsage.reasoningTokens) {
-                state.totalUsage.reasoningTokens = (state.totalUsage.reasoningTokens ?? 0) + roundUsage.reasoningTokens;
-            }
-            // CC accumulateUsage parity: forward cache tokens
-            if (roundUsage.cacheRead) {
-                state.totalUsage.cacheRead = (state.totalUsage.cacheRead ?? 0) + roundUsage.cacheRead;
-            }
-            if (roundUsage.cacheWrite) {
-                state.totalUsage.cacheWrite = (state.totalUsage.cacheWrite ?? 0) + roundUsage.cacheWrite;
-            }
-        }
-        // Turn-loop-guard: update token state from usage feedback
-        if (roundUsage?.inputTokens) {
-            guardState.promptTokens = roundUsage.inputTokens;
-        }
-        const roundText = textChunks.join("");
-        // Convert accumulated tool call deltas to OpenAiToolCall[]
-        let toolCalls = [...toolCallAccumulator.values()].map((tc) => ({
-            id: tc.id || `tc_${turnId}_${turnCount}_${Math.random().toString(36).slice(2, 8)}`,
-            type: "function",
-            function: { name: tc.name, arguments: tc.arguments },
-        }));
-        // - No tool calls: recovery checks + completion -
-        if (toolCalls.length === 0 && !hasToolCalls) {
-            if (roundText) {
-                state.finalText = roundText;
-            }
-            if (params.toolChoice === "required" &&
-                !requiredToolChoiceSatisfied &&
-                currentTools.length > 0 &&
-                requiredToolChoiceRetryCount < 2) {
-                requiredToolChoiceRetryCount++;
-                const toolNames = currentTools
-                    .map((tool) => tool.function.name)
-                    .filter(Boolean)
-                    .slice(0, 8)
-                    .join(", ");
-                state = {
-                    ...state,
-                    messages: [
-                        ...messages,
-                        {
-                            role: "user",
-                            content: `You must call one available tool before answering. ` +
-                                `Available tools for this request: ${toolNames}. ` +
-                                `Do not answer from memory, prior context, or guesses.`,
-                        },
-                    ],
-                    finalText: "",
-                    transition: { reason: "next_turn" },
-                };
-                continue;
-            }
-            // - 1. Withheld prompt-too-long recovery (CC collapse_drain_retry + reactive_compact_retry) -
-            if (withheldError && streamError && isPromptTooLongError(streamError)) {
-                // CC label: collapse_drain_retry
-                // First: drain all staged context-collapses.
-                // Skip if we already drained on the previous iteration.
-                if (state.transition?.reason !== "collapse_drain_retry") {
-                    const drained = recoverContextCollapseFromOverflow(messagesForQuery, collapseStore);
-                    if (drained.committed > 0) {
-                        log.info(`collapse drain: committed ${drained.committed} stages`);
-                        yield emitRecovery("collapse_drain", `${drained.committed} stages committed`);
-                        state = {
-                            ...state,
-                            messages: drained.messages,
-                            transition: { reason: "collapse_drain_retry", committed: drained.committed },
-                        };
-                        continue; // CC: collapse_drain_retry
-                    }
-                }
-                // CC label: reactive_compact_retry
-                // Collapse drain exhausted or insufficient -try reactive compact.
-                if (shouldAttemptReactiveCompact(reactiveCompactState)) {
-                    reactiveCompactState.attemptedThisTurn = true;
-                    guardState.hasAttemptedReactiveCompact = true;
-                    log.info("withheld 413: reactive compact attempt");
-                    yield emitRecovery("reactive_compact", "withheld prompt_too_long");
-                    state = {
-                        ...state,
-                        hasAttemptedReactiveCompact: true,
-                        transition: { reason: "reactive_compact_retry" },
-                    };
-                    continue; // CC: reactive_compact_retry
-                }
-                // Recovery exhausted -surface the withheld error
-                log.info("withheld 413: recovery exhausted, surfacing error");
-                // CC executeStopFailureHooks parity: fire stop.failure on recovery exhaustion
-                fireHook(hooks, "stop.failure", { sessionId, reason: "prompt_too_long", error: streamError.message }, log);
-                yield { type: "error", turnId, error: streamError.message, code: "PROMPT_TOO_LONG", usage: state.totalUsage };
-                return;
-            }
-            // - 1b. Withheld media error recovery (CC ImageSizeError strip-retry) -
-            if (withheldError && streamError && isMediaSizeError(streamError)) {
-                if (shouldAttemptReactiveCompact(reactiveCompactState)) {
-                    reactiveCompactState.attemptedThisTurn = true;
-                    guardState.hasAttemptedReactiveCompact = true;
-                    log.info("withheld media error: reactive compact strip-retry");
-                    yield emitRecovery("reactive_compact", "media error strip-retry");
-                    state = {
-                        ...state,
-                        hasAttemptedReactiveCompact: true,
-                        transition: { reason: "reactive_compact_retry" },
-                    };
-                    continue; // CC: reactive_compact_retry (media variant)
-                }
-                // Recovery exhausted -surface as image_error
-                log.info("withheld media error: recovery exhausted");
-                fireHook(hooks, "stop.failure", { sessionId, reason: "media_error", error: streamError.message }, log);
-                yield { type: "error", turnId, error: streamError.message, code: "IMAGE_ERROR", usage: state.totalUsage };
-                return;
-            }
-            // - 2. Max output tokens recovery (CC max_output_tokens_escalate + max_output_tokens_recovery) -
-            if (isMaxOutputTokensTruncation(finishReason)) {
-                // Turn-loop-guard: escalate output budget
-                guardState.consecutiveTruncations += 1;
-                const modelMaxOutput = params.modelMaxOutputTokens ?? DEFAULT_MODEL_MAX_OUTPUT_TOKENS;
-                const escalation = resolveOutputTokenEscalation(guardState, guardConfig, modelMaxOutput);
-                // CC label: max_output_tokens_escalate
-                // First escalation: retry with higher output token limit (no message injection)
-                if (escalation.shouldEscalate &&
-                    maxOutputTokensOverride === undefined) {
-                    guardState.currentMaxOutputTokens = escalation.newMax;
-                    log.info(`max_output_tokens escalate: ${escalation.newMax} tokens`);
-                    yield emitRecovery("output_escalation", `${escalation.newMax} tokens`);
-                    state = {
-                        ...state,
-                        maxOutputTokensOverride: ESCALATED_MAX_OUTPUT_TOKENS,
-                        transition: { reason: "max_output_tokens_escalate" },
-                    };
-                    continue; // CC: max_output_tokens_escalate
-                }
-                // CC label: max_output_tokens_recovery
-                // Escalation exhausted or already escalated -inject recovery message
-                if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
-                    const recoveryMsg = {
-                        role: "user",
-                        content: "Output token limit hit. Resume directly - no apology, no recap of what you were doing. " +
-                            "Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.",
-                    };
-                    log.info(`max_output_tokens recovery #${maxOutputTokensRecoveryCount + 1}`);
-                    yield emitRecovery("max_output_tokens_recovery", `attempt ${maxOutputTokensRecoveryCount + 1}`);
-                    state = {
-                        ...state,
-                        messages: [...messagesForQuery, recoveryMsg],
-                        maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1,
-                        maxOutputTokensOverride: undefined,
-                        transition: { reason: "max_output_tokens_recovery", attempt: maxOutputTokensRecoveryCount + 1 },
-                    };
-                    continue; // CC: max_output_tokens_recovery
-                }
-                // Recovery exhausted -surface truncation as completion
-                log.info("max_output_tokens recovery exhausted, completing with partial content");
-            }
-            else {
-                guardState.consecutiveTruncations = 0;
-            }
-            // - 3. Normal completion path -
-            toolLoopState = settleToolLoopState(toolLoopState, {
-                replayMessages: messages,
-                lastStopReason: "completed",
-            });
-            const stopPolicy = await resolveCompletionStopPolicy({
-                hooks,
-                sessionId,
-                messages,
-                finalText: state.finalText,
-                thinkingBlocks,
-                log,
-            });
-            if (stopPolicy?.action === "end") {
-                yield endEvent(stopPolicy.content);
-                return;
-            }
-            if (stopPolicy?.action === "continue") {
-                state = {
-                    ...state,
-                    messages: stopPolicy.messages,
-                    stopHookActive: stopPolicy.stopHookActive,
-                    transition: stopPolicy.transition,
-                };
-                continue;
-            }
-            const budgetPolicy = resolveBudgetContinuationPolicy({
-                tokenBudget: params.tokenBudget,
-                totalUsage: state.totalUsage,
-                budgetContinuationCount: state.budgetContinuationCount,
-                lastBudgetDeltaTokens: state.lastBudgetDeltaTokens,
-                lastBudgetGlobalTokens: state.lastBudgetGlobalTokens,
-                messages,
-                finalText: state.finalText,
-                thinkingBlocks,
-                getBudgetContinuationMessage: params.runtimePorts.getBudgetContinuationMessage,
-                log,
-            });
-            if (budgetPolicy) {
-                yield emitRecovery("budget_continuation", budgetPolicy.recoveryDetail);
-                state = {
-                    ...state,
-                    messages: budgetPolicy.messages,
-                    budgetContinuationCount: budgetPolicy.budgetContinuationCount,
-                    lastBudgetDeltaTokens: budgetPolicy.lastBudgetDeltaTokens,
-                    lastBudgetGlobalTokens: budgetPolicy.lastBudgetGlobalTokens,
-                    transition: budgetPolicy.transition,
-                };
-                continue;
-            }
-            const completionPolicy = resolveCompletionActionPolicy({
-                inputMessages,
-                messages,
-                finalText: state.finalText,
-                thinkingBlocks,
-                stopHookActive: state.stopHookActive,
-                totalToolCallCount,
-                distinctToolNames,
-                log,
-            });
-            if (completionPolicy) {
-                state = {
-                    ...state,
-                    messages: completionPolicy.messages,
-                    stopHookActive: completionPolicy.stopHookActive,
-                    transition: completionPolicy.transition,
-                };
-                continue;
-            }
-            const skillInstruction = resolveToolUsageSkillInstruction({
-                totalToolCallCount,
-                distinctToolNames,
-                projectRoot: params.projectRoot,
-            });
-            if (skillInstruction) {
-                yield { type: "skill_instruction", turnId, instruction: skillInstruction };
-            }
-            // OpenAI format compensation (CC parity): when LLM ends with empty text
-            // after tool execution rounds, synthesize content from tool results so
-            // the user doesn't see a blank response.
-            const endContent = state.finalText || synthesizeFallbackContent(messages, log);
-            for (const text of textChunks) {
-                yield { type: "delta", turnId, text };
-            }
-            yield endEvent(endContent);
-            return;
-        }
-        // - Has tool calls ->execute them -
-        // Emit tool_call events for allowed calls (non-variant-blocked).
-        // Variant-blocked calls are suppressed from the event stream to prevent
-        // inflating the client's tool_call count with synthetic blocked responses.
-        // NOTE: This emission is done BEFORE blocking checks for the allowed subset,
-        // so we need to re-emit only for the final variantAllowed set below.
-        // Build assistant message with tool calls.
-        // CC parity: preserve text alongside tool_use (Anthropic content block coexistence).
-        // In OpenAI streaming, text deltas may arrive before tool_call_deltas;
-        // we keep that text so the LLM can reference its own reasoning in subsequent turns.
-        // A3 parity: For OpenAI-chat transport, reasoning_delta events accumulate in
-        // thinkingChunks but no reasoning_block_complete is emitted (Anthropic-only).
-        // Pass leftover thinkingChunks as reasoning_content so GLM/DeepSeek can see
-        // the model's reasoning chain across tool-call rounds.
-        const leftoverReasoning = thinkingBlocks.length === 0 && thinkingChunks.length > 0
-            ? thinkingChunks.join("")
-            : undefined;
-        messages.push(buildAssistantToolCallMessage(toolCalls, undefined, thinkingBlocks.length > 0 ? thinkingBlocks : undefined, leftoverReasoning));
-        // Advance tool loop state
-        toolLoopState = advanceToolLoopState(toolLoopState, {
-            replayMessages: messages,
-            pendingToolCallIds: toolCalls.map((tc) => tc.id),
-            completedToolCallIds: toolLoopState.completedToolCallIds,
-            lastStopReason: "tool_calls",
-        });
-        // - AP4: Pre-execution identical call detection -
-        // Block calls that exceed MAX_IDENTICAL_CALL_REPEATS BEFORE execution.
-        // This saves time (no wasted API/disk calls) and forces the LLM to adapt.
-        const identicalCallCounts = state.identicalCallCounts;
-        const allowedCalls = [];
-        const blockedByAP4 = [];
-        let identicalCallNudgeInjected = false;
-        for (const tc of toolCalls) {
-            const callKey = `${tc.function.name}::${tc.function.arguments}`;
-            const prev = identicalCallCounts.get(callKey) ?? 0;
-            identicalCallCounts.set(callKey, prev + 1);
-            if (prev + 1 > MAX_IDENTICAL_CALL_REPEATS) {
-                blockedByAP4.push(tc);
-                if (!identicalCallNudgeInjected) {
-                    identicalCallNudgeInjected = true;
-                    log.info(`AP4 blocked: ${tc.function.name} repeated ${prev + 1}x`);
-                }
-            }
-            else {
-                allowedCalls.push(tc);
-            }
-        }
-        // Synthesize error results for blocked calls (before executor runs)
-        const executedToolCallIds = [];
-        for (const tc of blockedByAP4) {
-            const repeatCount = identicalCallCounts.get(`${tc.function.name}::${tc.function.arguments}`);
-            // Extract last error from previous tool results for the same tool
-            const lastError = findLastToolError(messages, tc.function.name);
-            const errorMsg = lastError
-                ? `This exact tool call has been attempted ${repeatCount} times. Last error: ${lastError}. Do not retry. Report this error to the user.`
-                : `This exact tool call has been attempted ${repeatCount} times and keeps failing. Do not retry it. Report the issue to the user or try a completely different approach.`;
-            const msg = buildToolResultMessage(tc.id, { ok: false, error: errorMsg });
-            messages.push(msg);
-            executedToolCallIds.push(tc.id);
-            distinctToolNames.add(tc.function.name);
-            totalToolCallCount++;
-            yield {
-                type: "tool_result",
-                turnId,
-                callId: tc.id,
-                name: tc.function.name,
-                ok: false,
-                error: errorMsg,
-            };
-        }
-        // Inject nudge if any calls were blocked
-        if (blockedByAP4.length > 0) {
-            const lastToolError = findLastToolError(messages, blockedByAP4[0].function.name);
-            const nudgeMsg = {
-                role: "user",
-                content: `Tool calls were blocked because you repeated them with identical arguments too many times. ` +
-                    (lastToolError
-                        ? `The error was: "${lastToolError}". Tell the user about this error. `
-                        : `The operation is not working. `) +
-                    `Stop retrying and report the result to the user.`,
-            };
-            messages.push(nudgeMsg);
-        }
-        const variantPolicy = splitVariantToolCalls(allowedCalls, state.toolFailureCounts);
-        const variantAllowed = variantPolicy.allowed;
-        if (variantPolicy.blocked.length > 0) {
-            for (const blocked of variantPolicy.blocked) {
-                const tc = blocked.call;
-                const msg = buildToolResultMessage(tc.id, { ok: false, error: blocked.error });
-                messages.push(msg);
-                executedToolCallIds.push(tc.id);
-                distinctToolNames.add(tc.function.name);
-                totalToolCallCount++;
-                yield {
-                    type: "tool_result",
-                    turnId,
-                    callId: tc.id,
-                    name: tc.function.name,
-                    ok: false,
-                    error: blocked.error,
-                };
-                log.info(`variant tool blocked: ${tc.function.name} failed ${blocked.failCount}x with different args`);
-            }
-            messages.push(variantBlockNudge());
-        }
-        // - Emit tool_call events for non-blocked calls only -
-        // Deferred from above: only emit for calls that will actually be attempted.
-        for (const tc of variantAllowed) {
-            let emittedArguments = tc.function.arguments;
-            const toolDef = currentTools.find((t) => t.function.name === tc.function.name);
-            if (toolDef?.backfillObservableInput) {
-                try {
-                    const parsed = JSON.parse(tc.function.arguments);
-                    const copy = { ...parsed };
-                    toolDef.backfillObservableInput(copy);
-                    const addedFields = Object.keys(copy).some((k) => !(k in parsed));
-                    if (addedFields) {
-                        emittedArguments = JSON.stringify(copy);
-                    }
-                }
-                catch { /* parse failure - emit original */ }
-            }
-            yield {
-                type: "tool_call",
-                turnId,
-                callId: tc.id,
-                name: tc.function.name,
-                arguments: emittedArguments,
-                inputSummary: summarizeToolInput(emittedArguments),
-            };
-        }
-        // - Execute tool calls via StreamingToolExecutor (CC parity) -
-        // Snapshot failure counts before execution so we can detect threshold crossings after
-        const variantFailureSnapshot = new Map(state.toolFailureCounts);
-        try {
-            const executor = params.runtimePorts.createStreamingToolExecutor({
-                toolInvoker,
-                hooks,
-                sessionId,
-                turnId,
-                log,
-                signal,
-                maxConcurrentTools: params?.maxConcurrentTools,
-            });
-            // Feed only allowed (non-blocked) tool calls into the executor
-            for (const tc of variantAllowed) {
-                executor.addTool(tc);
-            }
-            // Drain results as tools complete
-            for await (const r of executor.getRemainingResults()) {
-                if (r.blocked) {
-                    yield { type: "tool_blocked", turnId, callId: r.callId, name: r.toolName, reason: r.blockReason ?? "blocked" };
-                }
-                messages.push(r.message);
-                executedToolCallIds.push(r.callId);
-                distinctToolNames.add(r.toolName);
-                totalToolCallCount++;
-                recordToolFailureResult({
-                    toolFailureCounts: state.toolFailureCounts,
-                    toolName: r.toolName,
-                    ok: r.ok,
-                    softEmpty: r.ok && isEmptyToolResult(r),
-                });
-                // AP5: file read cycle detection -track file paths read and detect circular traversal
-                if (r.ok && r.toolName === "read") {
-                    const originalCall = variantAllowed.find(tc => tc.id === r.callId);
-                    if (originalCall) {
-                        try {
-                            const args = JSON.parse(originalCall.function.arguments);
-                            const filePath = (args.file_path ?? args.path ?? args.filePath ?? "");
-                            if (filePath) {
-                                const prev = state.fileReadCounts.get(filePath) ?? 0;
-                                state.fileReadCounts.set(filePath, prev + 1);
-                            }
-                        }
-                        catch { /* ignore parse errors */ }
-                    }
-                }
-                yield createToolResultEvent(turnId, r);
-                for (const event of createToolMediaResultEvents(turnId, r)) {
-                    yield event;
-                }
-                // - Sidecar event emission: plan_update + artifact -
-                for (const event of createToolSidecarEvents({ turnId, result: r, toolCalls })) {
-                    yield event;
-                }
-            }
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            yield { type: "error", turnId, error: message, code: "TOOL_EXECUTION_ERROR", usage: state.totalUsage };
-            return;
-        }
-        messages.push(...newVariantFailureNudges({
-            toolFailureCounts: state.toolFailureCounts,
-            snapshot: variantFailureSnapshot,
-        }));
-        // Settle tool loop state
-        toolLoopState = settleToolLoopState(toolLoopState, {
-            replayMessages: messages,
-            completedToolCallIds: [
-                ...toolLoopState.completedToolCallIds,
-                ...executedToolCallIds,
-            ],
-            lastStopReason: "tool_calls",
-        });
-        if (params.toolChoice === "required" && toolCalls.length > 0) {
-            requiredToolChoiceSatisfied = true;
-        }
-        // Fire-and-forget tool use summary (CC generateToolUseSummary parity)
-        // Promise resolves during next turn's LLM streaming (~5-30s), yielded at iteration start.
-        if (params.generateToolUseSummary && toolCalls.length > 0) {
-            const summaryInput = toolCalls.map((tc) => ({
-                name: tc.function.name,
-                arguments: tc.function.arguments,
-            }));
-            pendingToolUseSummary = params.generateToolUseSummary(summaryInput).catch(() => null);
-        }
-        // - Consecutive failure tracking -
-        // Check all tool results from this round (both AP4-blocked and executor results).
-        // AP4-blocked calls always fail. Executor results check content prefix.
-        const allFailed = toolCalls.length > 0 && toolCalls.every((tc) => {
-            // Find the tool result message for this call ID
-            const resultMsg = messages.find((m) => m?.role === "tool" &&
-                m?.tool_call_id === tc.id);
-            if (!resultMsg)
-                return true; // missing = failed
-            const content = resultMsg.content;
-            return typeof content === "string" && content.startsWith("Error: ");
-        });
-        let nextConsecutiveFailedRounds = state.consecutiveFailedRounds;
-        if (allFailed) {
-            nextConsecutiveFailedRounds += 1;
-            if (nextConsecutiveFailedRounds >= MAX_CONSECUTIVE_FAILURES) {
-                // CC parity: exit early on repeated tool failures -don't burn iterations
-                // waiting for the model to give up. Use synthesizeFallbackContent when
-                // LLM hasn't produced any text yet (e.g. sandbox/injection paths that
-                // fail immediately, before any assistant text block).
-                const endContent = state.finalText || synthesizeFallbackContent(messages, log);
-                log.info(`early exit: ${nextConsecutiveFailedRounds} consecutive failed rounds, returning ${state.finalText ? "partial" : "fallback"} response`);
-                yield endEvent(endContent);
-                return;
-            }
-        }
-        else {
-            nextConsecutiveFailedRounds = 0;
-        }
-        // - AP5: File read cycle detection -
-        // If any single file has been read 3+ times this turn, the LLM is likely
-        // stuck in a circular import/dependency chain. Inject a nudge and force
-        // one final round to let it summarize.
-        const MAX_FILE_READS = 3;
-        const cycledFiles = [...state.fileReadCounts.entries()].filter(([, count]) => count >= MAX_FILE_READS);
-        if (cycledFiles.length > 0) {
-            const fileNames = cycledFiles.map(([f]) => f).join(", ");
-            log.info(`AP5: file read cycle detected on ${fileNames}, injecting nudge`);
-            const nudge = {
-                role: "user",
-                content: `You are reading the same files repeatedly (${fileNames}). This indicates a circular dependency or cycle. ` +
-                    `Stop reading files, summarize your findings so far, and explain the circular structure to the user.`,
-            };
-            messages.push(nudge);
-            // Clear counts so we don't re-trigger on the final round
-            state.fileReadCounts.clear();
-        }
-        // - Max turns check (CC maxTurns parity) -
-        const nextTurnCount = turnCount + 1;
-        if (maxTurns > 0 && nextTurnCount > maxTurns) {
-            log.info(`max turns reached (${maxTurns}), completing`);
-            // CC multi-reason stop hook parity: fire stop hook on max_turns
-            if (hooks) {
-                const stopResult = await hooks.invoke("stop", { sessionId, reason: "max_turns" });
-                if (stopResult.action === "abort") {
-                    const reason = stopResult.reason ?? "Stop hook requested continuation after max_turns";
-                    const maxTurnsAssistantMsg = { role: "assistant", content: state.finalText, ...(thinkingBlocks.length > 0 && { thinkingBlocks: [...thinkingBlocks] }) };
-                    state = {
-                        ...state,
-                        messages: [...messages, maxTurnsAssistantMsg, { role: "user", content: reason }],
-                        stopHookActive: true,
-                        transition: { reason: "stop_hook_blocking" },
-                    };
-                    continue;
-                }
-            }
-            // OpenAI format compensation: when LLM only produced tool_calls (no text),
-            // finalText is empty. Synthesize from last tool results so user doesn't
-            // see blank. CC doesn't need this -Anthropic text+tool_use coexist.
-            const endContent = state.finalText || synthesizeFallbackContent(messages, log);
-            yield endEvent(endContent);
-            return;
-        }
-        // - Tool budget exhaustion check (CC max_turns parity) -
-        // CC returns directly on budget exhaustion -no forced text-only round.
-        // OpenAI format note: unlike Anthropic where text+tool_use blocks coexist,
-        // OpenAI responses often have null content when tool_calls are present.
-        // We synthesize fallback content from tool results when finalText is empty.
-        if (nextTurnCount > toolBudget) {
-            log.info(`tool loop budget exhausted (${toolBudget} rounds), returning`);
-            const skillInstruction = resolveToolUsageSkillInstruction({
-                totalToolCallCount,
-                distinctToolNames,
-                projectRoot: params.projectRoot,
-            });
-            if (skillInstruction) {
-                yield { type: "skill_instruction", turnId, instruction: skillInstruction };
-            }
-            const endContent = state.finalText || synthesizeFallbackContent(messages, log);
-            yield endEvent(endContent);
-            return;
-        }
-        // - CC label: next_turn -
-        state = {
-            messages,
-            maxOutputTokensRecoveryCount: 0,
-            hasAttemptedReactiveCompact: false,
-            maxOutputTokensOverride: undefined,
-            turnCount: nextTurnCount,
-            transition: { reason: "next_turn" },
-            guardState,
-            reactiveCompactState,
-            toolLoopState,
-            consecutiveFailedRounds: nextConsecutiveFailedRounds,
-            finalText: state.finalText,
-            totalUsage: state.totalUsage,
-            collapseStore,
-            // Propagate P0 state across iterations
-            currentModel: state.currentModel,
-            consecutive529Errors: 0, // reset on successful tool round
-            consecutiveApiRetries: 0, // reset on successful tool round
-            stopHookActive: state.stopHookActive,
-            lastResponseId: state.lastResponseId,
-            snipRemovedIds: state.snipRemovedIds,
-            contentReplacementState: state.contentReplacementState,
-            // Propagate across rounds: budget policy bounds total continuation
-            // nudges per TURN. Resetting per tool round defeated the cap (model alternating
-            // tool-call/done could be nudged forever) and broke diminishing-returns
-            // detection (which compares usage deltas across checks).
-            budgetContinuationCount: state.budgetContinuationCount,
-            lastBudgetDeltaTokens: state.lastBudgetDeltaTokens,
-            lastBudgetGlobalTokens: state.lastBudgetGlobalTokens,
-            identicalCallCounts, // propagate across rounds
-            toolFailureCounts: state.toolFailureCounts, // propagate across rounds
-            fileReadCounts: state.fileReadCounts, // propagate across rounds
-            recoveryTrace: state.recoveryTrace, // propagate across rounds
-        };
-    } // while (true)
-}