@namzu/sdk 27.0.0 → 28.0.0

package/src/provider/idle-timeout.ts

@@ -0,0 +1,112 @@
+import type { ChatCompletionParams, StreamChunk } from '../types/provider/index.js'
+import type { LLMProvider } from '../types/provider/interface.js'
+import type { Logger } from '../utils/logger.js'
+import { ProviderRequestError } from './errors.js'
+
+/**
+ * Notices a stream that stopped producing without ending.
+ *
+ * One driver had a per-chunk watchdog, written inline, and it defaulted to
+ * OFF — so zero of seven drivers re-armed on a stall unless a host set a
+ * config key it had no reason to know about. The only other bound is each
+ * driver's whole-REQUEST timeout, which a stream that opened successfully
+ * and then went quiet does not trip: the request is fine, the bytes have
+ * simply stopped.
+ *
+ * A run in that state is not slow, it is stuck. It holds its budget, its
+ * claim and its process, and nothing settles it until an operator
+ * notices — which is the failure mode a kernel with checkpoints and
+ * budgets exists to make impossible.
+ *
+ * ## Why a decorator and not a driver feature
+ *
+ * Written once here, in the shape `withProviderRetry` and
+ * `withProviderFallback` already use, so it composes with them rather than
+ * being reimplemented per driver. The failure is classified `network`,
+ * which is the same classification the inline version produced and the one
+ * retry and fallback already know how to act on: a stalled stream is
+ * retried by the layer above, or the chain moves to the next member.
+ *
+ * ## What it cannot do
+ *
+ * It cannot un-emit. A stall AFTER the first chunk surfaces as an error
+ * rather than a silent restart, exactly as `withProviderRetry` documents
+ * for the same reason — the consumer has already emitted those deltas.
+ */
+
+export interface WithStreamIdleTimeoutOptions {
+	/**
+	 * Milliseconds without a chunk before the stream is treated as stalled.
+	 * `0` or a non-finite value disables the watchdog and returns the
+	 * provider unwrapped.
+	 */
+	readonly idleTimeoutMs: number
+	readonly log?: Logger
+	/** Test seam. Defaults to `setTimeout`. */
+	readonly setTimeoutFn?: typeof setTimeout
+	/** Test seam. Defaults to `clearTimeout`. */
+	readonly clearTimeoutFn?: typeof clearTimeout
+}
+
+export function withStreamIdleTimeout(
+	provider: LLMProvider,
+	options: WithStreamIdleTimeoutOptions,
+): LLMProvider {
+	const { idleTimeoutMs } = options
+	// Unwrapped rather than wrapped-and-inert. A disabled watchdog that
+	// still races a promise per chunk costs the hottest path in the runtime
+	// a timer and a closure for nothing.
+	if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs <= 0) return provider
+
+	const arm = options.setTimeoutFn ?? setTimeout
+	const disarm = options.clearTimeoutFn ?? clearTimeout
+
+	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		const iterator = provider.chatStream(params)[Symbol.asyncIterator]()
+		try {
+			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)
+						}),
+					])
+				} finally {
+					// In a `finally`, so a rejection from either side of the
+					// race clears the timer. Clearing only on success leaks one
+					// per stalled stream, and a leaked timer keeps the process
+					// alive past the run it belonged to.
+					if (timer !== undefined) disarm(timer)
+				}
+				if (result.done) return
+				yield result.value
+			}
+		} finally {
+			// 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
+			// nothing and its promise never settles: awaiting it deadlocks on
+			// precisely the stalled stream the watchdog just caught. (Found
+			// that way: the first version hung this file's own test.)
+			//
+			// The call still matters — a driver holding a socket has no other
+			// 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(() => {})
+		}
+	}
+
+	return { ...provider, chatStream }
+}

package/src/provider/instrumentation.ts

@@ -1,5 +1,6 @@
 import { buildProbeContext } from '../probe/context.js'
-import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
+import { probe as defaultProbeRegistry } from '../probe/registry.js'
+import type { ProbeObservation } from '../probe/registry.js'
 import type { ProviderCallId, ProviderCallUsage } from '../types/bus/index.js'
 import type { TokenUsage } from '../types/common/index.js'
 import type { RunId } from '../types/ids/index.js'
@@ -8,7 +9,8 @@ import type { LLMProvider } from '../types/provider/interface.js'
 import type { StreamChunk } from '../types/provider/stream.js'
 
 export interface ProviderInstrumentationOptions {
-	readonly probes?: ProbeRegistry
+	/** Observation only — a provider wrapper records, it never refuses. */
+	readonly probes?: ProbeObservation
 	readonly runId?: RunId
 }
 

package/src/provider/retry.ts

@@ -1,3 +1,4 @@
+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 BackoffPolicy, backoffWithJitter, sleep } from '../utils/backoff.js'
@@ -67,11 +68,28 @@ export function withProviderRetry(
 	provider: LLMProvider,
 	options: WithProviderRetryOptions = {},
 ): LLMProvider {
-	const config: ProviderRetryConfig = { ...DEFAULT_PROVIDER_RETRY, ...options.config }
+	// Three layers, and the order is the contract. A driver's declaration is
+	// a DEFAULT — it sits above the generic one and below whatever the
+	// caller asked for, because the caller asked for something specific and
+	// the driver is only expressing what usually suits its vendor.
+	//
+	// Merged HERE rather than at the one call site in `query()`, because
+	// this function is exported: a host wrapping its own chain must get the
+	// same precedence, and a merge upstream would give it the generic
+	// default while `query()` got the driver's.
+	const config: ProviderRetryConfig = {
+		...DEFAULT_PROVIDER_RETRY,
+		...provider.retryDefaults,
+		...options.config,
+	}
 	const random = options.random ?? Math.random
 	const doSleep = options.sleepFn ?? sleep
 	const log = options.log
 
+	// AFTER the merge. Above it, a driver declaring `maxRetries: 0` — the
+	// one that most needs to be honoured, because it is saying its vendor
+	// must not be retried — was read from the generic default instead and
+	// retried anyway.
 	if (config.maxRetries <= 0) return provider
 
 	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
@@ -113,12 +131,12 @@ export function withProviderRetry(
 
 				if (produced || !classified.retryable || exhausted) {
 					log?.warn('Provider call failed', {
-						provider: provider.id,
-						code: classified.code,
-						status: classified.status,
-						attempt: attempt + 1,
-						retryable: classified.retryable,
-						reason: produced
+						[GENAI.SYSTEM]: provider.id,
+						'namzu.provider.code': classified.code,
+						'namzu.provider.status': classified.status,
+						'namzu.retry.attempt': attempt + 1,
+						'namzu.provider.retryable': classified.retryable,
+						'namzu.provider.reason': produced
 							? 'stream already produced output — cannot retry without duplicating it'
 							: exhausted
 								? 'retries exhausted'
@@ -167,13 +185,14 @@ export function withProviderRetry(
 				// failure until those attempts were gone.
 				if (serverDirected !== undefined && serverDirected > config.maxRetryAfterMs) {
 					log?.warn('Provider call failed — server-directed wait exceeds the ceiling', {
-						provider: provider.id,
-						code: classified.code,
-						status: classified.status,
-						attempt: attempt + 1,
-						retryAfterMs: serverDirected,
-						maxRetryAfterMs: config.maxRetryAfterMs,
-						reason: 'surfacing rather than retrying — the caller decides how to wait',
+						[GENAI.SYSTEM]: provider.id,
+						'namzu.provider.code': classified.code,
+						'namzu.provider.status': classified.status,
+						'namzu.retry.attempt': attempt + 1,
+						'namzu.provider.retry_after_ms': serverDirected,
+						'namzu.provider.max_retry_after_ms': config.maxRetryAfterMs,
+						'namzu.provider.reason':
+							'surfacing rather than retrying — the caller decides how to wait',
 					})
 					throw isProviderRequestError(err) ? err : classified
 				}
@@ -181,13 +200,13 @@ export function withProviderRetry(
 				const delay = serverDirected ?? backoffWithJitter(attempt, config, random)
 
 				log?.warn('Provider call failed — retrying', {
-					provider: provider.id,
-					code: classified.code,
-					status: classified.status,
-					attempt: attempt + 1,
-					maxRetries: config.maxRetries,
-					delayMs: delay,
-					serverDirected: serverDirected !== undefined,
+					[GENAI.SYSTEM]: provider.id,
+					'namzu.provider.code': classified.code,
+					'namzu.provider.status': classified.status,
+					'namzu.retry.attempt': attempt + 1,
+					'namzu.provider.max_retries': config.maxRetries,
+					'namzu.provider.delay_ms': delay,
+					'namzu.provider.server_directed': serverDirected !== undefined,
 				})
 
 				// Tell the consumer BEFORE sleeping. With the default policy a
@@ -241,5 +260,28 @@ export function withProviderRetry(
 		...(provider.doctorCheck
 			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
 			: {}),
+		// 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
+		// legitimate state and therefore a silent one. Retry is on by
+		// default, so a dropped member is dropped on essentially every run.
+		//
+		// `effortLevelsFor` was in that position and had no consumer at all,
+		// which is exactly why nobody noticed: a driver's declared effort
+		// levels became invisible the moment its provider was wrapped.
+		...(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
 }