@namzu/sdk 1.4.0 → 3.0.0

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

@@ -1,29 +1,63 @@
 import { SpanStatusCode } from '@opentelemetry/api';
 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 { collect } from '../../../provider/collect.js';
-import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attributes.js';
+import { GENAI, NAMZU, agentIterationSpanName, parentContext, } from '../../../telemetry/attributes.js';
 import { getTracer } from '../../../telemetry/runtime-accessors.js';
-import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js';
+import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js';
+import { createAssistantMessage, createSystemMessage, createUserMessage, } from '../../../types/message/index.js';
+import { classifyProviderError } from '../../../types/provider/errors.js';
 import { toErrorMessage } from '../../../utils/error.js';
 import { generateMessageId } from '../../../utils/id.js';
 import { applyLifecycleHookResults } from '../plugin-hooks.js';
 import { runAdvisoryPhase } from './phases/advisory.js';
 import { runIterationCheckpoint } from './phases/checkpoint.js';
-import { runCompactionCheck } from './phases/compaction.js';
+import { 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';
 import { streamProviderTurn } from './stream-turn.js';
+/**
+ * How many times an answer may be handed back before the run stops.
+ *
+ * Bounded for the same reason the structured-output re-prompt is: a judge
+ * that never accepts would otherwise spend the whole token budget
+ * rediscovering that, and the run would end on a budget error rather than
+ * on the thing that actually went wrong.
+ */
+const DEFAULT_ANSWER_REVIEW_LIMIT = 3;
 export class IterationOrchestrator {
     ctx;
+    /** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
+    answerReviewAttempts = 0;
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /**
+     * Adopt the run's span after construction.
+     *
+     * The orchestrator is built before `query()` enters its generator body,
+     * which is where the run span is created — so the parent cannot be a
+     * constructor argument without reordering setup around one field.
+     */
+    setRootSpan(span) {
+        this.ctx = { ...this.ctx, rootSpan: span };
+    }
     async *runLoop() {
         const { runConfig, runMgr } = this.ctx;
         const { model } = runConfig;
         const tracer = getTracer();
+        // One context-overflow relief per *stuck point*, not per run.
+        //
+        // The latch exists so that a second overflow immediately after a
+        // successful compaction — meaning the prompt is irreducible — stops
+        // instead of looping. It was never meant to disarm the mechanism for
+        // the rest of the run, which is what a run-scoped flag did: one
+        // relief at iteration 3 left iteration 40 to die on an overflow with
+        // obvious moves left. It is cleared by a turn that actually
+        // succeeded, which is the evidence that the run is no longer stuck.
+        let overflowRelieved = false;
         const planSignal = yield* runPlanGate(this.ctx);
         if (planSignal === 'stop')
             return;
@@ -65,7 +99,14 @@ export class IterationOrchestrator {
             if (iterationActivity) {
                 this.ctx.activityStore.start(iterationActivity.id);
             }
-            const iterSpan = tracer.startSpan(agentIterationSpanName(iterationNum));
+            // Parent explicitly: this body is an async generator, so the
+            // ambient context at resume time belongs to the CONSUMER, not to
+            // whoever created the run span. Without this every iteration
+            // emits as its own root and a 20-turn run shows up as 21
+            // disconnected traces.
+            const iterSpan = tracer.startSpan(agentIterationSpanName(iterationNum), {}, parentContext(this.ctx.rootSpan));
+            // Tool spans for this turn belong under this iteration.
+            this.ctx.toolExecutor.setParentSpan(iterSpan);
             iterSpan.setAttributes({
                 [NAMZU.ITERATION]: iterationNum,
                 [NAMZU.RUN_ID]: runMgr.id,
@@ -94,15 +135,55 @@ export class IterationOrchestrator {
                 // entire prompt-cache prefix (tools render at position 0) and
                 // risks a 400 because the history still carries
                 // tool_use/tool_result blocks.
-                const openAITools = this.ctx.tools.toLLMTools(this.ctx.allowedTools);
-                const messages = forceFinalize
+                // Snapshot the cumulative counters so the step can report ITS
+                // own usage rather than the run total.
+                const stepStartedAt = Date.now();
+                const usageBefore = { ...runMgr.tokenUsage };
+                const costBefore = { ...runMgr.costInfo };
+                // 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 step = await this.prepareStep(iterationNum);
+                const llmTools = this.ctx.tools.toLLMTools(step.allowedTools ?? this.ctx.allowedTools);
+                const stepModel = step.model ?? model;
+                const baseMessages = forceFinalize
                     ? [
                         ...runMgr.messages,
                         createUserMessage('[SYSTEM] You are approaching your resource limits. Provide your final, comprehensive response now based on everything you have gathered so far. Do not request any more tool calls.'),
                     ]
                     : runMgr.messages;
+                // Step guidance is appended to the REQUEST, never pushed onto
+                // the run's history: it applies to this step only, and pushing
+                // it would accumulate one stale instruction per iteration.
+                // Copy before it crosses the provider boundary. `runMgr.messages`
+                // is the LIVE run array, and the loop pushes onto it after the
+                // call returns — so a driver that retains what it was handed
+                // (to log it, cache it, or replay it on retry) watched its own
+                // input grow new turns underneath it. A capture provider in the
+                // estate recorded every turn as identical to the last for
+                // exactly this reason. Shallow is enough: the defect is array
+                // mutation, and per-iteration this is trivial next to the model
+                // call it precedes.
+                const messages = step.system
+                    ? [...baseMessages, createSystemMessage(step.system)]
+                    : [...baseMessages];
                 if (this.ctx.pluginManager) {
-                    const hookResults = await this.ctx.pluginManager.executeHooks('pre_llm_call', { runId: runMgr.id, iteration: iterationNum }, this.ctx.emitEvent);
+                    const hookResults = await this.ctx.pluginManager.executeHooks('pre_llm_call', {
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                        // Built inside the guard: a run with no plugins installed
+                        // pays nothing for a projection nobody reads.
+                        request: Object.freeze({
+                            model: stepModel,
+                            // Copied per turn, not handed over live: these are the
+                            // run's own message objects, and a hook writing into
+                            // one would edit the history the run is about to send.
+                            messages: Object.freeze(messages.map((m) => Object.freeze({ ...m }))),
+                            toolNames: Object.freeze(llmTools.map((t) => t.function.name)),
+                            temperature: step.temperature ?? runConfig.temperature,
+                            maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
+                        }),
+                    }, this.ctx.emitEvent);
                     applyLifecycleHookResults('pre_llm_call', hookResults);
                     yield* this.ctx.drainPending();
                 }
@@ -114,22 +195,36 @@ export class IterationOrchestrator {
                 // aggregated `ChatCompletionResponse` for the legacy
                 // downstream paths (assistantMsg construction, working
                 // state extraction, telemetry attribute stamping).
-                const { response } = yield* streamProviderTurn(this.ctx.provider, {
-                    model,
+                const { response, messageId } = yield* streamProviderTurn(this.ctx.provider, {
+                    model: stepModel,
                     messages,
-                    tools: openAITools.length > 0 ? openAITools : undefined,
-                    toolChoice: forceFinalize && openAITools.length > 0 ? 'none' : undefined,
-                    temperature: runConfig.temperature,
-                    maxTokens: runConfig.maxResponseTokens,
+                    tools: llmTools.length > 0 ? llmTools : undefined,
+                    toolChoice: forceFinalize && llmTools.length > 0 ? 'none' : undefined,
+                    temperature: step.temperature ?? runConfig.temperature,
+                    maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
                     cacheControl: { type: 'auto' },
+                    ...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
                     // 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.
                     signal: this.ctx.abortController.signal,
-                }, this.ctx.emitEvent, this.ctx.drainPending, runMgr.id, iterationNum, forceFinalize, this.ctx.log);
-                runMgr.accumulateUsage(response.usage);
+                }, this.ctx.emitEvent, this.ctx.drainPending, runMgr.id, iterationNum, forceFinalize, this.ctx.log, iterSpan);
+                // Main-loop turn: also records the prompt size compaction reads.
+                runMgr.recordTurnUsage(response.usage);
+                // The turn went through, so the run is not sitting on an
+                // irreducible prompt any more. Re-arm relief for the next one.
+                overflowRelieved = false;
                 if (this.ctx.pluginManager) {
-                    const hookResults = await this.ctx.pluginManager.executeHooks('post_llm_call', { runId: runMgr.id, iteration: iterationNum }, this.ctx.emitEvent);
+                    const hookResults = await this.ctx.pluginManager.executeHooks('post_llm_call', {
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                        response: Object.freeze({
+                            content: response.message.content,
+                            toolNames: Object.freeze((response.message.toolCalls ?? []).map((c) => c.function.name)),
+                            finishReason: response.finishReason,
+                            usage: Object.freeze({ ...response.usage }),
+                        }),
+                    }, this.ctx.emitEvent);
                     applyLifecycleHookResults('post_llm_call', hookResults);
                     yield* this.ctx.drainPending();
                 }
@@ -150,7 +245,15 @@ export class IterationOrchestrator {
                     usage: runMgr.tokenUsage,
                     cost: runMgr.costInfo,
                 });
-                const assistantMsg = createAssistantMessage(response.message.content, forceFinalize ? undefined : response.message.toolCalls);
+                // Reasoning rides along with the turn it belongs to, so the
+                // replay contract holds automatically: trimming or compacting
+                // the assistant message takes its thinking blocks with it,
+                // and no separate atomicity rule is needed.
+                const assistantMsg = createAssistantMessage(response.message.content, forceFinalize ? undefined : response.message.toolCalls, response.message.reasoning, 
+                // Rides with the turn it belongs to, like reasoning does, so
+                // trimming or compacting the turn takes its evidence with it
+                // rather than leaving citations pointing at prose that is gone.
+                response.message.citations);
                 runMgr.pushMessage(assistantMsg);
                 if (this.ctx.workingStateManager && this.ctx.compactionConfig && assistantMsg.content) {
                     extractFromAssistantMessage(this.ctx.workingStateManager, assistantMsg.content, this.ctx.compactionConfig);
@@ -167,10 +270,23 @@ export class IterationOrchestrator {
                         hasToolCalls: forceFinalize ? false : !!response.message.toolCalls?.length,
                     });
                 }
-                if (forceFinalize ||
-                    response.finishReason === 'stop' ||
-                    !response.message.toolCalls ||
-                    response.message.toolCalls.length === 0) {
+                // Tool calls beat the finish reason. The reason is the
+                // provider's SUMMARY of the turn and the tool calls are the
+                // turn itself, so when they disagree the calls are the fact.
+                // Several function-calling endpoints — gateways and local servers
+                // especially — report `stop` alongside a populated
+                // `tool_calls`, and three of this repo's drivers pass that
+                // value through untouched.
+                //
+                // Reading `stop` first meant the turn ended with every
+                // requested call silently skipped, an assistant message
+                // carrying tool_use blocks that were never answered, and a
+                // run that settled `end_turn` having done nothing it was
+                // asked to do. Checking the calls first costs nothing when
+                // the provider is honest and is the only thing that saves the
+                // run when it is not.
+                const hasToolCalls = (response.message.toolCalls?.length ?? 0) > 0;
+                if (forceFinalize || !hasToolCalls) {
                     // Every task-dispatch tool (create_task, continue_task, Agent)
                     // is BLOCKING: the worker's output returns as the dispatching
                     // tool_use's canonical tool_result, so by the time the model
@@ -195,11 +311,11 @@ export class IterationOrchestrator {
                     // another turn. The provider receives the partial
                     // assistant content + the continue prompt and
                     // resumes from where it left off, mirroring the
-                    // Claude.ai "Continue" affordance.
+                    // Auto-continuation after an output-ceiling cutoff.
                     //
                     // Guards:
                     //   - `hasContent` so we don't loop forever on an
-                    //     empty cutoff (Anthropic occasionally emits
+                    //     empty cutoff (a provider occasionally emits
                     //     `stop_reason: max_tokens` with no content
                     //     when an injected pre-fill blocks the model).
                     //   - `!forceFinalize` so the forced-finalize path
@@ -223,6 +339,84 @@ export class IterationOrchestrator {
                         iterSpan.end();
                         continue;
                     }
+                    // The model tried to finish in prose while a structured
+                    // output was demanded. Send it back with the schema error
+                    // rather than returning an unusable result — this is the
+                    // re-prompt half, and it is bounded so a model that cannot
+                    // satisfy the schema fails loudly instead of looping.
+                    if (!forceFinalize && this.needsStructuredOutput()) {
+                        const attempt = ++this.structuredOutputAttempts;
+                        const limit = this.structuredOutputRetryLimit();
+                        if (attempt > limit) {
+                            this.ctx.log.warn('Structured output not produced within its retries', {
+                                runId: runMgr.id,
+                                attempts: attempt - 1,
+                            });
+                            runMgr.setStopReason('structured_output_failed');
+                            iterSpan.end();
+                            break;
+                        }
+                        this.ctx.log.info('Re-prompting for structured output', {
+                            runId: runMgr.id,
+                            attempt,
+                            limit,
+                        });
+                        runMgr.pushMessage(createUserMessage(STRUCTURED_OUTPUT_REPROMPT));
+                        await this.ctx.emitEvent({
+                            type: 'iteration_completed',
+                            runId: runMgr.id,
+                            iteration: iterationNum,
+                            hasToolCalls: false,
+                        });
+                        yield* this.ctx.drainPending();
+                        iterSpan.end();
+                        continue;
+                    }
+                    // Let the host judge the ANSWER and hand back work.
+                    //
+                    // The stop predicate is only consulted after tools ran, so
+                    // there was no seam here at all: the moment the model
+                    // stopped calling tools the run finalized, whatever it had
+                    // produced. Verify-then-fix — run the build, feed the
+                    // failure back, let it try again — meant starting a whole
+                    // new run and re-supplying the context the first one had.
+                    //
+                    // Shaped after the structured-output re-prompt directly
+                    // above, which solves the same problem for one specific
+                    // judge: bounded attempts, feedback as a user message, and
+                    // a loud stop rather than a loop.
+                    if (!forceFinalize && this.ctx.reviewAnswer) {
+                        const review = await this.reviewAnswer(response.message.content ?? '');
+                        if (review && !review.accept) {
+                            const attempt = ++this.answerReviewAttempts;
+                            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,
+                                });
+                                runMgr.setStopReason('answer_rejected');
+                                iterSpan.end();
+                                break;
+                            }
+                            this.ctx.log.info('Answer rejected — returning it to the model', {
+                                runId: runMgr.id,
+                                attempt,
+                                limit,
+                            });
+                            runMgr.pushMessage(createUserMessage(review.feedback));
+                            await this.ctx.emitEvent({
+                                type: 'iteration_completed',
+                                runId: runMgr.id,
+                                iteration: iterationNum,
+                                hasToolCalls: false,
+                            });
+                            yield* this.ctx.drainPending();
+                            iterSpan.end();
+                            continue;
+                        }
+                    }
                     if (!hasContent && !forceFinalize) {
                         this.ctx.log.warn('Empty completion detected — requesting final summary', {
                             iteration: iterationNum,
@@ -253,14 +447,92 @@ export class IterationOrchestrator {
                     break;
                 }
                 const reviewOutcome = yield* runToolReview(this.ctx, response, iterationNum);
-                if (reviewOutcome === 'stop') {
+                // The step record is built even for a rejected batch: a run that
+                // spent a turn getting its tools refused still spent the tokens,
+                // and a caller reconstructing cost per step must see it.
+                this.recordStep({
+                    stepNumber: iterationNum,
+                    model,
+                    messageId,
+                    response,
+                    toolResults: reviewOutcome.results,
+                    toolExecutionMs: reviewOutcome.durationMs,
+                    startedAt: stepStartedAt,
+                    usageBefore,
+                    costBefore,
+                });
+                if (reviewOutcome.decision === 'stop') {
                     iterSpan.end();
                     return;
                 }
-                if (reviewOutcome === 'rejected') {
+                if (reviewOutcome.decision === 'rejected') {
                     iterSpan.end();
                     continue;
                 }
+                // A successful `structured_output` call IS the answer, so the
+                // run ends here rather than paying for another turn whose only
+                // job would be to restate it.
+                if (this.captureStructuredOutput(reviewOutcome.results)) {
+                    this.ctx.log.info('Structured output produced — ending run', {
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                    });
+                    runMgr.setStopReason('end_turn');
+                    await this.ctx.emitEvent({
+                        type: 'iteration_completed',
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                        hasToolCalls: true,
+                    });
+                    yield* this.ctx.drainPending();
+                    iterSpan.end();
+                    break;
+                }
+                // A tool the author declared terminal settles the run with its
+                // own output, the same rule `structured_output` has always
+                // had. Without it a delegation cost the parent one more model
+                // call at full context whose only job was to restate what the
+                // worker already said — and to restate it through the parent's
+                // compacted view, so the caller did not even receive the
+                // worker's words.
+                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,
+                    });
+                    runMgr.setResult(settled.output);
+                    runMgr.setStopReason('end_turn');
+                    await this.ctx.emitEvent({
+                        type: 'iteration_completed',
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                        hasToolCalls: true,
+                    });
+                    yield* this.ctx.drainPending();
+                    iterSpan.end();
+                    break;
+                }
+                // Evaluated AFTER the tools ran, so a predicate can see what they
+                // returned — which is what makes a terminal submit_answer tool
+                // usable without discarding its output.
+                if (await this.shouldStop()) {
+                    this.ctx.log.info('Stop condition met', {
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                    });
+                    runMgr.setStopReason('stop_condition');
+                    await this.ctx.emitEvent({
+                        type: 'iteration_completed',
+                        runId: runMgr.id,
+                        iteration: iterationNum,
+                        hasToolCalls: true,
+                    });
+                    yield* this.ctx.drainPending();
+                    iterSpan.end();
+                    break;
+                }
                 const checkpointSignal = yield* runIterationCheckpoint(this.ctx, iterationNum);
                 if (checkpointSignal === 'stop') {
                     iterSpan.end();
@@ -295,6 +567,34 @@ export class IterationOrchestrator {
                     iterSpan.end();
                     break;
                 }
+                // The one provider failure the kernel can actually do something
+                // about. `context_length_exceeded` is correctly non-retryable —
+                // resending the identical prompt cannot help — but the kernel
+                // owns a compaction subsystem that can make the prompt smaller.
+                // Without this the run died holding the remedy: the threshold
+                // path had simply guessed low, which a run carrying images or a
+                // language the chars-per-token ratio does not fit will do.
+                //
+                // Relief is attempted ONCE per iteration and only when it
+                // actually shed something. A second overflow after a successful
+                // compaction means the prompt is irreducible, and looping on it
+                // would burn the budget to arrive at the same error.
+                if (!overflowRelieved &&
+                    classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded') {
+                    overflowRelieved = true;
+                    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,
+                        });
+                        if (iterationActivity) {
+                            this.ctx.activityStore.complete(iterationActivity.id);
+                        }
+                        iterSpan.end();
+                        continue;
+                    }
+                }
                 if (iterationActivity) {
                     this.ctx.activityStore.fail(iterationActivity.id, toErrorMessage(err));
                 }
@@ -308,6 +608,244 @@ export class IterationOrchestrator {
             }
         }
     }
+    /**
+     * Ask the host how to shape this step.
+     *
+     * Fails OPEN on a throw — same reasoning as `stopWhen` and deliberately
+     * opposite to a guardrail: a broken step-shaping hook should not kill an
+     * otherwise healthy run, and unlike a safety check, nothing unsafe gets
+     * through when it is skipped.
+     */
+    async prepareStep(stepNumber) {
+        const configured = this.ctx.prepareStep;
+        if (!configured)
+            return {};
+        const stages = Array.isArray(configured) ? configured : [configured];
+        // Folded in DECLARATION order, each stage seeing what the ones
+        // before it decided. A later stage overriding a field is last-writer
+        // wins — visibly, because the order is a line in the host's code
+        // rather than an accident of install history.
+        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,
+                });
+                if (decided)
+                    result = { ...result, ...decided };
+            }
+            catch (err) {
+                // 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),
+                });
+            }
+        }
+        const prepared = {};
+        if (result.activeTools) {
+            // A phase list that outlives a tool rename should narrow the
+            // surface, not kill the agent mid-run.
+            const known = result.activeTools.filter((name) => this.ctx.tools.has(name));
+            const unknown = result.activeTools.filter((name) => !this.ctx.tools.has(name));
+            if (unknown.length > 0) {
+                this.ctx.log.warn('prepareStep named tools that are not registered — ignoring them', {
+                    runId: this.ctx.runMgr.id,
+                    stepNumber,
+                    unknown,
+                });
+            }
+            prepared.allowedTools = known;
+        }
+        if (result.model !== undefined)
+            prepared.model = result.model;
+        if (result.system !== undefined)
+            prepared.system = result.system;
+        if (result.temperature !== undefined)
+            prepared.temperature = result.temperature;
+        if (result.maxResponseTokens !== undefined) {
+            prepared.maxResponseTokens = result.maxResponseTokens;
+        }
+        return prepared;
+    }
+    /** Steps completed so far, exposed on the returned `Run`. */
+    steps = [];
+    getSteps() {
+        return this.steps;
+    }
+    /**
+     * Fold one iteration into a `StepResult`.
+     *
+     * Every field here was already computed somewhere in the loop; the only
+     * new work is subtracting the cumulative counters so the step carries
+     * ITS usage rather than the run's running total, which is the number a
+     * caller asking "what did this step cost" actually wants.
+     */
+    recordStep(input) {
+        const { runMgr } = this.ctx;
+        const toolCalls = input.response.message.toolCalls ?? [];
+        const byId = new Map(input.toolResults.map((r) => [r.toolCallId, r]));
+        const step = {
+            stepNumber: input.stepNumber,
+            model: input.model,
+            messageId: input.messageId,
+            content: input.response.message.content,
+            toolCalls,
+            // Ordered by the tool CALLS, not by completion, so the record
+            // matches what the model asked for.
+            toolResults: toolCalls.map((tc) => {
+                const outcome = byId.get(tc.id);
+                return {
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    output: outcome?.output ?? '',
+                    isError: outcome?.isError ?? false,
+                    durationMs: 0,
+                };
+            }),
+            finishReason: input.response.finishReason,
+            usage: subtractUsage(runMgr.tokenUsage, input.usageBefore),
+            costDelta: {
+                ...runMgr.costInfo,
+                totalCost: round6(runMgr.costInfo.totalCost - input.costBefore.totalCost),
+            },
+            startedAt: input.startedAt,
+            durationMs: Date.now() - input.startedAt,
+            toolExecutionMs: input.toolExecutionMs,
+        };
+        this.steps.push(step);
+        this.ctx.onStepFinish?.(step);
+    }
+    /** Turns spent asking the model again for a valid structured output. */
+    structuredOutputAttempts = 0;
+    structuredOutputDone = false;
+    structuredOutputRetryLimit() {
+        return this.ctx.structuredOutput?.maxRetries ?? DEFAULT_STRUCTURED_OUTPUT_RETRIES;
+    }
+    /** True while a structured output was demanded and has not arrived. */
+    needsStructuredOutput() {
+        return this.ctx.structuredOutput !== undefined && !this.structuredOutputDone;
+    }
+    /**
+     * Record the structured output if this batch produced one.
+     *
+     * The tool validates against the Zod schema before its `execute` runs,
+     * so reaching here successfully means the value is already valid — a
+     * failed parse comes back as an error result and simply does not
+     * satisfy the demand, which sends the loop round again.
+     */
+    /**
+     * The answer a terminal tool produced, or `undefined` to keep looping.
+     *
+     * Deliberately narrow. A terminal call decides the run only when it is
+     * the ONLY call the model made in that turn: a model that asked for
+     * other work meant to see those results, and settling here would throw
+     * away answers it requested. Same for a failed terminal call — an
+     * error is not an answer, and the model is the one that should read
+     * it. Both cases fall through to the ordinary path, and both say so in
+     * the log rather than quietly costing the relay the flag was set to
+     * avoid.
+     */
+    terminalToolOutput(results, response) {
+        const terminal = results.filter((r) => this.ctx.tools.get(r.toolName)?.terminal === true);
+        if (terminal.length === 0)
+            return undefined;
+        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,
+            });
+            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,
+            });
+            return undefined;
+        }
+        return hit;
+    }
+    captureStructuredOutput(results) {
+        if (!this.needsStructuredOutput())
+            return false;
+        const hit = results.find((r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError);
+        if (!hit)
+            return false;
+        try {
+            this.ctx.runMgr.setStructuredOutput(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);
+        }
+        this.structuredOutputDone = true;
+        return true;
+    }
+    /**
+     * Ask the host whether this answer is good enough.
+     *
+     * A hook that throws **accepts**, which is the opposite of what the
+     * safety gates do, and deliberately so. Those are asked "is this
+     * dangerous", where the cost of failing closed is one refused
+     * operation. This is asked "is this good enough", where failing closed
+     * means handing the answer back forever — so a broken judge would turn
+     * every run into a loop that ends on a budget error naming nothing. One
+     * unreviewed answer is the cheaper failure, and the throw is logged at
+     * `error` so it is not mistaken for approval.
+     */
+    async reviewAnswer(answer) {
+        if (!this.ctx.reviewAnswer)
+            return undefined;
+        try {
+            return await this.ctx.reviewAnswer(answer, {
+                runId: this.ctx.runMgr.id,
+                iteration: this.ctx.runMgr.currentIteration,
+                messages: this.ctx.runMgr.messages,
+            });
+        }
+        catch (err) {
+            this.ctx.log.error('Answer review threw — accepting the answer unreviewed', {
+                runId: this.ctx.runMgr.id,
+                error: toErrorMessage(err),
+            });
+            return { accept: true };
+        }
+    }
+    /** Evaluate the caller's halt predicate, if there is one. */
+    async shouldStop() {
+        const stopWhen = this.ctx.stopWhen;
+        const latestStep = this.steps.at(-1);
+        if (!stopWhen || !latestStep)
+            return false;
+        try {
+            return await stopWhen({
+                steps: this.steps,
+                latestStep,
+                totalUsage: this.ctx.runMgr.tokenUsage,
+                totalCost: this.ctx.runMgr.costInfo,
+            });
+        }
+        catch (err) {
+            // 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),
+            });
+            return false;
+        }
+    }
     hasRunningAgentTasks() {
         if (!this.ctx.taskGateway)
             return false;
@@ -344,6 +882,7 @@ export class IterationOrchestrator {
                 temperature: this.ctx.runConfig.temperature,
                 maxTokens: this.ctx.runConfig.maxResponseTokens,
                 cacheControl: { type: 'auto' },
+                ...(this.ctx.runConfig.thinking ? { thinking: this.ctx.runConfig.thinking } : {}),
                 // Cancellable too: a Stop during the closing summary must not
                 // stream to completion.
                 signal: this.ctx.abortController.signal,
@@ -375,4 +914,18 @@ export class IterationOrchestrator {
         }
     }
 }
+/** Per-step usage: the delta between two cumulative snapshots. */
+function subtractUsage(after, before) {
+    return {
+        promptTokens: after.promptTokens - before.promptTokens,
+        completionTokens: after.completionTokens - before.completionTokens,
+        totalTokens: after.totalTokens - before.totalTokens,
+        cachedTokens: (after.cachedTokens ?? 0) - (before.cachedTokens ?? 0),
+        cacheWriteTokens: (after.cacheWriteTokens ?? 0) - (before.cacheWriteTokens ?? 0),
+    };
+}
+/** Cost deltas are subtractions of floats; keep them presentable. */
+function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
 //# sourceMappingURL=index.js.map