@namzu/sdk 1.2.0 → 1.4.0

package/src/public-runtime.ts

@@ -47,11 +47,19 @@ export * from './utils/id.js'
 
 // ─── utility helpers ─────────────────────────────────────────────────────
 
-export { accumulateCost, calculateCost, formatCost, ZERO_COST } from './utils/cost.js'
+export {
+	accumulateCost,
+	calculateCost,
+	formatCost,
+	ZERO_COST,
+} from './utils/cost.js'
 export { toErrorMessage } from './utils/error.js'
 export { configureLogger, getRootLogger, Logger } from './utils/logger.js'
 export { buildToolResultHashes, hashToolResult } from './utils/hash.js'
-export { compressShellOutput, compressShellOutputFull } from './utils/shell-compress.js'
+export {
+	compressShellOutput,
+	compressShellOutputFull,
+} from './utils/shell-compress.js'
 export { createChildAbortController } from './utils/abort.js'
 export { memoizeAsync } from './utils/memoize.js'
 export { extractFinalResponse } from './utils/conversation.js'
@@ -61,7 +69,10 @@ export { extractFinalResponse } from './utils/conversation.js'
 export { resolveTaskModel } from './router/task-router.js'
 export { drainQuery, query } from './runtime/query/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
-export { CheckpointManager, projectEmergencyToCheckpoint } from './runtime/query/checkpoint.js'
+export {
+	CheckpointManager,
+	projectEmergencyToCheckpoint,
+} from './runtime/query/checkpoint.js'
 export { prepareReplayState } from './runtime/query/replay/prepare.js'
 export { listCheckpoints } from './runtime/query/replay/list.js'
 export { DecisionParser, FallbackResolver } from './runtime/decision/index.js'
@@ -73,8 +84,17 @@ export {
 
 // ─── personas, skills, advisory ──────────────────────────────────────────
 
-export { assembleSystemPrompt, mergePersonas, withSessionContext } from './persona/index.js'
-export { discoverSkills, loadSkill, resolveSkillChain, SkillRegistry } from './skills/index.js'
+export {
+	assembleSystemPrompt,
+	mergePersonas,
+	withSessionContext,
+} from './persona/index.js'
+export {
+	discoverSkills,
+	loadSkill,
+	resolveSkillChain,
+	SkillRegistry,
+} from './skills/index.js'
 export {
 	AdvisorRegistry,
 	AdvisoryContext,
@@ -144,17 +164,30 @@ export { LocalTaskGateway } from './gateway/local.js'
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 
 export {
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
 	DuplicateProviderError,
+	isCallerAbortError,
+	isProviderRequestError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
 	MOCK_CAPABILITIES,
 	MockLLMProvider,
+	parseRetryAfterMs,
 	PERMISSIVE_PROVIDER_CAPABILITIES,
+	providerHttpError,
+	providerVendorError,
 	ProviderRegistry,
+	ProviderRequestError,
 	registerMock,
 	resolveProviderCapabilities,
 	UnknownProviderError,
 } from './provider/index.js'
 
-export { LocalSandboxProvider, SandboxProviderFactory } from './sandbox/index.js'
+export {
+	LocalSandboxProvider,
+	SandboxProviderFactory,
+} from './sandbox/index.js'
 
 export { InMemoryCredentialVault } from './vault/index.js'
 
@@ -220,7 +253,10 @@ export {
 	runToA2ATask,
 } from './bridge/a2a/index.js'
 
-export { mapRunToStreamEvent, mapSessionToStreamEvent } from './bridge/sse/index.js'
+export {
+	mapRunToStreamEvent,
+	mapSessionToStreamEvent,
+} from './bridge/sse/index.js'
 
 // ─── bus, verification ───────────────────────────────────────────────────
 
@@ -353,10 +389,19 @@ export {
 // ─── runtime helpers colocated with shapes under `types/` (§1.5) ─────────
 
 export { A2AProtocolError } from './types/a2a/index.js'
-export { isTerminalActivityStatus, resolveActivityTracking } from './types/activity/index.js'
+export {
+	isTerminalActivityStatus,
+	resolveActivityTracking,
+} from './types/activity/index.js'
 export { isTerminalAgentTaskState } from './types/agent/task.js'
-export { accumulateTokenUsage, isTerminalStatus } from './types/common/index.js'
-export { assertComputerUseActionType, assertDisplayServer } from './types/computer-use/index.js'
+export {
+	accumulateTokenUsage,
+	isTerminalStatus,
+} from './types/common/index.js'
+export {
+	assertComputerUseActionType,
+	assertDisplayServer,
+} from './types/computer-use/index.js'
 export { isConnectorActive } from './types/connector/core.js'
 export { CONNECTOR_SCOPE_ORDER } from './types/connector/scope.js'
 export { RoutingResponseSchema } from './types/decision/index.js'

package/src/registry/tool/execute.test.ts

@@ -433,6 +433,20 @@ describe('ToolRegistry — execute', () => {
 		expect(result.error).toContain('Expected string, received number')
 	})
 
+	it('appends a tool-specific recovery hint to validation failures', async () => {
+		const r = new ToolRegistry()
+		r.register(
+			makeTool('strict', {
+				inputSchema: z.object({ required: z.string() }),
+				validationErrorHint: 'Retry with {"required":"value"}.',
+			}),
+		)
+		const result = await r.execute('strict', { required: 123 }, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Required: required: string.')
+		expect(result.error).toContain('Retry with {"required":"value"}.')
+	})
+
 	it('empty-args validation lists required params with descriptions', async () => {
 		const r = new ToolRegistry()
 		r.register(

package/src/registry/tool/execute.ts

@@ -370,10 +370,13 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						Object.keys(rawInput as Record<string, unknown>).length === 0)
 
 				const requiredHint = describeRequiredInput(tool.inputSchema)
+				const recoveryHint = tool.validationErrorHint?.trim()
+					? ` ${tool.validationErrorHint.trim()}`
+					: ''
 
 				const enrichedMessage = isEmptyInput
-					? `Tool "${toolName}" was called with no arguments. ${requiredHint} Retry the call with the required parameters populated.`
-					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}`
+					? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
+					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
 
 				this.log.error(`Tool input validation failed: ${toolName}`, {
 					errors: errorMessage,

package/src/runtime/query/__tests__/stream-recovery.test.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 
+import { ProviderRequestError } from '../../../provider/errors.js'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
@@ -72,6 +73,22 @@ class IdleDuringToolInputProvider implements LLMProvider {
 	}
 }
 
+class ClassifiedFailureProvider implements LLMProvider {
+	readonly id = 'classified-failure'
+	readonly name = 'Classified Failure Provider'
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		yield await Promise.reject(
+			new ProviderRequestError({
+				kind: 'throttle',
+				providerId: 'classified-failure',
+				status: 429,
+				retryAfterMs: 2000,
+			}),
+		)
+	}
+}
+
 describe('query stream recovery', () => {
 	let workdirs: string[] = []
 
@@ -82,7 +99,10 @@ describe('query stream recovery', () => {
 
 	it('turns an idle stream with partial tool JSON into retryable tool feedback', async () => {
 		const provider = new IdleDuringToolInputProvider()
-		const actualWrite = vi.fn(async () => ({ success: true, output: 'should not run' }))
+		const actualWrite = vi.fn(async () => ({
+			success: true,
+			output: 'should not run',
+		}))
 		const tools = new ToolRegistry()
 		tools.register({
 			name: 'write_file',
@@ -153,4 +173,47 @@ describe('query stream recovery', () => {
 			'extend it with edit using insertLine',
 		)
 	})
+
+	it('preserves classified provider metadata through the primary run boundary', async () => {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-provider-error-'))
+		workdirs.push(workingDirectory)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				provider: new ClassifiedFailureProvider(),
+				tools: new ToolRegistry(),
+				runConfig: {
+					model: 'mock-model',
+					timeoutMs: 5_000,
+					tokenBudget: 100_000,
+					maxIterations: 1,
+					maxResponseTokens: 256,
+				},
+				agentId: 'agent_test',
+				agentName: 'Test Agent',
+				messages: [createUserMessage('fail with classified metadata')],
+				workingDirectory,
+				sessionId: 'ses_provider_error' as SessionId,
+				threadId: 'thd_provider_error' as ThreadId,
+				projectId: 'prj_provider_error' as ProjectId,
+				tenantId: 'tnt_provider_error' as TenantId,
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('failed')
+		expect(run.lastProviderError).toEqual({
+			kind: 'throttle',
+			providerId: 'classified-failure',
+			status: 429,
+			retryAfterMs: 2000,
+		})
+		expect(events.find((event) => event.type === 'run_failed')).toMatchObject({
+			type: 'run_failed',
+			providerError: run.lastProviderError,
+		})
+	})
 })

package/src/runtime/query/iteration/phases/compaction-safe-cut.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The UNBOUNDED CUT.
+ *
+ * `runCompactionCheck` snaps the naive recent-window boundary
+ * (`messages.length - keepRecentMessages`) FORWARD via `findSafeTrimIndex` so a
+ * tool pair is never split. But `findSafeTrimIndex` only ever walks forward, and
+ * its leading-`tool`-message skip has no stop short of `messages.length` — so
+ * whenever the whole suffix from the naive index to the end is `tool` messages,
+ * the cut lands ON `messages.length`, `recentMessages` comes back EMPTY, and
+ * `[...preservedSystem, compactionMessage]` replaces the ENTIRE recent window.
+ * What is left is a transcript with no non-system message at all.
+ *
+ * The shape that produces it: ONE assistant turn that fans out
+ * `>= keepRecentMessages` parallel tool calls, measured at the START of the next
+ * iteration — which is exactly where `runCompactionCheck` runs (iteration/index.ts,
+ * after `refreshWorkingMemory`, before the model call), i.e. immediately after
+ * those results were appended.
+ *
+ * The `olderMessages.length < 1` guard at :117 cannot fire: `olderMessages` is
+ * the whole transcript in exactly this situation.
+ *
+ * Symmetrically, when the naive index lands BELOW `systemMessages.length` the
+ * cut sits inside the system prefix and the leading prompts are duplicated into
+ * `recentMessages`.
+ *
+ * The invariant these tests pin is the one a cut taken AT OR BELOW naive gives
+ * for free: a pass never removes more than the naive cut would, so at least
+ * `keepRecentMessages` original messages survive verbatim — or, when no safe cut
+ * exists at all, the pass is skipped and the transcript is untouched.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { WorkingStateManager } from '../../../../compaction/manager.js'
+import { CompactionConfigSchema } from '../../../../config/runtime.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createSystemMessage,
+	createToolMessage,
+	createUserMessage,
+} from '../../../../types/message/index.js'
+import type { Logger } from '../../../../utils/logger.js'
+import { runCompactionCheck } from './compaction.js'
+import type { IterationContext } from './context.js'
+
+function makeLogger(): Logger {
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+/** Long enough that a handful of messages overflow a tiny budget. */
+const FILLER = 'x'.repeat(200)
+
+const KEEP_RECENT = 4
+
+function makeCtx(opts: {
+	messages: Message[]
+	contextWindowTokens?: number
+	tokenBudget?: number
+}): IterationContext {
+	const config = CompactionConfigSchema.parse({
+		strategy: 'structured',
+		llmVerification: false,
+		keepRecentMessages: KEEP_RECENT,
+		...(opts.contextWindowTokens !== undefined
+			? { contextWindowTokens: opts.contextWindowTokens }
+			: {}),
+	})
+	const manager = new WorkingStateManager(config)
+	manager.addDecision('built the report as .docx')
+
+	return {
+		runConfig: { tokenBudget: opts.tokenBudget ?? 0 },
+		compactionConfig: config,
+		workingStateManager: manager,
+		log: makeLogger(),
+		runMgr: {
+			id: 'run_1' as RunId,
+			currentIteration: 3,
+			messages: opts.messages,
+		},
+	} as unknown as IterationContext
+}
+
+function toolCall(id: string) {
+	return { id, type: 'function' as const, function: { name: 'read', arguments: '{}' } }
+}
+
+/** How many of the ORIGINAL messages survived the pass, by identity. */
+function survivorCount(before: readonly Message[], after: readonly Message[]): number {
+	const kept = new Set<Message>(after)
+	return before.filter((m) => kept.has(m)).length
+}
+
+/**
+ * The exact shape the iteration loop holds when `runCompactionCheck` runs: the
+ * user's turn, one assistant that fanned out four parallel tool calls, and the
+ * four results that just landed. The next thing that happens is the model call —
+ * with whatever this function leaves behind.
+ */
+function buildParallelFanOutTail(): Message[] {
+	return [
+		createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+		createUserMessage(`please rename the heading to Q3 ${FILLER}`),
+		createAssistantMessage(`reading the sources ${FILLER}`, [
+			toolCall('a'),
+			toolCall('b'),
+			toolCall('c'),
+			toolCall('d'),
+		]),
+		createToolMessage(`result a ${FILLER}`, 'a'),
+		createToolMessage(`result b ${FILLER}`, 'b'),
+		createToolMessage(`result c ${FILLER}`, 'c'),
+		createToolMessage(`result d ${FILLER}`, 'd'),
+	]
+}
+
+describe('compaction — the unbounded cut', () => {
+	it('keeps at least keepRecentMessages messages verbatim when the tail is a parallel tool fan-out', async () => {
+		const messages = buildParallelFanOutTail()
+		const before = [...messages]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		expect(survivorCount(before, messages)).toBeGreaterThanOrEqual(KEEP_RECENT)
+	})
+
+	it('never leaves a system-only transcript (nothing for the next turn to answer)', async () => {
+		const messages = buildParallelFanOutTail()
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		const nonSystem = messages.filter((m) => m.role !== 'system')
+		expect(nonSystem.length).toBeGreaterThan(0)
+	})
+
+	it('skips the pass, leaving the transcript intact, when no safe cut exists at or below naive', async () => {
+		// System prefix, then a single assistant fanning out six parallel calls.
+		// Every candidate boundary at or below naive splits that one pair-set, so
+		// there is nothing safe to cut to — skipping beats deleting the turn.
+		const ids = ['a', 'b', 'c', 'd', 'e', 'f']
+		const messages: Message[] = [
+			createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+			createAssistantMessage(`fanning out ${FILLER}`, ids.map(toolCall)),
+			...ids.map((id) => createToolMessage(`result ${id} ${FILLER}`, id)),
+		]
+		const before = [...messages]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		expect(messages).toEqual(before)
+	})
+
+	it('does not duplicate the leading system prompts when the naive cut lands inside them', async () => {
+		// Legacy (tokenBudget) path: five leading system messages and only three
+		// conversational ones, so naive = 8 - 4 = 4 < systemMessages.length = 5.
+		const messages: Message[] = [
+			createSystemMessage(`SYS-1 ${FILLER}`, 'cache'),
+			createSystemMessage(`SYS-2 ${FILLER}`),
+			createSystemMessage(`SYS-3 ${FILLER}`),
+			createSystemMessage(`SYS-4 ${FILLER}`),
+			createSystemMessage(`SYS-5 UNIQUE-MARKER ${FILLER}`),
+			createUserMessage(`user 0 ${FILLER}`),
+			createAssistantMessage(`assistant 0 ${FILLER}`),
+			createUserMessage(`user 1 ${FILLER}`),
+		]
+		const ctx = makeCtx({ messages, tokenBudget: 100 })
+
+		await runCompactionCheck(ctx)
+
+		const marker = messages.filter((m) => m.content?.includes('UNIQUE-MARKER'))
+		expect(marker).toHaveLength(1)
+	})
+})

package/src/runtime/query/iteration/phases/compaction.ts

@@ -94,18 +94,60 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	}
 	if (systemMessages.length === 0) return
 
-	// Tool-pair atomicity guard. A naive cut at `length - keepRecentMessages`
-	// can land BETWEEN an assistant-with-toolCalls (which would be dropped into
-	// `olderMessages`) and its `tool` results (kept in `recentMessages`),
-	// leaving orphaned `tool_result` blocks at the head of the recent window.
-	// The Anthropic provider then emits a `tool_result` with no matching
-	// `tool_use` and the API rejects the next turn with a 400 — so compaction,
-	// whose whole job is to keep a long run alive, instead kills it. Snap the
-	// boundary FORWARD to a safe point (existing `findSafeTrimIndex`, previously
-	// only wired to the unused ConversationManager strategy classes) so no pair
-	// is split. Any message this moves out of the recent window is already
-	// represented in the extracted WorkingState the summary is built from.
-	const keepStart = findSafeTrimIndex(messages, messages.length - config.keepRecentMessages)
+	// Tool-pair atomicity guard, taken DOWNWARD.
+	//
+	// A naive cut at `length - keepRecentMessages` can land BETWEEN an
+	// assistant-with-toolCalls (dropped into `olderMessages`) and its `tool`
+	// results (kept in `recentMessages`), leaving orphaned `tool_result` blocks at
+	// the head of the recent window. The Anthropic provider then emits a
+	// `tool_result` with no matching `tool_use` and the API rejects the next turn
+	// with a 400 — so compaction, whose whole job is to keep a long run alive,
+	// instead kills it.
+	//
+	// Snapping FORWARD via `findSafeTrimIndex` fixes the orphan and introduces a
+	// worse failure. That walk skips leading `tool` messages with no stop short of
+	// `messages.length`, so whenever the entire suffix from the naive index is
+	// `tool` messages, the boundary lands ON `messages.length`: `recentMessages`
+	// comes back EMPTY and `[...preservedSystem, compactionMessage]` replaces the
+	// whole recent window. The model is then asked to answer a conversation whose
+	// last turn — including the user's own message — was deleted, and it answers a
+	// question nobody asked. The shape is routine, not exotic: one assistant turn
+	// fanning out `>= keepRecentMessages` parallel tool calls, measured at the
+	// start of the very next iteration, which is exactly where this runs. The
+	// `olderMessages` floor guard below cannot catch it either — in that shape
+	// `olderMessages` is the whole transcript.
+	//
+	// So take the LARGEST safe boundary AT OR BELOW naive instead. A cut that low
+	// removes no more than the naive cut would, so at least `keepRecentMessages`
+	// original messages always survive verbatim, and the transcript can never be
+	// reduced to system messages alone. `findSafeTrimIndex(m, k) === k` is the
+	// safety predicate — reused rather than reimplemented, so the function itself
+	// (public API, other callers) is untouched.
+	const naiveKeepStart = messages.length - config.keepRecentMessages
+	let keepStart = -1
+	for (let candidate = naiveKeepStart; candidate > systemMessages.length; candidate--) {
+		if (findSafeTrimIndex(messages, candidate) === candidate) {
+			keepStart = candidate
+			break
+		}
+	}
+
+	// No safe boundary at or below naive. Either every candidate splits a pair-set
+	// (one assistant fanning out more calls than the recent window holds), or naive
+	// itself sits inside the leading system prefix — which would otherwise
+	// duplicate those prompts into `recentMessages`. Skipping costs one iteration's
+	// worth of context headroom; cutting anyway costs the live turn. The condition
+	// is self-clearing: the next assistant message moves naive past the tool block.
+	if (keepStart < 0) {
+		ctx.log.debug('Skipping compaction — no safe cut at or below the naive boundary', {
+			runId: ctx.runMgr.id,
+			naiveKeepStart,
+			systemMessages: systemMessages.length,
+			messageCount: messages.length,
+		})
+		return
+	}
+
 	const recentMessages = messages.slice(keepStart)
 	const olderMessages = messages.slice(systemMessages.length, keepStart)
 

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

@@ -1,3 +1,4 @@
+import { isProviderRequestError } from '../../../provider/errors.js'
 import { mergeTokenUsage } from '../../../types/common/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
 import type {
@@ -111,9 +112,12 @@ export async function* streamProviderTurn(
 			inputTruncated: boolean
 		}
 	>()
-	let streamError: string | undefined
+	let streamError: Error | undefined
 
-	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
@@ -145,7 +149,7 @@ export async function* streamProviderTurn(
 			if (res.done) break
 			const chunk = res.value
 			if (chunk.error) {
-				streamError = chunk.error
+				streamError = new Error(`Provider stream error: ${chunk.error}`)
 				break
 			}
 			if (!id && chunk.id) id = chunk.id
@@ -252,7 +256,7 @@ export async function* streamProviderTurn(
 		// run as cancelled rather than recording a normal (errored) turn. Any
 		// other stream error is captured into the synthesized response as before.
 		if (signal?.aborted) throw err
-		streamError = err instanceof Error ? err.message : String(err)
+		streamError = err instanceof Error ? err : new Error(String(err))
 	} finally {
 		if (onAbort) signal?.removeEventListener('abort', onAbort)
 		// Release the underlying connection on every exit (natural end, error,
@@ -355,7 +359,7 @@ export async function* streamProviderTurn(
 		log.warn('provider stream failed after tool input; surfacing tool call to executor', {
 			runId,
 			iteration,
-			error: streamError,
+			error: streamError?.message ?? 'provider stream failed',
 			toolCallCount: toolCalls.length,
 		})
 	}
@@ -378,7 +382,8 @@ export async function* streamProviderTurn(
 	yield* drainPending()
 
 	if (streamError && !recoveredToolInputFromStreamError) {
-		throw new Error(`Provider stream error: ${streamError}`)
+		if (isProviderRequestError(streamError)) throw streamError
+		throw new Error(`Provider stream error: ${streamError.message}`)
 	}
 
 	const response: ChatCompletionResponse = {

package/src/runtime/query/result.ts

@@ -1,6 +1,7 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
+import { isProviderRequestError } from '../../provider/errors.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
 import type { Run, RunEvent } from '../../types/run/index.js'
@@ -61,7 +62,15 @@ export class ResultAssembler {
 	async *handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent> {
 		const { runMgr, planManager, log, emitEvent, drainPending } = this.config
 		const errorMessage = toErrorMessage(err)
-		runMgr.markFailed(errorMessage)
+		const providerError = isProviderRequestError(err)
+			? {
+					kind: err.kind,
+					providerId: err.providerId,
+					...(err.status !== undefined ? { status: err.status } : {}),
+					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+				}
+			: undefined
+		runMgr.markFailed(errorMessage, providerError)
 
 		if (planManager.isActive) {
 			planManager.failPlan(errorMessage)
@@ -71,6 +80,7 @@ export class ResultAssembler {
 			type: 'run_failed',
 			runId: runMgr.id,
 			error: errorMessage,
+			...(providerError ? { providerError } : {}),
 		})
 		yield* drainPending()