@namzu/sdk 2.0.0 → 3.1.0

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)
+	})
+})

package/src/types/provider/__tests__/overflow-classification.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest'
+
+import { classifyProviderError } from '../errors.js'
+
+/**
+ * Overflow is the one 4xx the runtime can act on: it sheds history and
+ * retries. Everything else in the 400 family is surfaced. So the rescue is
+ * gated on the code being EXACTLY `context_length_exceeded`, and anything
+ * that misses that gate dies holding the remedy.
+ *
+ * Detection was a substring search over five phrases. The structural code —
+ * the one field a provider has for saying what went wrong — was extracted
+ * from the cause chain and then fed only to the two transport-errno sets,
+ * so a provider that said `context_length_exceeded` in so many words was
+ * answered with a phrase search that did not match.
+ */
+
+const overflowReaches = (err: unknown) =>
+	classifyProviderError(err).code === 'context_length_exceeded'
+
+describe('the structural code', () => {
+	it('is believed over the status that carries it', () => {
+		// A 400 is a category; the code is the diagnosis.
+		expect(
+			overflowReaches(
+				Object.assign(new Error('Bad request'), { status: 400, code: 'context_length_exceeded' }),
+			),
+		).toBe(true)
+	})
+
+	it('is read from a gateway body discriminator too', () => {
+		expect(
+			overflowReaches(
+				Object.assign(new Error('Bad request'), { status: 400, type: 'context_length_exceeded' }),
+			),
+		).toBe(true)
+	})
+
+	it('is read from a nested error envelope', () => {
+		expect(
+			overflowReaches(
+				Object.assign(new Error('Bad request'), {
+					status: 400,
+					error: { type: 'context_window_exceeded' },
+				}),
+			),
+		).toBe(true)
+	})
+
+	it('is found under a wrapper', () => {
+		const inner = Object.assign(new Error('Bad request'), { code: 'max_tokens_exceeded' })
+		expect(overflowReaches(new Error('request failed', { cause: inner }))).toBe(true)
+	})
+
+	it('classifies a rate limit from the code alone', () => {
+		const classified = classifyProviderError(
+			Object.assign(new Error('Bad request'), { status: 400, code: 'rate_limit_exceeded' }),
+		)
+		expect(classified.code).toBe('rate_limit')
+		expect(classified.retryable).toBe(true)
+	})
+
+	it('leaves a code it does not recognise to the other signals', () => {
+		const classified = classifyProviderError(
+			Object.assign(new Error('nope'), { status: 404, code: 'some_vendor_specific_thing' }),
+		)
+		expect(classified.code).toBe('not_found')
+	})
+})
+
+describe('wordings that used to miss', () => {
+	it.each([
+		'Input is too long for requested model.',
+		'This request exceeds the maximum length for this model',
+		'The input is too large for the context window',
+		'payload too large for the selected model',
+	])('%s', (message) => {
+		expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true)
+	})
+
+	it('still recognises the wordings that already worked', () => {
+		for (const message of [
+			'prompt is too long',
+			'maximum context length exceeded',
+			'too many tokens in request',
+		]) {
+			expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true)
+		}
+	})
+
+	it('does not fire on an ordinary bad request', () => {
+		const classified = classifyProviderError(
+			Object.assign(new Error('The model id is not valid'), { status: 400 }),
+		)
+		// Overreaching here would send a run into compaction it cannot be
+		// rescued by, and hide the real error behind a retry.
+		expect(classified.code).toBe('invalid_request')
+	})
+})
+
+describe('an already-classified error', () => {
+	it('is not re-examined, which is why a driver must not guess', () => {
+		// The classifier short-circuits on a typed error. That is correct —
+		// a driver knows its own vendor best — but it means a driver that
+		// pre-files a name whose meaning depends on the body makes the body
+		// unreadable.
+		const preFiled = classifyProviderError(
+			Object.assign(new Error('Input is too long for requested model.'), { status: 400 }),
+		)
+		expect(preFiled.code).toBe('context_length_exceeded')
+		expect(classifyProviderError(preFiled)).toBe(preFiled)
+	})
+})

package/src/types/provider/chat.ts

@@ -1,5 +1,5 @@
 import type { TokenUsage } from '../common/index.js'
-import type { Message, ToolCall } from '../message/index.js'
+import type { Message, ReasoningBlock, ToolCall } from '../message/index.js'
 import type { LLMToolSchema } from '../tool/index.js'
 
 export type ToolChoice =
@@ -63,6 +63,30 @@ export interface ChatCompletionParams {
 	repetitionPenalty?: number
 
 	responseFormat?: ResponseFormat
+
+	/**
+	 * Extended-thinking request.
+	 *
+	 * Absent from this struct entirely before, and `buildCreateParams`
+	 * assembles the request body key-by-key with no passthrough, so
+	 * thinking could not be *requested* — while on models where it is on by
+	 * default the runtime received blocks it then discarded. Neither half
+	 * was expressible.
+	 *
+	 * Drivers that do not support it ignore the field.
+	 */
+	thinking?: ThinkingConfig
+}
+
+export interface ThinkingConfig {
+	type: 'enabled' | 'disabled'
+	/** Token allowance for the thinking pass. */
+	budgetTokens?: number
+	/**
+	 * Whether the provider should return full thinking text or a summary.
+	 * Purely a request hint; the runtime stores whatever comes back.
+	 */
+	display?: 'full' | 'summarized'
 }
 
 export interface ChatCompletionResponse {
@@ -72,6 +96,10 @@ export interface ChatCompletionResponse {
 		role: 'assistant'
 		content: string | null
 		toolCalls?: ToolCall[]
+		/** Reasoning blocks the model emitted, in original block order. */
+		reasoning?: readonly ReasoningBlock[]
+		/** Passages this turn cites, in the order the model made them. */
+		citations?: readonly import('../message/index.js').Citation[]
 	}
 	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
 	usage: TokenUsage

package/src/types/provider/config.ts

@@ -28,11 +28,85 @@ export type ProviderFactoryConfig = {
 	[K in ProviderType]: ProviderConfigRegistry[K]
 }[ProviderType]
 
-export interface MockProviderConfig {
-	type: 'mock'
+/** One scripted tool call within a {@link MockTurn}. */
+export interface MockToolCall {
+	name: string
+	/** Serialized to JSON and streamed in fragments. */
+	args?: Record<string, unknown>
+	/** Defaults to a deterministic `call_<turn>_<index>`. */
+	id?: string
+	/** Fragment size for the argument JSON; smaller exercises more buffering. */
+	argChunkSize?: number
+	/**
+	 * Omit the block-close signal and stop mid-JSON, reproducing the
+	 * provider cutting a tool call off at `max_tokens`. The consumer should
+	 * mark the call `inputTruncated` rather than crashing on a parse.
+	 */
+	truncateArguments?: boolean
+	/**
+	 * Emit this raw string as the argument payload instead of serializing
+	 * `args`. For scripting malformed or partial JSON the model could
+	 * plausibly produce.
+	 */
+	rawArguments?: string
+	/**
+	 * Throw after the argument fragments, mid-tool-block.
+	 *
+	 * This is the failure the truncated-tool-input recovery path exists
+	 * for — a provider going idle while streaming tool JSON — so it has to
+	 * be scriptable, or that path can only be tested by hand-rolling a
+	 * provider.
+	 */
+	throwAfterArguments?: string
+}
+
+/** One assistant turn the mock provider plays. */
+export interface MockTurn {
+	text?: string
+	toolCalls?: MockToolCall[]
+	/** Passages this scripted turn cites, emitted before its text. */
+	citations?: import('../message/index.js').Citation[]
+	finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	usage?: Partial<import('../common/index.js').TokenUsage>
+	/** Text fragment size. */
+	chunkSize?: number
+	/** Fail the request outright, before any chunk — e.g. a 429. */
+	error?: { message: string; status?: number }
+	/** Fail mid-stream after N text chunks, to exercise recovery paths. */
+	throwAfterChunks?: number
+	throwMessage?: string
+}
+
+/**
+ * The scripted behavior itself, without the registry discriminant, so a
+ * test can `new MockLLMProvider({ turns: [...] })` directly.
+ */
+export interface MockScript {
 	model?: string
+	/** Shorthand for a single text-only turn. */
 	responseText?: string
 	responseDelayMs?: number
+	/**
+	 * Scripted turns. A script shorter than the run repeats its last entry,
+	 * so a loop bug shows up as repetition rather than a crash.
+	 */
+	turns?: MockTurn[]
+	/** Full control: decide each turn from the request that triggered it. */
+	nextTurn?: (params: import('./chat.js').ChatCompletionParams, turnIndex: number) => MockTurn
+	/**
+	 * Override the capability declaration for this instance.
+	 *
+	 * Capability negotiation degrades a run when a driver says it cannot do
+	 * something, and testing that path means being able to SAY it — a fixed
+	 * registry-level declaration cannot express "a driver with no vision".
+	 */
+	capabilities?: ProviderCapabilities
+	/** Observe every request (assert on tools, toolChoice, cacheControl…). */
+	onRequest?: (params: import('./chat.js').ChatCompletionParams) => void
+}
+
+export interface MockProviderConfig extends MockScript {
+	type: 'mock'
 }
 
 /**
@@ -57,6 +131,13 @@ export interface ProviderCapabilities {
 	 * default — the runtime only warns when a driver explicitly says no).
 	 */
 	supportsVision?: boolean
+	/**
+	 * Whether the driver maps user-message DOCUMENT attachments into the
+	 * provider request. Separate from vision because the two are separate
+	 * wire shapes and a driver can map one without the other. Absent ⇒
+	 * treated as capable, same permissive default.
+	 */
+	supportsDocuments?: boolean
 	maxOutputTokens?: number
 }