@namzu/sdk 16.0.0 → 18.0.0

package/src/provider/fallback.ts

@@ -0,0 +1,388 @@
+/**
+ * Advance through a declared provider chain when a member cannot serve.
+ *
+ * The sibling of `withProviderRetry`, one level out: retry asks "will the SAME
+ * member succeed if I ask again?", this asks "will ANOTHER member succeed if I
+ * ask it instead?". They compose in exactly one order —
+ * `fallback(retry(m0), retry(m1), …)` — and that order is the policy, not an
+ * implementation detail:
+ *
+ *  - the primary is the operator's choice and gets its retries first, so a
+ *    throttle or a 5xx only reaches this decorator once the inner budget is
+ *    spent;
+ *  - a failure the inner loop refuses to retry (`auth`, `not_found`) arrives
+ *    here immediately, which is what "fall over at once on a bad credential"
+ *    means — retrying a wrong key just spends the turn;
+ *  - a server-directed `Retry-After` is honoured by the inner loop before any
+ *    error escapes, so a transient wait is a wait and not a swap.
+ *
+ * None of those three behaviours is implemented here. They fall out of the
+ * nesting, which is why `query()` builds the composition rather than letting a
+ * host assemble it in whichever order it happens to pick.
+ */
+
+import { classifyProviderError, isAbortError } from '../types/provider/errors.js'
+import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../types/provider/index.js'
+import type { Logger } from '../utils/logger.js'
+
+/**
+ * One member of the chain: a constructed provider, and the model to ask it for.
+ *
+ * `model` overrides {@link ChatCompletionParams.model} for this member's
+ * requests and nothing else. Every shipped driver reads that field
+ * (`params.model`, or `params.model || <its configured default>`), so a member
+ * needs no reconstruction to be asked for a different model — which is what
+ * keeps this decorator ignorant of credentials, base URLs and registries. A
+ * chain is an ordered list of (provider, model); building one is the host's
+ * job, walking it is this file's.
+ *
+ * Absent means "whatever the request already asked for", which is the right
+ * default for a member declared without a model: the registry default was
+ * resolved into the request before it got here.
+ */
+export interface ProviderChainMember {
+	readonly provider: LLMProvider
+	readonly model?: string
+}
+
+/**
+ * The member serving from now on.
+ *
+ * `index` is a position in the chain the host declared, so a reader can name
+ * the member without holding the chain: "member 2 of 4" is the sentence an
+ * operator writes in an incident note.
+ */
+export interface ServingMember {
+	readonly index: number
+	readonly providerId: string
+	/** Absent for a member declared without one — see {@link ProviderChainMember.model}. */
+	readonly model?: string
+}
+
+export interface WithProviderFallbackOptions {
+	readonly log?: Logger
+	/**
+	 * Called once per swap, with the member that serves from here on.
+	 *
+	 * A callback is enough to describe the WHOLE truth, not a sample of it,
+	 * and that is a property of the cursor rather than of this option: the
+	 * chain never rewinds, so "who is serving" is exactly "the head, plus
+	 * every swap so far". A listener that starts at member 0 and applies each
+	 * call is never behind.
+	 *
+	 * It exists beside the in-band `fallback` chunk rather than instead of it
+	 * because the two have different observers and neither covers the other's
+	 * case. The chunk reaches whoever is iterating the stream, at the moment
+	 * of the swap — that is the operator. This reaches a party that has to
+	 * know AFTER the request is over and may never have iterated the stream at
+	 * all — that is the run record. Two things follow that the chunk alone
+	 * cannot give it:
+	 *
+	 *  - the cursor outlives the request, so a swap on the turn at step 3
+	 *    still describes steps 4..N, which emit no further chunk;
+	 *  - a side call that aggregates the stream through `collect()` — the
+	 *    compaction verifier and the forced-final summary both do — drops the
+	 *    `fallback` chunk on the floor, so a swap inside one is invisible to
+	 *    every chunk consumer. (The advisory executor calls its OWN advisor's
+	 *    provider, not the run's, so it is not one of these.)
+	 *
+	 * ## Fired when the replacement is ASKED, not when the cursor moves
+	 *
+	 * The two are not the same instant and the difference is observable. The
+	 * cursor moves inside the catch; the notice chunk is then yielded, and the
+	 * replacement request is only issued when the consumer comes back for
+	 * another chunk. A consumer that stops there — a Stop, a `break`, a host
+	 * that abandons the iterator — leaves a chain that selected a member and
+	 * never asked it.
+	 *
+	 * Announcing at cursor-move would report that member as serving, and a
+	 * ledger saying a provider served a turn it was never sent is the exact
+	 * defect this callback exists to end, reintroduced one layer down. So the
+	 * announcement sits at the top of the loop, immediately before the
+	 * replacement's `chatStream` — the earliest moment at which the member is
+	 * actually being asked.
+	 *
+	 * ## One stream at a time
+	 *
+	 * `cursor` is shared by every concurrent `chatStream` on this wrapper, so
+	 * two overlapping calls can advance it under one another: one call's
+	 * failure moves the cursor while the other is still being served by the
+	 * head, and a listener would hear about a member that answered nothing for
+	 * that call. Nothing here serializes or refuses concurrency — the
+	 * property held before this option existed and is not introduced by it.
+	 * `query()` issues its main turn and its side calls in sequence, which is
+	 * what makes the reading exact there.
+	 */
+	readonly onSwap?: (to: ServingMember) => void
+}
+
+/**
+ * Failures that are a property of the REQUEST rather than of the member serving
+ * it.
+ *
+ * This is the whole decision, stated once. A request fault reproduces
+ * identically on the next member, so falling over would spend a second
+ * provider's money to buy the same error. Everything else — a throttle, an
+ * outage, a rejected credential, a model this provider does not have, a stream
+ * that came back malformed — is a fact about the member, and the next member is
+ * worth asking.
+ *
+ * The three entries, and what each of them being here means:
+ *
+ * - `context_length_exceeded` — the run's own remedy is compaction, which sheds
+ *   history and asks again. Falling over instead would carry the same oversized
+ *   prompt to a provider that has not been given the chance to fit it. Note the
+ *   limit of that reasoning: a chain MAY pair a small window with a larger one,
+ *   and then a fallback genuinely could have succeeded. Compaction is still
+ *   preferred because it is cheaper and it keeps the operator on the provider
+ *   they chose.
+ * - `invalid_request` — namzu built a request the provider rejected. The
+ *   counter-case is real and is recorded here rather than hidden: drivers
+ *   translate the same tool schema differently onto the wire, so a 400 about a
+ *   JSON Schema dialect (see `provider/errors.ts`) is provider-specific and
+ *   another member might accept it. Abort still wins, because the common case
+ *   is a request that is wrong everywhere, and spending the entire chain to
+ *   rediscover one defect is the worse failure.
+ * - `content_filter` — a refusal. No shipped driver reaches this through a
+ *   THROW today: the drivers that surface a filtered completion do so as
+ *   `finishReason: 'content_filter'`, which is a finished stream, not an error.
+ *   The input that makes this entry fire is a driver that throws instead — the
+ *   classifier maps a `content_policy_violation` structural code onto it, and
+ *   `ProviderError` is a public type a third-party driver constructs directly.
+ *   Named rather than omitted for that reason; see
+ *   `docs/conventions/a-check-that-cannot-fail.md` for why an unnameable one
+ *   would have been left out.
+ */
+const REQUEST_FAULT_CODES: ReadonlySet<string> = new Set([
+	'context_length_exceeded',
+	'invalid_request',
+	'content_filter',
+])
+
+/**
+ * Does this failure justify asking the next member?
+ *
+ * The classification is taken from `classifyProviderError` and not re-derived.
+ * A second classifier that disagreed with the first would be two answers to one
+ * question, and the retry decorator already stands on that same answer.
+ *
+ * `status === 404` is read ALONGSIDE the code, and it is not a second opinion —
+ * it is a second field of the one classification. A 404 reaches `not_found`
+ * only on the unclassified path (`codeFromStatus`). A driver that classified
+ * its own 404 into a `ProviderRequestError` gets `kind: 'bad_request'` from
+ * `classifyProviderHttpStatus`, which `KIND_TO_CODE` maps to
+ * `invalid_request` — a request fault, so the run would ABORT on a model the
+ * next member may well have. The status survives on both paths; the code does
+ * not, so the status is what this reads.
+ */
+function shouldFallOver(err: unknown, providerId: string): boolean {
+	const classified = classifyProviderError(err, providerId)
+	if (classified.status === 404) return true
+	return !REQUEST_FAULT_CODES.has(classified.code)
+}
+
+/**
+ * Has the consumer already been handed something a restart would duplicate?
+ *
+ * Deliberately NOT the retry decorator's rule, and the difference is the bug
+ * this function exists to prevent. Retry treats every chunk that is not
+ * error-only as output, which is correct INSIDE retry because each attempt
+ * starts with the flag cleared. Reused one level out it is wrong in the worst
+ * possible place: the inner decorator emits a backoff notice through this
+ * stream on its way to sleeping, that notice is not error-only, and a fallback
+ * reading it as output would refuse to advance for the rest of the turn — for
+ * the 429/5xx path, which is the main reason a chain is declared at all.
+ *
+ * So this asks the narrow question instead: did a chunk carry something the
+ * orchestrator turned into a visible event? `text_delta`, tool-input fragments
+ * and their per-tool boundary, reasoning blocks and citations all did.
+ * `usage`, `finishReason` and the two control notices did not.
+ */
+function isOutputChunk(chunk: StreamChunk): boolean {
+	if (chunk.retry !== undefined || chunk.fallback !== undefined) return false
+	const { content, toolCalls, toolCallEnd, reasoning, citation } = chunk.delta
+	return Boolean(
+		content ||
+			toolCalls?.length ||
+			toolCallEnd ||
+			reasoning !== undefined ||
+			citation !== undefined,
+	)
+}
+
+/**
+ * Wrap an ordered chain so a member that cannot serve is replaced in place.
+ *
+ * ## The cursor's lifetime IS the scope
+ *
+ * Once this decorator advances, every later request in its life goes to the new
+ * member; the chain never rewinds. That is deliberate and it is how "the
+ * primary is restored at each new user message" is implemented — by NOT
+ * implementing it. `query()` builds one of these per call and a host's call is
+ * its turn, so the cursor cannot outlive the turn because the object cannot.
+ * There is no reset to forget to call, and no way for a rate limit at 14:00 to
+ * leave an operator on a cheaper model at 17:00.
+ *
+ * Rewinding within the turn would be the alternative, and it is worse: the
+ * member that just failed would be re-asked on the next iteration of the same
+ * turn, which is a retry wearing a chain's clothes and which the inner
+ * decorator already declined to do.
+ *
+ * ## Each member is tried at most once per turn, and the whole chain is walked
+ *
+ * A chain of N members yields up to N attempts, not one. An operator who
+ * declares four members and is served only by the second on a bad day has been
+ * given three decorative entries — that is the declared-but-undriven defect
+ * this file exists to remove, and stopping after one step would reintroduce it
+ * at position 2 instead of position 1. When the last member fails, its error is
+ * thrown untouched and ordinary error handling takes over.
+ *
+ * ## Once output is out, there is no fallback
+ *
+ * Inherited from retry, for the same reason and not a weaker one: a stream that
+ * has emitted bytes cannot be restarted without duplicating them, and the
+ * consumer has already appended them to a message it is rendering. A mid-stream
+ * failure after output is surfaced, never swapped. See {@link isOutputChunk} —
+ * the definition of "output" is where this property is actually won or lost.
+ *
+ * ## Capabilities are the head's
+ *
+ * The getters below are transparent, so a run negotiates tools, vision and
+ * documents ONCE against `members[0]` and keeps that answer after a swap. This
+ * is a real limitation and it is why the host is expected to refuse a chain
+ * 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.
+ */
+export function withProviderFallback(
+	members: readonly ProviderChainMember[],
+	options: WithProviderFallbackOptions = {},
+): LLMProvider {
+	const first = members[0]
+	if (!first) {
+		throw new Error('withProviderFallback needs at least one member')
+	}
+	// A one-member chain is the identity. Returning the provider itself rather
+	// than a wrapper that can never advance keeps the no-chain path byte-identical
+	// to what it was before this file existed.
+	//
+	// `onSwap` is therefore never called on this path, and that is the correct
+	// reading rather than a hole: a listener starts at member 0 and a one-member
+	// chain never leaves it. Announcing member 0 here would say "the chain
+	// advanced" about a chain that cannot.
+	if (members.length === 1) return first.provider
+
+	const log = options.log
+	let cursor = 0
+	/**
+	 * The last position {@link WithProviderFallbackOptions.onSwap} was told
+	 * about. Lags `cursor` for exactly as long as the consumer has the notice
+	 * chunk and has not come back for more — which is the window in which a
+	 * selected member has not been asked anything. See that option's doc.
+	 */
+	let announced = 0
+
+	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		for (;;) {
+			const member = members[cursor]
+			// Unreachable while `cursor` only ever moves to an index this loop has
+			// bounds-checked below; kept because the alternative on a future edit is
+			// calling `chatStream` on undefined, which names neither the field nor
+			// the fix.
+			if (!member) throw new Error(`provider chain has no member at position ${cursor}`)
+
+			if (announced !== cursor) {
+				announced = cursor
+				options.onSwap?.({
+					index: cursor,
+					providerId: member.provider.id,
+					...(member.model !== undefined ? { model: member.model } : {}),
+				})
+			}
+
+			const request = member.model !== undefined ? { ...params, model: member.model } : params
+			let produced = false
+			try {
+				for await (const chunk of member.provider.chatStream(request)) {
+					if (isOutputChunk(chunk)) produced = true
+					yield chunk
+				}
+				return
+			} catch (err) {
+				// A Stop is control flow, not a provider failure. Without this the
+				// classifier — which has no concept of cancellation — would file an
+				// abort as some ordinary failure and the run would walk the entire
+				// chain re-issuing an already-cancelled request, one member at a
+				// time, instead of settling as `cancelled`. The retry decorator
+				// guards the same way and for the same reason.
+				if (isAbortError(err) || params.signal?.aborted) throw err
+
+				const next = cursor + 1
+				const to = members[next]
+				if (produced || !to || !shouldFallOver(err, member.provider.id)) {
+					log?.warn('Provider chain: not falling over', {
+						provider: member.provider.id,
+						position: cursor,
+						reason: produced
+							? 'stream already produced output — cannot restart without duplicating it'
+							: !to
+								? 'chain exhausted'
+								: 'the failure is a property of the request, not of the provider',
+					})
+					throw err
+				}
+
+				const classified = classifyProviderError(err, member.provider.id)
+				cursor = next
+				log?.warn('Provider chain: falling over', {
+					from: member.provider.id,
+					fromPosition: cursor - 1,
+					to: to.provider.id,
+					toPosition: cursor,
+					code: classified.code,
+					status: classified.status,
+				})
+
+				// In-band, exactly like the retry notice and for the same reason: the
+				// consumer is blocked inside this iterator, so the stream is the only
+				// channel that reaches it at the moment the swap happens rather than
+				// after the replacement request has already run.
+				yield {
+					id: '',
+					delta: {},
+					fallback: {
+						fromIndex: cursor - 1,
+						fromProviderId: member.provider.id,
+						...(member.model !== undefined ? { fromModel: member.model } : {}),
+						toIndex: cursor,
+						toProviderId: to.provider.id,
+						...(to.model !== undefined ? { toModel: to.model } : {}),
+						code: classified.code,
+						...(classified.status !== undefined ? { status: classified.status } : {}),
+						reason: classified.message,
+					},
+				}
+			}
+		}
+	}
+
+	// Transparent to capability negotiation and identity, like the retry
+	// decorator. The head's declarations are what a run is configured from; see
+	// the note on capabilities above for the limitation that carries.
+	return {
+		get id() {
+			return first.provider.id
+		},
+		get name() {
+			return first.provider.name
+		},
+		get capabilities() {
+			return first.provider.capabilities
+		},
+		chatStream,
+		...(first.provider.listModels ? { listModels: () => first.provider.listModels?.() } : {}),
+		...(first.provider.healthCheck ? { healthCheck: () => first.provider.healthCheck?.() } : {}),
+		...(first.provider.doctorCheck ? { doctorCheck: () => first.provider.doctorCheck?.() } : {}),
+	} as LLMProvider
+}

package/src/provider/index.ts

@@ -35,3 +35,9 @@ export {
 } from '../types/provider/errors.js'
 export { DEFAULT_PROVIDER_RETRY, withProviderRetry } from './retry.js'
 export type { ProviderRetryConfig, WithProviderRetryOptions } from './retry.js'
+export { withProviderFallback } from './fallback.js'
+export type {
+	ProviderChainMember,
+	ServingMember,
+	WithProviderFallbackOptions,
+} from './fallback.js'

package/src/provider/retry.ts

@@ -14,6 +14,15 @@ export interface ProviderRetryConfig {
 	 * Cap on a server-directed `Retry-After`. A provider asking for 15
 	 * minutes should not silently park an interactive run for 15 minutes;
 	 * past this we surface the error and let the caller decide.
+	 *
+	 * "Surface" is the whole of it: there is no shorter retry underneath. A
+	 * server that named a wait has said something specific, and answering it
+	 * with a half-second backoff neither honours the wait nor tells anyone it
+	 * was refused. The error carries `retryAfterMs`, so a host that wants to
+	 * come back in fifteen minutes can — that decision is above this loop.
+	 *
+	 * Raise it to let the run sleep longer; a request under the ceiling is
+	 * still slept exactly as instructed.
 	 */
 	readonly maxRetryAfterMs: number
 }
@@ -153,10 +162,48 @@ export function withProviderRetry(
 				}
 
 				const serverDirected = classified.retryAfterMs
-				const delay =
-					serverDirected !== undefined && serverDirected <= config.maxRetryAfterMs
-						? serverDirected
-						: backoffWithJitter(attempt, config, random)
+
+				// The server named a wait longer than the caller's ceiling, so the
+				// error goes to the caller — which is what `maxRetryAfterMs`
+				// documents and what it now does.
+				//
+				// It used to fall through to the jittered backoff instead, and that
+				// is degrading where the contract says refuse
+				// (`docs/conventions/refuse-do-not-degrade.md`). The ceiling was
+				// read as "how long may I sleep", so a provider asking for fifteen
+				// minutes was re-asked in half a second: the one instruction the
+				// server gave was the one thing discarded, and the retries that
+				// followed were sent to an endpoint that had already said it would
+				// not serve them. They cost the run its whole budget to rediscover
+				// a 429 it had been told about in advance.
+				//
+				// The caller loses nothing it had. This throws the SAME error the
+				// exhausted path throws, so the run settles exactly as it did
+				// before — only sooner, and with `retryAfterMs` intact for a host
+				// that wants to schedule against it. What it gains is the wait
+				// itself, which no backoff of ours can honour: fifteen minutes is
+				// not a number this loop is allowed to sleep for.
+				//
+				// With a chain declared it gains more than that. The error is a
+				// `rate_limit`, which is a fact about the MEMBER, so
+				// `withProviderFallback` moves to the next one — the run continues
+				// on another provider instead of spending its budget arguing with
+				// the first. Under the old behaviour the chain did not see the
+				// 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',
+					})
+					throw isProviderRequestError(err) ? err : classified
+				}
+
+				const delay = serverDirected ?? backoffWithJitter(attempt, config, random)
 
 				log?.warn('Provider call failed — retrying', {
 					provider: provider.id,

package/src/public-runtime.ts

@@ -268,9 +268,15 @@ export {
 	registerMock,
 	resolveProviderCapabilities,
 	UnknownProviderError,
+	withProviderFallback,
 	withProviderRetry,
 } from './provider/index.js'
-export type { ProviderRetryConfig, WithProviderRetryOptions } from './provider/index.js'
+export type {
+	ProviderChainMember,
+	ProviderRetryConfig,
+	WithProviderFallbackOptions,
+	WithProviderRetryOptions,
+} from './provider/index.js'
 
 export {
 	assertIsolation,

package/src/run/reporter.ts

@@ -332,6 +332,26 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'provider_fallback':
+				// `warn` for the same reason as a retry, and one stronger: the rest
+				// of this run is being served by a provider the caller did not pick.
+				log.warn(
+					`Provider ${event.fromProviderId} could not serve — continuing on ${event.toProviderId}`,
+					{
+						runId: event.runId,
+						iteration: event.iteration,
+						fromIndex: event.fromIndex,
+						fromProviderId: event.fromProviderId,
+						fromModel: event.fromModel,
+						toIndex: event.toIndex,
+						toProviderId: event.toProviderId,
+						toModel: event.toModel,
+						code: event.code,
+						status: event.status,
+					},
+				)
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/query/index.ts

@@ -16,6 +16,11 @@ 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,
+	type ServingMember,
+	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 +125,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 +494,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 +551,48 @@ 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() })
+	// Who is serving right now, for the run RECORD rather than for the request.
+	//
+	// It starts at the head and moves only when the chain does, which is the
+	// whole of the truth because the cursor never rewinds. The run cannot read
+	// this off `resilientProvider`: that wrapper reports the head's `id` on
+	// purpose, so asking it produces the declaration back — the defect this
+	// record exists to fix.
+	const serving: { current: ServingMember } = {
+		current: { index: 0, providerId: params.provider.id },
+	}
+	const resilientProvider = withProviderFallback(
+		chain.map((member) => ({ ...member, provider: withRetry(member.provider) })),
+		{
+			log: getRootLogger(),
+			onSwap: (to) => {
+				serving.current = to
+				// `ctx` is declared below and is initialized before anything can
+				// call the provider: this fires from inside a `chatStream`, and
+				// the first one is issued by the loop that `ctx` is built for.
+				ctx.runMgr.setServingProvider(to.providerId)
+			},
+		},
+	)
 
 	const ctx = RunContextFactory.build({
 		agentId: params.agentId,
@@ -821,6 +921,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 	const iterationOrchestrator = new IterationOrchestrator({
 		provider: resilientProvider,
+		servingMember: () => serving.current,
 		runConfig: params.runConfig,
 		...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
 		...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),