qlogicagent 2.13.4 → 2.13.5

package/dist/agent/tool-loop.js

@@ -0,0 +1,1017 @@
+/**
+ * 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)
+}