@namzu/sdk 23.0.0 → 26.0.0

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,

package/src/runtime/query/tool-pause.ts

@@ -32,6 +32,43 @@ import type { PendingAnswers, QuestionParkRecorder } from './question-park.js'
  */
 export const pauseId = (toolUseId: string, name: string): string => `${toolUseId}:${name}`
 
+/**
+ * Does this pause id belong to `callId`?
+ *
+ * The other half of the scheme above, and it lives beside the mint rather
+ * than at the gate that asks it, so the two cannot drift apart again. They
+ * already had: the resume gate compared the whole parked id against a raw
+ * tool-use id, which a composite can never equal, so a pause raised
+ * through {@link createToolPause} was refused by every cross-process
+ * resume — while the built-in question tool, whose `questionId` IS the raw
+ * id, passed the same gate and worked.
+ *
+ * Asked against an id actually present in the turn rather than by
+ * splitting the composite on `:`. The left half is the provider's tool-use
+ * id and nothing forbids a colon in it, so a split takes `call:9:confirm`
+ * apart at the wrong place and then compares against `call` — a string no
+ * provider minted. Testing a `<callId>:` prefix asks about candidates that
+ * exist instead.
+ *
+ * It is not exact, and the inexactness is bounded rather than absent: a
+ * call whose id is literally `call` matches a pause raised on `call:9`.
+ * That costs nothing while the real call is also in the turn, because the
+ * pause does belong to a call there; and when it is not, the answer is
+ * filed under a key no tool asks for, so the tool asks again. A resume
+ * that re-asks, never one that misdelivers — routing below is still an
+ * exact key match.
+ *
+ * Membership only — is there a call in this turn that this pause was
+ * raised from. The full composite still ROUTES the answer, by exact key in
+ * `PendingAnswers`, which is what keeps a call that pauses twice from
+ * delivering its second answer against its first question.
+ *
+ * Every sentence above that names a condition and an outcome is pinned in
+ * `__tests__/tool-pause.test.ts`, under "the id a resume gate matches on".
+ */
+export const isPauseForCall = (pause: string, callId: string): boolean =>
+	pause === callId || pause.startsWith(`${callId}:`)
+
 interface ToolPauseDeps {
 	readonly runId: RunId
 	readonly toolUseId: string

package/src/runtime/query/tooling.ts

@@ -6,6 +6,7 @@ import type { PermissionMode } from '../../types/permission/index.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { RequestToolPause, ToolRegistryContract } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
+import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { Logger } from '../../utils/logger.js'
 import { ToolExecutor } from './executor.js'
 
@@ -22,6 +23,7 @@ export interface ToolingBootstrapConfig {
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
 	toolTimeoutMs?: number
+	toolRetryBackoff?: Partial<BackoffPolicy>
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
 	maxToolContentBytes?: number
@@ -50,6 +52,9 @@ export class ToolingBootstrap {
 				invocationState: config.invocationState,
 				pluginManager: config.pluginManager,
 				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),
+				...(config.toolRetryBackoff !== undefined
+					? { toolRetryBackoff: config.toolRetryBackoff }
+					: {}),
 				...(config.maxToolConcurrency !== undefined
 					? { maxToolConcurrency: config.maxToolConcurrency }
 					: {}),

package/src/types/agent/reactive.ts

@@ -86,6 +86,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	retry?: QueryParams['retry']
 	emergencySave?: boolean
 	toolTimeoutMs?: number
+	toolRetryBackoff?: QueryParams['toolRetryBackoff']
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
 	/**

package/src/types/connector/mcp.ts

@@ -18,7 +18,24 @@ export interface MCPStdioTransportConfig extends MCPTransportConfigBase {
 	type: 'stdio'
 	command: string
 	args?: string[]
+	/** Literal values for the child. Highest precedence. */
 	env?: Record<string, string>
+	/**
+	 * Parent variables the child may have, named one at a time.
+	 *
+	 * The spawn used to pass the whole parent environment, so a server that
+	 * needed one token received every credential the host held. It now gets
+	 * process plumbing plus what is named here and in `env`, which is what
+	 * makes the grant reviewable: the config says which secrets cross the
+	 * boundary instead of the answer being "all of them".
+	 *
+	 * Use this rather than `env` for a credential — `env` puts the value in the
+	 * config file, and this keeps it in the environment where it already lives.
+	 *
+	 * A name the parent does not hold is absent from the child rather than
+	 * empty, and does not fail the spawn.
+	 */
+	inheritEnv?: readonly string[]
 	cwd?: string
 }
 

package/src/types/provider/interface.ts

@@ -73,7 +73,23 @@ export interface LLMProvider {
 	 */
 	probeCredential?(): Promise<void>
 
-	healthCheck?(): Promise<boolean>
+	/**
+	 * Is this driver able to serve traffic? A summary bit; `doctorCheck` is
+	 * the same probe with its reasoning intact.
+	 *
+	 * `model` is the model the CALLER intends to run, and it is a parameter
+	 * rather than something the driver reads off its own config because at
+	 * least one driver's config does not carry a model at all. That driver
+	 * hardcoded an id instead, which is how its check came to probe a model
+	 * nobody used — and, once the id went stale, could not pass at any
+	 * credential, region or service state. A health check against a model the
+	 * operator does not run tests the wrong thing even while the id is valid.
+	 *
+	 * Optional, and a driver may ignore it: one that probes an endpoint rather
+	 * than a model has nothing to do with the argument. Passing it is always
+	 * safe.
+	 */
+	healthCheck?(model?: string): Promise<boolean>
 
 	/**
 	 * Optional structured health probe used by `runDoctor()`.
@@ -82,8 +98,13 @@ export interface LLMProvider {
 	 * (latency, model availability, auth status, …). Providers that
 	 * cannot be cheaply probed should return `{ status: 'inconclusive' }`
 	 * so the doctor doesn't mark them as failing — see ses_007 Q6.4.
+	 *
+	 * Takes `model` for the reason `healthCheck` does, and a driver is free to
+	 * return a SUBTYPE of `DoctorCheckResult` carrying its own machine-readable
+	 * detail. `status` is what `runDoctor()` reads; a caller holding the
+	 * concrete driver can read more.
 	 */
-	doctorCheck?(): Promise<DoctorCheckResult>
+	doctorCheck?(model?: string): Promise<DoctorCheckResult>
 
 	/**
 	 * Which {@link ChatCompletionParams.effort} levels this model accepts,

package/src/types/run/step.ts

@@ -1,6 +1,7 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { MessageId } from '../ids/index.js'
 import type { ToolCall } from '../message/index.js'
+import type { ProviderErrorCode } from '../provider/errors.js'
 
 /**
  * What one iteration of the agent loop did.
@@ -55,13 +56,56 @@ export interface StepResult {
 	 * it is handed.
 	 */
 	servedBy?: StepProvenance
-	messageId: MessageId
+	/**
+	 * The assistant message this step produced.
+	 *
+	 * Absent only on a step whose iteration ended before the model's message
+	 * was announced — a compaction failure, a lifecycle hook that threw, a
+	 * transport error raised before the first chunk. Absence is left meaning
+	 * "there was no message" rather than filled with an id the event stream
+	 * never carried: a `messageId` a reader cannot find a `message_started`
+	 * for is worse evidence than no id at all, because it invites the
+	 * correlation and then loses it.
+	 *
+	 * Present, and correlatable, on every step whose iteration got as far as
+	 * the provider call — including one that failed mid-stream. The loop
+	 * mints the id before the call that announces it, and a dying stream
+	 * emits `message_completed` on its way out, so the events carry both
+	 * ends of the message a failed step points at.
+	 */
+	messageId?: MessageId
 	/** Assistant text for this step, if any. */
 	content: string | null
 	toolCalls: readonly ToolCall[]
-	/** Tool outcomes, in the same order as `toolCalls`. */
+	/**
+	 * Tool outcomes, in the same order as `toolCalls`.
+	 *
+	 * Shorter than `toolCalls` on a step that ended in failure: only the
+	 * outcomes that exist are recorded, so a call with no entry here reads
+	 * as "never came back" rather than as an empty success. Pair by
+	 * `toolCallId`, not by index.
+	 */
 	toolResults: readonly StepToolResult[]
-	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * How the turn ended.
+	 *
+	 * `error` and `cancelled` are not provider verdicts — no provider reports
+	 * them — but a step exists for a failed iteration too, and it has to say
+	 * how it ended in the same field a reader already sorts by. `error` comes
+	 * with {@link failure}; `cancelled` means a Stop tore the turn down and
+	 * there is no failure to report.
+	 */
+	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'error' | 'cancelled'
+	/**
+	 * What went wrong, on a step with `finishReason: 'error'`.
+	 *
+	 * Absent everywhere else. A run whose ledger is complete except on the
+	 * turns that failed reads as "nothing went wrong" precisely when
+	 * something did, which is worse than an absent record — so the failed
+	 * turn gets the same record as every other, and this is what makes it
+	 * legible as a failure.
+	 */
+	failure?: StepFailure
 	/** Usage for THIS step, not the run's cumulative total. */
 	usage: TokenUsage
 	/** Cost delta attributable to this step. Zero without a pricing table. */
@@ -88,6 +132,35 @@ export interface StepProvenance {
 	readonly chainIndex: number
 }
 
+/**
+ * Why a step ended in `finishReason: 'error'`.
+ *
+ * The step-level counterpart of the pair a failed run already carries —
+ * {@link import('./entity.js').Run.lastError} and
+ * {@link import('./entity.js').Run.lastProviderError} — and shaped from the
+ * same classification, so the two agree when the failed step is the one that
+ * ended the run. What a run records once, a run of twenty iterations records
+ * per iteration, which is the difference between "this run failed" and "this
+ * turn failed, and the next four succeeded".
+ */
+export interface StepFailure {
+	/** The failure's message, as the iteration's span and log recorded it. */
+	readonly message: string
+	/**
+	 * Where the classifier placed it.
+	 *
+	 * `unknown` for a failure that is not a provider failure at all — a
+	 * plugin hook that threw, a bug in a tool wrapper. That is the honest
+	 * reading of the code's own contract ("unclassifiable"), and it is left
+	 * saying so rather than being given a more specific-looking code.
+	 */
+	readonly code: ProviderErrorCode
+	/** HTTP status, when the failure carried one. */
+	readonly status?: number
+	/** Whether sending the same request again could have worked. */
+	readonly retryable: boolean
+}
+
 export interface StepToolResult {
 	toolCallId: string
 	toolName: string