@namzu/sdk 1.4.0 → 3.0.0

package/src/provider/__tests__/mock-script.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { collect } from '../../provider/collect.js'
+import type { ChatCompletionParams } from '../../types/provider/index.js'
+import { MOCK_CAPABILITIES } from '../mock-register.js'
+import { MockLLMProvider } from '../mock.js'
+
+/**
+ * The mock could only emit text, and declared `supportsTools: false`, so
+ * capability negotiation stripped the tool surface before a request was even
+ * built. No consumer could test that the agent loop calls their tool — and
+ * namzu's own maintainers hand-rolled eight `implements LLMProvider` fakes
+ * across seven test files to work around exactly that. Six of those are now
+ * gone; the two that remain are in `registry.test.ts`, which tests that the
+ * registry accepts arbitrary provider CONSTRUCTORS — collapsing those onto
+ * this mock would defeat what they check.
+ *
+ * These cases assert the mock produces the frame sequence a REAL driver
+ * produces, so a test written against it exercises the consumer path rather
+ * than a shortcut through it.
+ */
+
+const PARAMS = { model: 'mock', messages: [] } as unknown as ChatCompletionParams
+
+describe('MockLLMProvider — scripted tool calls', () => {
+	it('declares tool support, so capability negotiation does not strip tools', () => {
+		expect(MOCK_CAPABILITIES.supportsTools).toBe(true)
+		expect(MOCK_CAPABILITIES.supportsFunctionCalling).toBe(true)
+	})
+
+	it('emits a tool call the aggregator can reassemble', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'read', args: { path: 'a.txt' } }] }],
+		})
+
+		const response = await collect(provider.chatStream(PARAMS))
+
+		expect(response.finishReason).toBe('tool_calls')
+		expect(response.message.toolCalls).toHaveLength(1)
+		const call = response.message.toolCalls?.[0]
+		expect(call?.function.name).toBe('read')
+		expect(JSON.parse(call?.function.arguments ?? '{}')).toEqual({ path: 'a.txt' })
+	})
+
+	it('streams arguments in fragments — the buffering path is real, not bypassed', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'grep', args: { pattern: 'needle' }, argChunkSize: 2 }] }],
+		})
+
+		const fragments: string[] = []
+		for await (const chunk of provider.chatStream(PARAMS)) {
+			const args = chunk.delta.toolCalls?.[0]?.function?.arguments
+			if (args) fragments.push(args)
+		}
+
+		expect(fragments.length).toBeGreaterThan(3)
+		expect(JSON.parse(fragments.join(''))).toEqual({ pattern: 'needle' })
+	})
+
+	it('opens each block with id + name and closes it with toolCallEnd', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'ls', id: 'call_x' }] }],
+		})
+
+		let opened = false
+		let closed = false
+		for await (const chunk of provider.chatStream(PARAMS)) {
+			const tc = chunk.delta.toolCalls?.[0]
+			if (tc?.id === 'call_x' && tc.function?.name === 'ls') opened = true
+			if (chunk.delta.toolCallEnd?.id === 'call_x') closed = true
+		}
+
+		expect(opened).toBe(true)
+		expect(closed).toBe(true)
+	})
+
+	it('can emit several tool calls in one turn, each on its own index', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'a' }, { name: 'b' }, { name: 'c' }] }],
+		})
+		const response = await collect(provider.chatStream(PARAMS))
+		expect(response.message.toolCalls?.map((t) => t.function.name)).toEqual(['a', 'b', 'c'])
+	})
+
+	it('reproduces a tool call cut off mid-JSON', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'write', args: { content: 'x' }, truncateArguments: true }] }],
+		})
+
+		let sawEnd = false
+		for await (const chunk of provider.chatStream(PARAMS)) {
+			if (chunk.delta.toolCallEnd) sawEnd = true
+		}
+		// No block-close signal — the consumer must infer truncation.
+		expect(sawEnd).toBe(false)
+	})
+})
+
+describe('MockLLMProvider — multi-turn scripts', () => {
+	it('plays turns in order', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'read' }] }, { text: 'all done' }],
+		})
+
+		const first = await collect(provider.chatStream(PARAMS))
+		const second = await collect(provider.chatStream(PARAMS))
+
+		expect(first.message.toolCalls).toHaveLength(1)
+		expect(second.message.content).toBe('all done')
+		expect(second.finishReason).toBe('stop')
+	})
+
+	it('repeats the last turn rather than exhausting, so a loop bug reads as repetition', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'only' }] })
+		await collect(provider.chatStream(PARAMS))
+		const third = await collect(provider.chatStream(PARAMS))
+		expect(third.message.content).toBe('only')
+	})
+
+	it('nextTurn can decide from the request it just received', async () => {
+		const provider = new MockLLMProvider({
+			nextTurn: (_params, i) =>
+				i === 0 ? { toolCalls: [{ name: 'read' }] } : { text: `turn ${i}` },
+		})
+		expect((await collect(provider.chatStream(PARAMS))).message.toolCalls).toHaveLength(1)
+		expect((await collect(provider.chatStream(PARAMS))).message.content).toBe('turn 1')
+	})
+
+	it('captures requests so a test can assert on tools / toolChoice / cacheControl', async () => {
+		const onRequest = vi.fn()
+		const provider = new MockLLMProvider({ turns: [{ text: 'hi' }], onRequest })
+
+		await collect(provider.chatStream({ ...PARAMS, toolChoice: 'none' }))
+
+		expect(onRequest).toHaveBeenCalledTimes(1)
+		expect(provider.requests[0]?.toolChoice).toBe('none')
+	})
+
+	it('reset() rewinds the script and clears captured requests', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'first' }, { text: 'second' }] })
+		await collect(provider.chatStream(PARAMS))
+		provider.reset()
+		expect((await collect(provider.chatStream(PARAMS))).message.content).toBe('first')
+		expect(provider.requests).toHaveLength(1)
+	})
+})
+
+describe('MockLLMProvider — failure injection', () => {
+	it('can fail a request outright with a status, for retry tests', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ error: { message: 'rate limited', status: 429 } }],
+		})
+		await expect(collect(provider.chatStream(PARAMS))).rejects.toMatchObject({ status: 429 })
+	})
+
+	it('can fail mid-stream after N chunks, for recovery tests', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ text: 'abcdefghijkl', chunkSize: 4, throwAfterChunks: 2 }],
+		})
+
+		const seen: string[] = []
+		await expect(
+			(async () => {
+				for await (const chunk of provider.chatStream(PARAMS)) {
+					if (chunk.delta.content) seen.push(chunk.delta.content)
+				}
+			})(),
+		).rejects.toThrow('mock stream failure')
+
+		expect(seen).toEqual(['abcd', 'efgh'])
+	})
+})
+
+describe('MockLLMProvider — back-compat', () => {
+	it('still accepts the old responseText shorthand', async () => {
+		const provider = new MockLLMProvider({ responseText: 'legacy' })
+		expect((await collect(provider.chatStream(PARAMS))).message.content).toBe('legacy')
+	})
+})

package/src/provider/__tests__/registry.test.ts

@@ -17,7 +17,7 @@ import {
 } from '../registry.js'
 
 // Simulate a downstream provider package's type registration via module augmentation.
-// This is the pattern @namzu/bedrock, @namzu/openai, etc. use in their own code.
+// This is the pattern every driver package uses in its own code.
 interface TestProviderConfig {
 	type: 'test'
 	value?: string

package/src/provider/__tests__/retry-visibility.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { LLMProvider, StreamChunk } from '../../types/provider/index.js'
+import type { Logger } from '../../utils/logger.js'
+import { withProviderRetry } from '../retry.js'
+
+/**
+ * A backoff used to produce no signal of any kind. With the default policy
+ * — three retries, a 16s cap — or a server-directed delay up to the 60s
+ * ceiling, a run can sit silent for the better part of a minute between
+ * `iteration_started` and the next event. A non-CLI host saw nothing and
+ * got no keepalive, so its watchdog cancelled a run that was about to
+ * succeed; on the CLI the spinner kept moving, which made a backoff
+ * indistinguishable from a hang rather than visibly frozen.
+ *
+ * The omission was never principled: `tool_progress` exists precisely to
+ * answer "is it still working?", and the wire contract justifies the
+ * reasoning events on exactly the same grounds.
+ */
+
+function makeLogger(): Logger & { warns: unknown[][] } {
+	const warns: unknown[][] = []
+	const self = {
+		warns,
+		info: vi.fn(),
+		warn: (...args: unknown[]) => warns.push(args),
+		error: vi.fn(),
+		debug: vi.fn(),
+	} as unknown as Logger & { warns: unknown[][] }
+	;(self as unknown as { child: () => Logger }).child = () => self
+	return self
+}
+
+/** A driver that fails `failures` times with a retryable error, then succeeds. */
+function flakyProvider(failures: number, error?: unknown): LLMProvider {
+	let attempts = 0
+	return {
+		id: 'test',
+		name: 'Test',
+		capabilities: {},
+		async *chatStream(): AsyncIterable<StreamChunk> {
+			if (attempts++ < failures) {
+				throw error ?? Object.assign(new Error('service unavailable'), { status: 503 })
+			}
+			yield { id: 'c1', delta: { content: 'ok' } }
+		},
+	} as unknown as LLMProvider
+}
+
+async function collect(provider: LLMProvider): Promise<StreamChunk[]> {
+	const chunks: StreamChunk[] = []
+	for await (const chunk of provider.chatStream({ model: 'm', messages: [] } as never)) {
+		chunks.push(chunk)
+	}
+	return chunks
+}
+
+describe('a retry announces itself', () => {
+	const sleepFn = async () => {}
+
+	it('yields a notice before each backoff', async () => {
+		const wrapped = withProviderRetry(flakyProvider(2), { sleepFn, random: () => 0.5 })
+		const chunks = await collect(wrapped)
+
+		const notices = chunks.filter((c) => c.retry)
+		expect(notices).toHaveLength(2)
+		expect(notices[0]?.retry?.attempt).toBe(1)
+		expect(notices[1]?.retry?.attempt).toBe(2)
+	})
+
+	it('carries the classification, not just the fact', async () => {
+		const wrapped = withProviderRetry(flakyProvider(1), { sleepFn, random: () => 0.5 })
+		const notice = (await collect(wrapped)).find((c) => c.retry)?.retry
+
+		// A host deciding whether to keep waiting needs to know what went
+		// wrong and for how long, which is what a bare "retrying" cannot say.
+		expect(notice?.status).toBe(503)
+		expect(notice?.code).toBeTruthy()
+		expect(notice?.delayMs).toBeGreaterThan(0)
+		expect(notice?.maxRetries).toBe(3)
+	})
+
+	it('names a server-directed delay as such', async () => {
+		const directed = Object.assign(new Error('slow down'), {
+			status: 429,
+			headers: { 'retry-after': '2' },
+		})
+		const wrapped = withProviderRetry(flakyProvider(1, directed), { sleepFn, random: () => 0.5 })
+		const notice = (await collect(wrapped)).find((c) => c.retry)?.retry
+
+		expect(notice?.serverDirected).toBe(true)
+		expect(notice?.delayMs).toBe(2000)
+	})
+
+	it('carries no delta, so it is never mistaken for output', async () => {
+		const wrapped = withProviderRetry(flakyProvider(1), { sleepFn, random: () => 0.5 })
+		const notice = (await collect(wrapped)).find((c) => c.retry)
+
+		expect(notice?.delta).toEqual({})
+		expect(notice?.finishReason).toBeUndefined()
+	})
+
+	it('is emitted BEFORE the sleep, so the delay it names is still ahead', async () => {
+		const order: string[] = []
+		const wrapped = withProviderRetry(flakyProvider(1), {
+			sleepFn: async () => {
+				order.push('slept')
+			},
+			random: () => 0.5,
+		})
+
+		for await (const chunk of wrapped.chatStream({ model: 'm', messages: [] } as never)) {
+			if (chunk.retry) order.push('notice')
+		}
+
+		// Reversed, this tells the host about a wait that is already over.
+		expect(order).toEqual(['notice', 'slept'])
+	})
+
+	it('says nothing when the call succeeds first time', async () => {
+		const wrapped = withProviderRetry(flakyProvider(0), { sleepFn })
+		expect((await collect(wrapped)).some((c) => c.retry)).toBe(false)
+	})
+
+	it('says nothing more once it gives up', async () => {
+		const wrapped = withProviderRetry(flakyProvider(99), {
+			sleepFn,
+			config: { maxRetries: 2 },
+			random: () => 0.5,
+		})
+
+		const chunks: StreamChunk[] = []
+		await expect(async () => {
+			for await (const chunk of wrapped.chatStream({ model: 'm', messages: [] } as never)) {
+				chunks.push(chunk)
+			}
+		}).rejects.toThrow()
+
+		// Two notices for two retries, then the throw — not a third notice
+		// promising a backoff that never happens.
+		expect(chunks.filter((c) => c.retry)).toHaveLength(2)
+	})
+})
+
+describe('the logger the sole production call site never passed', () => {
+	it('warns on a retry when it is given one', async () => {
+		// Every warn in the decorator is guarded behind `options.log`, and
+		// production never supplied it — so these lines were dead code and a
+		// backoff left no trace anywhere at all.
+		const log = makeLogger()
+		const wrapped = withProviderRetry(flakyProvider(1), {
+			sleepFn: async () => {},
+			random: () => 0.5,
+			log,
+		})
+		await collect(wrapped)
+
+		expect(log.warns.some(([message]) => String(message).includes('retrying'))).toBe(true)
+	})
+})

package/src/provider/__tests__/retry.test.ts

@@ -0,0 +1,296 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { ProviderError, classifyProviderError, isAbortError } from '../../types/provider/errors.js'
+import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../../types/provider/index.js'
+import { withProviderRetry } from '../retry.js'
+
+const PARAMS = { model: 'm', messages: [] } as unknown as ChatCompletionParams
+
+function chunk(content: string): StreamChunk {
+	return { id: 'c', delta: { content } }
+}
+
+/** A driver whose behavior is scripted per attempt. */
+function scripted(
+	script: Array<() => AsyncIterable<StreamChunk>>,
+): LLMProvider & { calls: number } {
+	let calls = 0
+	const provider = {
+		id: 'scripted',
+		name: 'Scripted',
+		chatStream: (_params: ChatCompletionParams) => {
+			const step = script[Math.min(calls, script.length - 1)]
+			calls++
+			if (!step) throw new Error('script exhausted')
+			return step()
+		},
+		get calls() {
+			return calls
+		},
+	}
+	return provider as unknown as LLMProvider & { calls: number }
+}
+
+function httpError(status: number, message = `HTTP ${status}`, headers?: Record<string, string>) {
+	return Object.assign(new Error(message), { status, headers })
+}
+
+async function drain(stream: AsyncIterable<StreamChunk>): Promise<string> {
+	let out = ''
+	for await (const c of stream) out += c.delta.content ?? ''
+	return out
+}
+
+const noSleep = async () => {}
+
+describe('classifyProviderError', () => {
+	it.each([
+		[429, 'rate_limit', true],
+		[529, 'overloaded', true],
+		[503, 'overloaded', true],
+		[500, 'server_error', true],
+		[502, 'server_error', true],
+		[408, 'timeout', true],
+		[401, 'auth', false],
+		[403, 'auth', false],
+		[404, 'not_found', false],
+		[400, 'invalid_request', false],
+	])('maps HTTP %i to %s (retryable=%s)', (status, code, retryable) => {
+		const e = classifyProviderError(httpError(status as number))
+		expect(e.code).toBe(code)
+		expect(e.retryable).toBe(retryable)
+		expect(e.status).toBe(status)
+	})
+
+	it('files a window overflow as context_length_exceeded even though it arrives as a 400', () => {
+		const e = classifyProviderError(httpError(400, 'prompt is too long: 250000 tokens > 200000'))
+		expect(e.code).toBe('context_length_exceeded')
+		// Retrying the identical request cannot help — the caller must shed history.
+		expect(e.retryable).toBe(false)
+	})
+
+	it('classifies transport errnos without a status', () => {
+		expect(
+			classifyProviderError(Object.assign(new Error('reset'), { code: 'ECONNRESET' })).code,
+		).toBe('network')
+		expect(
+			classifyProviderError(Object.assign(new Error('slow'), { code: 'ETIMEDOUT' })).code,
+		).toBe('timeout')
+		// undici nests the errno under `cause`.
+		expect(
+			classifyProviderError(Object.assign(new Error('x'), { cause: { code: 'EAI_AGAIN' } })).code,
+		).toBe('network')
+	})
+
+	it('reads Retry-After as delta-seconds and as an HTTP date', () => {
+		expect(classifyProviderError(httpError(429, '', { 'retry-after': '2' })).retryAfterMs).toBe(
+			2000,
+		)
+
+		const now = Date.parse('2026-07-31T10:00:00Z')
+		const at = new Date(now + 5000).toUTCString()
+		expect(
+			classifyProviderError(httpError(429, '', { 'retry-after': at }), undefined, now).retryAfterMs,
+		).toBe(5000)
+	})
+
+	it('is idempotent — re-classifying a ProviderError returns it unchanged', () => {
+		const first = classifyProviderError(httpError(429))
+		expect(classifyProviderError(first)).toBe(first)
+	})
+
+	it('does not treat an abort as a provider failure', () => {
+		const abort = Object.assign(new Error('aborted'), { name: 'AbortError' })
+		expect(isAbortError(abort)).toBe(true)
+	})
+})
+
+describe('withProviderRetry', () => {
+	it('retries a 429 and succeeds', async () => {
+		const provider = scripted([
+			() => {
+				throw httpError(429)
+			},
+			async function* () {
+				yield chunk('ok')
+			},
+		])
+		const wrapped = withProviderRetry(provider, { sleepFn: noSleep, random: () => 0.5 })
+		expect(await drain(wrapped.chatStream(PARAMS))).toBe('ok')
+		expect(provider.calls).toBe(2)
+	})
+
+	it('does NOT retry a 400 — a malformed request stays malformed', async () => {
+		const provider = scripted([
+			() => {
+				throw httpError(400, 'bad tool schema')
+			},
+		])
+		const wrapped = withProviderRetry(provider, { sleepFn: noSleep })
+		await expect(drain(wrapped.chatStream(PARAMS))).rejects.toMatchObject({
+			code: 'invalid_request',
+		})
+		expect(provider.calls).toBe(1)
+	})
+
+	it('gives up after maxRetries and throws a classified ProviderError', async () => {
+		const provider = scripted([
+			() => {
+				throw httpError(503)
+			},
+		])
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetries: 2 },
+			sleepFn: noSleep,
+		})
+		const err = await drain(wrapped.chatStream(PARAMS)).catch((e) => e)
+		expect(err).toBeInstanceOf(ProviderError)
+		expect(err.code).toBe('overloaded')
+		expect(provider.calls).toBe(3) // initial + 2 retries
+	})
+
+	it('NEVER retries once a content chunk has been produced', async () => {
+		// Retrying here would replay "hello" and duplicate it in the buffer
+		// the consumer has already emitted as text_delta events.
+		const provider = scripted([
+			async function* () {
+				yield chunk('hello')
+				throw httpError(503)
+			},
+			async function* () {
+				yield chunk('SHOULD NOT HAPPEN')
+			},
+		])
+		const wrapped = withProviderRetry(provider, { sleepFn: noSleep })
+
+		let seen = ''
+		const err = await (async () => {
+			try {
+				for await (const c of wrapped.chatStream(PARAMS)) seen += c.delta.content ?? ''
+				return undefined
+			} catch (e) {
+				return e
+			}
+		})()
+
+		expect(seen).toBe('hello')
+		expect(err).toBeInstanceOf(ProviderError)
+		expect(provider.calls).toBe(1)
+	})
+
+	it('retries a driver that reports failure in-band via chunk.error', async () => {
+		const provider = scripted([
+			async function* () {
+				yield { id: 'c', delta: {}, error: 'overloaded_error' } as StreamChunk
+			},
+			async function* () {
+				yield chunk('recovered')
+			},
+		])
+		const wrapped = withProviderRetry(provider, { sleepFn: noSleep })
+		expect(await drain(wrapped.chatStream(PARAMS))).toBe('recovered')
+		expect(provider.calls).toBe(2)
+	})
+
+	it('honours a server-directed Retry-After instead of the computed backoff', async () => {
+		const slept: number[] = []
+		const provider = scripted([
+			() => {
+				throw httpError(429, 'slow down', { 'retry-after': '7' })
+			},
+			async function* () {
+				yield chunk('ok')
+			},
+		])
+		const wrapped = withProviderRetry(provider, {
+			sleepFn: async (ms) => {
+				slept.push(ms)
+			},
+		})
+		await drain(wrapped.chatStream(PARAMS))
+		expect(slept).toEqual([7000])
+	})
+
+	it('ignores an absurd Retry-After and falls back to bounded backoff', async () => {
+		const slept: number[] = []
+		const provider = scripted([
+			() => {
+				throw httpError(429, '', { 'retry-after': '900' }) // 15 minutes
+			},
+			async function* () {
+				yield chunk('ok')
+			},
+		])
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetryAfterMs: 60_000, initialDelayMs: 500 },
+			random: () => 1,
+			sleepFn: async (ms) => {
+				slept.push(ms)
+			},
+		})
+		await drain(wrapped.chatStream(PARAMS))
+		expect(slept).toEqual([500])
+	})
+
+	it('applies full jitter — the delay is scaled by the random source', async () => {
+		const slept: number[] = []
+		const provider = scripted([
+			() => {
+				throw httpError(500)
+			},
+			() => {
+				throw httpError(500)
+			},
+			async function* () {
+				yield chunk('ok')
+			},
+		])
+		const wrapped = withProviderRetry(provider, {
+			config: { initialDelayMs: 1000, maxDelayMs: 16_000 },
+			random: () => 0.5,
+			sleepFn: async (ms) => {
+				slept.push(ms)
+			},
+		})
+		await drain(wrapped.chatStream(PARAMS))
+		// attempt 0 → 0.5 * 1000, attempt 1 → 0.5 * 2000
+		expect(slept).toEqual([500, 1000])
+	})
+
+	it('propagates an abort untouched so the run still settles as cancelled', async () => {
+		const controller = new AbortController()
+		controller.abort()
+		const abortErr = Object.assign(new Error('aborted'), { name: 'AbortError' })
+		const provider = scripted([
+			() => {
+				throw abortErr
+			},
+		])
+		const wrapped = withProviderRetry(provider, { sleepFn: noSleep })
+		await expect(drain(wrapped.chatStream({ ...PARAMS, signal: controller.signal }))).rejects.toBe(
+			abortErr,
+		)
+		expect(provider.calls).toBe(1)
+	})
+
+	it('returns the provider untouched when retrying is disabled', () => {
+		const provider = scripted([])
+		expect(withProviderRetry(provider, { config: { maxRetries: 0 } })).toBe(provider)
+	})
+
+	it('is transparent to identity and capability negotiation', () => {
+		const base = {
+			id: 'anthropic',
+			name: 'Anthropic',
+			capabilities: { supportsTools: true, supportsVision: false },
+			chatStream: async function* () {},
+			listModels: vi.fn(async () => []),
+		} as unknown as LLMProvider
+		const wrapped = withProviderRetry(base)
+		expect(wrapped.id).toBe('anthropic')
+		expect(wrapped.name).toBe('Anthropic')
+		expect(wrapped.capabilities).toEqual({ supportsTools: true, supportsVision: false })
+		expect(typeof wrapped.listModels).toBe('function')
+		expect(wrapped.healthCheck).toBeUndefined()
+	})
+})

package/src/provider/capabilities.ts

@@ -9,6 +9,7 @@ export interface ResolvedProviderCapabilities {
 	supportsStreaming: boolean
 	supportsFunctionCalling: boolean
 	supportsVision: boolean
+	supportsDocuments: boolean
 	maxOutputTokens?: number
 }
 
@@ -23,6 +24,7 @@ export const PERMISSIVE_PROVIDER_CAPABILITIES: ResolvedProviderCapabilities = {
 	supportsStreaming: true,
 	supportsFunctionCalling: true,
 	supportsVision: true,
+	supportsDocuments: true,
 }
 
 /**
@@ -42,6 +44,8 @@ export function resolveProviderCapabilities(
 		supportsFunctionCalling:
 			declared?.supportsFunctionCalling ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsFunctionCalling,
 		supportsVision: declared?.supportsVision ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsVision,
+		supportsDocuments:
+			declared?.supportsDocuments ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsDocuments,
 		maxOutputTokens: declared?.maxOutputTokens,
 	}
 }

package/src/provider/collect.test.ts

@@ -11,7 +11,7 @@
  *   `arguments` fragments for that index.
  * - Latest-wins for `finishReason` and `usage`; defaults
  *   `finishReason: 'stop'` and zero usage if the provider omits them
- *   (defensive — see anthropics/anthropic-sdk-typescript#842).
+ *   (defensive — a vendor SDK has shipped this shape before).
  * - Throws if any chunk surfaces a `chunk.error`.
  *
  * Phase 2 swaps every internal `provider.chat()` call site for

package/src/provider/collect.ts

@@ -17,7 +17,7 @@ import type { StreamChunk } from '../types/provider/stream.js'
  * - tool calls are bucketed by `index` into the existing
  *   `Array<{ id, function: { name, arguments } }>` shape;
  * - usage and finishReason fall back to safe defaults when the provider
- *   omits them (defensive — see anthropics/anthropic-sdk-typescript#842
+ *   omits them (defensive — a known vendor-SDK failure mode
  *   where `message_stop` is occasionally dropped on connection close).
  *
  * The orchestrator does NOT call this helper — it consumes the stream