@namzu/sdk 1.4.0 → 3.0.0

package/src/types/message/content.ts

@@ -0,0 +1,50 @@
+import type { ToolResultBlock, ToolResultContent } from './index.js'
+
+/**
+ * Normalize tool-result content to blocks.
+ *
+ * A plain string is the common case and stays first-class; this is the
+ * adapter for drivers that want to walk blocks uniformly.
+ */
+export function toToolResultBlocks(content: ToolResultContent): readonly ToolResultBlock[] {
+	return typeof content === 'string' ? [{ type: 'text', text: content }] : content
+}
+
+/**
+ * Flatten tool-result content to text.
+ *
+ * For drivers that cannot express non-text tool results, and for every
+ * host-facing surface (transcript, compaction, UI) that reasons over
+ * strings. Non-text blocks become a short, honest placeholder rather than
+ * their base64 payload: dumping the bytes is what made `computer-use`
+ * send megabytes of undecodable characters as text, and silently dropping
+ * them would let the model believe it saw something it did not.
+ */
+export function toolResultToText(content: ToolResultContent): string {
+	if (typeof content === 'string') return content
+	return content
+		.map((block) => {
+			switch (block.type) {
+				case 'text':
+					return block.text
+				case 'image':
+					return `[image: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`
+				case 'document':
+					return `[document${block.name ? ` "${block.name}"` : ''}: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`
+			}
+		})
+		.join('\n')
+}
+
+/** True when the content needs a driver that can carry non-text blocks. */
+export function hasNonTextBlocks(content: ToolResultContent): boolean {
+	return typeof content !== 'string' && content.some((b) => b.type !== 'text')
+}
+
+/** Approximate decoded byte count of a base64 payload, for a human-readable note. */
+function describeSize(base64: string): string {
+	const bytes = Math.floor((base64.length * 3) / 4)
+	if (bytes < 1024) return `${bytes} B`
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}

package/src/types/message/index.ts

@@ -4,16 +4,88 @@ export type CacheHint = 'cache' | 'ephemeral' | 'none'
 
 /**
  * An image attached to a user message (vision input). Additive: providers
- * that support vision (e.g. Anthropic) emit it as an image content block
+ * that support vision emit it as an image content block
  * alongside the text; providers that don't simply ignore it.
  */
 export interface ImageAttachment {
+	/**
+	 * Optional, and optional forever: an attachment without a discriminant
+	 * is an image, which is what every attachment was before documents
+	 * existed. Requiring it would have broken every caller to describe a
+	 * default they were already relying on.
+	 */
+	readonly type?: 'image'
 	/** Base64-encoded image bytes (no `data:` URI prefix). */
 	readonly data: string
 	/** IANA media type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
 	readonly mediaType: string
 }
 
+/**
+ * A document attached to a user message.
+ *
+ * Documents existed in the type system only in the TOOL-RESULT direction,
+ * so "here is the contract, answer questions about it" was reachable only
+ * by having a tool read the file and stringify it. That loses the
+ * provider's native document handling — page structure, built-in OCR,
+ * citations — and pays the text cost instead.
+ */
+export interface DocumentAttachment {
+	readonly type: 'document'
+	/**
+	 * Ask the model to cite this document when it uses it.
+	 *
+	 * Opt-in, because it is not free: the provider splits the document
+	 * into citable units and the answer carries the passages it leaned
+	 * on, which costs tokens on a turn that may not need them.
+	 *
+	 * Citations come back on the assistant message, not in its text —
+	 * see {@link Citation}.
+	 */
+	readonly citations?: boolean
+	/** Base64-encoded bytes (no `data:` URI prefix). */
+	readonly data: string
+	/** IANA media type, e.g. `application/pdf`. */
+	readonly mediaType: string
+	/** Shown to the model, so it can refer to the file by name. */
+	readonly name?: string
+}
+
+/**
+ * Where a passage the model cited came from.
+ *
+ * Sending a document buys the provider's native handling of it — page
+ * structure, built-in OCR, and the ability to say WHICH passage an
+ * answer rests on. namzu could send the document and could not receive
+ * the third: an answer about a contract arrived as prose, and checking
+ * it meant reading the contract again by hand. A citation is the
+ * difference between an answer you trust and one you verify.
+ *
+ * The location is a union rather than a page number because providers
+ * segment differently and the segmentation is theirs: pages for a
+ * paginated document, character offsets for plain text, block indices
+ * for something already structured. Flattening them all to "page" would
+ * invent a number for the two that have none.
+ */
+export interface Citation {
+	/** The passage itself, verbatim from the source. */
+	readonly citedText: string
+	/** Which attachment, by position in the message that carried it. */
+	readonly documentIndex: number
+	readonly documentTitle?: string
+	readonly location:
+		| { readonly kind: 'page'; readonly start: number; readonly end: number }
+		| { readonly kind: 'char'; readonly start: number; readonly end: number }
+		| { readonly kind: 'block'; readonly start: number; readonly end: number }
+}
+
+/** What a user message may carry alongside its text. */
+export type MessageAttachment = ImageAttachment | DocumentAttachment
+
+export const isDocumentAttachment = (
+	attachment: MessageAttachment,
+): attachment is DocumentAttachment => attachment.type === 'document'
+
 export interface ToolCall {
 	id: string
 	type: 'function'
@@ -28,14 +100,49 @@ export interface ToolCall {
 	 */
 	metadata?: {
 		inputTruncated?: boolean
+		/**
+		 * The partial argument buffer as it arrived, when the stream cut off
+		 * mid-JSON. `function.arguments` is normalized to `"{}"` in that
+		 * case so tool args stay clean, which leaves this as the only record
+		 * of what the model was actually saying — and a `repairToolCall`
+		 * hook has nothing to repair without it.
+		 */
+		partialArguments?: string
 	}
 }
 
 export interface BaseMessage {
+	/**
+	 * Widened from `string | null` so `ToolMessage` can carry content
+	 * blocks. Each variant below narrows it back to exactly what that role
+	 * may hold, so no caller loses type safety — only the shared base is
+	 * permissive.
+	 */
 	role: MessageRole
-	content: string | null
+	content: string | null | readonly ToolResultBlock[]
 	timestamp?: number
 	cacheHint?: CacheHint
+	/**
+	 * Exempt this message from compaction and from tool-result clearing.
+	 *
+	 * Everything the run protected before was protected by POSITION — the
+	 * leading system run, the working-memory slot, the last N turns, the
+	 * most recent tool results. A standing constraint stated in the middle
+	 * of a conversation ("the account id is X; never bill a different
+	 * one") therefore aged out at the same rate as chatter, and no
+	 * positional rule could express it.
+	 *
+	 * Protection is transitive across a tool pair: pinning a
+	 * `tool_result` also pins the assistant turn that called it, and
+	 * pinning that turn pins every result answering it. Half a pair is not
+	 * a smaller history, it is one the provider rejects.
+	 *
+	 * Pinned turns are exempt from the reclaim that keeps a long run
+	 * alive, so this is a budget the setter spends. Nothing caps it: a cap
+	 * would have to guess which pin mattered, and dropping the wrong one
+	 * quietly is worse than a run that overflows in the open.
+	 */
+	retain?: boolean
 }
 
 export interface SystemMessage extends BaseMessage {
@@ -46,20 +153,93 @@ export interface SystemMessage extends BaseMessage {
 export interface UserMessage extends BaseMessage {
 	role: 'user'
 	content: string
-	/** Optional image attachments (vision input). */
-	attachments?: readonly ImageAttachment[]
+	/** Optional image or document attachments. */
+	attachments?: readonly MessageAttachment[]
+}
+
+/**
+ * An opaque reasoning block produced by the model.
+ *
+ * Deliberately opaque: the SDK stores and replays it, never interprets it.
+ * A provider whose reasoning blocks are signed requires the preceding
+ * assistant turn to be echoed back **verbatim** — thinking blocks and
+ * their cryptographic `signature` included — whenever a `tool_result`
+ * follows. namzu's drivers *rebuilt* each assistant turn as
+ * `[text?, ...tool_use]`, which is exactly the pattern such a contract
+ * prohibits, and `AssistantMessage` had nowhere to keep a signature
+ * even if a driver had parsed one.
+ *
+ * The requirement is not one vendor's quirk: dropping reasoning items
+ * costs measurable multi-step accuracy wherever they are signed.
+ */
+export interface ReasoningBlock {
+	readonly type: 'thinking' | 'redacted_thinking'
+	readonly text?: string
+	/** Cryptographic signature; replaying it unchanged is mandatory. */
+	readonly signature?: string
+	/** Opaque payload for the ZDR / stateless path. */
+	readonly encrypted?: string
 }
 
 export interface AssistantMessage extends BaseMessage {
 	role: 'assistant'
 	content: string | null
 	toolCalls?: ToolCall[]
+	/**
+	 * Reasoning the model emitted before this turn's content, in order.
+	 * Replayed verbatim and ahead of the text/tool blocks — see
+	 * {@link ReasoningBlock}.
+	 */
+	reasoning?: readonly ReasoningBlock[]
+	/**
+	 * Passages this turn rests on, when the request asked for them.
+	 *
+	 * On the message rather than inside its text: the text is what a
+	 * human reads and the citations are what a checker follows, and
+	 * splicing markers into the prose would make the answer worse to read
+	 * in exchange for making it machine-checkable. Empty and absent mean
+	 * the same thing — the model cited nothing.
+	 */
+	citations?: readonly Citation[]
 }
 
+/**
+ * A block of tool-result content the model can actually perceive.
+ *
+ * `ToolMessage.content` was `string`, so anything non-textual had to be
+ * stringified to reach the model. `@namzu/computer-use`'s `screenshot`
+ * returned ~400 KB–2.7 MB of base64 as TEXT — roughly 100k–670k tokens of
+ * characters no model can decode — and every MCP `image`/`resource` block
+ * was silently dropped by the adapter. Computer use was, in practice,
+ * non-functional.
+ */
+export type ToolResultBlock =
+	| { readonly type: 'text'; readonly text: string }
+	| { readonly type: 'image'; readonly data: string; readonly mediaType: string }
+	| DocumentAttachment
+
+/**
+ * String stays a first-class shape, not a deprecated one: it is the
+ * overwhelmingly common case, and keeping it means every existing tool and
+ * driver compiles unchanged while the block array is added beside it.
+ */
+export type ToolResultContent = string | readonly ToolResultBlock[]
+
 export interface ToolMessage extends BaseMessage {
 	role: 'tool'
-	content: string
+	content: ToolResultContent
 	toolCallId: string
+	/**
+	 * Marks the result as a failure on the wire — each provider spells it
+	 * differently (`is_error`, `status: 'error'`), and every driver has
+	 * somewhere to put it.
+	 *
+	 * The executor already computed this and routed it to the SSE bridge,
+	 * the A2A bridge and the TUI — then dropped it at the provider
+	 * boundary, so the model's trained tool-failure recovery path never
+	 * fired and namzu relied on prose formatting to convey failure.
+	 */
+	isError?: boolean
 }
 
 export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
@@ -75,7 +255,7 @@ export function createSystemMessage(content: string, cacheHint?: CacheHint): Sys
 
 export function createUserMessage(
 	content: string,
-	attachments?: readonly ImageAttachment[],
+	attachments?: readonly MessageAttachment[],
 ): UserMessage {
 	return {
 		role: 'user',
@@ -88,10 +268,31 @@ export function createUserMessage(
 export function createAssistantMessage(
 	content: string | null,
 	toolCalls?: ToolCall[],
+	reasoning?: readonly ReasoningBlock[],
+	citations?: readonly Citation[],
 ): AssistantMessage {
-	return { role: 'assistant', content, toolCalls, timestamp: Date.now() }
+	return {
+		role: 'assistant',
+		content,
+		toolCalls,
+		...(reasoning && reasoning.length > 0 ? { reasoning } : {}),
+		...(citations && citations.length > 0 ? { citations } : {}),
+		timestamp: Date.now(),
+	}
 }
 
-export function createToolMessage(content: string, toolCallId: string): ToolMessage {
-	return { role: 'tool', content, toolCallId, timestamp: Date.now() }
+export function createToolMessage(
+	content: ToolResultContent,
+	toolCallId: string,
+	isError?: boolean,
+): ToolMessage {
+	return {
+		role: 'tool',
+		content,
+		toolCallId,
+		...(isError !== undefined ? { isError } : {}),
+		timestamp: Date.now(),
+	}
 }
+
+export { hasNonTextBlocks, toToolResultBlocks, toolResultToText } from './content.js'

package/src/types/plugin/index.ts

@@ -9,6 +9,7 @@ import {
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
 import type { PluginId, RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -109,6 +110,35 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 	}
 }
 
+/**
+ * What an extension is shown about a model call it is about to make.
+ *
+ * A projection, not the live request object. The wire params carry driver
+ * concerns an extension has no business depending on, and handing them
+ * over would make every future field of that type part of the plugin
+ * contract by accident.
+ */
+export interface PluginModelRequest {
+	readonly model: string
+	readonly messages: readonly Message[]
+	/** Names only. A hook auditing tool exposure needs the set, not the schemas. */
+	readonly toolNames: readonly string[]
+	readonly temperature?: number
+	readonly maxTokens?: number
+}
+
+/** What an extension is shown about the model's reply. */
+export interface PluginModelResponse {
+	readonly content: string | null
+	readonly toolNames: readonly string[]
+	readonly finishReason: string
+	readonly usage: {
+		readonly promptTokens: number
+		readonly completionTokens: number
+		readonly totalTokens: number
+	}
+}
+
 export interface PluginHookContext {
 	readonly runId: RunId
 	readonly pluginId: PluginId
@@ -117,6 +147,42 @@ export interface PluginHookContext {
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
 	readonly iteration?: number
+
+	/**
+	 * The request about to be sent, on `pre_llm_call`.
+	 *
+	 * Both model-call hooks fired directly beside this data and were handed
+	 * none of it — only a run id and an iteration number — so an extension
+	 * could observe THAT a call was happening and nothing about what it
+	 * was. A redaction pass, a prompt audit, a per-tenant token ledger: all
+	 * of them needed the one thing the hook did not carry.
+	 *
+	 * Read-only. Frozen before fan-out for the same reason probe events
+	 * are: a hook that mutated the live request would change what every
+	 * later hook sees, and the last one registered would silently win.
+	 * Shaping the request stays the job of the single-slot host callback
+	 * that owns it, where one writer is the contract rather than an
+	 * accident of registration order.
+	 *
+	 * The freeze is one level deep, as elsewhere: each message is a frozen
+	 * copy, so writing to one is inert and cannot reach the run's history,
+	 * but a nested array inside a message is still the run's own.
+	 */
+	readonly request?: Readonly<PluginModelRequest>
+
+	/**
+	 * What came back, on `post_llm_call`. Read-only, same reasoning.
+	 */
+	readonly response?: Readonly<PluginModelResponse>
+	/**
+	 * Aborts when this hook's deadline expires.
+	 *
+	 * The runtime stops waiting on a slow hook either way, but without a
+	 * signal the hook itself never learns it was abandoned: an HTTP request
+	 * inside it keeps a socket open and its eventual result is written into
+	 * a run that moved on without it. A hook doing I/O should forward this.
+	 */
+	readonly signal?: AbortSignal
 }
 
 export type PluginHookResult =
@@ -124,7 +190,6 @@ export type PluginHookResult =
 	| { action: 'skip'; reason: string }
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
-	| { action: 'resume'; input: string }
 	| { action: 'retry' }
 
 export function assertPluginHookResult(result: PluginHookResult): asserts result {
@@ -134,7 +199,6 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 		case 'skip':
 		case 'modify':
 		case 'error':
-		case 'resume':
 		case 'retry':
 			break
 		default: {
@@ -147,6 +211,22 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 export interface PluginHookDefinition {
 	readonly event: PluginHookEvent
 	readonly handler: (context: PluginHookContext) => Promise<PluginHookResult>
+	/**
+	 * Lower runs first. Default 100.
+	 *
+	 * Order was install order, which is neither declared nor stable — it
+	 * depends on when each plugin happened to be installed. That is fine
+	 * for hooks that only observe, and wrong for the ones that decide:
+	 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
+	 * denies a dangerous command only gets to deny it if it runs before
+	 * whatever else stops the chain. A guard that fires depending on
+	 * installation history is not a guard.
+	 *
+	 * Ties keep registration order, so plugins that never set a priority
+	 * behave exactly as before. Convention: guards below 100, observers
+	 * above.
+	 */
+	readonly priority?: number
 }
 
 // ---------------------------------------------------------------------------

package/src/types/provider/__tests__/cause-chain.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+
+import { classifyProviderError } from '../errors.js'
+
+/**
+ * Every signal was read off the error handed in, so one layer of wrapping
+ * hid it — and wrapping is the normal case, not an edge one: a vendor SDK
+ * wraps its transport error and the runtime wraps again on the way out.
+ *
+ * A rate limit wrapped ONCE classified as `unknown`, which is treated as
+ * non-retryable. The retry policy was dead for every failure that was not
+ * the outermost throwable, which is most of them.
+ */
+
+const wrap = (message: string, cause: unknown) => new Error(message, { cause })
+
+describe('status through the chain', () => {
+	// Deliberately mute: a message that says "too many requests" would let
+	// the message-text fallback reach the same verdict, and the test would
+	// pass with the status walk removed.
+	const throttled = Object.assign(new Error('upstream returned an error'), { status: 429 })
+
+	it('finds a rate limit one layer down', () => {
+		const classified = classifyProviderError(wrap('request failed', throttled))
+		expect(classified.code).toBe('rate_limit')
+		expect(classified.retryable).toBe(true)
+	})
+
+	it('finds it three layers down', () => {
+		const classified = classifyProviderError(
+			wrap('run failed', wrap('step failed', wrap('request failed', throttled))),
+		)
+		expect(classified.code).toBe('rate_limit')
+	})
+
+	it('finds a status hidden in a metadata bag under a wrapper', () => {
+		const aws = Object.assign(new Error('ThrottlingException'), {
+			$metadata: { httpStatusCode: 429 },
+		})
+		expect(classifyProviderError(wrap('send failed', aws)).code).toBe('rate_limit')
+	})
+
+	it('still prefers the outermost status when two links carry one', () => {
+		const inner = Object.assign(new Error('inner'), { status: 500 })
+		const outer = Object.assign(wrap('outer', inner), { status: 429 })
+		// The outer link is what the driver chose to expose; walking
+		// outward-in keeps the un-wrapped case behaving exactly as before.
+		expect(classifyProviderError(outer).status).toBe(429)
+	})
+})
+
+describe('errno through the chain', () => {
+	const reset = Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' })
+
+	it('finds a transport failure two layers down', () => {
+		const classified = classifyProviderError(
+			wrap('provider call failed', wrap('fetch failed', reset)),
+		)
+		// The one class of failure where retrying is almost always right.
+		expect(classified.code).toBe('network')
+		expect(classified.retryable).toBe(true)
+	})
+
+	it('finds a timeout errno under a wrapper', () => {
+		const timedOut = Object.assign(new Error('headers timeout'), {
+			code: 'UND_ERR_HEADERS_TIMEOUT',
+		})
+		expect(classifyProviderError(wrap('failed', timedOut)).code).toBe('timeout')
+	})
+})
+
+describe('retry-after through the chain', () => {
+	it('reads the header off the link that carries it', () => {
+		const limited = Object.assign(new Error('rate limited'), {
+			status: 429,
+			headers: { 'retry-after': '30' },
+		})
+		expect(classifyProviderError(wrap('failed', limited)).retryAfterMs).toBe(30_000)
+	})
+})
+
+describe('message through the chain', () => {
+	it('reads a window overflow off an inner message', () => {
+		const overflow = new Error('prompt is too long for this model')
+		// A wrapper's message is usually generic, so matching only the outer
+		// text looks at the one string least likely to say anything.
+		expect(classifyProviderError(wrap('request failed', overflow)).code).toBe(
+			'context_length_exceeded',
+		)
+	})
+
+	it('lets a status anywhere on the chain beat message text', () => {
+		const badRequest = Object.assign(new Error('bad request'), { status: 400 })
+		const classified = classifyProviderError(wrap('the operation timed out', badRequest))
+		// Status is the more reliable signal, wherever it sits; a wrapper
+		// whose prose says "timed out" must not overrule it.
+		expect(classified.code).toBe('invalid_request')
+	})
+})
+
+describe('safety', () => {
+	it('terminates on a cause cycle', () => {
+		const a: { cause?: unknown; message: string } = { message: 'a' }
+		const b = { message: 'b', cause: a }
+		a.cause = b
+
+		// Easy to build by accident when errors are re-wrapped in a retry
+		// loop; without a seen-set the walk never returns.
+		expect(classifyProviderError(a).code).toBe('unknown')
+	})
+
+	it('handles a chain that ends in a non-object', () => {
+		expect(classifyProviderError(wrap('failed', 'a string cause')).code).toBe('unknown')
+	})
+
+	it('leaves an already-classified error alone', () => {
+		const classified = classifyProviderError(Object.assign(new Error('x'), { status: 429 }))
+		expect(classifyProviderError(wrap('outer', classified))).not.toBe(classified)
+		expect(classifyProviderError(classified)).toBe(classified)
+	})
+
+	it('classifies an unwrapped error exactly as before', () => {
+		for (const [err, code] of [
+			[Object.assign(new Error('x'), { status: 401 }), 'auth'],
+			[Object.assign(new Error('x'), { status: 404 }), 'not_found'],
+			[Object.assign(new Error('x'), { status: 529 }), 'overloaded'],
+			[new Error('nothing recognisable'), 'unknown'],
+		] as const) {
+			expect(classifyProviderError(err).code).toBe(code)
+		}
+	})
+})

package/src/types/provider/__tests__/declared-retryable.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+
+import { ProviderError, classifyProviderError, declaredRetryable } from '../errors.js'
+
+/**
+ * Retryability was derived solely from namzu's own code set, so a vendor
+ * SDK that says outright "this one is safe to retry" was not listened to.
+ * That set is a second-hand inference from status and wording, and it
+ * necessarily lags every new failure shape a provider invents — a failure
+ * nobody has characterised yet lands on `unknown`, which is treated as
+ * non-retryable, even when its own author flagged it retryable.
+ *
+ * The classification still decides WHAT went wrong. Only the retry verdict
+ * defers to a first-hand statement.
+ */
+
+describe('a retryable flag declared upstream', () => {
+	it('is read off the error itself', () => {
+		const err = Object.assign(new Error('something new'), { retryable: true })
+		expect(classifyProviderError(err).retryable).toBe(true)
+	})
+
+	it('is read off a wrapped cause', () => {
+		// Wrapping is the normal case, not an edge one: vendor SDKs wrap
+		// their transport errors and the runtime wraps again on the way out.
+		const inner = Object.assign(new Error('inner'), { retryable: true })
+		const outer = new Error('request failed', { cause: inner })
+		expect(classifyProviderError(outer).retryable).toBe(true)
+	})
+
+	it('can also say a failure is NOT retryable', () => {
+		// A 503 that the provider knows is permanent for this request.
+		const err = Object.assign(new Error('permanently unavailable'), {
+			status: 503,
+			retryable: false,
+		})
+		const classified = classifyProviderError(err)
+
+		expect(classified.code).toBe('overloaded')
+		// The code still says what it is; only the verdict changed.
+		expect(classified.retryable).toBe(false)
+	})
+
+	it('does not change the classification, only the verdict', () => {
+		const err = Object.assign(new Error('bad request'), { status: 400, retryable: true })
+		const classified = classifyProviderError(err)
+
+		expect(classified.code).toBe('invalid_request')
+		expect(classified.retryable).toBe(true)
+	})
+
+	it('takes the outermost declaration when links disagree', () => {
+		// The outer layer made the more recent statement, knowing what the
+		// inner one said.
+		const inner = Object.assign(new Error('inner'), { retryable: true })
+		const outer = Object.assign(new Error('outer'), { retryable: false, cause: inner })
+		expect(declaredRetryable(outer)).toBe(false)
+	})
+
+	it('leaves the code in charge when nothing declared anything', () => {
+		expect(declaredRetryable(new Error('plain'))).toBeUndefined()
+		expect(classifyProviderError(Object.assign(new Error('x'), { status: 429 })).retryable).toBe(
+			true,
+		)
+		expect(classifyProviderError(Object.assign(new Error('x'), { status: 401 })).retryable).toBe(
+			false,
+		)
+	})
+
+	it('ignores a non-boolean flag rather than coercing it', () => {
+		// `retryable: 'yes'` is a foreign object's field, not a contract.
+		// Coercing it would let any truthy value silently enable retries.
+		expect(declaredRetryable({ retryable: 'yes' })).toBeUndefined()
+		expect(declaredRetryable({ retryable: 1 })).toBeUndefined()
+	})
+
+	it('is honoured when a ProviderError is constructed directly', () => {
+		const err = new ProviderError({
+			code: 'invalid_request',
+			message: 'x',
+			retryable: true,
+		})
+		expect(err.retryable).toBe(true)
+	})
+})