@namzu/sdk 2.0.0 → 3.0.0

package/dist/runtime/query/index.js

@@ -1,25 +1,40 @@
-import { AdvisorRegistry, AdvisoryContext, AdvisoryExecutor, TriggerEvaluator, } from '../../advisory/index.js';
+import { join } from 'node:path';
+import { AdvisorRegistry, AdvisoryContext, AdvisoryExecutor, TriggerEvaluator, assertBudgetEnforceable, } from '../../advisory/index.js';
+import { findDanglingMessages, removeDanglingMessages } from '../../compaction/dangling.js';
 import { extractFromUserMessage } from '../../compaction/extractor.js';
 import { WorkingStateManager } from '../../compaction/manager.js';
+import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js';
+import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js';
+import { EmergencySaveManager } from '../../manager/run/emergency.js';
 import { resolveProviderCapabilities } from '../../provider/capabilities.js';
-import { GENAI, NAMZU, agentRunSpanName } from '../../telemetry/attributes.js';
+import { withProviderRetry } from '../../provider/retry.js';
+import { GENAI, NAMZU, agentRunSpanName, parentContext, serializeSpan, } from '../../telemetry/attributes.js';
+import { recordRunDuration } from '../../telemetry/metrics.js';
 import { getTracer } from '../../telemetry/runtime-accessors.js';
 import { buildAdvisoryTools } from '../../tools/advisory/index.js';
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js';
+import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool, } from '../../tools/builtins/structuredOutput.js';
 import { buildTaskTools } from '../../tools/task/index.js';
+import { NamzuError } from '../../types/errors/index.js';
 import { autoApproveHandler, } from '../../types/hitl/index.js';
 import { createSystemMessage } from '../../types/message/index.js';
+import { memoryCandidateFor } from '../../types/run/memory-promotion.js';
+import { getRootLogger } from '../../utils/logger.js';
 import { VerificationGate } from '../../verification/gate.js';
 import { CheckpointManager } from './checkpoint.js';
 import { RunContextFactory } from './context.js';
 import { EventTranslator } from './events.js';
 import { GuardCoordinator } from './guard.js';
+import { runInputGuardrails, runOutputGuardrails } from './guardrails.js';
 import { IterationOrchestrator } from './iteration/index.js';
 import { isCompactionMessage } from './iteration/phases/compaction.js';
 import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js';
 import { applyLifecycleHookResults } from './plugin-hooks.js';
 import { PromptBuilder } from './prompt.js';
 import { ResultAssembler } from './result.js';
+import { applyPendingResume, planCrashResume, planPendingResume, recoverCompletedCalls, unansweredToolCalls, } from './resume-pending.js';
+import { ToolGrantSet } from './tool-grants.js';
+import { createToolPause } from './tool-pause.js';
 import { ToolingBootstrap } from './tooling.js';
 export async function* query(params) {
     // Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
@@ -29,11 +44,22 @@ export async function* query(params) {
     // sync for tests / non-async call sites.
     const cwdForMigration = params.workingDirectory ?? process.cwd();
     await RunContextFactory.ensureMigrated(`${cwdForMigration}/.namzu`);
+    // Every model call in the run — the loop's turns, the forced-final
+    // summary, advisory and compaction side calls — goes through this one
+    // wrapped provider, so the retry policy cannot be bypassed by a code
+    // path that happens to hold the raw driver.
+    // The logger is passed on purpose: `withProviderRetry` guards every one
+    // of its warns behind `options.log`, and this is its only production
+    // call site — so without it the "failed, retrying" and "failed, giving
+    // up" lines were dead code and a backoff left no trace anywhere.
+    const resilientProvider = params.retry === false
+        ? params.provider
+        : withProviderRetry(params.provider, { config: params.retry, log: getRootLogger() });
     const ctx = RunContextFactory.build({
         agentId: params.agentId,
         agentName: params.agentName,
         runConfig: params.runConfig,
-        provider: params.provider,
+        provider: resilientProvider,
         workingDirectory: params.workingDirectory,
         pricing: params.pricing,
         enableActivityTracking: params.enableActivityTracking,
@@ -108,6 +134,14 @@ export async function* query(params) {
             params.tools.register(SearchToolsTool);
         }
     }
+    // Registered HERE, before the first turn, not when the model is nearly
+    // done. Tools render at prefix position 0, so injecting one late would
+    // invalidate the whole prompt cache for the rest of the run — the same
+    // reason the forced-final turn keeps its tools array and uses
+    // `toolChoice: 'none'` instead of dropping it.
+    if (params.structuredOutput && !params.tools.has(STRUCTURED_OUTPUT_TOOL_NAME)) {
+        params.tools.register(createStructuredOutputTool(params.structuredOutput.schema));
+    }
     // ─── Provider capability negotiation (before tooling bootstrap) ────────
     // Compare what the request asks for with what the DRIVER declared it
     // does. Undeclared capabilities resolve permissively (today's behavior
@@ -116,13 +150,24 @@ export async function* query(params) {
     const capabilities = resolveProviderCapabilities(params.provider);
     const registeredToolCount = params.tools.listNames().length;
     const stripToolSurfaces = !capabilities.supportsTools && registeredToolCount > 0;
+    // Counted separately because they are separate wire shapes: a driver can
+    // map images and drop documents, and a vision warning would send the
+    // reader looking at the wrong half.
+    const carries = (m, kind) => m.role === 'user' && (m.attachments ?? []).some((a) => (a.type ?? 'image') === kind);
     const attachmentMessageCount = capabilities.supportsVision
         ? 0
-        : params.messages.filter((m) => m.role === 'user' && m.attachments !== undefined && m.attachments.length > 0).length;
+        : params.messages.filter((m) => carries(m, 'image')).length;
+    const documentMessageCount = capabilities.supportsDocuments
+        ? 0
+        : params.messages.filter((m) => carries(m, 'document')).length;
     if (stripToolSurfaces) {
         const message = `Provider '${params.provider.id}' declares supportsTools: false but ${registeredToolCount} tool(s) are registered — stripping all tool surfaces from the prompt and request so the model is never told about tools it cannot call. Pass strictCapabilities: true to fail instead, or use a tools-capable provider.`;
         if (params.strictCapabilities) {
-            throw new Error(message);
+            throw new NamzuError({
+                code: 'capability_unavailable',
+                message,
+                details: { providerId: params.provider.id, capability: 'tools', registeredToolCount },
+            });
         }
         ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
             providerId: params.provider.id,
@@ -132,16 +177,38 @@ export async function* query(params) {
     if (attachmentMessageCount > 0) {
         const message = `Provider '${params.provider.id}' declares supportsVision: false but ${attachmentMessageCount} user message(s) carry image attachments — the driver will not map them, so the model never sees the images. Pass strictCapabilities: true to fail instead, or use a vision-capable provider.`;
         if (params.strictCapabilities) {
-            throw new Error(message);
+            throw new NamzuError({
+                code: 'capability_unavailable',
+                message,
+                details: { providerId: params.provider.id, capability: 'vision', attachmentMessageCount },
+            });
         }
         ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
             providerId: params.provider.id,
             attachmentMessageCount,
         });
     }
+    if (documentMessageCount > 0) {
+        const message = `Provider '${params.provider.id}' declares supportsDocuments: false but ${documentMessageCount} user message(s) carry document attachments — the driver will not map them, so the model never sees the documents. Pass strictCapabilities: true to fail instead, or use a document-capable provider.`;
+        if (params.strictCapabilities) {
+            throw new NamzuError({
+                code: 'capability_unavailable',
+                message,
+                details: { providerId: params.provider.id, capability: 'documents', documentMessageCount },
+            });
+        }
+        ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
+            providerId: params.provider.id,
+            documentMessageCount,
+        });
+    }
     const effectiveAllowedTools = stripToolSurfaces
         ? []
         : withDeferredDiscoveryTool(params.tools, params.allowedTools);
+    //  is null only when the run has no disk layout (tests,
+    // in-memory hosts); the budget then degrades to middle-elision.
+    const runDirForTools = ctx.runMgr.getRunDir();
+    const toolOutputDir = runDirForTools ? join(runDirForTools, TOOL_OUTPUT_DIR_NAME) : undefined;
     const toolExecutor = ToolingBootstrap.init({
         tools: params.tools,
         runId: ctx.runId,
@@ -152,6 +219,33 @@ export async function* query(params) {
         allowedTools: effectiveAllowedTools,
         invocationState: params.invocationState,
         pluginManager: params.pluginManager,
+        ...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
+        ...(params.maxToolConcurrency !== undefined
+            ? { maxToolConcurrency: params.maxToolConcurrency }
+            : {}),
+        ...(params.maxToolOutputChars !== undefined
+            ? { maxToolOutputChars: params.maxToolOutputChars }
+            : {}),
+        ...(params.maxToolContentBytes !== undefined
+            ? { maxToolContentBytes: params.maxToolContentBytes }
+            : {}),
+        // Overflow lands beside the run's other artifacts, so it is
+        // cleaned up with the run and reachable by the model's own
+        // `read`/`grep` without a new affordance.
+        ...(toolOutputDir ? { toolOutputDir } : {}),
+        ...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
+        // The durable pause, reachable from any tool rather than from the
+        // four kernel-owned points that used to own it. Built here from
+        // the machinery the run already holds; the recorder binds a few
+        // lines below, and until it does a pause is in-process only —
+        // the same degradation the built-in question tool has.
+        toolPause: (toolUseId) => createToolPause({
+            runId: ctx.runId,
+            toolUseId,
+            parkHandler: params.resumeHandler,
+            ...(params.questionParks ? { recorder: params.questionParks } : {}),
+            ...(params.pendingAnswers ? { pendingAnswers: params.pendingAnswers } : {}),
+        }),
     }, ctx.activityStore, eventTranslator.emitEvent, ctx.log);
     let workingStateManager;
     if (params.compactionConfig && params.compactionConfig.strategy !== 'disabled') {
@@ -174,6 +268,15 @@ export async function* query(params) {
         maxIterations: params.runConfig.maxIterations,
     });
     const checkpointMgr = new CheckpointManager(ctx.runMgr.getCheckpointStore(), ctx.runMgr.getRunScope());
+    // Every checkpoint carries compaction's accumulated state, so a run that
+    // comes back in a new process can adopt it (see the restore block).
+    // Without it, compaction's own justification for dropping the prior
+    // `[COMPACTED CONTEXT]` block — that `serializeState` is cumulative —
+    // holds within one process and fails across a resume.
+    if (workingStateManager) {
+        const manager = workingStateManager;
+        checkpointMgr.setWorkingStateSource(() => snapshotWorkingState(manager));
+    }
     const resultAssembler = new ResultAssembler({
         runMgr: ctx.runMgr,
         planManager: ctx.planManager,
@@ -181,11 +284,17 @@ export async function* query(params) {
         log: ctx.log,
         emitEvent: eventTranslator.emitEvent,
         drainPending: () => eventTranslator.drainPending(),
+        // Read at settle time, not now: checkpoints are written per
+        // iteration, so the answer changes as the run proceeds.
+        resumeCheckpointId: () => checkpointMgr.lastCheckpointId,
     });
     let advisoryCtx;
     if (params.advisory && params.advisory.advisors.length > 0) {
         const advisorRegistry = new AdvisorRegistry(params.advisory.advisors, params.advisory.defaultAdvisorId);
-        const advisoryExecutor = new AdvisoryExecutor(ctx.log);
+        // A budget the runtime cannot measure is refused here rather than
+        // silently ignored for the length of the run.
+        assertBudgetEnforceable(params.advisory);
+        const advisoryExecutor = new AdvisoryExecutor(ctx.log, params.advisory.budget);
         const triggerEvaluator = new TriggerEvaluator(params.advisory.triggers ?? [], params.advisory.budget);
         advisoryCtx = new AdvisoryContext(advisorRegistry, advisoryExecutor, triggerEvaluator, params.advisory.budget);
         if (params.advisory.enableAgentTool) {
@@ -203,8 +312,17 @@ export async function* query(params) {
         ? new VerificationGate(params.verificationGate, ctx.log)
         : undefined;
     const iterationOrchestrator = new IterationOrchestrator({
-        provider: params.provider,
+        provider: resilientProvider,
         runConfig: params.runConfig,
+        ...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
+        ...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
+        ...(params.onStepFinish ? { onStepFinish: params.onStepFinish } : {}),
+        ...(params.reviewAnswer ? { reviewAnswer: params.reviewAnswer } : {}),
+        ...(params.maxAnswerReviews !== undefined ? { maxAnswerReviews: params.maxAnswerReviews } : {}),
+        ...(params.structuredOutput ? { structuredOutput: params.structuredOutput } : {}),
+        ...(params.parkRecordDelayMs !== undefined
+            ? { parkRecordDelayMs: params.parkRecordDelayMs }
+            : {}),
         tools: params.tools,
         allowedTools: effectiveAllowedTools,
         runMgr: ctx.runMgr,
@@ -221,6 +339,9 @@ export async function* query(params) {
         taskGateway: params.taskGateway,
         taskStore: params.taskStore,
         launchedTasks: params.launchedTasks ?? new Map(),
+        // Run-scoped. An approval is a statement about this run's work;
+        // carrying one into a later run would be reuse nobody agreed to.
+        toolGrants: new ToolGrantSet(),
         compactionConfig: params.compactionConfig,
         workingStateManager,
         workingMemoryProvider: params.workingMemoryProvider,
@@ -231,7 +352,92 @@ export async function* query(params) {
     });
     const tracer = getTracer();
     return yield* (async function* () {
-        const rootSpan = tracer.startSpan(agentRunSpanName(params.agentName));
+        // Parent explicitly when a caller supplied one. Without this every
+        // run starts its OWN root trace, so a supervisor delegating to three
+        // children produced four disconnected traces instead of one tree —
+        // the same defect that made a 20-turn run show up as 21 roots before
+        // iterations were parented, except across the spawn boundary, where
+        // it is worse: the delegation structure is the thing you most want
+        // to see.
+        const runStartedAt = Date.now();
+        // Read before the span is minted, because a parent can only be set
+        // at creation. A resumed run used to start a brand-new trace with no
+        // link to the one that crashed, so the failure and its recovery
+        // could not be put on one timeline — the run id correlated them well
+        // enough to find both by query and not well enough to see a single
+        // waterfall, and for a replay fork (which mints a new run id) not
+        // even that. An explicit caller-supplied parent still wins: it is
+        // the more specific statement about where this run belongs.
+        const resumedTrace = params.resumeFromCheckpoint
+            ? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
+            : undefined;
+        const rootSpan = tracer.startSpan(agentRunSpanName(params.agentName), {}, parentContext(params.parentSpan ?? resumedTrace));
+        // Hand the run span to the loop so every iteration parents to it.
+        iterationOrchestrator.setRootSpan(rootSpan);
+        // Every checkpoint from here on records the trace it was taken
+        // inside, so the next resume can join this one.
+        checkpointMgr.setTraceSource(() => serializeSpan(rootSpan));
+        // And every park it records carries an absolute deadline, so an
+        // unanswered approval cannot outlive the worker that asked for it.
+        checkpointMgr.setParkTtl(params.runConfig.hitlParkTtlMs);
+        // A question raised from inside a tool becomes a real checkpoint
+        // here. It used to park under a synthetic id nothing ever wrote, so
+        // the checkpoint did not exist: nothing on disk said a human owed
+        // this run an answer, and a remote host could not observe the
+        // question at all.
+        params.questionParks?.bind({
+            record: async (question) => {
+                try {
+                    const checkpoint = await checkpointMgr.create(ctx.runMgr, ctx.runMgr.currentIteration);
+                    const parked = await checkpointMgr.park(checkpoint, {
+                        type: 'user_question',
+                        runId: ctx.runMgr.id,
+                        checkpointId: checkpoint.id,
+                        question,
+                    });
+                    await eventTranslator.emitEvent({
+                        type: 'user_question_asked',
+                        runId: ctx.runMgr.id,
+                        checkpointId: parked.id,
+                        questionId: question.questionId,
+                        question: question.question,
+                    });
+                    return parked.id;
+                }
+                catch (err) {
+                    // A store that cannot record the park must not take the
+                    // tool down with it: the in-process await is still valid
+                    // and only the cross-process handoff is lost. Loudly,
+                    // because a host building an approval queue from durable
+                    // state will not see this question.
+                    ctx.log.error('Failed to record a question park — it is not resumable', {
+                        runId: ctx.runMgr.id,
+                        questionId: question.questionId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    return null;
+                }
+            },
+            resolve: async (checkpointId, decision) => {
+                await checkpointMgr.unpark(checkpointId, decision).catch((err) => {
+                    ctx.log.error('Failed to clear a recorded question park', {
+                        runId: ctx.runMgr.id,
+                        checkpointId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    return null;
+                });
+                await eventTranslator.emitEvent({
+                    type: 'user_question_answered',
+                    runId: ctx.runMgr.id,
+                    checkpointId,
+                    ...(decision.action === 'answer_question' && decision.questionId !== undefined
+                        ? { questionId: decision.questionId }
+                        : {}),
+                    answered: decision.action === 'answer_question',
+                });
+            },
+        });
         rootSpan.setAttributes({
             [NAMZU.RUN_ID]: ctx.runMgr.id,
             [GENAI.AGENT_NAME]: params.agentName,
@@ -240,6 +446,12 @@ export async function* query(params) {
             [GENAI.SYSTEM]: params.provider.id,
         });
         let sandbox;
+        // Decided during checkpoint restore, executed after the sandbox
+        // exists — the approved tools may well need it.
+        let pendingResume = null;
+        /** Tool results recovered from the transcript; see the restore path. */
+        let recoveredResults = new Map();
+        let emergencyManager;
         try {
             await ctx.runMgr.init();
             ctx.log.info('Starting query', {
@@ -282,8 +494,92 @@ export async function* query(params) {
                     fromCheckpointId: checkpoint.id,
                 });
                 yield* eventTranslator.drainPending();
+                // Budgets are properties of the RUN, not of the process hosting
+                // it. The checkpoint already carried all three; they were
+                // written and then discarded on the way back in, so a run
+                // recalled at $4.80 of a $5 cap came back with a fresh $5 and
+                // a fresh timeout clock. Restore before the first iteration so
+                // a resumed run that is already over budget stops immediately.
+                ctx.runMgr.restoreUsage(checkpoint.tokenUsage, checkpoint.costInfo, checkpoint.guardState.iterationCount);
+                guard.restoreElapsed(checkpoint.guardState.elapsedMs);
+                // Adopt the working state the earlier summary was built from.
+                // The `[COMPACTED CONTEXT]` block below is preserved precisely
+                // because it is the only surviving record of the history the
+                // first pass deleted — and without this, the NEXT compaction
+                // would drop it and replace it with a summary covering only
+                // what happened after the resume, silently losing the run's
+                // first hour.
+                if (workingStateManager && checkpoint.workingState && params.compactionConfig) {
+                    const revived = restoreWorkingState(checkpoint.workingState, params.compactionConfig);
+                    workingStateManager.replaceState(revived.getState());
+                    ctx.log.info('Restored compaction working state from checkpoint', {
+                        runId: ctx.runMgr.id,
+                        checkpointId: checkpoint.id,
+                        slots: workingStateManager.slotCount(),
+                    });
+                }
+                ctx.log.info('Restored budgets from checkpoint', {
+                    runId: ctx.runMgr.id,
+                    checkpointId: checkpoint.id,
+                    totalTokens: checkpoint.tokenUsage.totalTokens,
+                    totalCost: checkpoint.costInfo.totalCost,
+                    iteration: checkpoint.guardState.iterationCount,
+                    elapsedMs: checkpoint.guardState.elapsedMs,
+                });
                 pushSystemMessages();
-                for (const msg of checkpoint.messages) {
+                // A human answered the park in a different process; apply that
+                // answer to the tool calls they were actually shown. Without
+                // this the repair below throws the approval away and the model
+                // re-decides, so "yes, delete that row" degrades into "ask
+                // again and hope it asks for the same thing".
+                pendingResume =
+                    params.pendingDecision && checkpoint.pending
+                        ? planPendingResume(checkpoint, params.pendingDecision, ctx.log)
+                        : null;
+                // Results of tools that finished before the process died. The
+                // executor already emits one `tool_completed` per tool inline
+                // and the transcript already persists it, so the record was
+                // durable all along — it was simply never read back, and the
+                // resumed run re-ran calls that had already charged a card or
+                // sent an email.
+                const unanswered = unansweredToolCalls(checkpoint.messages);
+                recoveredResults =
+                    unanswered.length > 0
+                        ? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log)
+                        : new Map();
+                // A batch caught MID-execution is a resume, not a fresh
+                // decision: stripping the turn and letting the model re-decide
+                // would re-run everything that already ran. Only taken when
+                // the transcript proves execution had begun — a tool-review
+                // park has no completions and keeps the cheap repair below.
+                if (!pendingResume && recoveredResults.size > 0) {
+                    pendingResume = planCrashResume(checkpoint, recoveredResults, ctx.log);
+                }
+                // A checkpoint taken at a tool-review park snapshots the
+                // assistant turn AFTER its `tool_use` blocks but BEFORE any
+                // `tool_result` exists, so replaying it verbatim would send a
+                // malformed request on the first model call of the resumed
+                // run. Repair the incomplete turn rather than inheriting it:
+                // the model re-decides from the last valid state.
+                //
+                // The pending-decision path uses the SAME repair: it strips
+                // the unanswered turn here and `applyPendingResume` re-appends
+                // it together with the results that answer it, so the history
+                // stays well-formed either way.
+                const dangling = findDanglingMessages(checkpoint.messages);
+                const restoredMessages = dangling.isValid
+                    ? checkpoint.messages
+                    : removeDanglingMessages(checkpoint.messages);
+                if (!dangling.isValid && !pendingResume) {
+                    ctx.log.warn('Checkpoint contained unanswered tool calls — repaired on restore', {
+                        runId: ctx.runMgr.id,
+                        checkpointId: checkpoint.id,
+                        unansweredAssistantTurns: dangling.assistantsWithUnmatchedCalls.length,
+                        orphanedToolMessages: dangling.orphanedToolMessages.length,
+                        removed: checkpoint.messages.length - restoredMessages.length,
+                    });
+                }
+                for (const msg of restoredMessages) {
                     if (msg.role === 'system') {
                         // Re-push the FRESH static/dynamic floor (done above) but PRESERVE
                         // the two system messages that carry irreplaceable run state: the
@@ -376,18 +672,165 @@ export async function* query(params) {
                     rootDir: sandbox.rootDir,
                 });
             }
+            // Crash-save handlers live for exactly the run's lifetime, and are
+            // removed in the `finally` below. Opt-in — see `emergencySave`.
+            if (params.emergencySave) {
+                const runDir = ctx.runMgr.getRunDir();
+                if (runDir) {
+                    emergencyManager = EmergencySaveManager.instance(ctx.log);
+                    emergencyManager.attach(ctx.runMgr, runDir, ctx.log);
+                }
+                else {
+                    ctx.log.warn('emergencySave requested but the run has no output directory — crash dumps disabled', { runId: ctx.runId });
+                }
+            }
+            // Before the first model call: the cheapest place to refuse, since
+            // nothing has been spent. Previously unreachable — `run_start`
+            // fires with only `{ runId }` and `run_started` carries only the
+            // system prompt, so no hook could see the user's message.
+            const inputVerdict = await runInputGuardrails(params.inputGuardrails, {
+                runId: ctx.runId,
+                messages: ctx.runMgr.messages,
+                ...(segments?.static ? { systemPrompt: segments.static } : {}),
+            }, ctx.log);
+            if (inputVerdict.blocked) {
+                await eventTranslator.emitEvent({
+                    type: 'guardrail_triggered',
+                    runId: ctx.runId,
+                    stage: 'input',
+                    action: 'block',
+                    ...(inputVerdict.name ? { guardrail: inputVerdict.name } : {}),
+                    ...(inputVerdict.reason ? { reason: inputVerdict.reason } : {}),
+                });
+                yield* eventTranslator.drainPending();
+                ctx.runMgr.setStopReason('input_guardrail');
+                ctx.runMgr.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail');
+                yield* resultAssembler.completeRun(rootSpan);
+                return ctx.runMgr.getRun();
+            }
+            // Honor the approval a human already gave, before the loop's
+            // first model call. The sandbox exists by now, so an approved
+            // tool that needs one gets it.
+            if (pendingResume) {
+                ctx.log.info('Applying a pending HITL decision to the checkpointed tool calls', {
+                    runId: ctx.runId,
+                    tools: pendingResume.response.message.toolCalls?.map((tc) => tc.function.name),
+                    denied: pendingResume.denials.size,
+                });
+                // Hand the recorded answer to the already-built tool. The tool
+                // closed over its registry when the agent was constructed,
+                // long before this run existed, so the answers are copied in
+                // rather than passed down.
+                if (pendingResume.answers && params.pendingAnswers) {
+                    for (const [questionId, answer] of pendingResume.answers.entries()) {
+                        params.pendingAnswers.set(questionId, answer);
+                    }
+                }
+                await applyPendingResume(pendingResume, ctx.runMgr, toolExecutor, recoveredResults);
+                yield* eventTranslator.drainPending();
+                // The decision has now actually been carried out, so the park
+                // is no longer outstanding. Without this the checkpoint keeps
+                // reporting `pending` with no `resolvedAt`, and an approval
+                // queue re-serves a destructive call that already ran — which
+                // defeats the entire point of recording the park.
+                const resolvedCheckpointId = pendingResume.checkpointId;
+                if (params.pendingDecision) {
+                    await checkpointMgr
+                        .unpark(resolvedCheckpointId, params.pendingDecision)
+                        .catch((err) => {
+                        ctx.log.error('Applied a pending decision but failed to clear the park', {
+                            runId: ctx.runId,
+                            checkpointId: resolvedCheckpointId,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        return null;
+                    });
+                }
+            }
             yield* iterationOrchestrator.runLoop();
             if (params.pluginManager) {
                 const hookResults = await params.pluginManager.executeHooks('run_end', { runId: ctx.runId }, eventTranslator.emitEvent);
                 applyLifecycleHookResults('run_end', hookResults);
                 yield* eventTranslator.drainPending();
             }
+            // Hand the step record to the run before it settles, so the
+            // returned `Run` carries it.
+            ctx.runMgr.setSteps(iterationOrchestrator.getSteps());
+            // Gates the FINAL result, not the stream — `text_delta` already
+            // reached the host as the model produced it. A rewrite is
+            // therefore a correction, and the event says so; buffering every
+            // token to gate the stream itself would trade the streaming UX
+            // for the guarantee, which is the host's call, not the SDK's.
+            if (params.outputGuardrails && params.outputGuardrails.length > 0) {
+                // Read what the run produced WITHOUT settling it. This used to
+                // call `markCompleted()` just to materialize the text, which
+                // force-marked a cancelled or paused run `completed` merely
+                // because a guardrail was configured — the presence of a
+                // safety check silently rewrote the run's own outcome.
+                const produced = ctx.runMgr.materializeResult();
+                const outputVerdict = await runOutputGuardrails(params.outputGuardrails, { runId: ctx.runId, output: produced, messages: ctx.runMgr.messages }, ctx.log);
+                if (outputVerdict.blocked) {
+                    await eventTranslator.emitEvent({
+                        type: 'guardrail_triggered',
+                        runId: ctx.runId,
+                        stage: 'output',
+                        action: 'block',
+                        ...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
+                        ...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+                    });
+                    yield* eventTranslator.drainPending();
+                    ctx.runMgr.setStopReason('output_guardrail');
+                    ctx.runMgr.setLastError(outputVerdict.reason ?? 'blocked by an output guardrail');
+                    ctx.runMgr.setResult('');
+                }
+                else if (outputVerdict.rewritten !== undefined) {
+                    await eventTranslator.emitEvent({
+                        type: 'guardrail_triggered',
+                        runId: ctx.runId,
+                        stage: 'output',
+                        action: 'rewrite',
+                        ...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
+                        ...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+                    });
+                    yield* eventTranslator.drainPending();
+                    ctx.runMgr.setResult(outputVerdict.rewritten);
+                }
+            }
             yield* resultAssembler.completeRun(rootSpan);
         }
         catch (err) {
+            // A failed run still spent its steps; report them.
+            ctx.runMgr.setSteps(iterationOrchestrator.getSteps());
             yield* resultAssembler.handleError(err, rootSpan);
         }
         finally {
+            // Release the process's termination path as soon as this run is
+            // done with it. Leaving the handlers installed would keep a
+            // WeakRef'd, settled run as the crash target for the rest of the
+            // process's life.
+            emergencyManager?.detach();
+            // Same reasoning for the question channel: the tools outlive the
+            // run that bound them, so leaving it attached would have a later
+            // run's question written into this run's checkpoint store.
+            params.questionParks?.unbind();
+            // Offer what the run learned to whoever decides what is worth
+            // keeping. In `finally` and awaited: a run that failed still
+            // discovered things, and a fire-and-forget write would race the
+            // process exiting on a one-shot CLI run. A throw here is
+            // swallowed — a memory that failed to form must not retract an
+            // answer that was already produced.
+            const candidate = memoryCandidateFor(ctx.runId, workingStateManager);
+            if (params.promoteMemory && candidate) {
+                try {
+                    await params.promoteMemory(candidate);
+                }
+                catch (promoteErr) {
+                    ctx.log.error('Memory promotion threw — the run is unaffected', {
+                        runId: ctx.runId,
+                        error: promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
+                    });
+                }
+            }
             // --- Sandbox lifecycle: destroy after run ---
             if (sandbox) {
                 const sandboxId = sandbox.id;
@@ -408,6 +851,11 @@ export async function* query(params) {
                 }
             }
             unsubscribeTaskStore?.();
+            // Keyed by HOW it settled, not just that it did: a run that was
+            // cancelled and a run that hit its budget have very different
+            // duration distributions, and averaging them together describes
+            // neither.
+            recordRunDuration(ctx.runMgr.getRun().status ?? 'unknown', Date.now() - runStartedAt);
             rootSpan.end();
         }
         return await resultAssembler.finalize();