@namzu/sdk 35.0.0 → 37.0.0

package/src/runtime/query/iteration/index.ts

@@ -1,6 +1,10 @@
 import { type Span, 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,
@@ -9,6 +13,7 @@ import {
 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,
@@ -24,6 +29,7 @@ import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId } from '../../../types/ids/index.js'
 import {
 	type Message,
+	type UserMessage,
 	createAssistantMessage,
 	createRuntimeContextMessage,
 	createSystemMessage,
@@ -33,6 +39,7 @@ import { classifyProviderError } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
 import type { AnswerReview } from '../../../types/run/answer-review.js'
 import type {
+	PrepareStepContext,
 	PrepareStepResult,
 	RunEvent,
 	StepFailure,
@@ -54,10 +61,16 @@ import {
 	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 type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
@@ -168,9 +181,34 @@ export class IterationOrchestrator {
 	 * sets it.
 	 */
 	private stopDeferredForOutstandingWork = false
+	/** One current input, independent of the compactable history array. */
+	private latestUserMessage: UserMessage | undefined
 
 	constructor(ctx: IterationContext) {
-		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')
 	}
 
 	/**
@@ -252,6 +290,17 @@ 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.
 		//
@@ -278,6 +327,26 @@ 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
@@ -325,6 +394,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
@@ -431,10 +508,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
@@ -452,10 +525,25 @@ 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
@@ -632,6 +720,18 @@ export class IterationOrchestrator {
 						this.ctx.provider,
 						{
 							model: stepModel,
+							...(this.ctx.structuredOutput?.mode === 'native'
+								? {
+										responseFormat: {
+											type: 'json_schema' as const,
+											json_schema: {
+												name: 'structured_output',
+												schema: renderToolSchema(this.ctx.structuredOutput.schema),
+												strict: true,
+											},
+										},
+									}
+								: {}),
 							providerRoute: requestedRoute,
 							messages,
 							tools: llmTools.length > 0 ? llmTools : undefined,
@@ -771,11 +871,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,
@@ -932,6 +1028,70 @@ export class IterationOrchestrator {
 							costBefore,
 						})
 
+						if (this.ctx.structuredOutput?.mode === 'native') {
+							const candidate = await parseNativeCandidate(
+								this.ctx.structuredOutput.schema,
+								response,
+								this.ctx.abortController.signal,
+							)
+							let outcome: 'accepted' | 'retry' | 'exhausted' | 'cancelled'
+							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
 
@@ -1022,6 +1182,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
@@ -1159,12 +1324,39 @@ 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,
@@ -1172,6 +1364,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
 					}
 
@@ -1450,9 +1649,9 @@ export class IterationOrchestrator {
 	/**
 	 * Hold the run open for a worker that has not finished, and deliver it.
 	 *
-	 * Returns whether a completion arrived and was put in the transcript — the
-	 * caller continues the loop on `true`, so the model gets a turn in which to
-	 * USE the result. That turn is the entire justification for waiting, which
+	 * Returns whether a completion or operator message entered the transcript —
+	 * the caller continues on `true`, so the model gets a turn to respond.
+	 * That turn is the entire justification for waiting, which
 	 * is why only the exits that can still take one call this.
 	 *
 	 * Bounded by `settleGraceMs` and by `maxIterations`, so a worker that never
@@ -1473,14 +1672,34 @@ export class IterationOrchestrator {
 			[NAMZU.ITERATION]: iterationNum,
 			'namzu.runtime.grace_ms': graceMs,
 		})
-		await this.ctx.completionInbox.waitForArrival(graceMs)
+		// User input releases this wait without cancelling any child. Both waits
+		// share a disposable signal so the losing arrival listener cannot leak.
+		const waiting = new AbortController()
+		const runSignal = this.ctx.abortController.signal
+		const cancelWait = () => waiting.abort(runSignal.reason)
+		runSignal.addEventListener('abort', cancelWait, { once: true })
+		if (runSignal.aborted) cancelWait()
+		try {
+			await Promise.race([
+				this.ctx.completionInbox.waitForArrival(graceMs, waiting.signal),
+				...(this.ctx.waitForInbound ? [this.ctx.waitForInbound(waiting.signal)] : []),
+			])
+		} catch (error) {
+			if (!runSignal.aborted) throw error
+		} finally {
+			waiting.abort()
+			runSignal.removeEventListener('abort', cancelWait)
+		}
+		runSignal.throwIfAborted()
 
 		const arrived = this.ctx.completionInbox.drain()
-		if (arrived.length === 0) return false
-
-		this.ctx.runMgr.pushMessage(
-			createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
-		)
+		if (arrived.length > 0) {
+			this.ctx.runMgr.pushMessage(
+				createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
+			)
+		}
+		const inbound = this.deliverInbound()
+		if (arrived.length === 0 && inbound === 0) return false
 		await this.ctx.emitEvent({
 			type: 'iteration_completed',
 			runId: this.ctx.runMgr.id,
@@ -1583,19 +1802,51 @@ export class IterationOrchestrator {
 	 * message becomes the reason, so an operator is not left with a run
 	 * that stopped and no account of it.
 	 */
+	private stepContext(stepNumber: number, prepared: PrepareStepResult): PrepareStepContext {
+		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,
+		}
+	}
+
 	private async beforeStep(stepNumber: number): Promise<StepVeto | undefined> {
 		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)}` }
 		}
@@ -1621,14 +1872,9 @@ export class IterationOrchestrator {
 		let result: PrepareStepResult = {}
 		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
 				// not silently disable the others it was declared beside.
@@ -1690,6 +1936,18 @@ export class IterationOrchestrator {
 		return prepared
 	}
 
+	private async selectContextModel(model: string | undefined): Promise<void> {
+		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`. */
 	private readonly steps: StepResult[] = []
 
@@ -1718,18 +1976,33 @@ 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.
 	 */
+	private rememberUserMessage(message: Message, arriving = true): void {
+		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)
+		}
+	}
+
 	private deliverInbound(): number {
 		const queued = this.ctx.inboundMessages?.() ?? []
-		for (const message of queued) this.ctx.runMgr.pushMessage(message)
+		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)
@@ -1836,7 +2109,10 @@ export class IterationOrchestrator {
 
 	/** Turns spent asking the model again for a valid structured output. */
 	private structuredOutputAttempts = 0
+	private nativeStructuredAttempts = 0
 	private structuredOutputDone = false
+	private pendingStructuredOutput: unknown
+	private structuredReviewAttempts = 0
 
 	private structuredOutputRetryLimit(): number {
 		return this.ctx.structuredOutput?.maxRetries ?? DEFAULT_STRUCTURED_OUTPUT_RETRIES
@@ -1863,6 +2139,7 @@ export class IterationOrchestrator {
 		results: readonly ToolCallOutcome[],
 		response: ChatCompletionResponse,
 	): ToolCallOutcome | undefined {
+		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
 
@@ -1931,13 +2208,14 @@ export class IterationOrchestrator {
 	 * doing work, and it is the bound the neighbour relies on for the
 	 * identical pathology.
 	 */
-	private captureStructuredOutput(
+	private async captureStructuredOutput(
 		results: readonly ToolCallOutcome[],
 		response: ChatCompletionResponse,
-	): boolean {
-		if (!this.needsStructuredOutput()) return false
+	): Promise<'absent' | 'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
+		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
+		if (!hit) return 'absent'
 
 		const callCount = response.message.toolCalls?.length ?? 0
 		if (callCount > 1) {
@@ -1945,18 +2223,90 @@ export class IterationOrchestrator {
 				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
 				'namzu.runtime.calls_in_turn': callCount,
 			})
-			return false
+			return 'absent'
 		}
 
+		let parsed: unknown
 		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)
+	}
+
+	private publishStructuredOutput(): void {
+		this.ctx.runMgr.setStructuredOutput(this.pendingStructuredOutput)
 		this.structuredOutputDone = true
-		return true
+	}
+
+	private async reviewStructuredOutput(
+		parsed: unknown,
+	): Promise<'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
+		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: () => void = () => {}
+			const aborted = new Promise<never>((_resolve, reject) => {
+				onAbort = () => reject(signal.reason ?? new Error('Structured review cancelled'))
+				signal.addEventListener('abort', onAbort, { once: true })
+			})
+			let verdict: AnswerReview
+			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'
 	}
 
 	/**
@@ -1977,6 +2327,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,
 			})
 		} catch (err) {
@@ -2039,6 +2390,8 @@ export class IterationOrchestrator {
 		model: string,
 		reason: StopReason,
 	): Promise<StopReason | undefined> {
+		if (this.ctx.structuredOutput?.mode === 'native') return 'structured_output_failed'
+
 		const lastAssistant = [...this.ctx.runMgr.messages]
 			.reverse()
 			.find((m) => m.role === 'assistant')