@namzu/sdk 36.0.0 → 38.0.0

package/dist/runtime/query/iteration/index.js

@@ -1,11 +1,13 @@
 import { SpanStatusCode } from '@opentelemetry/api';
 import { resolveContextWindow } from '../../../compaction/context-window.js';
-import { extractFromAssistantMessage } from '../../../compaction/extractor.js';
+import { extractFromAssistantMessage, extractFromUserMessage, } from '../../../compaction/extractor.js';
+import { estimateMessageTokens } from '../../../compaction/token-estimate.js';
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js';
 import { DEFAULT_STRUCTURED_OUTPUT_RETRIES, STRUCTURED_OUTPUT_REPROMPT, } from '../../../constants/tools/index.js';
 import { renderSkillsSection } from '../../../persona/assembler.js';
 import { resolveProviderCapabilities } from '../../../provider/capabilities.js';
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js';
+import { renderToolSchema } from '../../../registry/tool/schema.js';
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js';
 import { GENAI, NAMZU, agentIterationSpanName, parentContext, } from '../../../telemetry/attributes.js';
 import { getTracer } from '../../../telemetry/runtime-accessors.js';
@@ -17,12 +19,15 @@ import { classifyProviderError } from '../../../types/provider/errors.js';
 import { toErrorMessage } from '../../../utils/error.js';
 import { stableDigest } from '../../../utils/hash.js';
 import { generateMessageId } from '../../../utils/id.js';
+import { projectObservationContext } from '../observation-context.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
+import { diffRequestContext, snapshotRequestContext, } from '../request-context.js';
 import { DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES, markProviderRejectedImage, projectRequestRichContent, } from '../request-rich-content.js';
-import { formatSteeringNote } from '../steering.js';
+import { formatSteeringNote, isOperatorUserMessage } from '../steering.js';
+import { parseNativeCandidate } from './native-output.js';
 import { runAdvisoryPhase } from './phases/advisory.js';
 import { runIterationCheckpoint } from './phases/checkpoint.js';
-import { measureContext, relieveOverflow, runCompactionCheck } from './phases/compaction.js';
+import { activeContextWindow, measureContext, relieveOverflow, runCompactionCheck, } from './phases/compaction.js';
 import { runPlanGate } from './phases/plan.js';
 import { runToolReview } from './phases/tool-review.js';
 import { refreshWorkingMemory } from './phases/working-memory.js';
@@ -104,6 +109,13 @@ export class IterationOrchestrator {
      * one process must not suppress each other's first envelope.
      */
     lastEnvelopeKey;
+    previousRequestContext;
+    projectObservations(messages) {
+        const config = this.ctx.compactionConfig;
+        return config && config.strategy !== 'disabled' && config.deduplicateObservations !== false
+            ? projectObservationContext(messages, this.ctx.tools, config.preserveToolResultsFrom)
+            : messages;
+    }
     /** Rich tool blocks already reported; durable history is scanned every turn. */
     warnedRichToolResults = new Set();
     /**
@@ -121,8 +133,29 @@ export class IterationOrchestrator {
      * sets it.
      */
     stopDeferredForOutstandingWork = false;
+    /** One current input, independent of the compactable history array. */
+    latestUserMessage;
     constructor(ctx) {
-        this.ctx = ctx;
+        this.ctx = {
+            ...ctx,
+            onSteeringDelivered: (text) => {
+                this.rememberUserMessage(createRuntimeContextMessage(text, 'steering'));
+            },
+        };
+        ctx.checkpointMgr.setLatestUserMessageSource(() => this.latestUserMessage);
+        ctx.checkpointMgr.setStructuredReviewAttemptsSource?.(() => this.structuredReviewAttempts);
+        ctx.checkpointMgr.setNativeStructuredAttemptsSource?.(() => this.nativeStructuredAttempts);
+        if (ctx.structuredOutput?.mode === 'native') {
+            const limit = ctx.structuredOutput.maxRetries;
+            if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0))
+                throw new RangeError('Native structuredOutput.maxRetries must be a nonnegative safe integer');
+        }
+        if (ctx.structuredOutput?.mode !== undefined &&
+            !['tool', 'native'].includes(ctx.structuredOutput.mode))
+            throw new RangeError('Unknown structuredOutput.mode');
+        const maxReviews = ctx.structuredOutput?.maxReviews;
+        if (maxReviews !== undefined && (!Number.isSafeInteger(maxReviews) || maxReviews < 0))
+            throw new RangeError('structuredOutput.maxReviews must be a nonnegative safe integer');
     }
     /**
      * Check the exact post-budget request for tool-result shapes the active driver
@@ -198,6 +231,19 @@ export class IterationOrchestrator {
         const { runConfig, runMgr } = this.ctx;
         const { model } = runConfig;
         const tracer = getTracer();
+        // Resume hydration happens after construction, before the loop starts.
+        this.latestUserMessage = this.ctx.checkpointMgr.restoredLatestUserMessage;
+        this.structuredReviewAttempts = this.ctx.checkpointMgr.restoredStructuredReviewAttempts ?? 0;
+        this.nativeStructuredAttempts = this.ctx.checkpointMgr.restoredNativeStructuredAttempts ?? 0;
+        if (!this.latestUserMessage) {
+            for (const message of runMgr.messages)
+                this.rememberUserMessage(message, false);
+        }
+        // The restored field can outlive the historical message it describes.
+        // Only known post-checkpoint arrivals may supersede it, never an old
+        // retained user turn encountered while scanning restored history.
+        for (const message of this.ctx.resumedInput ?? [])
+            this.rememberUserMessage(message);
         // One context-overflow relief per *stuck point*, not per run.
         //
         // The latch exists so that a second overflow immediately after a
@@ -222,6 +268,22 @@ export class IterationOrchestrator {
         // no post-loop block reaches.
         try {
             while (true) {
+                if (this.ctx.abortController.signal.aborted) {
+                    runMgr.setStopReason('cancelled');
+                    runMgr.markCancelled();
+                    break;
+                }
+                if (this.ctx.structuredOutput?.mode === 'native' &&
+                    this.nativeStructuredAttempts > this.structuredOutputRetryLimit()) {
+                    runMgr.setStopReason('structured_output_failed');
+                    break;
+                }
+                if (this.ctx.structuredOutput?.review &&
+                    this.structuredReviewAttempts >
+                        (this.ctx.structuredOutput.maxReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)) {
+                    runMgr.setStopReason('answer_rejected');
+                    break;
+                }
                 // Read AND clear, in that order, in this one place.
                 //
                 // The flag is set by the previous iteration and read by this
@@ -265,6 +327,14 @@ export class IterationOrchestrator {
                 // run and been paid for; this is the seam a host with a live
                 // rate limit or a revoked tenant actually needs.
                 const veto = await this.beforeStep(runMgr.currentIteration + 1);
+                // The hook may settle because its run signal was aborted. Stop
+                // before interpreting that settlement as a policy refusal or
+                // counting an iteration that will never reach the provider.
+                if (this.ctx.abortController.signal.aborted) {
+                    runMgr.setStopReason('cancelled');
+                    runMgr.markCancelled();
+                    break;
+                }
                 if (veto) {
                     // Namespaced. The un-namespaced keys elsewhere in this file are
                     // the frozen inventory LOG-22 exists to drain; a new call site
@@ -354,10 +424,6 @@ export class IterationOrchestrator {
                     // compaction preserves). No-op when no provider is configured.
                     await refreshWorkingMemory(this.ctx);
                     await runCompactionCheck(this.ctx);
-                    // A context edit is a host-visible state transition, not a prelude
-                    // whose events may wait behind the next network call. In particular,
-                    // a slow or failing provider must not leave the host displaying the
-                    // pre-compaction context after Run.messages already shrank.
                     yield* this.ctx.drainPending();
                     // Cache discipline: keep the tools param byte-stable even on the
                     // forced-final iteration and forbid tool use via tool_choice
@@ -373,9 +439,22 @@ export class IterationOrchestrator {
                     // Shape this step before calling the model. `stopWhen` decides
                     // whether to keep going; this decides HOW. No-op when the host
                     // supplied no hook.
+                    const contextModelBeforePreparation = this.ctx.contextModel ?? model;
                     const step = await this.prepareStep(iterationNum);
+                    stepModel = step.model ?? model;
+                    await this.selectContextModel(stepModel);
+                    // Preserve post-compaction preparation/recall semantics. A changed
+                    // model needs a second check against its own window; never replay
+                    // host preparation effects merely to rebuild its request guidance.
+                    if (stepModel !== contextModelBeforePreparation)
+                        await runCompactionCheck(this.ctx);
+                    // Publish context edits before entering a possibly slow provider.
+                    yield* this.ctx.drainPending();
                     const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools;
-                    const llmTools = this.ctx.tools.toLLMTools(stepAllowedTools);
+                    const llmTools = this.ctx.tools
+                        .toLLMTools(stepAllowedTools)
+                        .filter((tool) => this.ctx.structuredOutput?.mode !== 'native' ||
+                        tool.function.name !== STRUCTURED_OUTPUT_TOOL_NAME);
                     // The same list the request was built from now also bounds what
                     // may run. Narrowing only the request left the restriction
                     // presentational — the model was shown fewer tools and could
@@ -438,7 +517,7 @@ export class IterationOrchestrator {
                     const requestHistory = stepPreamble
                         ? [...baseMessages, createSystemMessage(stepPreamble)]
                         : [...baseMessages];
-                    const messages = projectRequestRichContent(requestHistory, this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
+                    const messages = projectRequestRichContent(this.projectObservations(requestHistory), this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
                     await this.reportUnsupportedToolResults(messages);
                     yield* this.ctx.drainPending();
                     // What the model is about to be ASKED, recorded when it
@@ -482,6 +561,16 @@ export class IterationOrchestrator {
                         });
                     }
                     if (this.ctx.pluginManager) {
+                        const snapshot = snapshotRequestContext(messages);
+                        const context = Object.freeze({
+                            snapshot,
+                            ...(this.previousRequestContext
+                                ? {
+                                    change: diffRequestContext(this.previousRequestContext, snapshot),
+                                }
+                                : {}),
+                        });
+                        this.previousRequestContext = snapshot;
                         const hookResults = await this.ctx.pluginManager.executeHooks('pre_llm_call', {
                             runId: runMgr.id,
                             iteration: iterationNum,
@@ -489,6 +578,7 @@ export class IterationOrchestrator {
                             // Built inside the guard: a run with no plugins installed
                             // pays nothing for a projection nobody reads.
                             request: Object.freeze({
+                                context,
                                 model: stepModel,
                                 // Copied per turn, not handed over live: these are the
                                 // run's own message objects, and a hook writing into
@@ -531,6 +621,18 @@ export class IterationOrchestrator {
                     };
                     const { response, messageId } = yield* streamProviderTurn(this.ctx.provider, {
                         model: stepModel,
+                        ...(this.ctx.structuredOutput?.mode === 'native'
+                            ? {
+                                responseFormat: {
+                                    type: 'json_schema',
+                                    json_schema: {
+                                        name: 'structured_output',
+                                        schema: renderToolSchema(this.ctx.structuredOutput.schema),
+                                        strict: true,
+                                    },
+                                },
+                            }
+                            : {}),
                         providerRoute: requestedRoute,
                         messages,
                         tools: llmTools.length > 0 ? llmTools : undefined,
@@ -550,6 +652,7 @@ export class IterationOrchestrator {
                         cacheControl: { type: 'auto' },
                         ...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
                         ...(runConfig.effort ? { effort: runConfig.effort } : {}),
+                        ...(!forceFinalize && runConfig.webSearch ? { webSearch: runConfig.webSearch } : {}),
                         // Thread the run abort into the model call so a Stop tears the
                         // in-flight turn down (provider passes it to fetch; the consumer
                         // also races it). Inert when never aborted.
@@ -646,7 +749,7 @@ export class IterationOrchestrator {
                     const contextFigures = this.ctx.compactionConfig
                         ? (() => {
                             const measured = measureContext(this.ctx);
-                            const window = resolveContextWindow(this.ctx.compactionConfig?.contextWindowTokens, runConfig.model, this.ctx.providerContextWindow);
+                            const window = activeContextWindow(this.ctx);
                             return {
                                 contextTokens: measured.tokens,
                                 contextMeasuredBy: measured.source,
@@ -780,6 +883,60 @@ export class IterationOrchestrator {
                             usageBefore,
                             costBefore,
                         });
+                        if (this.ctx.structuredOutput?.mode === 'native') {
+                            const candidate = await parseNativeCandidate(this.ctx.structuredOutput.schema, response, this.ctx.abortController.signal);
+                            let outcome;
+                            if (candidate.success)
+                                outcome = await this.reviewStructuredOutput(candidate.value);
+                            else {
+                                this.nativeStructuredAttempts++;
+                                runMgr.pushMessage(createRuntimeContextMessage('Return a complete JSON value matching the supplied response schema. Do not continue a partial JSON fragment.', 'structured-output'));
+                                const checkpoint = await this.ctx.checkpointMgr.create(runMgr, iterationNum);
+                                await this.ctx.emitEvent({
+                                    type: 'checkpoint_created',
+                                    runId: runMgr.id,
+                                    checkpointId: checkpoint.id,
+                                    iteration: iterationNum,
+                                });
+                                outcome =
+                                    this.nativeStructuredAttempts > this.structuredOutputRetryLimit()
+                                        ? 'exhausted'
+                                        : 'retry';
+                            }
+                            await this.ctx.emitEvent({
+                                type: 'iteration_completed',
+                                runId: runMgr.id,
+                                iteration: iterationNum,
+                                hasToolCalls: false,
+                            });
+                            yield* this.ctx.drainPending();
+                            if (this.ctx.abortController.signal.aborted || outcome === 'cancelled') {
+                                runMgr.setStopReason('cancelled');
+                                runMgr.markCancelled();
+                                break;
+                            }
+                            if (outcome === 'accepted') {
+                                if (!forceFinalize) {
+                                    const changed = yield* this.holdForOutstandingWork(iterationNum, false);
+                                    const inbound = this.deliverInbound();
+                                    if (changed || inbound > 0)
+                                        continue;
+                                }
+                                if (this.ctx.abortController.signal.aborted) {
+                                    runMgr.setStopReason('cancelled');
+                                    runMgr.markCancelled();
+                                    break;
+                                }
+                                this.publishStructuredOutput();
+                                runMgr.setStopReason('end_turn');
+                                break;
+                            }
+                            if (outcome === 'exhausted') {
+                                runMgr.setStopReason(candidate.success ? 'answer_rejected' : 'structured_output_failed');
+                                break;
+                            }
+                            continue;
+                        }
                         const hasContent = response.message.content !== null && response.message.content.length > 0;
                         // Auto-continuation on `stop_reason: max_tokens`. The
                         // model hit its per-call output cap mid-text (NOT
@@ -862,6 +1019,11 @@ export class IterationOrchestrator {
                         // a loud stop rather than a loop.
                         if (!forceFinalize && this.ctx.reviewAnswer) {
                             const review = await this.reviewAnswer(response.message.content ?? '');
+                            if (this.ctx.abortController.signal.aborted) {
+                                runMgr.setStopReason('cancelled');
+                                runMgr.markCancelled();
+                                break;
+                            }
                             if (review && !review.accept) {
                                 const attempt = ++this.answerReviewAttempts;
                                 const limit = this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT;
@@ -988,12 +1150,34 @@ export class IterationOrchestrator {
                     // run ends here rather than paying for another turn whose only
                     // job would be to restate it — unless it shared its turn with
                     // other calls, which relays instead. See the method.
-                    if (this.captureStructuredOutput(reviewOutcome.results, response)) {
+                    const structuredOutcome = await this.captureStructuredOutput(reviewOutcome.results, response);
+                    if (structuredOutcome === 'retry' ||
+                        structuredOutcome === 'exhausted' ||
+                        structuredOutcome === 'cancelled') {
+                        await this.ctx.emitEvent({
+                            type: 'iteration_completed',
+                            runId: runMgr.id,
+                            iteration: iterationNum,
+                            hasToolCalls: true,
+                        });
+                        yield* this.ctx.drainPending();
+                        if (this.ctx.abortController.signal.aborted) {
+                            runMgr.setStopReason('cancelled');
+                            runMgr.markCancelled();
+                            break;
+                        }
+                        if (structuredOutcome === 'retry')
+                            continue;
+                        runMgr.setStopReason(structuredOutcome === 'cancelled' ? 'cancelled' : 'answer_rejected');
+                        if (structuredOutcome === 'cancelled')
+                            runMgr.markCancelled();
+                        break;
+                    }
+                    if (structuredOutcome === 'accepted') {
                         this.ctx.log.info('Structured output produced — ending run', {
                             [NAMZU.RUN_ID]: runMgr.id,
                             [NAMZU.ITERATION]: iterationNum,
                         });
-                        runMgr.setStopReason('end_turn');
                         await this.ctx.emitEvent({
                             type: 'iteration_completed',
                             runId: runMgr.id,
@@ -1001,6 +1185,13 @@ export class IterationOrchestrator {
                             hasToolCalls: true,
                         });
                         yield* this.ctx.drainPending();
+                        if (this.ctx.abortController.signal.aborted) {
+                            runMgr.setStopReason('cancelled');
+                            runMgr.markCancelled();
+                            break;
+                        }
+                        this.publishStructuredOutput();
+                        runMgr.setStopReason('end_turn');
                         break;
                     }
                     // A tool the author declared terminal settles the run with its
@@ -1406,18 +1597,39 @@ export class IterationOrchestrator {
      * message becomes the reason, so an operator is not left with a run
      * that stopped and no account of it.
      */
+    stepContext(stepNumber, prepared) {
+        const model = prepared.model ?? this.ctx.runConfig.model;
+        const window = resolveContextWindow(this.ctx.compactionConfig?.contextWindowTokens, model, model === this.ctx.runConfig.model
+            ? this.ctx.providerContextWindow
+            : model === this.ctx.contextModel
+                ? this.ctx.activeProviderContextWindow
+                : undefined);
+        const skills = prepared.skills ? renderSkillsSection([...prepared.skills]) : null;
+        const preamble = [prepared.system, skills].filter(Boolean).join('\n\n');
+        const preparedTokens = preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0;
+        const responseReserve = Math.min(prepared.maxResponseTokens ??
+            this.ctx.runConfig.maxResponseTokens ??
+            Math.floor(window.tokens / 4), Math.floor(window.tokens / 4));
+        return {
+            runId: this.ctx.runMgr.id,
+            stepNumber,
+            messages: this.ctx.runMgr.messages,
+            ...(this.latestUserMessage ? { latestUserMessage: this.latestUserMessage } : {}),
+            signal: this.ctx.abortController.signal,
+            contextBudget: {
+                windowTokens: window.tokens,
+                remainingTokens: Math.max(0, Math.floor(window.tokens - measureContext(this.ctx).tokens - preparedTokens - responseReserve)),
+            },
+            steps: this.steps,
+            prepared,
+        };
+    }
     async beforeStep(stepNumber) {
         const configured = this.ctx.beforeStep;
         if (!configured)
             return undefined;
         try {
-            return ((await configured({
-                runId: this.ctx.runMgr.id,
-                stepNumber,
-                messages: this.ctx.runMgr.messages,
-                steps: this.steps,
-                prepared: {},
-            })) ?? undefined);
+            return (await configured(this.stepContext(stepNumber, {}))) ?? undefined;
         }
         catch (err) {
             return { reason: `beforeStep threw: ${toErrorMessage(err)}` };
@@ -1435,15 +1647,10 @@ export class IterationOrchestrator {
         let result = {};
         for (const stage of stages) {
             try {
-                const decided = await stage({
-                    runId: this.ctx.runMgr.id,
-                    stepNumber,
-                    messages: this.ctx.runMgr.messages,
-                    steps: this.steps,
-                    prepared: result,
-                });
+                const decided = await stage(this.stepContext(stepNumber, result));
                 if (decided)
                     result = { ...result, ...decided };
+                await this.selectContextModel(result.model ?? this.ctx.runConfig.model);
             }
             catch (err) {
                 // Skipped, and the rest still run: one broken concern must
@@ -1498,6 +1705,17 @@ export class IterationOrchestrator {
         }
         return prepared;
     }
+    async selectContextModel(model) {
+        if (model !== (this.ctx.contextModel ?? this.ctx.runConfig.model)) {
+            // A measurement from another tokenizer cannot price the new request.
+            this.ctx.runMgr.clearLastPromptTokens();
+        }
+        this.ctx.contextModel = model;
+        this.ctx.activeProviderContextWindow =
+            model && model !== this.ctx.runConfig.model && !this.ctx.compactionConfig?.contextWindowTokens
+                ? await this.ctx.resolveModelContextWindow?.(model)
+                : undefined;
+    }
     /** Steps completed so far, exposed on the returned `Run`. */
     steps = [];
     getSteps() {
@@ -1524,16 +1742,32 @@ export class IterationOrchestrator {
      * empty drain must change nothing at all: a `continue` on nothing queued
      * spends an iteration and a model call to say the same thing again.
      */
+    rememberUserMessage(message, arriving = true) {
+        if (!isOperatorUserMessage(message))
+            return;
+        this.latestUserMessage = message;
+        // The hook field alone does not reach the model. Preserve arrivals in
+        // the compaction state too, before their original message or attached
+        // tool result can be shed. Initial history was already extracted at seed.
+        const manager = this.ctx.workingStateManager;
+        if (arriving && manager) {
+            extractFromUserMessage(manager, message.content, !manager.getState().task);
+        }
+    }
     deliverInbound() {
         const queued = this.ctx.inboundMessages?.() ?? [];
-        for (const message of queued)
+        for (const message of queued) {
             this.ctx.runMgr.pushMessage(message);
+            this.rememberUserMessage(message);
+        }
         // The steering channel's remainder. `attachSteering` already took
         // what it could carry on a tool result; anything still pending is
         // guidance from a turn that had no result to attach it to.
         const stranded = this.ctx.steering?.drain();
         if (stranded) {
-            this.ctx.runMgr.pushMessage(createRuntimeContextMessage(formatSteeringNote(stranded), 'steering'));
+            const message = createRuntimeContextMessage(formatSteeringNote(stranded), 'steering');
+            this.ctx.runMgr.pushMessage(message);
+            this.rememberUserMessage(createRuntimeContextMessage(stranded, 'steering'));
         }
         return queued.length + (stranded ? 1 : 0);
     }
@@ -1611,7 +1845,10 @@ export class IterationOrchestrator {
     }
     /** Turns spent asking the model again for a valid structured output. */
     structuredOutputAttempts = 0;
+    nativeStructuredAttempts = 0;
     structuredOutputDone = false;
+    pendingStructuredOutput;
+    structuredReviewAttempts = 0;
     structuredOutputRetryLimit() {
         return this.ctx.structuredOutput?.maxRetries ?? DEFAULT_STRUCTURED_OUTPUT_RETRIES;
     }
@@ -1632,6 +1869,8 @@ export class IterationOrchestrator {
      * avoid.
      */
     terminalToolOutput(results, response) {
+        if (this.ctx.structuredOutput?.mode === 'native')
+            return undefined;
         const terminal = results.filter((r) => this.ctx.tools.get(r.toolName)?.terminal === true);
         if (terminal.length === 0)
             return undefined;
@@ -1698,30 +1937,98 @@ export class IterationOrchestrator {
      * doing work, and it is the bound the neighbour relies on for the
      * identical pathology.
      */
-    captureStructuredOutput(results, response) {
-        if (!this.needsStructuredOutput())
-            return false;
+    async captureStructuredOutput(results, response) {
+        if (!this.needsStructuredOutput() || this.ctx.structuredOutput?.mode === 'native')
+            return 'absent';
         const hit = results.find((r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError);
         if (!hit)
-            return false;
+            return 'absent';
         const callCount = response.message.toolCalls?.length ?? 0;
         if (callCount > 1) {
             this.ctx.log.info('Structured output shared its turn — relaying instead of settling', {
                 [NAMZU.RUN_ID]: this.ctx.runMgr.id,
                 'namzu.runtime.calls_in_turn': callCount,
             });
-            return false;
+            return 'absent';
         }
+        let parsed;
         try {
-            this.ctx.runMgr.setStructuredOutput(JSON.parse(hit.output));
+            parsed = JSON.parse(hit.output);
         }
         catch {
             // The tool serializes its own validated input, so this is
             // unreachable in practice; keep the raw text rather than losing it.
-            this.ctx.runMgr.setStructuredOutput(hit.output);
+            if (this.ctx.structuredOutput?.review)
+                throw new Error('Structured review requires an intact JSON tool result; check tool-output limits and result transformations');
+            parsed = hit.output;
         }
+        return this.reviewStructuredOutput(parsed);
+    }
+    publishStructuredOutput() {
+        this.ctx.runMgr.setStructuredOutput(this.pendingStructuredOutput);
         this.structuredOutputDone = true;
-        return true;
+    }
+    async reviewStructuredOutput(parsed) {
+        if (this.ctx.abortController.signal.aborted)
+            return 'cancelled';
+        const reviewer = this.ctx.structuredOutput?.review;
+        if (reviewer) {
+            const signal = this.ctx.abortController.signal;
+            if (signal.aborted)
+                return 'cancelled';
+            let onAbort = () => { };
+            const aborted = new Promise((_resolve, reject) => {
+                onAbort = () => reject(signal.reason ?? new Error('Structured review cancelled'));
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+            let verdict;
+            try {
+                verdict = await Promise.race([
+                    Promise.resolve().then(() => reviewer(structuredClone(parsed), {
+                        runId: this.ctx.runMgr.id,
+                        iteration: this.ctx.runMgr.currentIteration,
+                        signal,
+                        messages: this.ctx.runMgr.messages,
+                    })),
+                    aborted,
+                ]);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return 'cancelled';
+                throw error;
+            }
+            finally {
+                signal.removeEventListener('abort', onAbort);
+            }
+            if (signal.aborted)
+                return 'cancelled';
+            if (!verdict || typeof verdict.accept !== 'boolean')
+                throw new Error('Structured reviewer returned an invalid verdict');
+            if (!verdict.accept) {
+                if (typeof verdict.feedback !== 'string' || verdict.feedback.trim().length === 0)
+                    throw new Error('Structured reviewer rejection requires feedback');
+                this.structuredReviewAttempts++;
+                this.ctx.runMgr.pushMessage(createRuntimeContextMessage(verdict.feedback, 'answer-review'));
+                // Persist both the feedback and its consumed allowance before the
+                // next request. This checkpoint is not an approval/park boundary.
+                const checkpoint = await this.ctx.checkpointMgr.create(this.ctx.runMgr, this.ctx.runMgr.currentIteration);
+                await this.ctx.emitEvent({
+                    type: 'checkpoint_created',
+                    runId: this.ctx.runMgr.id,
+                    checkpointId: checkpoint.id,
+                    iteration: this.ctx.runMgr.currentIteration,
+                });
+                if (signal.aborted)
+                    return 'cancelled';
+                return this.structuredReviewAttempts >
+                    (this.ctx.structuredOutput?.maxReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
+                    ? 'exhausted'
+                    : 'retry';
+            }
+        }
+        this.pendingStructuredOutput = parsed;
+        return 'accepted';
     }
     /**
      * Ask the host whether this answer is good enough.
@@ -1742,6 +2049,7 @@ export class IterationOrchestrator {
             return await this.ctx.reviewAnswer(answer, {
                 runId: this.ctx.runMgr.id,
                 iteration: this.ctx.runMgr.currentIteration,
+                signal: this.ctx.abortController.signal,
                 messages: this.ctx.runMgr.messages,
             });
         }
@@ -1801,6 +2109,8 @@ export class IterationOrchestrator {
         });
     }
     async requestFinalResponse(model, reason) {
+        if (this.ctx.structuredOutput?.mode === 'native')
+            return 'structured_output_failed';
         const lastAssistant = [...this.ctx.runMgr.messages]
             .reverse()
             .find((m) => m.role === 'assistant');
@@ -1823,7 +2133,7 @@ export class IterationOrchestrator {
                 ...this.ctx.runMgr.messages,
                 createRuntimeContextMessage(`[SYSTEM] Run is ending due to ${reason}. You MUST provide a final response now summarizing all your findings and work so far. Do not use any tools.`, 'limit-finalization'),
             ];
-            const finalMessages = projectRequestRichContent(finalHistory, this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
+            const finalMessages = projectRequestRichContent(this.projectObservations(finalHistory), this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES);
             await this.reportUnsupportedToolResults(finalMessages);
             // Same cache discipline as the forced-final iteration: keep the
             // tools param identical to prior iterations (cache prefix intact,