@namzu/sdk 27.0.0 → 28.0.0

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

@@ -6,9 +6,9 @@ import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
-import { formatCompletionNotification } from '../../../gateway/completion-inbox.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
-import { collect } from '../../../provider/collect.js'
+import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
+import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import {
 	GENAI,
 	NAMZU,
@@ -35,14 +35,17 @@ import type {
 	StepFailure,
 	StepProvenance,
 	StepResult,
+	StepVeto,
 	StopReason,
 } from '../../../types/run/index.js'
 import type { Skill } from '../../../types/skills/index.js'
 import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
+import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
+import { formatSteeringNote } from '../steering.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
 import { measureContext, relieveOverflow, runCompactionCheck } from './phases/compaction.js'
@@ -132,6 +135,12 @@ export class IterationOrchestrator {
 	private ctx: IterationContext
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
 	private answerReviewAttempts = 0
+	/**
+	 * The last request envelope this run recorded, so an unchanged one
+	 * costs a hash and no event. Per RUNNER, not module-level: two runs in
+	 * one process must not suppress each other's first envelope.
+	 */
+	private lastEnvelopeKey: string | undefined
 	/**
 	 * The previous iteration held a `stopWhen` decision open for a worker.
 	 *
@@ -211,7 +220,7 @@ export class IterationOrchestrator {
 
 				if (guardResult.shouldStop) {
 					if (guardResult.isCancelled) {
-						this.ctx.log.info('Run cancelled by signal', { runId: runMgr.id })
+						this.ctx.log.info('Run cancelled by signal', { [NAMZU.RUN_ID]: runMgr.id })
 						runMgr.setStopReason('cancelled')
 						runMgr.markCancelled()
 						break
@@ -219,11 +228,11 @@ export class IterationOrchestrator {
 
 					const stopReason = guardResult.stopReason ?? 'end_turn'
 					this.ctx.log.info('Guard enforcing stop', {
-						runId: runMgr.id,
-						stopReason,
-						iteration: runMgr.currentIteration,
-						inputTokens: runMgr.tokenUsage.promptTokens,
-						outputTokens: runMgr.tokenUsage.completionTokens,
+						[NAMZU.RUN_ID]: runMgr.id,
+						'namzu.runtime.stop_reason': stopReason,
+						[NAMZU.ITERATION]: runMgr.currentIteration,
+						'namzu.runtime.input_tokens': runMgr.tokenUsage.promptTokens,
+						'namzu.runtime.output_tokens': runMgr.tokenUsage.completionTokens,
 					})
 					await this.requestFinalResponse(model, stopReason)
 					yield* this.ctx.drainPending()
@@ -231,14 +240,34 @@ export class IterationOrchestrator {
 					break
 				}
 
+				// Consulted here, after the guard and BEFORE the iteration is
+				// counted or the provider is called. `stopWhen` reads `steps`
+				// and so can only speak after the step it disliked has already
+				// 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)
+				if (veto) {
+					// Namespaced. The un-namespaced keys elsewhere in this file are
+					// the frozen inventory LOG-22 exists to drain; a new call site
+					// has no reason to join it.
+					this.ctx.log.info('Step refused by beforeStep', {
+						[NAMZU.RUN_ID]: runMgr.id,
+						[NAMZU.ITERATION]: runMgr.currentIteration + 1,
+						'namzu.step.veto_reason': veto.reason,
+					})
+					runMgr.setLastError(`beforeStep refused the next step: ${veto.reason}`)
+					runMgr.setStopReason('step_refused')
+					break
+				}
+
 				const forceFinalize = guardResult.forceFinalize
 				const iterationNum = runMgr.incrementIteration()
 				this.ctx.log.debug('Iteration started', {
-					runId: runMgr.id,
-					iteration: iterationNum,
-					model,
-					forceFinalize,
-					messageCount: runMgr.messages.length,
+					[NAMZU.RUN_ID]: runMgr.id,
+					[NAMZU.ITERATION]: iterationNum,
+					[GENAI.REQUEST_MODEL]: model,
+					'namzu.runtime.force_finalize': forceFinalize,
+					'namzu.runtime.message_count': runMgr.messages.length,
 				})
 
 				const iterationActivity = this.ctx.activityStore.create({
@@ -376,11 +405,79 @@ export class IterationOrchestrator {
 					// there is no length check here — a second guard for the same
 					// case is one more thing to keep in agreement with the first.
 					const stepSkills = step.skills ? renderSkillsSection([...step.skills]) : null
-					const stepPreamble = [step.system, stepSkills].filter(Boolean).join('\n\n')
+					// A supervision change rides the same ephemeral slot, and for
+					// the same reason: it applies to what happens next, not to the
+					// run's history. The model plans around how closely it is being
+					// watched — a run that silently stops asking a human leaves it
+					// batching destructive calls it expects to be reviewed, and one
+					// that silently starts leaves it waiting on permission nobody
+					// is left to give.
+					//
+					// Read-and-CLEAR, so it is said exactly once. Repeating it
+					// every iteration would read as supervision moving again on
+					// each turn.
+					const policyChange = this.ctx.takeApprovalPolicyChange?.()
+					const policyNotice = policyChange
+						? `Approval policy changed from "${policyChange.from}" to "${policyChange.to}" (${policyChange.reason}). Tool calls from here on are reviewed under the new policy.`
+						: null
+					// State that changed during the run, reported once per turn.
+					// `turn` contributions land HERE and nowhere else: in the
+					// system prompt they would be cached for the run or read as
+					// a standing instruction, and either way the state they
+					// exist to report goes stale silently.
+					const turnSections =
+						this.ctx.promptContributions?.render('turn', { iteration: iterationNum }) ?? []
+
+					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
+						.filter(Boolean)
+						.join('\n\n')
 					const messages = stepPreamble
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
 
+					// What the model is about to be ASKED, recorded when it
+					// changed. `run_started` carries one system prompt and tool
+					// schemas never reached the transcript at all — while
+					// `prepareStep` rewrites the system text, narrows the tool
+					// list or swaps the model, and a step's skills ride the
+					// ephemeral preamble above. So a transcript showed one
+					// question for a run that had asked several.
+					//
+					// Emitted only on a change: the digest is compared against
+					// the last one this run recorded, so the common case costs
+					// one hash and nothing else. Copying an unchanged system
+					// prompt every iteration is the fastest way to make a
+					// durable log too large to read.
+					const envelope = {
+						model: stepModel,
+						// Read off `messages`, which is what the request is actually
+						// built from — including the ephemeral preamble. Recomputing
+						// it from the run's history would describe a request nobody
+						// sent the moment the two diverge.
+						systemPrompt: messages
+							.filter((m) => m.role === 'system')
+							.map((m) => String(m.content))
+							.join('\n\n'),
+						toolNames: llmTools.map((t) => t.function.name),
+						// Over the SCHEMAS, sorted. A name list cannot see a tool
+						// whose schema body changed while its name did not, which
+						// is the change most likely to alter what the model does.
+						toolSchemaDigest: stableDigest(
+							[...llmTools].sort((a, b) => (a.function.name < b.function.name ? -1 : 1)),
+						),
+					}
+					const envelopeKey = stableDigest(envelope)
+					if (envelopeKey !== this.lastEnvelopeKey) {
+						this.lastEnvelopeKey = envelopeKey
+						await this.ctx.emitEvent?.({
+							type: 'request_envelope',
+							runId: runMgr.id,
+							iteration: iterationNum,
+							...envelope,
+							toolNames: Object.freeze([...envelope.toolNames]),
+						})
+					}
+
 					if (this.ctx.pluginManager) {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'pre_llm_call',
@@ -537,15 +634,16 @@ export class IterationOrchestrator {
 					}
 
 					this.ctx.log.debug('LLM response received', {
-						runId: runMgr.id,
-						iteration: iterationNum,
-						finishReason: response.finishReason,
-						hasContent: response.message.content !== null && response.message.content.length > 0,
-						toolCallCount: response.message.toolCalls?.length ?? 0,
-						promptTokens: response.usage.promptTokens,
-						completionTokens: response.usage.completionTokens,
-						totalTokens: runMgr.tokenUsage.totalTokens,
-						totalCost: runMgr.costInfo.totalCost,
+						[NAMZU.RUN_ID]: runMgr.id,
+						[NAMZU.ITERATION]: iterationNum,
+						'namzu.runtime.finish_reason': response.finishReason,
+						'namzu.runtime.has_content':
+							response.message.content !== null && response.message.content.length > 0,
+						'namzu.runtime.tool_call_count': response.message.toolCalls?.length ?? 0,
+						[GENAI.USAGE_INPUT_TOKENS]: response.usage.promptTokens,
+						[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
+						'namzu.usage.total_tokens': runMgr.tokenUsage.totalTokens,
+						'namzu.runtime.total_cost': runMgr.costInfo.totalCost,
 					})
 
 					// The context figures ride with the spend figures because a
@@ -564,6 +662,7 @@ export class IterationOrchestrator {
 								const window = resolveContextWindow(
 									this.ctx.compactionConfig?.contextWindowTokens,
 									runConfig.model,
+									this.ctx.providerContextWindow,
 								)
 								return {
 									contextTokens: measured.tokens,
@@ -651,8 +750,8 @@ export class IterationOrchestrator {
 							this.ctx.log.warn(
 								'LLM ended turn with agent tasks still running — ending run without waiting (orphan tasks have no delivery path)',
 								{
-									runId: runMgr.id,
-									iteration: iterationNum,
+									[NAMZU.RUN_ID]: runMgr.id,
+									[NAMZU.ITERATION]: iterationNum,
 								},
 							)
 						}
@@ -737,9 +836,9 @@ export class IterationOrchestrator {
 						//   - max_iterations bounds the loop in any case.
 						if (!forceFinalize && response.finishReason === 'length' && hasContent) {
 							this.ctx.log.info('LLM hit max_tokens mid-text — auto-continuing', {
-								runId: runMgr.id,
-								iteration: iterationNum,
-								completionTokens: response.usage.completionTokens,
+								[NAMZU.RUN_ID]: runMgr.id,
+								[NAMZU.ITERATION]: iterationNum,
+								[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
 							})
 							runMgr.pushMessage(createUserMessage(AUTO_CONTINUATION_USER_MESSAGE))
 							await this.ctx.emitEvent({
@@ -762,16 +861,16 @@ export class IterationOrchestrator {
 							const limit = this.structuredOutputRetryLimit()
 							if (attempt > limit) {
 								this.ctx.log.warn('Structured output not produced within its retries', {
-									runId: runMgr.id,
-									attempts: attempt - 1,
+									[NAMZU.RUN_ID]: runMgr.id,
+									'namzu.runtime.attempts': attempt - 1,
 								})
 								runMgr.setStopReason('structured_output_failed')
 								break
 							}
 							this.ctx.log.info('Re-prompting for structured output', {
-								runId: runMgr.id,
-								attempt,
-								limit,
+								[NAMZU.RUN_ID]: runMgr.id,
+								'namzu.retry.attempt': attempt,
+								'namzu.runtime.limit': limit,
 							})
 							runMgr.pushMessage(createUserMessage(STRUCTURED_OUTPUT_REPROMPT))
 							await this.ctx.emitEvent({
@@ -804,17 +903,17 @@ export class IterationOrchestrator {
 								const limit = this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT
 								if (attempt > limit) {
 									this.ctx.log.warn('Answer rejected more times than the run allows', {
-										runId: runMgr.id,
-										attempts: attempt - 1,
-										limit,
+										[NAMZU.RUN_ID]: runMgr.id,
+										'namzu.runtime.attempts': attempt - 1,
+										'namzu.runtime.limit': limit,
 									})
 									runMgr.setStopReason('answer_rejected')
 									break
 								}
 								this.ctx.log.info('Answer rejected — returning it to the model', {
-									runId: runMgr.id,
-									attempt,
-									limit,
+									[NAMZU.RUN_ID]: runMgr.id,
+									'namzu.retry.attempt': attempt,
+									'namzu.runtime.limit': limit,
 								})
 								runMgr.pushMessage(createUserMessage(review.feedback))
 								await this.ctx.emitEvent({
@@ -838,10 +937,30 @@ export class IterationOrchestrator {
 							continue
 						}
 
+						// Anything queued while this turn ran, on the path where
+						// there is no tool result to carry it. Without this the
+						// run settles with the channel still pending — which is
+						// the failure the steering channel's own test used to
+						// PIN as correct behaviour.
+						//
+						// After the outstanding-work hold above, so a delivery
+						// does not race a worker still finishing, and before the
+						// settle below, which is the last moment it can matter.
+						if (!forceFinalize && this.deliverInbound() > 0) {
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								runId: runMgr.id,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							continue
+						}
+
 						if (!hasContent && !forceFinalize) {
 							this.ctx.log.warn('Empty completion detected — requesting final summary', {
-								iteration: iterationNum,
-								finishReason: response.finishReason,
+								[NAMZU.ITERATION]: iterationNum,
+								'namzu.runtime.finish_reason': response.finishReason,
 							})
 							await this.requestFinalResponse(model, 'end_turn')
 							yield* this.ctx.drainPending()
@@ -914,8 +1033,8 @@ export class IterationOrchestrator {
 					// other calls, which relays instead. See the method.
 					if (this.captureStructuredOutput(reviewOutcome.results, response)) {
 						this.ctx.log.info('Structured output produced — ending run', {
-							runId: runMgr.id,
-							iteration: iterationNum,
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
 						})
 						runMgr.setStopReason('end_turn')
 						await this.ctx.emitEvent({
@@ -938,9 +1057,9 @@ export class IterationOrchestrator {
 					const settled = this.terminalToolOutput(reviewOutcome.results, response)
 					if (settled !== undefined) {
 						this.ctx.log.info('Terminal tool produced the answer — ending run', {
-							runId: runMgr.id,
-							iteration: iterationNum,
-							tool: settled.toolName,
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
+							[GENAI.TOOL_NAME]: settled.toolName,
 						})
 						runMgr.setResult(settled.output)
 						runMgr.setStopReason('end_turn')
@@ -984,8 +1103,8 @@ export class IterationOrchestrator {
 						}
 
 						this.ctx.log.info('Stop condition met', {
-							runId: runMgr.id,
-							iteration: iterationNum,
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
 						})
 						runMgr.setStopReason('stop_condition')
 						await this.ctx.emitEvent({
@@ -1025,13 +1144,19 @@ export class IterationOrchestrator {
 					const unheard = this.ctx.completionInbox?.drain() ?? []
 					if (unheard.length > 0) {
 						this.ctx.log.info('Delivering unawaited task completions', {
-							runId: runMgr.id,
-							iteration: iterationNum,
-							tasks: unheard.map((h) => h.taskId),
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
+							'namzu.runtime.tasks': unheard.map((h) => h.taskId),
 						})
 						runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
 					}
 
+					// The same seam, for the two channels that could accept text
+					// and never deliver it. Placed here rather than at the top of
+					// the next iteration so a message queued during THIS turn is
+					// in the history the next request is built from.
+					this.deliverInbound()
+
 					await runAdvisoryPhase(this.ctx, iterationNum, response)
 
 					if (this.ctx.pluginManager) {
@@ -1092,9 +1217,9 @@ export class IterationOrchestrator {
 					// followed it reaches the caller as the run's error.
 					if (this.steps.at(-1)?.stepNumber === iterationNum) {
 						this.ctx.log.warn('Iteration failed after its step was already recorded', {
-							runId: runMgr.id,
-							iteration: iterationNum,
-							error: toErrorMessage(err),
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
+							'exception.message': toErrorMessage(err),
 						})
 					} else {
 						this.recordStep({
@@ -1155,8 +1280,8 @@ export class IterationOrchestrator {
 						const shed = await relieveOverflow(this.ctx)
 						if (shed) {
 							this.ctx.log.info('Retrying the turn after relieving a context overflow', {
-								runId: runMgr.id,
-								iteration: iterationNum,
+								[NAMZU.RUN_ID]: runMgr.id,
+								[NAMZU.ITERATION]: iterationNum,
 							})
 							if (iterationActivity) {
 								this.ctx.activityStore.complete(iterationActivity.id)
@@ -1210,9 +1335,9 @@ export class IterationOrchestrator {
 		// must not open a wait against a reserve it has already entered.
 		const graceMs = settleGraceMs(this.ctx.guard.remainingBeforeFinalizeMs())
 		this.ctx.log.info('Holding the run open for a background task', {
-			runId: this.ctx.runMgr.id,
-			iteration: iterationNum,
-			graceMs,
+			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			[NAMZU.ITERATION]: iterationNum,
+			'namzu.runtime.grace_ms': graceMs,
 		})
 		await this.ctx.completionInbox.waitForArrival(graceMs)
 
@@ -1265,8 +1390,8 @@ export class IterationOrchestrator {
 		if (abandoned.length === 0) return
 
 		this.ctx.log.warn('Run ended with delegated work still running', {
-			runId: this.ctx.runMgr.id,
-			tasks: abandoned,
+			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			'namzu.runtime.tasks': abandoned,
 		})
 		this.ctx.runMgr.setAbandonedTaskIds(abandoned)
 	}
@@ -1295,8 +1420,8 @@ export class IterationOrchestrator {
 		if (answer.length > 0) this.ctx.runMgr.setResult(answer)
 
 		this.ctx.log.info('Delivering task completions the run would have settled over', {
-			runId: this.ctx.runMgr.id,
-			tasks: unheard.map((h) => h.taskId),
+			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			'namzu.runtime.tasks': unheard.map((h) => h.taskId),
 		})
 		this.ctx.runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
 	}
@@ -1309,6 +1434,35 @@ export class IterationOrchestrator {
 	 * otherwise healthy run, and unlike a safety check, nothing unsafe gets
 	 * through when it is skipped.
 	 */
+	/**
+	 * A host's chance to refuse the next model call.
+	 *
+	 * Fails CLOSED, which is the opposite of `prepareStep` below and the
+	 * reason they are separate hooks rather than one with two return
+	 * shapes. A broken step-SHAPER skipped costs a run its per-step tuning;
+	 * a broken step-REFUSER skipped is a refusal that did not happen, which
+	 * is precisely what the hook exists to prevent. The thrown error's
+	 * message becomes the reason, so an operator is not left with a run
+	 * that stopped and no account of it.
+	 */
+	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
+			)
+		} catch (err) {
+			return { reason: `beforeStep threw: ${toErrorMessage(err)}` }
+		}
+	}
+
 	private async prepareStep(stepNumber: number): Promise<{
 		allowedTools?: string[]
 		toolChoice?: ToolChoice
@@ -1341,9 +1495,9 @@ export class IterationOrchestrator {
 				// Skipped, and the rest still run: one broken concern must
 				// not silently disable the others it was declared beside.
 				this.ctx.log.error('a prepareStep stage threw — skipping it', {
-					runId: this.ctx.runMgr.id,
-					stepNumber,
-					error: toErrorMessage(err),
+					[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+					'namzu.runtime.step_number': stepNumber,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -1378,10 +1532,10 @@ export class IterationOrchestrator {
 						? 'prepareStep named only tools that are not registered — this step can call nothing'
 						: 'prepareStep named tools that are not registered — ignoring them'
 				this.ctx.log.warn(message, {
-					runId: this.ctx.runMgr.id,
-					stepNumber,
-					unknown,
-					remaining: known.length,
+					[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+					'namzu.runtime.step_number': stepNumber,
+					'namzu.runtime.unknown': unknown,
+					'namzu.runtime.remaining': known.length,
 				})
 			}
 			prepared.allowedTools = known
@@ -1413,6 +1567,34 @@ export class IterationOrchestrator {
 	 * ITS usage rather than the run's running total, which is the number a
 	 * caller asking "what did this step cost" actually wants.
 	 */
+	/**
+	 * Take everything queued for this run since the last turn.
+	 *
+	 * Both channels drain here. `inboundMessages` is the manager's queue —
+	 * what `continueTask` and `queueMessage` push onto and nothing ever
+	 * collected. `steering` is the host's, and it could only ride on a tool
+	 * result, so guidance queued during a turn that called no tools stayed
+	 * pending until the run ended.
+	 *
+	 * Returns the count so a caller can decide whether a turn is owed. An
+	 * 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 deliverInbound(): number {
+		const queued = this.ctx.inboundMessages?.() ?? []
+		for (const message of queued) this.ctx.runMgr.pushMessage(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(createUserMessage(formatSteeringNote(stranded)))
+		}
+
+		return queued.length + (stranded ? 1 : 0)
+	}
+
 	private recordStep(input: {
 		stepNumber: number
 		model: string
@@ -1505,9 +1687,9 @@ export class IterationOrchestrator {
 			this.ctx.onStepFinish?.(step)
 		} catch (err) {
 			this.ctx.log.warn('onStepFinish threw while recording a failed step', {
-				runId: runMgr.id,
-				step: input.stepNumber,
-				error: toErrorMessage(err),
+				[NAMZU.RUN_ID]: runMgr.id,
+				'namzu.runtime.step': input.stepNumber,
+				'exception.message': toErrorMessage(err),
 			})
 		}
 	}
@@ -1547,9 +1729,9 @@ export class IterationOrchestrator {
 		const callCount = response.message.toolCalls?.length ?? 0
 		if (callCount > 1) {
 			this.ctx.log.info('Terminal tool shared its turn — relaying instead of settling', {
-				runId: this.ctx.runMgr.id,
-				tool: terminal[0]?.toolName,
-				callsInTurn: callCount,
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				[GENAI.TOOL_NAME]: terminal[0]?.toolName,
+				'namzu.runtime.calls_in_turn': callCount,
 			})
 			return undefined
 		}
@@ -1557,8 +1739,8 @@ export class IterationOrchestrator {
 		const hit = terminal[0]
 		if (!hit || hit.isError) {
 			this.ctx.log.info('Terminal tool failed — returning the error to the model', {
-				runId: this.ctx.runMgr.id,
-				tool: hit?.toolName,
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				[GENAI.TOOL_NAME]: hit?.toolName,
 			})
 			return undefined
 		}
@@ -1620,8 +1802,8 @@ export class IterationOrchestrator {
 		const callCount = response.message.toolCalls?.length ?? 0
 		if (callCount > 1) {
 			this.ctx.log.info('Structured output shared its turn — relaying instead of settling', {
-				runId: this.ctx.runMgr.id,
-				callsInTurn: callCount,
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				'namzu.runtime.calls_in_turn': callCount,
 			})
 			return false
 		}
@@ -1659,8 +1841,8 @@ export class IterationOrchestrator {
 			})
 		} catch (err) {
 			this.ctx.log.error('Answer review threw — accepting the answer unreviewed', {
-				runId: this.ctx.runMgr.id,
-				error: toErrorMessage(err),
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				'exception.message': toErrorMessage(err),
 			})
 			return { accept: true }
 		}
@@ -1682,8 +1864,8 @@ export class IterationOrchestrator {
 			// A throwing predicate must not kill a run that is otherwise
 			// healthy; failing open keeps the existing budgets in charge.
 			this.ctx.log.error('Stop condition threw — continuing the run', {
-				runId: this.ctx.runMgr.id,
-				error: toErrorMessage(err),
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				'exception.message': toErrorMessage(err),
 			})
 			return false
 		}
@@ -1709,7 +1891,7 @@ export class IterationOrchestrator {
 		if (hasResult) return
 
 		this.ctx.log.info('Requesting final response before limit enforcement', {
-			reason,
+			'namzu.runtime.reason': reason,
 		})
 
 		try {
@@ -1725,7 +1907,7 @@ export class IterationOrchestrator {
 			// no 400 on tool blocks in history) and forbid use via tool_choice.
 			const finalTools = this.ctx.tools.toLLMTools(this.ctx.allowedTools)
 			const finalEnforced = enforcedModelInputToolNames(this.ctx.tools, finalTools)
-			const response = await collect(
+			const response = await collectChatCompletion(
 				this.ctx.provider.chatStream({
 					model,
 					messages: finalMessages,
@@ -1772,7 +1954,7 @@ export class IterationOrchestrator {
 			})
 		} catch (err) {
 			this.ctx.log.error('Failed to get final response', {
-				error: toErrorMessage(err),
+				'exception.message': toErrorMessage(err),
 			})
 		}
 	}