@namzu/sdk 27.1.0 → 28.0.0

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

@@ -3,9 +3,9 @@ import { resolveContextWindow } from '../../../compaction/context-window.js';
 import { extractFromAssistantMessage } from '../../../compaction/extractor.js';
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js';
 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, agentIterationSpanName, parentContext, } from '../../../telemetry/attributes.js';
 import { getTracer } from '../../../telemetry/runtime-accessors.js';
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js';
@@ -13,8 +13,10 @@ import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js';
 import { createAssistantMessage, createSystemMessage, createUserMessage, } from '../../../types/message/index.js';
 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 { 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';
@@ -92,6 +94,12 @@ export class IterationOrchestrator {
     ctx;
     /** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
     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.
+     */
+    lastEnvelopeKey;
     /**
      * The previous iteration held a `stopWhen` decision open for a worker.
      *
@@ -164,32 +172,51 @@ export class IterationOrchestrator {
                 const guardResult = this.ctx.guard.beforeIteration(runMgr, this.ctx.abortController.signal);
                 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;
                     }
                     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();
                     runMgr.setStopReason(stopReason);
                     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({
                     type: 'llm_turn',
@@ -304,10 +331,73 @@ 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', {
                             runId: runMgr.id,
@@ -436,15 +526,15 @@ export class IterationOrchestrator {
                         yield* this.ctx.drainPending();
                     }
                     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
                     // surface showing one almost always wants the other — and
@@ -459,7 +549,7 @@ export class IterationOrchestrator {
                     const contextFigures = this.ctx.compactionConfig
                         ? (() => {
                             const measured = measureContext(this.ctx);
-                            const window = resolveContextWindow(this.ctx.compactionConfig?.contextWindowTokens, runConfig.model);
+                            const window = resolveContextWindow(this.ctx.compactionConfig?.contextWindowTokens, runConfig.model, this.ctx.providerContextWindow);
                             return {
                                 contextTokens: measured.tokens,
                                 contextMeasuredBy: measured.source,
@@ -528,8 +618,8 @@ export class IterationOrchestrator {
                         // out. Log the orphans honestly and end the turn normally.
                         if (!forceFinalize && this.hasRunningAgentTasks()) {
                             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,
                             });
                         }
                         // This iteration gets a step too.
@@ -608,9 +698,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({
@@ -632,16 +722,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({
@@ -673,17 +763,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({
@@ -705,10 +795,29 @@ export class IterationOrchestrator {
                         if (!forceFinalize && (yield* this.holdForOutstandingWork(iterationNum, false))) {
                             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();
@@ -775,8 +884,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({
@@ -798,9 +907,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');
@@ -842,8 +951,8 @@ export class IterationOrchestrator {
                             continue;
                         }
                         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({
@@ -881,12 +990,17 @@ 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) {
                         const hookResults = await this.ctx.pluginManager.executeHooks('iteration_end', { runId: runMgr.id, iteration: iterationNum }, this.ctx.emitEvent);
@@ -941,9 +1055,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 {
@@ -1001,8 +1115,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);
@@ -1052,9 +1166,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);
         const arrived = this.ctx.completionInbox.drain();
@@ -1104,8 +1218,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);
     }
@@ -1133,8 +1247,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)));
     }
@@ -1146,6 +1260,34 @@ 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.
+     */
+    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);
+        }
+        catch (err) {
+            return { reason: `beforeStep threw: ${toErrorMessage(err)}` };
+        }
+    }
     async prepareStep(stepNumber) {
         const configured = this.ctx.prepareStep;
         if (!configured)
@@ -1172,9 +1314,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),
                 });
             }
         }
@@ -1198,10 +1340,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;
@@ -1234,6 +1376,32 @@ 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.
+     */
+    deliverInbound() {
+        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);
+    }
     recordStep(input) {
         const { runMgr } = this.ctx;
         const toolCalls = input.response?.message.toolCalls ?? [];
@@ -1300,9 +1468,9 @@ export class IterationOrchestrator {
         }
         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),
             });
         }
     }
@@ -1335,17 +1503,17 @@ 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;
         }
         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;
         }
@@ -1404,8 +1572,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;
         }
@@ -1444,8 +1612,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 };
         }
@@ -1468,8 +1636,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;
         }
@@ -1491,7 +1659,7 @@ export class IterationOrchestrator {
         if (hasResult)
             return;
         this.ctx.log.info('Requesting final response before limit enforcement', {
-            reason,
+            'namzu.runtime.reason': reason,
         });
         try {
             const finalMessages = [
@@ -1503,7 +1671,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(this.ctx.provider.chatStream({
+            const response = await collectChatCompletion(this.ctx.provider.chatStream({
                 model,
                 messages: finalMessages,
                 tools: finalTools.length > 0 ? finalTools : undefined,
@@ -1546,7 +1714,7 @@ export class IterationOrchestrator {
         }
         catch (err) {
             this.ctx.log.error('Failed to get final response', {
-                error: toErrorMessage(err),
+                'exception.message': toErrorMessage(err),
             });
         }
     }