@namzu/sdk 16.0.0 → 17.0.0

package/src/runtime/query/index.ts

@@ -16,6 +16,7 @@ import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
+import { type ProviderChainMember, withProviderFallback } from '../../provider/fallback.js'
 import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import {
@@ -120,6 +121,23 @@ export interface QueryParams {
 	 */
 	retry?: Partial<ProviderRetryConfig> | false
 
+	/**
+	 * Members to fall over to, in order, when {@link provider} cannot serve.
+	 *
+	 * Absent means what it always meant: one provider, no failover. Each member
+	 * is tried at most once per call and the chain never rewinds, so the scope
+	 * of a swap is this `query()` — for a host whose call is one user turn, that
+	 * is turn scope with no reset to forget. See `withProviderFallback`.
+	 *
+	 * Two things this does NOT do, both deliberate. Capabilities are negotiated
+	 * once against {@link provider}, so a member that declares less will be sent
+	 * a request shaped for the head — refuse a disagreeing chain before you
+	 * build one. And a fallback loses the prompt cache: the replacement provider
+	 * has never seen this conversation, so the turn re-reads its whole context
+	 * at full price.
+	 */
+	fallbackProviders?: readonly ProviderChainMember[]
+
 	/**
 	 * Install process-level crash handlers that dump this run's state to
 	 * `<runDir>/../emergency/<runId>.json` on SIGINT, SIGTERM or an
@@ -472,6 +490,46 @@ export interface QueryParams {
 	strictCapabilities?: boolean
 }
 
+/**
+ * Refuse to price a run whose tokens two differently-priced members may produce.
+ *
+ * `RunPersistence` holds ONE {@link ModelPricing} table and applies it to every
+ * accumulation regardless of which model produced the tokens. Across a swap that
+ * makes `costInfo.totalCost` wrong by an unbounded margin, and silently — the
+ * number keeps the shape of an answer. `CostInfo` cannot express the truth
+ * either: it carries `inputCostPer1M` / `outputCostPer1M`, and there is no
+ * honest value for those once a total spans two rate cards.
+ *
+ * So the total is refused rather than blended. Naming what that costs is part
+ * of the refusal, because the caller loses `costLimitUsd` with it: the guard
+ * enforces that limit from this same accumulated total, and a limit enforced
+ * with the wrong rate card stops a run early or late by the same unbounded
+ * margin. A budget that is quietly wrong is worse than a budget that is
+ * declined.
+ *
+ * Reachable, not decorative: a host that passes `pricing` and declares a chain
+ * hits it on the first call. It costs `@namzu/cli` nothing, which passes no
+ * pricing at all — its `/cost` already reports that the provider gave no price.
+ *
+ * The way out is per-member pricing, which needs a `CostInfo` that can sum over
+ * heterogeneous rates. That is a public-type change and it is not this one.
+ */
+function assertCostIsAttributable(
+	chain: readonly ProviderChainMember[],
+	pricing: ModelPricing | undefined,
+): void {
+	if (pricing === undefined || chain.length < 2) return
+	throw new NamzuError({
+		code: 'invalid_config',
+		message:
+			`A provider chain of ${chain.length} members was declared together with a single pricing table. ` +
+			'One table cannot price two members, so the run would report a total that is wrong by an unbounded ' +
+			'margin — and `runConfig.costLimitUsd` would be enforced against that same wrong total. ' +
+			'Either drop `pricing` (usage is still reported per model in the run) or declare one member.',
+		details: { chainLength: chain.length },
+	})
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
 	// call per process per root actually runs; subsequent calls short-circuit
@@ -489,10 +547,29 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// of its warns behind `options.log`, and this is its only production
 	// call site — so without it the "failed, retrying" and "failed, giving
 	// up" lines were dead code and a backoff left no trace anywhere.
-	const resilientProvider =
+	//
+	// With a chain declared, the same sentence holds one level out: retry is
+	// applied per MEMBER and the fallback decorator wraps the result, so the
+	// composition is `fallback(retry(m0), retry(m1), …)`. That order is not a
+	// preference. Assembled the other way round — which is what a host gets if
+	// it wraps its own chain and hands the result in, because this function
+	// would then wrap THAT in retry — an exhausted chain gets restarted from
+	// the head by the outer loop and a throttle on the last member is counted
+	// by two budgets. Building it here is what makes the order unspellable
+	// wrong.
+	const chain: readonly ProviderChainMember[] = [
+		{ provider: params.provider },
+		...(params.fallbackProviders ?? []),
+	]
+	assertCostIsAttributable(chain, params.pricing)
+	const withRetry = (provider: LLMProvider): LLMProvider =>
 		params.retry === false
-			? params.provider
-			: withProviderRetry(params.provider, { config: params.retry, log: getRootLogger() })
+			? provider
+			: withProviderRetry(provider, { config: params.retry, log: getRootLogger() })
+	const resilientProvider = withProviderFallback(
+		chain.map((member) => ({ ...member, provider: withRetry(member.provider) })),
+		{ log: getRootLogger() },
+	)
 
 	const ctx = RunContextFactory.build({
 		agentId: params.agentId,

package/src/runtime/query/iteration/stream-turn.ts

@@ -258,6 +258,32 @@ export async function* streamProviderTurn(
 				continue
 			}
 
+			// A chain swap, not output, and handled beside the retry notice
+			// because it is the same kind of thing: a fact about HOW the answer
+			// is being produced, arriving on the only channel open while the
+			// consumer is blocked inside the provider's iterator. It carries no
+			// delta, so nothing below applies to it either.
+			if (chunk.fallback) {
+				await emitEvent({
+					type: 'provider_fallback',
+					runId,
+					iteration,
+					fromIndex: chunk.fallback.fromIndex,
+					fromProviderId: chunk.fallback.fromProviderId,
+					...(chunk.fallback.fromModel !== undefined
+						? { fromModel: chunk.fallback.fromModel }
+						: {}),
+					toIndex: chunk.fallback.toIndex,
+					toProviderId: chunk.fallback.toProviderId,
+					...(chunk.fallback.toModel !== undefined ? { toModel: chunk.fallback.toModel } : {}),
+					code: chunk.fallback.code,
+					...(chunk.fallback.status !== undefined ? { status: chunk.fallback.status } : {}),
+					reason: chunk.fallback.reason,
+				})
+				yield* drainPending()
+				continue
+			}
+
 			if (chunk.error) {
 				streamError = chunk.error
 				break

package/src/types/provider/stream.ts

@@ -81,6 +81,18 @@ export interface StreamChunk {
 	 * output.
 	 */
 	retry?: ProviderRetryNotice
+
+	/**
+	 * The call failed and a different member of the provider chain is taking
+	 * over from here.
+	 *
+	 * Emitted by the fallback decorator, never by a driver, and it rides the
+	 * stream for the reason {@link retry} does. Like a retry notice it carries
+	 * no delta and must not be treated as output — and that distinction is
+	 * load-bearing twice over, because the fallback decorator reads these
+	 * chunks too when deciding whether output has already gone out.
+	 */
+	fallback?: ProviderFallbackNotice
 }
 
 /** See {@link StreamChunk.retry}. */
@@ -96,3 +108,28 @@ export interface ProviderRetryNotice {
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
 }
+
+/**
+ * See {@link StreamChunk.fallback}.
+ *
+ * Both members are named, not just the new one. Naming only the replacement
+ * does not tell an operator which of their declared members went down, and on a
+ * chain of four that is the only fact they can act on.
+ *
+ * The positions are 0-based indices into the chain as the host declared it, so
+ * a surface can name a member the way its own configuration does rather than
+ * inventing a second numbering.
+ */
+export interface ProviderFallbackNotice {
+	readonly fromIndex: number
+	readonly fromProviderId: string
+	readonly fromModel?: string
+	readonly toIndex: number
+	readonly toProviderId: string
+	readonly toModel?: string
+	/** Classified failure code, as `classifyProviderError` reports it. */
+	readonly code: string
+	readonly status?: number
+	/** The classified failure's own sentence, already redacted at its source. */
+	readonly reason: string
+}

package/src/types/run/events.ts

@@ -186,6 +186,35 @@ type CoreRunEvent =
 			/** The delay came from the server's own `Retry-After`. */
 			serverDirected: boolean
 	  }
+	/**
+	 * A member of the provider chain could not serve, and a later member has
+	 * taken over. The run continues from where it stopped.
+	 *
+	 * This event is the feature's honesty. A chain that swapped silently would
+	 * produce a run that succeeded while quietly not doing what the operator
+	 * asked — served by a provider they did not choose, at a price and a
+	 * quality they did not agree to, with nothing in the transcript saying so.
+	 * A host is expected to SHOW this, not log it.
+	 *
+	 * Emitted at the moment of the swap, before the replacement request runs.
+	 */
+	| {
+			type: 'provider_fallback'
+			runId: RunId
+			iteration: number
+			/** 0-based position in the chain, as the host declared it. */
+			fromIndex: number
+			fromProviderId: string
+			fromModel?: string
+			toIndex: number
+			toProviderId: string
+			toModel?: string
+			/** Classified failure code, as the boundary classifier reports it. */
+			code: string
+			status?: number
+			/** The classified failure's own sentence. */
+			reason: string
+	  }
 	| {
 			type: 'tool_completed'
 			runId: RunId