@namzu/sdk 22.1.0 → 25.0.0

package/src/runtime/query/executor.ts

@@ -34,6 +34,7 @@ import type {
 	ToolCallRepairReason,
 } from '../../types/tool/repair.js'
 import { abortReasonText } from '../../utils/abort.js'
+import { type BackoffPolicy, backoffWithJitter, sleep } from '../../utils/backoff.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
@@ -74,6 +75,33 @@ export const DEFAULT_TOOL_CONCURRENCY = 8
  */
 export const HOOK_RETRY_BUDGET = 1
 
+/**
+ * Wait between in-loop tool retry attempts.
+ *
+ * There was none. A tool that declared itself retryable was re-run the
+ * instant it failed, as many times as its budget allowed — and the failures
+ * worth retrying are the ones an immediate retry makes worse: a rate limit
+ * answers the second call faster than it recovers, a contended lock is still
+ * held, a connection that has not finished opening has not finished opening.
+ *
+ * The numbers are the provider policy's, deliberately, and not because a tool
+ * is a model call. Nothing here has been measured against tools specifically,
+ * and inventing a second curve to look considered would be a guess wearing
+ * different digits; the shared one is at least the curve this codebase has
+ * already run in anger. Full jitter draws each wait from `[0, curve]`, so the
+ * first retry of a tool with the shipped budget waits under half a second on
+ * average.
+ *
+ * The ceiling is inert at the budgets anyone sets — a tool declaring
+ * `maxRetries: 3` never reaches 2s — and binds only a host that sets a large
+ * one. Override with {@link ToolExecutorConfig.toolRetryBackoff}; set
+ * `initialDelayMs: 0` for the previous no-wait behaviour.
+ */
+export const DEFAULT_TOOL_RETRY_BACKOFF: BackoffPolicy = {
+	initialDelayMs: 500,
+	maxDelayMs: 16_000,
+}
+
 /**
  * An empty arguments string means "no arguments", not "malformed" — the
  * shape a no-parameter tool arrives in.
@@ -95,6 +123,16 @@ export interface ToolExecutorConfig {
 	pluginManager?: PluginLifecycleManager
 	/** Run-level default deadline; per-tool `timeoutMs` overrides it. */
 	toolTimeoutMs?: number
+	/**
+	 * Wait between in-loop retries of a failed tool call. Defaults to
+	 * {@link DEFAULT_TOOL_RETRY_BACKOFF}.
+	 *
+	 * Applies only to a tool that opted into retrying at all
+	 * ({@link ToolDefinition.maxRetries}) or to a `post_tool_use` hook that
+	 * asked for one, so a run whose tools all take the shipped default of
+	 * zero retries never sleeps here.
+	 */
+	toolRetryBackoff?: Partial<BackoffPolicy>
 	/** Max concurrently-executing concurrency-safe tools. */
 	maxToolConcurrency?: number
 
@@ -648,6 +686,10 @@ export class ToolExecutor {
 		// because the SDK cannot know a tool is idempotent — silently
 		// re-running a write or a payment is worse than never retrying.
 		const maxRetries = Math.max(0, this.config.tools.get(toolName)?.maxRetries ?? 0)
+		const backoff: BackoffPolicy = {
+			...DEFAULT_TOOL_RETRY_BACKOFF,
+			...this.config.toolRetryBackoff,
+		}
 		for (let attempt = 1; ; attempt++) {
 			// A missing file will not appear on the second attempt; burning
 			// the budget on it only delays the error the model needs to see.
@@ -664,14 +706,46 @@ export class ToolExecutor {
 			const budget = post.retry ? Math.max(maxRetries, HOOK_RETRY_BUDGET) : maxRetries
 			if (attempt > budget) break
 
+			// Wait before trying again, on the curve the provider path has
+			// used all along. This loop had NO delay: a tool failing on a
+			// transient condition — a rate-limited HTTP call, a lock, a cold
+			// connection — was re-run immediately, several times, which is the
+			// pattern most likely to prolong the very condition it is retrying
+			// against.
+			//
+			// Full jitter rather than a fixed wait, and the concurrency that
+			// makes it matter is one this loop creates itself: a model emits a
+			// batch of parallel calls, `executeBatch` runs up to
+			// DEFAULT_TOOL_CONCURRENCY of them at once, they hit the same
+			// rate-limited endpoint and fail together. A fixed backoff would
+			// resynchronise that batch on every attempt.
+			//
+			// `attempt` is 1-based here and `backoffWithJitter` is 0-based, so
+			// the first retry draws from `[0, initialDelayMs]`.
+			const delayMs = backoffWithJitter(attempt - 1, backoff)
+
 			this.log.info('Retrying a failed tool call', {
 				runId: this.config.runId,
 				tool: toolName,
 				attempt,
 				budget,
 				requestedByHook: post.retry,
+				delayMs,
 				error: result.error,
 			})
+
+			try {
+				await sleep(delayMs, this.config.abortSignal)
+			} catch {
+				// Stopped mid-backoff. Give up retrying and let the failure
+				// already in `result` be this call's answer, rather than
+				// throwing: every `tool_use` must be answered by a
+				// `tool_result` with the same id, and an abort escaping from
+				// here would leave this one open in the transcript for a
+				// resume to trip over.
+				break
+			}
+
 			result = await this.runOnce(toolName, input, toolContext)
 			post = await this.runPostToolHook(toolName, input, result)
 		}

package/src/runtime/query/index.ts

@@ -83,6 +83,7 @@ import type { TaskStore } from '../../types/task/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { VerificationGateConfig } from '../../types/verification/index.js'
+import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { getRootLogger } from '../../utils/logger.js'
 import { VerificationGate } from '../../verification/gate.js'
@@ -98,7 +99,7 @@ import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js'
 import { applyLifecycleHookResults } from './plugin-hooks.js'
 import { PromptBuilder } from './prompt.js'
 import type { PromptSegments } from './prompt.js'
-import type { PendingAnswers, QuestionParkBinding } from './question-park.js'
+import { PendingAnswers, QuestionParkBinding } from './question-park.js'
 import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
@@ -168,14 +169,20 @@ export interface QueryParams {
 	emergencySave?: boolean
 
 	/**
-	 * Durability for questions raised from inside a tool.
+	 * Durability for questions raised by a tool that closed over its
+	 * binding before the run existed.
 	 *
-	 * The tool that asks is built before the run exists, so the binding is
-	 * created by whoever builds the tools and attached here — that is what
-	 * lets one tool instance be durable inside a run and inert outside one.
-	 * Without it, a question park exists only as a suspended `await`: kill
-	 * the process while somebody is looking at the card and the answer can
-	 * never be applied.
+	 * The built-in `ask_user_question` is built with the agent's tool
+	 * registry, so only whoever builds the tools can hand it one — that is
+	 * what lets a single tool instance be durable inside a run and inert
+	 * outside one. Without it, THAT tool's park is only a suspended
+	 * `await`: kill the process while somebody is looking at the card and
+	 * the answer can never be applied.
+	 *
+	 * Not required for `ToolContext.requestPause`. The run builds that
+	 * seam per call and binds its own recorder when none is passed, so a
+	 * pause raised from a host-authored tool is durable on every surface
+	 * rather than only on the one agent class that supplies this.
 	 */
 	questionParks?: QuestionParkBinding
 
@@ -192,16 +199,28 @@ export interface QueryParams {
 	/**
 	 * The registry a re-entered `ask_user_question` reads its answer from.
 	 *
-	 * Same shape as {@link questionParks}: the tool is built before the run
-	 * exists, so the instance is created by whoever builds the tools and
-	 * filled here on the resume path. Without it a resumed run re-asks a
-	 * question the user already answered.
+	 * Same shape, same reason and same limit as {@link questionParks}: it
+	 * exists for a tool that closed over the instance before the run did,
+	 * and without it a resumed run re-asks that tool's question. A pause
+	 * from `ToolContext.requestPause` needs none, because the run fills
+	 * its own on the resume path.
 	 */
 	pendingAnswers?: PendingAnswers
 
 	/** Default per-tool execution deadline. See {@link ToolDefinition.timeoutMs}. */
 	toolTimeoutMs?: number
 
+	/**
+	 * Wait between in-loop retries of a failed tool call, with full jitter.
+	 * Defaults to {@link DEFAULT_TOOL_RETRY_BACKOFF}.
+	 *
+	 * Only reached by a tool that opted into retrying
+	 * ({@link ToolDefinition.maxRetries}) or a `post_tool_use` hook that asked
+	 * for one. Set `initialDelayMs: 0` for the retry-immediately behaviour
+	 * this loop had before it had any backoff at all.
+	 */
+	toolRetryBackoff?: Partial<BackoffPolicy>
+
 	/** Max concurrently-executing concurrency-safe tools in one batch. */
 	maxToolConcurrency?: number
 
@@ -874,6 +893,25 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		? []
 		: withDeferredDiscoveryTool(params.tools, params.allowedTools)
 
+	// The two halves of a durable pause, owned by the RUN when the host
+	// does not own them.
+	//
+	// `SupervisorAgent` builds both before the run exists, because the
+	// tools it builds close over them, and it passes them in. Nothing else
+	// could: neither type is exported from `public-runtime.ts`, so a host
+	// on `ReactiveAgent`, `drainQuery` or `resumeRun` had no way to supply
+	// either — and `ToolContext.requestPause`, which every tool author is
+	// handed, silently wrote no checkpoint and could receive no answer on
+	// those surfaces. Which agent class the host happened to pick is not
+	// visible at the call site, so the degradation was invisible too.
+	//
+	// A run-local pair is enough for the general seam because `query()`
+	// builds its `createToolPause` itself, below, and can hand it the
+	// run's own. Pinned by the "a pause is durable on any surface" cases
+	// in `__tests__/tool-pause-resume.test.ts`.
+	const questionParks = params.questionParks ?? new QuestionParkBinding()
+	const pendingAnswers = params.pendingAnswers ?? new PendingAnswers()
+
 	//  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()
@@ -891,6 +929,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			invocationState: params.invocationState,
 			pluginManager: params.pluginManager,
 			...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
+			...(params.toolRetryBackoff !== undefined
+				? { toolRetryBackoff: params.toolRetryBackoff }
+				: {}),
 			...(params.maxToolConcurrency !== undefined
 				? { maxToolConcurrency: params.maxToolConcurrency }
 				: {}),
@@ -915,8 +956,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					runId: ctx.runId,
 					toolUseId,
 					parkHandler: params.resumeHandler,
-					...(params.questionParks ? { recorder: params.questionParks } : {}),
-					...(params.pendingAnswers ? { pendingAnswers: params.pendingAnswers } : {}),
+					recorder: questionParks,
+					pendingAnswers,
 				}),
 		},
 		ctx.activityStore,
@@ -1130,7 +1171,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// 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({
+		questionParks.bind({
 			record: async (question) => {
 				try {
 					const checkpoint = await checkpointMgr.create(ctx.runMgr, ctx.runMgr.currentIteration)
@@ -1537,9 +1578,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				// 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) {
+				if (pendingResume.answers) {
 					for (const [questionId, answer] of pendingResume.answers.entries()) {
-						params.pendingAnswers.set(questionId, answer)
+						pendingAnswers.set(questionId, answer)
 					}
 				}
 
@@ -1642,7 +1683,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// 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()
+			questionParks.unbind()
 
 			// Offer what the run learned to whoever decides what is worth
 			// keeping. In `finally` and awaited: a run that failed still

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

@@ -32,6 +32,7 @@ import type { AnswerReview } from '../../../types/run/answer-review.js'
 import type {
 	PrepareStepResult,
 	RunEvent,
+	StepFailure,
 	StepProvenance,
 	StepResult,
 	StopReason,
@@ -258,6 +259,30 @@ export class IterationOrchestrator {
 					{},
 					parentContext(this.ctx.rootSpan),
 				)
+
+				// Everything the step record needs, hoisted so the `catch` can
+				// read whatever the iteration got as far as computing.
+				//
+				// The failure path is the one the ledger's own argument was
+				// written for and the one it never reached: an iteration that
+				// threw recorded a span exception and re-threw, so the turn with
+				// no record was exactly the turn that went wrong. A reader could
+				// not tell that from a turn that never happened.
+				//
+				// Declared as `let` with real initial values rather than left
+				// undefined, because a failure BEFORE the snapshot below is
+				// taken has spent nothing, and these are then exact. The success
+				// path is untouched: the assignments inside the try still happen
+				// where they always did, so compaction and the working-memory
+				// refresh stay outside a successful step's window.
+				let stepStartedAt = Date.now()
+				let usageBefore: TokenUsage = { ...runMgr.tokenUsage }
+				let costBefore: CostInfo = { ...runMgr.costInfo }
+				let stepModel = model
+				let stepMessageId: MessageId | undefined
+				let stepResponse: ChatCompletionResponse | undefined
+				let stepServedBy: StepProvenance | undefined
+
 				try {
 					// Tool spans for this turn belong under this iteration. Inside
 					// the try rather than before it: a throw from any of these left
@@ -303,9 +328,9 @@ export class IterationOrchestrator {
 					// tool_use/tool_result blocks.
 					// 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 }
+					stepStartedAt = Date.now()
+					usageBefore = { ...runMgr.tokenUsage }
+					costBefore = { ...runMgr.costInfo }
 
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
@@ -320,7 +345,7 @@ export class IterationOrchestrator {
 					// still call any of them by name.
 					this.ctx.toolExecutor.setStepAllowedTools(stepAllowedTools)
 					const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools)
-					const stepModel = step.model ?? model
+					stepModel = step.model ?? model
 
 					const baseMessages = forceFinalize
 						? [
@@ -389,6 +414,16 @@ export class IterationOrchestrator {
 					// aggregated `ChatCompletionResponse` for the legacy
 					// downstream paths (assistantMsg construction, working
 					// state extraction, telemetry attribute stamping).
+					//
+					// The message id is minted HERE, immediately before the call
+					// that announces it,
+					// rather than inside that call. The return value never arrives
+					// when the stream throws, so a step recorded from the catch
+					// could otherwise never name the message — and a stream that
+					// died part-way has already emitted both `message_started` and
+					// `message_completed` under this id, which is the trail a
+					// reader wants most on exactly that turn.
+					stepMessageId = generateMessageId()
 					const { response, messageId } = yield* streamProviderTurn(
 						this.ctx.provider,
 						{
@@ -424,7 +459,9 @@ export class IterationOrchestrator {
 						forceFinalize,
 						this.ctx.log,
 						iterSpan,
+						stepMessageId,
 					)
+					stepResponse = response
 
 					// Who answered THIS turn.
 					//
@@ -459,6 +496,7 @@ export class IterationOrchestrator {
 							chainIndex: member.index,
 						}
 					})()
+					stepServedBy = servedBy
 
 					// Main-loop turn: also records the prompt size compaction reads.
 					//
@@ -1014,6 +1052,76 @@ export class IterationOrchestrator {
 					})
 					yield* this.ctx.drainPending()
 				} catch (err) {
+					const cancelled = this.ctx.abortController.signal.aborted
+
+					// This iteration gets a step too, and it is the one the
+					// argument three hundred lines above was actually about.
+					//
+					// That docblock makes the case for a rejected tool batch — "a
+					// run that spent a turn getting its tools refused still spent
+					// the tokens" — and every call site it produced sat on a
+					// success path. So the ledger was complete except on the turns
+					// that failed, which is the worst shape it could have: an
+					// evidence record that goes quiet exactly where something went
+					// wrong reads as "nothing went wrong". A reader could not
+					// distinguish iteration N failing from iteration N never
+					// happening, while the events said plainly that it started.
+					//
+					// Recorded HERE, at the top of the catch, rather than at each
+					// of its exits — the same reasoning the success path already
+					// wrote down for itself. All three exits spend a turn: the
+					// cancellation breaks, the overflow-relief retry continues
+					// under a NEW iteration number (so its tokens belong to no
+					// later step), and the re-throw ends the run.
+					//
+					// What it carries is what the iteration got as far as knowing.
+					// `usage` is the same subtraction a successful step makes, so
+					// a turn that failed after the provider answered carries that
+					// answer's tokens, and one that failed before it carries the
+					// zero it actually spent. Nothing is estimated to fill a gap.
+					//
+					// At most ONE step per iteration. Both success paths record
+					// before the work that follows them — the advisory phase, the
+					// structured-output capture, the `iteration_end` hooks, the
+					// terminal `iteration_completed` — and any of those can throw
+					// into here. A second entry numbered N would double-count that
+					// turn's tokens against `run.tokenUsage`, which is the same
+					// class of wrong as dropping them and harder to notice, since
+					// the ledger would look fuller rather than emptier. That turn's
+					// own verdict is already written down; the failure that
+					// 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),
+						})
+					} else {
+						this.recordStep({
+							stepNumber: iterationNum,
+							model: stepModel,
+							...(stepServedBy ? { servedBy: stepServedBy } : {}),
+							...(stepMessageId ? { messageId: stepMessageId } : {}),
+							...(stepResponse ? { response: stepResponse } : {}),
+							// Tool outcomes are produced and returned together by
+							// `runToolReview`, so a throw from inside it leaves none
+							// to salvage: an empty list here means "none came back",
+							// which is what the shorter-than-`toolCalls` contract
+							// says.
+							toolResults: [],
+							toolExecutionMs: 0,
+							startedAt: stepStartedAt,
+							usageBefore,
+							costBefore,
+							unfinished: cancelled
+								? { finishReason: 'cancelled' }
+								: {
+										finishReason: 'error',
+										failure: describeStepFailure(err, this.ctx.provider.id),
+									},
+						})
+					}
+
 					// A Stop that aborted the in-flight turn surfaces here as a
 					// thrown abort (the provider stream was raced against the run
 					// signal). Settle it as a CANCELLATION — mirroring the
@@ -1021,7 +1129,7 @@ export class IterationOrchestrator {
 					// recording it as an SDK failure (error span + failed activity)
 					// and re-throwing. The run then returns cleanly with a
 					// 'cancelled' stop reason instead of propagating an error.
-					if (this.ctx.abortController.signal.aborted) {
+					if (cancelled) {
 						runMgr.setStopReason('cancelled')
 						runMgr.markCancelled()
 						break
@@ -1308,39 +1416,69 @@ export class IterationOrchestrator {
 	private recordStep(input: {
 		stepNumber: number
 		model: string
-		servedBy: StepProvenance
-		messageId: MessageId
-		response: ChatCompletionResponse
+		servedBy?: StepProvenance
+		messageId?: MessageId
+		/**
+		 * The turn's response. Absent only when the iteration failed before
+		 * the provider produced one — see `unfinished`.
+		 */
+		response?: ChatCompletionResponse
 		toolResults: readonly ToolCallOutcome[]
 		toolExecutionMs: number
 		startedAt: number
 		usageBefore: TokenUsage
 		costBefore: CostInfo
+		/**
+		 * Set only by the `catch`, for an iteration that did not finish.
+		 *
+		 * The same writer builds both records on purpose: a failed turn's
+		 * step is a `StepResult` like any other, so a caller reconstructing
+		 * cost or history sorts them together instead of discovering that
+		 * failures live somewhere else.
+		 */
+		unfinished?: { finishReason: 'error' | 'cancelled'; failure?: StepFailure }
 	}): void {
 		const { runMgr } = this.ctx
-		const toolCalls = input.response.message.toolCalls ?? []
+		const toolCalls = input.response?.message.toolCalls ?? []
 		const byId = new Map(input.toolResults.map((r) => [r.toolCallId, r]))
 
 		const step: StepResult = {
 			stepNumber: input.stepNumber,
 			model: input.model,
-			servedBy: input.servedBy,
-			messageId: input.messageId,
-			content: input.response.message.content,
+			...(input.servedBy ? { servedBy: input.servedBy } : {}),
+			...(input.messageId ? { messageId: input.messageId } : {}),
+			content: input.response?.message.content ?? null,
 			toolCalls,
 			// Ordered by the tool CALLS, not by completion, so the record
 			// matches what the model asked for.
-			toolResults: toolCalls.map((tc) => {
+			//
+			// On an unfinished step the calls with no outcome are DROPPED
+			// rather than filled with `{output: '', isError: false}`. That
+			// filler is a reading of "the batch was refused" on the success
+			// path, where every call in a batch shares one verdict; under a
+			// step that says `error` it would say a tool ran and returned
+			// nothing successfully, which is the same lie one level down as
+			// the missing step itself.
+			toolResults: toolCalls.flatMap((tc) => {
 				const outcome = byId.get(tc.id)
-				return {
-					toolCallId: tc.id,
-					toolName: tc.function.name,
-					output: outcome?.output ?? '',
-					isError: outcome?.isError ?? false,
-					durationMs: 0,
-				}
+				if (input.unfinished && !outcome) return []
+				return [
+					{
+						toolCallId: tc.id,
+						toolName: tc.function.name,
+						output: outcome?.output ?? '',
+						isError: outcome?.isError ?? false,
+						durationMs: 0,
+					},
+				]
 			}),
-			finishReason: input.response.finishReason,
+			// The turn's own verdict where there is one. A step that ended in
+			// the catch has none — no provider reported `error` or
+			// `cancelled` — so `unfinished` wins even when a response had
+			// already arrived: a turn that answered and then threw during
+			// tool execution did not end in `tool_calls`.
+			finishReason: input.unfinished?.finishReason ?? input.response?.finishReason ?? 'error',
+			...(input.unfinished?.failure ? { failure: input.unfinished.failure } : {}),
 			usage: subtractUsage(runMgr.tokenUsage, input.usageBefore),
 			costDelta: {
 				...runMgr.costInfo,
@@ -1352,7 +1490,26 @@ export class IterationOrchestrator {
 		}
 
 		this.steps.push(step)
-		this.ctx.onStepFinish?.(step)
+
+		if (!input.unfinished) {
+			this.ctx.onStepFinish?.(step)
+			return
+		}
+
+		// Nothing here is allowed to throw over the failure that is already
+		// unwinding — the same rule `settleCancelledTurn` states for the
+		// cancellation path. A host callback that throws while being told a
+		// turn failed would REPLACE the reason the turn failed, so the run
+		// would report the observer's bug and lose the original.
+		try {
+			this.ctx.onStepFinish?.(step)
+		} catch (err) {
+			this.ctx.log.warn('onStepFinish threw while recording a failed step', {
+				runId: runMgr.id,
+				step: input.stepNumber,
+				error: toErrorMessage(err),
+			})
+		}
 	}
 
 	/** Turns spent asking the model again for a valid structured output. */
@@ -1621,6 +1778,26 @@ export class IterationOrchestrator {
 	}
 }
 
+/**
+ * Fold whatever ended an iteration into the record a reader gets.
+ *
+ * Classified through `classifyProviderError` — the same call the catch
+ * already makes to decide whether compaction relief applies — so the step's
+ * verdict and the loop's own decision cannot drift apart. It also handles a
+ * failure that is not a provider failure at all: the code set's `unknown`
+ * means "unclassifiable", which is the true answer for a plugin hook that
+ * threw and is left saying so rather than dressed up as something specific.
+ */
+function describeStepFailure(err: unknown, providerId: string): StepFailure {
+	const classified = classifyProviderError(err, providerId)
+	return {
+		message: toErrorMessage(err),
+		code: classified.code,
+		...(classified.status !== undefined ? { status: classified.status } : {}),
+		retryable: classified.retryable,
+	}
+}
+
 /** Per-step usage: the delta between two cumulative snapshots. */
 function subtractUsage(after: TokenUsage, before: TokenUsage): TokenUsage {
 	return {

package/src/runtime/query/iteration/stream-turn.ts

@@ -134,6 +134,19 @@ export async function* streamProviderTurn(
 	forceFinalize: boolean,
 	log: Logger,
 	parentSpan?: Span,
+	/**
+	 * The id to announce this message under.
+	 *
+	 * Supplied by the loop so a turn that THROWS still leaves the caller
+	 * holding the id it announced. The return value never arrives on a
+	 * failure, so without this the one case where a failed step most wants
+	 * to point at the event stream — a stream that died after
+	 * `message_started`, having already emitted `message_completed` on the
+	 * way out — is precisely the case that could not.
+	 *
+	 * Optional, so a caller with no use for the id is unchanged.
+	 */
+	announceAs?: import('../../../types/ids/index.js').MessageId,
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
 	// The `chat {model}` span the GenAI conventions require. There was none:
 	// `chatSpanName` existed with zero call sites, so a trace carried no LLM
@@ -151,7 +164,7 @@ export async function* streamProviderTurn(
 		...(params.maxTokens !== undefined ? { [GENAI.REQUEST_MAX_TOKENS]: params.maxTokens } : {}),
 	})
 
-	const messageId = generateMessageId()
+	const messageId = announceAs ?? generateMessageId()
 	await emitEvent({ type: 'message_started', runId, iteration, messageId })
 	yield* drainPending()
 
@@ -194,7 +207,12 @@ export async function* streamProviderTurn(
 	// verbatim — so the map is drained in index order at the end.
 	const reasoningBuckets = new Map<
 		number,
-		{ type: 'thinking' | 'redacted_thinking'; text: string; signature?: string; encrypted?: string }
+		{
+			type: 'thinking' | 'redacted_thinking'
+			text: string
+			signature?: string
+			encrypted?: string
+		}
 	>()
 
 	// Citations arrive as their own deltas, in the order the model made
@@ -205,7 +223,10 @@ export async function* streamProviderTurn(
 	let streamError: string | undefined
 	let streamCause: unknown
 
-	const stream = provider.chatStream({ ...params, stream: true }) as AsyncIterable<StreamChunk>
+	const stream = provider.chatStream({
+		...params,
+		stream: true,
+	}) as AsyncIterable<StreamChunk>
 
 	// Drive the stream manually so each `.next()` can be RACED against the run
 	// abort: a Stop tears the in-flight model request down (the provider got

package/src/runtime/query/resume-pending.ts

@@ -9,6 +9,7 @@ import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { Logger } from '../../utils/logger.js'
 import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
 import { PendingAnswers } from './question-park.js'
+import { isPauseForCall } from './tool-pause.js'
 
 /**
  * Apply a decision collected out-of-band to the tool calls a run parked on.
@@ -154,7 +155,15 @@ function planQuestionResume(
 	// otherwise have its answer delivered to whatever tool now holds that
 	// slot — the misdirection the asking tool's own id guard exists to
 	// prevent, checked here too because by then the tool has been entered.
-	if (!assistant.toolCalls.some((tc) => tc.id === questionId)) {
+	//
+	// Through `isPauseForCall` rather than by equality, because a parked
+	// question id is not a call id. The general seam appends the tool
+	// author's pause name to it, so equality compared
+	// `call_1:target_environment` against `call_1`, could never hold, and
+	// refused every cross-process resume of a host-authored pause. Only
+	// the built-in question tool got through, and only because it parks
+	// under the bare tool-use id.
+	if (!assistant.toolCalls.some((tc) => isPauseForCall(questionId, tc.id))) {
 		log.error('The parked question does not belong to any unanswered call in this turn', {
 			checkpointId: checkpoint.id,
 			questionId,