@namzu/sdk 30.1.0 → 31.0.0

package/src/provider/fallback.ts

@@ -23,7 +23,13 @@
 
 import { GENAI } from '../constants/telemetry/index.js'
 import { classifyProviderError, isAbortError } from '../types/provider/errors.js'
-import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../types/provider/index.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	ReasoningEffort,
+	StreamChunk,
+	ThinkingConfig,
+} from '../types/provider/index.js'
 import type { Logger } from '../utils/logger.js'
 
 /**
@@ -211,6 +217,42 @@ function isOutputChunk(chunk: StreamChunk): boolean {
 	)
 }
 
+/** Read one member's canonical menu, adapting the one-release legacy member. */
+function memberReasoningEffortLevels(
+	member: ProviderChainMember,
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): readonly ReasoningEffort[] | undefined {
+	const model = member.model ?? requestModel
+	if (member.provider.reasoningEffortLevelsFor) {
+		return member.provider.reasoningEffortLevelsFor(model, thinking)
+	}
+	return member.provider.effortLevelsFor?.(model, thinking)
+}
+
+/**
+ * The levels one request may carry safely through every member it can reach.
+ *
+ * `ChatCompletionParams.effort` survives a fallback swap unchanged. A menu
+ * copied from the head can therefore offer a value the tail rejects, turning
+ * recovery into a second request failure. Preserve the head's ordering while
+ * intersecting every member's exact, member-model-specific answer. One unknown
+ * answer makes the chain unknown; an explicit empty/no-common answer is `[]`.
+ */
+function commonReasoningEffortLevels(
+	members: readonly ProviderChainMember[],
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): readonly ReasoningEffort[] | undefined {
+	let common: readonly ReasoningEffort[] | undefined
+	for (const member of members) {
+		const offered = memberReasoningEffortLevels(member, requestModel, thinking)
+		if (offered === undefined) return undefined
+		common = common === undefined ? [...offered] : common.filter((level) => offered.includes(level))
+	}
+	return common ?? []
+}
+
 /**
  * Wrap an ordered chain so a member that cannot serve is replaced in place.
  *
@@ -254,7 +296,9 @@ function isOutputChunk(chunk: StreamChunk): boolean {
  * whose members disagree before ever building one (`@namzu/cli` does, and only
  * runs a mismatched chain when the operator has said so explicitly). Taking the
  * intersection here instead would cost the primary a capability on every run to
- * guard against a failure that happens rarely.
+ * guard against a failure that happens rarely. Reasoning effort is the deliberate
+ * exception: the SAME field is replayed unchanged after a swap, so only a common
+ * level can be truthfully offered before the request.
  */
 export function withProviderFallback(
 	members: readonly ProviderChainMember[],
@@ -302,7 +346,20 @@ export function withProviderFallback(
 				})
 			}
 
-			const request = member.model !== undefined ? { ...params, model: member.model } : params
+			const targetModel = member.model ?? params.model
+			// Route identity is stamped at the final member dispatch, not only by
+			// query's initial head request. A fallback may share a provider id/model
+			// with another member while using different credentials or a different
+			// endpoint; `chainIndex` is what keeps their native replay state apart.
+			const request: ChatCompletionParams = {
+				...params,
+				model: targetModel,
+				providerRoute: {
+					providerId: member.provider.id,
+					model: targetModel,
+					chainIndex: cursor,
+				},
+			}
 			let produced = false
 			try {
 				for await (const chunk of member.provider.chatStream(request)) {
@@ -382,7 +439,16 @@ export function withProviderFallback(
 			return first.provider.capabilities
 		},
 		chatStream,
-		...(first.provider.listModels ? { listModels: () => first.provider.listModels?.() } : {}),
+		...(first.provider.listModels
+			? {
+					listModels: (signal?: AbortSignal) => first.provider.listModels?.(signal),
+				}
+			: {}),
+		...(first.provider.probeCredential
+			? {
+					probeCredential: (signal?: AbortSignal) => first.provider.probeCredential?.(signal),
+				}
+			: {}),
 		// Forwarded for the reason `retry.ts` forwards it: a wrapper that drops
 		// the model turns a probe the caller could answer into one it cannot.
 		...(first.provider.healthCheck
@@ -391,13 +457,15 @@ export function withProviderFallback(
 		...(first.provider.doctorCheck
 			? { doctorCheck: (model?: string) => first.provider.doctorCheck?.(model) }
 			: {}),
-		// The HEAD's answer, like every other member here, and that is the
-		// right reading rather than a limitation: the window is resolved once
-		// at the start of a run, when the head is what is serving. A chain
-		// that swaps mid-run has bigger differences between its members than
-		// a context size, and re-resolving on every swap would put a network
-		// call on the recovery path — which is the last place that can afford
-		// one.
+		// Unlike the legacy head-only member below, this is a declaration about
+		// the request that may actually traverse the whole chain. The method is
+		// always present on a multi-member wrapper: `undefined` is its honest
+		// answer when any member cannot enumerate its selected model.
+		reasoningEffortLevelsFor: (model: string, thinking?: ThinkingConfig) =>
+			commonReasoningEffortLevels(members, model, thinking),
+		// Compatibility projection only. Existing consumers of the deprecated
+		// member keep the head-only answer they had; new consumers use the
+		// canonical chain-aware member above.
 		...(first.provider.effortLevelsFor
 			? {
 					effortLevelsFor: (

package/src/provider/idle-timeout.ts

@@ -3,6 +3,22 @@ import type { LLMProvider } from '../types/provider/interface.js'
 import type { Logger } from '../utils/logger.js'
 import { ProviderRequestError } from './errors.js'
 
+/** Five minutes without one provider chunk is a stalled model call. */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 5 * 60_000
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+
+/** Resolve the shared run/router stream bound before either creates durable run identity. */
+export function resolveStreamIdleTimeoutMs(value: number | undefined): number {
+	const resolved = value ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
+	if (!Number.isInteger(resolved) || resolved < 0 || resolved > MAX_TIMER_DELAY_MS) {
+		throw new RangeError(
+			`streamIdleTimeoutMs must be an integer from 0 to ${MAX_TIMER_DELAY_MS}; received ${String(resolved)}`,
+		)
+	}
+	return resolved
+}
+
 /**
  * Notices a stream that stopped producing without ending.
  *
@@ -62,26 +78,77 @@ export function withStreamIdleTimeout(
 	const disarm = options.clearTimeoutFn ?? clearTimeout
 
 	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-		const iterator = provider.chatStream(params)[Symbol.asyncIterator]()
+		const callerSignal = params.signal
+		callerSignal?.throwIfAborted()
+
+		// Do not abort the caller's controller. The watchdog owns this transport
+		// signal and fuses the caller's stop into it in the one safe direction.
+		// Keeping it stable for the whole stream is important: drivers attach one
+		// listener when the request opens and expect that signal to remain the
+		// request's cancellation identity until the socket closes.
+		const transportAbort = new AbortController()
+		type TerminalCause =
+			| { readonly kind: 'caller'; readonly reason: unknown }
+			| { readonly kind: 'idle'; readonly error: ProviderRequestError }
+		let terminalCause: TerminalCause | undefined
+		let rejectCallerAbort: ((reason?: unknown) => void) | undefined
+		const callerAbort = callerSignal
+			? new Promise<never>((_resolve, reject) => {
+					rejectCallerAbort = reject
+				})
+			: undefined
+		const onCallerAbort = (): void => {
+			const reason = callerSignal?.reason
+			if (terminalCause === undefined) terminalCause = { kind: 'caller', reason }
+			if (!transportAbort.signal.aborted) transportAbort.abort(reason)
+			rejectCallerAbort?.(reason)
+		}
+		callerSignal?.addEventListener('abort', onCallerAbort, { once: true })
+
+		let iteratorForCleanup: AsyncIterator<StreamChunk> | undefined
 		try {
+			const iterator = provider
+				.chatStream({ ...params, signal: transportAbort.signal })
+				[Symbol.asyncIterator]()
+			iteratorForCleanup = iterator
 			for (;;) {
 				let timer: ReturnType<typeof setTimeout> | undefined
 				let result: IteratorResult<StreamChunk>
 				try {
-					result = await Promise.race([
-						iterator.next(),
-						new Promise<never>((_resolve, reject) => {
-							timer = arm(() => {
-								reject(
-									new ProviderRequestError({
-										kind: 'network',
-										providerId: provider.id,
-										detail: `stream idle for ${Math.round(idleTimeoutMs / 1000)}s — aborting so the run lifecycle can settle it`,
-									}),
-								)
-							}, idleTimeoutMs)
-						}),
-					])
+					const idle = new Promise<never>((_resolve, reject) => {
+						timer = arm(() => {
+							if (terminalCause !== undefined) return
+							const duration =
+								idleTimeoutMs < 1_000 || idleTimeoutMs % 1_000 !== 0
+									? `${idleTimeoutMs}ms`
+									: `${idleTimeoutMs / 1_000}s`
+							const error = new ProviderRequestError({
+								kind: 'network',
+								providerId: provider.id,
+								detail: `stream idle for ${duration} — aborting so the run lifecycle can settle it`,
+							})
+							// Latch BEFORE the transport is aborted. Some provider SDKs
+							// synchronously reject their pending `next()` with a generic
+							// AbortError. Retry/fallback correctly treat that shape as a
+							// caller stop, so letting it escape would erase this network
+							// cause and make the recovery policy unreachable.
+							terminalCause = { kind: 'idle', error }
+							transportAbort.abort(error)
+							reject(error)
+						}, idleTimeoutMs)
+					})
+					const pending = callerAbort
+						? [iterator.next(), idle, callerAbort]
+						: [iterator.next(), idle]
+					result = await Promise.race(pending)
+				} catch (err) {
+					// The first control-flow cause wins even if the driver's own
+					// abort listener rejected its pull with a different error object.
+					// In particular, a generic AbortError caused by OUR watchdog is
+					// still the network failure retry/fallback need to see.
+					if (terminalCause?.kind === 'idle') throw terminalCause.error
+					if (terminalCause?.kind === 'caller') throw terminalCause.reason
+					throw err
 				} finally {
 					// In a `finally`, so a rejection from either side of the
 					// race clears the timer. Clearing only on success leaks one
@@ -93,6 +160,7 @@ export function withStreamIdleTimeout(
 				yield result.value
 			}
 		} finally {
+			callerSignal?.removeEventListener('abort', onCallerAbort)
 			// Asked to clean up, NOT awaited — and the difference is the whole
 			// case this decorator exists for. A generator stalled inside an
 			// `await` is not suspended at a `yield`, so `return()` resumes
@@ -104,9 +172,67 @@ export function withStreamIdleTimeout(
 			// signal that nobody is reading — so it is made and abandoned,
 			// with the rejection swallowed because there is no one left to
 			// tell.
-			void iterator.return?.().catch(() => {})
+			try {
+				void iteratorForCleanup?.return?.().catch(() => {})
+			} catch {
+				// A non-conforming iterator can throw before returning its cleanup
+				// promise. The original stream outcome still owns this boundary.
+			}
 		}
 	}
 
-	return { ...provider, chatStream }
+	// Explicit forwarding rather than object spread. A provider may be a class
+	// whose methods live on its prototype; spreading it silently strips those
+	// methods, and retry reads `retryDefaults` AFTER this wrapper is installed.
+	return {
+		get id() {
+			return provider.id
+		},
+		get name() {
+			return provider.name
+		},
+		get capabilities() {
+			return provider.capabilities
+		},
+		get retryDefaults() {
+			return provider.retryDefaults
+		},
+		chatStream,
+		...(provider.listModels
+			? { listModels: (signal?: AbortSignal) => provider.listModels?.(signal) }
+			: {}),
+		...(provider.probeCredential
+			? {
+					probeCredential: (signal?: AbortSignal) => provider.probeCredential?.(signal),
+				}
+			: {}),
+		...(provider.healthCheck
+			? { healthCheck: (model?: string) => provider.healthCheck?.(model) }
+			: {}),
+		...(provider.doctorCheck
+			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
+			: {}),
+		...(provider.reasoningEffortLevelsFor
+			? {
+					reasoningEffortLevelsFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortLevelsFor']>>[1],
+					) => provider.reasoningEffortLevelsFor?.(model, thinking),
+				}
+			: {}),
+		...(provider.effortLevelsFor
+			? {
+					effortLevelsFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['effortLevelsFor']>>[1],
+					) => provider.effortLevelsFor?.(model, thinking) ?? [],
+				}
+			: {}),
+		...(provider.resolveContextWindow
+			? {
+					resolveContextWindow: (model: string, signal?: AbortSignal) =>
+						provider.resolveContextWindow?.(model, signal) ?? Promise.resolve(undefined),
+				}
+			: {}),
+	} as LLMProvider
 }

package/src/provider/index.ts

@@ -36,6 +36,8 @@ export {
 export { DEFAULT_PROVIDER_RETRY, withProviderRetry } from './retry.js'
 export type { ProviderRetryConfig, WithProviderRetryOptions } from './retry.js'
 export { withProviderFallback } from './fallback.js'
+export { DEFAULT_STREAM_IDLE_TIMEOUT_MS, withStreamIdleTimeout } from './idle-timeout.js'
+export type { WithStreamIdleTimeoutOptions } from './idle-timeout.js'
 export type {
 	ProviderChainMember,
 	ServingMember,

package/src/provider/instrumentation.ts

@@ -43,6 +43,7 @@ export function wrapProviderWithProbes(
 		id: provider.id,
 		name: provider.name,
 		listModels: provider.listModels?.bind(provider),
+		probeCredential: provider.probeCredential?.bind(provider),
 		healthCheck: provider.healthCheck?.bind(provider),
 
 		async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {

package/src/provider/retry.ts

@@ -249,7 +249,14 @@ export function withProviderRetry(
 			return provider.capabilities
 		},
 		chatStream,
-		...(provider.listModels ? { listModels: () => provider.listModels?.() } : {}),
+		...(provider.listModels
+			? { listModels: (signal?: AbortSignal) => provider.listModels?.(signal) }
+			: {}),
+		...(provider.probeCredential
+			? {
+					probeCredential: (signal?: AbortSignal) => provider.probeCredential?.(signal),
+				}
+			: {}),
 		// The model is forwarded, not dropped. A wrapper that swallowed it would
 		// leave the wrapped driver probing whatever it probes with no argument
 		// — which for at least one driver is "nothing", so the check would come
@@ -260,6 +267,14 @@ export function withProviderRetry(
 		...(provider.doctorCheck
 			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
 			: {}),
+		...(provider.reasoningEffortLevelsFor
+			? {
+					reasoningEffortLevelsFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortLevelsFor']>>[1],
+					) => provider.reasoningEffortLevelsFor?.(model, thinking),
+				}
+			: {}),
 		// Forwarded for the same reason `healthCheck` is, and both were
 		// missing until something consumed them. A member this wrapper drops
 		// does not fail — it reads as "this driver cannot answer", which is a