@nexus-cortex/core 4.51.0 → 4.52.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -41,10 +41,14 @@ import { classifyApiError } from './apiErrorClassifier.js';
 import { pinStaticSystemPrompt } from './staticSystemPromptPin.js';
 import { hasVisibleAssistantText, shouldForceSynthesis } from './assistantTextPresence.js';
 import { computeToolBudgetSignal, isToolProgressStalled } from './toolBudgetSignal.js';
+import { createStructuredOutputTurnState, ensureStructuredOutputTool, evaluateStructuredOutputCall, finalizeStructuredOutput, isStructuredOutputToolName, } from './structuredOutput.js';
 // Phase 2.6: MCP Model Management Tools
 import { ListAvailableMcpServers, SearchMcpServers, GetMcpConfig, EnableMcpServer, DisableMcpServer, ConfigureMcpServer, InitMcpConfig } from '../tools/mcp-management/index.js';
 // Context Management Tools
 import { InitCortexContext, MemoryWrite, MemoryRecall } from '../tools/context-management/index.js';
+import { pruneAgedToolResults } from '../conversation/ToolResultPruner.js';
+import { detectTailRepetition, tailLoopGuardEnabled } from './tailRepetitionDetector.js';
+import { classifyEmptyResponse, emptyResponseNudge } from './emptyResponseClassifier.js';
 // PTC: Progressive tool loading for non-PTC providers
 import { ClientSideToolFilter } from '../tools/ClientSideToolFilter.js';
 /**
@@ -93,6 +97,9 @@ export class CortexOrchestrator {
     // in messageHistory — they're sent separately to the API — so the budget must
     // reserve space for them. The old hardcoded estimate (2000) was ~4-5x too low.
     currentToolTokens = 0;
+    /** Active model's context window, captured by ensureHistoryFitsModel for
+     *  the request-build pruning gate (pruneAgedForRequest). */
+    lastKnownContextWindow;
     // Responses API stateful chaining: track last response ID for XAI/OpenAI
     // When set, continuation requests send previous_response_id instead of full history,
     // letting the server preserve reasoning state and improve coherence.
@@ -608,6 +615,19 @@ export class CortexOrchestrator {
         if (!isPTCEnabled && this.config.enableDeferredToolLoading && toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.toolFilter.getFilteredTools(toolsToUse);
         }
+        // StructuredOutput (grok-build port): when the caller requested
+        // schema-constrained output, inject the request-scoped synthetic tool.
+        // Appended AFTER server-side detection and the deferred filter so it can
+        // neither trigger endpoint switching nor be stripped; `toolsToUse` is the
+        // variable every request of this turn (initial, retries, EndTurn-gate,
+        // continuations) is prepared from, so one append covers the whole loop —
+        // except the deferred re-filter inside the loop, which re-appends.
+        const structuredOutputState = options.jsonSchema
+            ? createStructuredOutputTurnState(options.jsonSchema)
+            : undefined;
+        if (structuredOutputState) {
+            toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
+        }
         // Reset sequential call counter at start of each user turn
         this.mentorshipMiddleware?.resetSequentialCalls(this.currentSessionId);
         const preparedRequest = this.gatewayTranslation.prepareRequest(canonicalHistory, toolsToUse, effectiveModel, {
@@ -737,12 +757,34 @@ export class CortexOrchestrator {
             }
         }
         // 9. Convert response back to canonical format
-        const convertedResponse = this.gatewayTranslation.convertResponse(apiResponse.data, effectiveModel, // Use effectiveModel (may have switched to Responses API)
+        let convertedResponse = this.gatewayTranslation.convertResponse(apiResponse.data, effectiveModel, // Use effectiveModel (may have switched to Responses API)
         {
             sessionId: this.currentSessionId,
             conversationId: this.currentConversationId,
             turnNumber: this.turnNumber + 1
         });
+        // Non-streaming tail-repetition doom-loop guard (grok-build port) — OPT-IN,
+        // default OFF. The streaming path aborts mid-stream; on a single response
+        // we detect a repeating thinking tail POST-HOC and resample ONCE (a fresh
+        // sample at temp>0 escapes the attractor). Same flag + detector as the
+        // streaming guard, bounded to one extra call. OFF = byte-identical.
+        if (tailLoopGuardEnabled(effectiveModel.provider)) {
+            const thinkingText = (convertedResponse.messages || [])
+                .flatMap((m) => (Array.isArray(m.content) ? m.content : []))
+                .filter((b) => b?.type === 'thinking' && typeof b.thinking === 'string')
+                .map((b) => b.thinking)
+                .join('\n');
+            const loop = detectTailRepetition(thinkingText);
+            if (loop.looping) {
+                console.warn(`[TailLoopGuard] xAI thinking loop detected (non-streaming, ${loop.trigger}) — resampling once`);
+                apiResponse = await this.apiClient.sendRequest(preparedRequest, effectiveModel);
+                convertedResponse = this.gatewayTranslation.convertResponse(apiResponse.data, effectiveModel, {
+                    sessionId: this.currentSessionId,
+                    conversationId: this.currentConversationId,
+                    turnNumber: this.turnNumber + 1
+                });
+            }
+        }
         // Track Responses API response ID for stateful chaining (XAI, OpenAI)
         // R20a: also track which provider produced it — prevents cross-provider
         // leak (XAI UUIDs vs OpenAI resp_* are mutually incompatible).
@@ -927,9 +969,21 @@ export class CortexOrchestrator {
                     // emit thinking blocks then stop without producing the final
                     // answer. Retry ONCE with an explicit completion prompt.
                     const hasVisibleText = hasVisibleAssistantText(currentAssistantCanonicalMessage.content);
-                    if (!hasVisibleText && !emptyResponseRetryUsed) {
+                    // R18b skip-when-captured (2026-08-01): when the caller requested
+                    // structured output and a StructuredOutput call was already captured,
+                    // an empty visible-text turn is EXPECTED — the model correctly ended
+                    // after its final tool call. Nudging it for "no text" would burn an
+                    // extra round-trip (observed with haiku in the structured-output
+                    // canary). The structured result IS the deliverable, so skip R18b.
+                    if (!hasVisibleText && !emptyResponseRetryUsed && !structuredOutputState?.result) {
                         emptyResponseRetryUsed = true;
-                        console.warn(`[Orchestrator] Empty response detected (no tool_use, no text, iteration=${toolCallIteration}). ` +
+                        // Typed empty-response classification (grok-build port): distinguish
+                        // reasoning_only (model reasoned but never answered) from
+                        // no_visible_content (nothing at all) for observability + a nudge
+                        // tailored to the failure shape. Does NOT change the one-bounded-retry
+                        // decision — only the log + nudge text.
+                        const emptyClass = classifyEmptyResponse(currentAssistantCanonicalMessage.content);
+                        console.warn(`[Orchestrator] Empty response detected (${emptyClass.kind}, hadReasoning=${emptyClass.hadReasoning}, iteration=${toolCallIteration}). ` +
                             `Retrying once with explicit completion prompt.`);
                         // R26 (2026-05-15, surfaced by A/B benchmark): the empty assistant
                         // turn is already in messageHistory. The retry below rebuilds the
@@ -969,7 +1023,7 @@ export class CortexOrchestrator {
                                 role: 'user',
                                 content: [{
                                         type: 'text',
-                                        text: '<system-reminder>Your previous response had no visible text. Please provide your final answer in plain text now — summarize your findings or complete the requested task. Do not call any more tools.</system-reminder>',
+                                        text: `<system-reminder>${emptyResponseNudge(emptyClass.kind)} Do not call any more tools.</system-reminder>`,
                                     }],
                             },
                             timeline: {
@@ -1104,16 +1158,16 @@ export class CortexOrchestrator {
                             ? ' You ran edit/write/bash this turn: in `verification` list every build/test/lint command you ACTUALLY ran with the real result line you saw — do not claim a check you did not run.'
                             : '';
                         const endTurnReminderText = !endTurnCalled
-                            ? ('<system-reminder>You used tools this turn but have not called end_turn. ' +
-                                'You MUST call end_turn before any final answer. It is generative, not a checkbox: ' +
+                            ? ('<system-reminder>You used tools this turn but have not called EndTurn. ' +
+                                'You MUST call EndTurn before any final answer. It is generative, not a checkbox: ' +
                                 'reconstruct `citations` (array of {reference, verbatim_source}), `verification` ' +
                                 '(array of {command, observed_result}), `summary`, `open_items`, and a skeptical ' +
                                 '`self_review` (what you did NOT check, what is assumed/possibly wrong, what one ' +
                                 'more tool call would verify).' +
                                 citEmphasis +
                                 verEmphasis +
-                                ' Call end_turn now — do not produce a final answer until you have.</system-reminder>')
-                            : ('<system-reminder>end_turn REJECTED. Your drafted answer asserts line number(s) ' +
+                                ' Call EndTurn now — do not produce a final answer until you have.</system-reminder>')
+                            : ('<system-reminder>EndTurn REJECTED. Your drafted answer asserts line number(s) ' +
                                 stage3Violations.map((v) => v.line).join(', ') +
                                 ' that are NOT backed by any citation whose verbatim_source actually sits at that ' +
                                 "line in what you read this turn — a regurgitated coordinate, not an observation, " +
@@ -1122,7 +1176,7 @@ export class CortexOrchestrator {
                                 "is the EXACT code copied from that line of this turn's read output; " +
                                 '(2) for any you cannot ground, DELETE the number and quote the verbatim code ' +
                                 'instead — a quote with no number is correct; a wrong number is a failed answer. ' +
-                                'Then call end_turn again with corrected citations and produce the answer.</system-reminder>');
+                                'Then call EndTurn again with corrected citations and produce the answer.</system-reminder>');
                         const endTurnReminder = {
                             uuid: uuidv4(),
                             timestamp: new Date().toISOString(),
@@ -1348,7 +1402,7 @@ export class CortexOrchestrator {
                 // Track which tool_use_ids have been processed to avoid duplicates in error handler
                 const processedToolUseIds = new Set();
                 try {
-                    const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal);
+                    const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal, structuredOutputState);
                     clearTimeout(timeoutId);
                     // R21 (2026-05-15): MAX_CONSECUTIVE_ERRORS now counts CONSECUTIVE
                     // ITERATIONS WITH ZERO SUCCESSFUL TOOLS, not cumulative individual
@@ -1407,9 +1461,9 @@ export class CortexOrchestrator {
                                 .join('\n');
                             tr.is_error = true;
                             tr.content =
-                                `end_turn REJECTED — these citations are not grounded in anything you read this turn:\n${bad}\n\n` +
+                                `EndTurn REJECTED — these citations are not grounded in anything you read this turn:\n${bad}\n\n` +
                                     `A quote or coordinate you did not transcribe from this turn's tool output is a fabrication (a regurgitated guess), exactly like a non-matching edit old_string. ` +
-                                    `Either RE-READ the exact region and copy the real text, or DELETE that reference from your answer (quote only code you can ground), then call end_turn again.`;
+                                    `Either RE-READ the exact region and copy the real text, or DELETE that reference from your answer (quote only code you can ground), then call EndTurn again.`;
                             console.warn(`[Orchestrator] Stage2: EndTurn rejected — ${verdict.ungrounded.length} ungrounded citation(s).`);
                         }
                     }
@@ -1603,6 +1657,12 @@ export class CortexOrchestrator {
                     if (this.config.enableDeferredToolLoading && !isPTCEnabled) {
                         const beforeCount = toolsToUse.length;
                         toolsToUse = this.toolFilter.getFilteredTools(allTools);
+                        // StructuredOutput: the re-filter rebuilds from allTools (which never
+                        // contained the request-scoped tool) — re-append so it stays present
+                        // on every request of the turn.
+                        if (structuredOutputState) {
+                            toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
+                        }
                         if (this.config.debug && toolsToUse.length !== beforeCount) {
                             console.log(`[Deferred] Tools re-filtered: ${beforeCount} → ${toolsToUse.length} (${toolsToUse.map(t => t.name).join(', ')})`);
                         }
@@ -1879,8 +1939,15 @@ export class CortexOrchestrator {
                 await this.historyStore.appendMessage(this.currentSessionId, synthUserMessage);
                 await this.ensureHistoryFitsModel(effectiveModel);
                 const synthCanonicalHistory = this.convertToCanonicalMessages([...this.messageHistory]);
-                const synthRequest = this.gatewayTranslation.prepareRequest(synthCanonicalHistory, [], // tools suppressed — the model MUST produce text, not call more tools
-                effectiveModel, {
+                const synthRequest = this.gatewayTranslation.prepareRequest(synthCanonicalHistory, 
+                // Tools suppressed — the model MUST produce text, not call more tools.
+                // NOTE (structured-output constraint, 2026-08-02): this is R29a's
+                // plain-text escape hatch for tool-loop EXHAUSTION (30+ calls). A
+                // jsonSchema turn that gets here degrades to text; StructuredOutput
+                // is deliberately NOT re-forced (this terminal synth turn has no
+                // tool-interception, so a StructuredOutput call would go uncaptured —
+                // worse than the graceful text fallback + structuredOutput.valid=false).
+                [], effectiveModel, {
                     temperature: options.parameters?.temperature,
                     maxTokens: options.parameters?.maxTokens,
                     topP: options.parameters?.topP,
@@ -2046,6 +2113,16 @@ export class CortexOrchestrator {
                 // Phase 2.5 Day 2: Multi-turn tool execution metadata
                 toolCallIterations: toolCallIteration,
                 multiTurnToolExecution: toolCallIteration > 0,
+                // StructuredOutput (grok-build port): surfaced whenever the caller
+                // set options.jsonSchema — deterministic even if the tool was never called.
+                ...(structuredOutputState
+                    ? { structuredOutput: finalizeStructuredOutput(structuredOutputState) }
+                    : {}),
+                // Served-model drift (2026-08-01): provider served a different backend
+                // than the requested slug (see GatewayTranslationLayer.convertResponse).
+                ...(convertedResponse?.servedModelDrift
+                    ? { servedModel: convertedResponse.servedModel, servedModelDrift: true }
+                    : {}),
                 ...(usedHelperModel ? helperModelMetadata : {}),
                 ...(turnSummaryData ? {
                     turnSummary: turnSummaryData.summary,
@@ -2330,6 +2407,16 @@ export class CortexOrchestrator {
         if (!isPTCEnabled && this.config.enableDeferredToolLoading && toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.toolFilter.getFilteredTools(toolsToUse);
         }
+        // StructuredOutput (grok-build port) — streaming mirror of the sendMessage
+        // injection: appended AFTER server-side detection and the deferred filter;
+        // covers every request of the turn via the shared `toolsToUse` variable
+        // (the in-loop deferred re-filter re-appends).
+        const structuredOutputState = options.jsonSchema
+            ? createStructuredOutputTurnState(options.jsonSchema)
+            : undefined;
+        if (structuredOutputState) {
+            toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
+        }
         // Reset sequential call counter at start of each user turn
         this.mentorshipMiddleware?.resetSequentialCalls(this.currentSessionId);
         // Input-slicing at initial (streaming) request: send only items since last checkpoint
@@ -2367,7 +2454,7 @@ export class CortexOrchestrator {
             preparedRequest.parameters.enablePTC = true;
         }
         // 7. Stream request (NEW: Use streaming API)
-        const streamingResponse = this.apiClient.streamRequest(preparedRequest, effectiveModel);
+        let streamingResponse = this.apiClient.streamRequest(preparedRequest, effectiveModel);
         // CRITICAL: Attach a catch handler to finalMessage immediately to prevent unhandled rejection
         // If stream is interrupted (ESC), the SDK may reject finalMessage after we've exited
         // This prevents the "unhandledRejection" crash while still allowing errors when awaited
@@ -2378,21 +2465,61 @@ export class CortexOrchestrator {
         });
         // Track whether stream completed normally (vs interrupted by ESC/abort)
         let streamCompleted = false;
+        // Tail-repetition doom-loop guard (grok-build port, 2026-08-01) — OPT-IN,
+        // default OFF. When XAI_TAIL_LOOP_GUARD=true and the provider is xAI, watch
+        // the thinking channel (chunks already flowing past us — NO edit to the
+        // sacred APIClient reader) for a repeating tail; on a confident loop,
+        // abandon the doomed stream and resample ONCE (a fresh sample at temp>0
+        // usually escapes the attractor — grok-build's own remedy). Bounded to one
+        // resample; when off, the loop body is byte-identical to before.
+        const tailGuardOn = tailLoopGuardEnabled(effectiveModel.provider);
+        let tailResampleUsed = false;
         // 8. Yield chunks in real-time
-        try {
-            for await (const chunk of streamingResponse.chunks) {
+        while (true) {
+            let tailLoopTrigger = null;
+            let thinkingBuf = '';
+            let lastTailCheck = 0;
+            try {
+                for await (const chunk of streamingResponse.chunks) {
+                    if (this.config.debug) {
+                        console.log(`[Orchestrator] Yielding chunk type: ${chunk.type}, delta length: ${chunk.delta?.length || 0}`);
+                    }
+                    if (tailGuardOn && !tailResampleUsed
+                        && chunk.data?.reasoning === true && typeof chunk.delta === 'string') {
+                        thinkingBuf += chunk.delta;
+                        if (thinkingBuf.length - lastTailCheck >= 400) {
+                            lastTailCheck = thinkingBuf.length;
+                            const d = detectTailRepetition(thinkingBuf);
+                            if (d.looping) {
+                                tailLoopTrigger = d.trigger || 'tail_repetition@thinking';
+                                break;
+                            }
+                        }
+                    }
+                    yield chunk;
+                }
+                if (tailLoopTrigger === null) {
+                    streamCompleted = true;
+                }
+            }
+            catch (streamError) {
+                // Stream was interrupted or errored - log but don't throw yet
                 if (this.config.debug) {
-                    console.log(`[Orchestrator] Yielding chunk type: ${chunk.type}, delta length: ${chunk.delta?.length || 0}`);
+                    console.log(`[Orchestrator] Stream interrupted:`, streamError);
                 }
-                yield chunk;
             }
-            streamCompleted = true;
-        }
-        catch (streamError) {
-            // Stream was interrupted or errored - log but don't throw yet
-            if (this.config.debug) {
-                console.log(`[Orchestrator] Stream interrupted:`, streamError);
+            if (tailLoopTrigger !== null && !tailResampleUsed) {
+                // One bounded resample: re-issue the identical prepared request (fresh
+                // sample). The abandoned stream's finalMessage rejection is already
+                // caught above; re-point to the new stream.
+                tailResampleUsed = true;
+                console.warn(`[TailLoopGuard] xAI thinking loop detected (${tailLoopTrigger}) — resampling once`);
+                streamingResponse = this.apiClient.streamRequest(preparedRequest, effectiveModel);
+                finalMessageError = null;
+                streamingResponse.finalMessage.catch((err) => { finalMessageError = err; });
+                continue;
             }
+            break;
         }
         // 9. Get final accumulated message (SDK accumulates internally)
         // Only await finalMessage if stream completed normally
@@ -2676,7 +2803,7 @@ export class CortexOrchestrator {
             }, TOOL_TIMEOUT_MS);
             try {
                 // Execute tools (reuse existing method)
-                const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal);
+                const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal, structuredOutputState);
                 clearTimeout(timeoutId);
                 // R21 (2026-05-15): same fix as non-streaming path — count consecutive
                 // ITERATIONS WITH ZERO SUCCESSFUL TOOLS, not cumulative individual
@@ -2878,6 +3005,11 @@ export class CortexOrchestrator {
                 // Re-filter tools after SearchTools discovery (same as sendMessage path)
                 if (this.config.enableDeferredToolLoading && !isPTCEnabled) {
                     toolsToUse = this.toolFilter.getFilteredTools(allTools);
+                    // StructuredOutput: re-filter rebuilds from allTools — re-append the
+                    // request-scoped tool (same as the sendMessage continuation path).
+                    if (structuredOutputState) {
+                        toolsToUse = ensureStructuredOutputTool(toolsToUse, structuredOutputState);
+                    }
                 }
                 // Input-slicing for stateful Responses API (same logic as non-streaming path)
                 const streamCanSliceInput = this.lastResponseId !== null &&
@@ -3293,6 +3425,16 @@ export class CortexOrchestrator {
                 },
                 durationMs: Date.now() - turnStartMs,
                 toolCallIterations: toolCallIteration,
+                // StructuredOutput (grok-build port): streaming surface — present
+                // whenever the caller set options.jsonSchema.
+                ...(structuredOutputState
+                    ? { structuredOutput: finalizeStructuredOutput(structuredOutputState) }
+                    : {}),
+                // Served-model drift (2026-08-01): best-effort on streaming (the
+                // provider model field is present when the SDK final message carries it).
+                ...(convertedResponse?.servedModelDrift
+                    ? { servedModel: convertedResponse.servedModel, servedModelDrift: true }
+                    : {}),
             },
         };
         // Clean up ephemeral mentorship messages — they served their purpose during this turn
@@ -3469,7 +3611,7 @@ export class CortexOrchestrator {
     isMutationTool(toolName) {
         const mutationTools = new Set([
             'Write', 'Edit', 'NotebookEdit',
-            'TodoCreate', 'TodoUpdate', 'TodoWrite',
+            'TodoCreate', 'TodoUpdate',
             'Bash',
         ]);
         return mutationTools.has(toolName);
@@ -3999,6 +4141,10 @@ export class CortexOrchestrator {
      * - Preserves critical messages (tool calls, recent context)
      */
     async ensureHistoryFitsModel(model) {
+        // Capture the active model's context window for request-build-time
+        // pruning (pruneAgedForRequest) — set before any early return so the
+        // gate works even when compaction itself is disabled.
+        this.lastKnownContextWindow = model.limits?.contextWindow;
         // Skip if compaction disabled in config
         if (!this.config.autoCompact) {
             return;
@@ -4085,18 +4231,16 @@ export class CortexOrchestrator {
         const truncated = this.truncateToolOutput(toolOutput, MAX_TOOL_OUTPUT_TOKENS);
         const toolLower = toolName.toLowerCase();
         let toolSpecificHint = '';
-        if (toolLower === 'read' || toolLower === 'readfile') {
+        if (toolLower === 'read') {
             toolSpecificHint = `This file is too large to read ${MAX_TOOL_OUTPUT_TOKENS.toLocaleString()} tokens at once. ` +
                 `Re-read with limit: 500 (or smaller) and use offset to navigate to the section you need.\n\n`;
         }
         const guidanceMessage = `Tool result too large (~${estimatedTokens.toLocaleString()} tokens, limit ${MAX_TOOL_OUTPUT_TOKENS.toLocaleString()}).\n\n` +
             toolSpecificHint +
             `Please try a more targeted approach:\n` +
-            `• For read: Use limit: 500 (or smaller) with offset to read manageable chunks\n` +
-            `• For grep/rg: Add --max-count=100 or search specific paths\n` +
-            `• For find: Use -maxdepth N to limit recursion\n` +
-            `• For ls: Target specific directories instead of -R\n` +
-            `• For bash: Pipe to 'head -n 100' or use more specific filters\n\n` +
+            `• For Read: Use limit: 500 (or smaller) with offset to read manageable chunks\n` +
+            `• For Grep: Use head_limit (e.g. 100) or search specific paths\n` +
+            `• For Bash: pipe to 'head -n 100', use find -maxdepth N, and target specific directories instead of ls -R\n\n` +
             `Preview of truncated output (first/last portions shown):\n` +
             `${'='.repeat(70)}\n${truncated}\n${'='.repeat(70)}\n\n` +
             `If you cannot be more specific, acknowledge this and request the truncated output, ` +
@@ -4324,7 +4468,42 @@ export class CortexOrchestrator {
      * @param signal AbortSignal for cancellation
      * @returns Array of tool results
      */
-    async handleToolCalls(toolUseBlocks, signal) {
+    async handleToolCalls(toolUseBlocks, signal, structuredOutputState) {
+        // StructuredOutput (grok-build port): intercept BEFORE any dispatch — the
+        // synthetic tool is request-scoped (never in a registry) and must NEVER
+        // reach a real executor. Each call gets a synthesized tool_result:
+        // co-emission steering (other tools in the same round), corrective
+        // validation errors (bounded retries), or acceptance (valid or fail-open).
+        // Remaining tools are dispatched normally via recursion.
+        if (structuredOutputState && toolUseBlocks.some((t) => isStructuredOutputToolName(t.name))) {
+            const structuredCalls = toolUseBlocks.filter((t) => isStructuredOutputToolName(t.name));
+            const otherCalls = toolUseBlocks.filter((t) => !isStructuredOutputToolName(t.name));
+            // Co-emission = any other tool in the round, or multiple simultaneous
+            // StructuredOutput calls (it must be the single final action).
+            const hasOthersInRound = toolUseBlocks.length > 1;
+            const syntheticResults = [];
+            for (const call of structuredCalls) {
+                const decision = evaluateStructuredOutputCall(structuredOutputState.schema, call.input, structuredOutputState.attempts, hasOthersInRound);
+                structuredOutputState.attempts = decision.attemptsAfter;
+                if (decision.result) {
+                    structuredOutputState.result = decision.result;
+                }
+                if (this.config.debug) {
+                    console.log(`[Orchestrator] StructuredOutput call: accepted=${decision.accepted} ` +
+                        `attempts=${decision.attemptsAfter} coEmission=${hasOthersInRound}`);
+                }
+                syntheticResults.push({
+                    tool_use_id: call.id,
+                    tool_name: call.name,
+                    content: decision.toolResultText,
+                    is_error: decision.isError,
+                });
+            }
+            const otherResults = otherCalls.length > 0
+                ? await this.handleToolCalls(otherCalls, signal)
+                : [];
+            return [...otherResults, ...syntheticResults];
+        }
         const results = [];
         if (this.config.debug) {
             console.log(`[Orchestrator Phase 2.5] Executing ${toolUseBlocks.length} tool call(s)`);
@@ -6106,7 +6285,48 @@ export class CortexOrchestrator {
             return { ...fresh };
         });
         // Validate and repair any orphaned tool_use blocks (crash recovery)
-        return this.validateAndRepairMessages(converted);
+        const repaired = this.validateAndRepairMessages(converted);
+        // Age-tiered tool-result pruning on the outgoing request copy (all
+        // request-build call sites flow through here). No-op below the
+        // utilization gate; never touches the cache (pruner clones).
+        return this.pruneAgedForRequest(repaired);
+    }
+    /**
+     * Apply age-tiered tool-result pruning to an outgoing canonical request
+     * copy (grok-build port, 2026-08-01). Gated on estimated context
+     * utilization > 50% — below that, the identity function, so ordinary
+     * conversations keep byte-stable request prefixes for prompt caching. At
+     * high utilization the trade inverts: pruning old tool results is strictly
+     * gentler than the compaction it defers (which rewrites the whole history).
+     *
+     * The context window is captured by ensureHistoryFitsModel (which every
+     * request path calls before converting); when it has not run yet, this is
+     * a no-op.
+     */
+    pruneAgedForRequest(messages) {
+        const window = this.lastKnownContextWindow;
+        if (!window || window <= 0)
+            return messages;
+        let approxChars = 0;
+        for (const m of messages) {
+            for (const b of m.content) {
+                if (b.type === 'text' && b.text)
+                    approxChars += b.text.length;
+                else if (b.type === 'thinking' && b.thinking)
+                    approxChars += b.thinking.length;
+                else
+                    approxChars += JSON.stringify(b)?.length ?? 0;
+            }
+        }
+        const approxTokens = Math.ceil(approxChars / 4) + (this.currentToolTokens || 0);
+        if (approxTokens / window <= 0.5)
+            return messages;
+        const pruned = pruneAgedToolResults(messages);
+        if (pruned.prunedCount > 0 && this.config.debug) {
+            console.log(`[Orchestrator Context] Aged tool-result pruning: ${pruned.prunedCount} results, ` +
+                `~${pruned.savedChars} chars removed from request copy (history unchanged)`);
+        }
+        return pruned.messages;
     }
     /**
      * Pure conversion of a single Message to its CanonicalMessage form.
@@ -6557,7 +6777,7 @@ export class CortexOrchestrator {
                 lines.push(`- ${convert(d.name)} — ${firstSentence}`);
             }
         }
-        return `<harness-note source="automated-harness" from-user="false">\nThe following is automated context injected by the harness — NOT a message from the user. The tools below are available but their schemas are NOT loaded yet. To use any of them, call search_tools first to load the schema, then call the tool.\n${lines.join('\n')}\n</harness-note>`;
+        return `<harness-note source="automated-harness" from-user="false">\nThe following is automated context injected by the harness — NOT a message from the user. The tools below are available but their schemas are NOT loaded yet. To use any of them, call ${convert('SearchTools')} first to load the schema, then call the tool.\n${lines.join('\n')}\n</harness-note>`;
     }
 }
 //# sourceMappingURL=CortexOrchestrator.js.map