@namzu/sdk 17.0.0 → 18.1.0

package/dist/types/run/step.d.ts

@@ -14,7 +14,46 @@ import type { ToolCall } from '../message/index.js';
 export interface StepResult {
     /** 1-based, matching `iteration` on the run events. */
     stepNumber: number;
+    /**
+     * The model this step ASKED for: the run's configured model, or the
+     * override a `prepareStep` hook returned for this step.
+     *
+     * It used to be the run's model unconditionally — the loop passed its own
+     * `model` here while building the request from `step.model ?? model` a few
+     * lines above — so a host that routed one step to a cheaper model read the
+     * expensive one back out of the ledger. No chain was needed to see it.
+     *
+     * What was asked for and what answered are two facts, and after a provider
+     * chain falls over they differ. This is the first; {@link servedBy} is the
+     * second.
+     */
     model: string;
+    /**
+     * Who actually answered, and with which model.
+     *
+     * Equal to {@link model} and to `run.metadata.provider` on every run
+     * without a chain, which is most of them; it diverges exactly when
+     * `withProviderFallback` advanced. Recorded even when it agrees, because a
+     * ledger that carries the fact only when it is surprising cannot be read as
+     * evidence — a reader could not tell "the head served" from "nobody wrote
+     * it down".
+     *
+     * Optional only for records that predate the field. Absence means "not
+     * recorded", and it is left meaning that rather than backfilled: the sdk
+     * shipped a chain that could fall over one release before it recorded
+     * which member did, so filling those in from the declared head would state
+     * as fact the exact thing that release got wrong, on exactly the runs
+     * where it was wrong. Every step this build produces has it.
+     *
+     * **Reaches a host through the returned `Run`, not through `run.json`.**
+     * `RunDiskStore.writeRunMeta` persists the metadata and the counters and
+     * does not write `steps` at all, so the built-in store carries the
+     * run-level {@link
+     * import('./entity.js').RunStateMetadata.servingProvider} and none of
+     * this. A host that wants per-step provenance on disk persists the `Run`
+     * it is handed.
+     */
+    servedBy?: StepProvenance;
     messageId: MessageId;
     /** Assistant text for this step, if any. */
     content: string | null;
@@ -32,6 +71,20 @@ export interface StepResult {
     /** Portion of `durationMs` spent inside tools. */
     toolExecutionMs: number;
 }
+/**
+ * The chain member that served one step.
+ *
+ * `chainIndex` is a position in the chain the host declared, and it is here
+ * rather than derived from `providerId` because a chain may legitimately name
+ * the same provider twice — two models, or two credentials, on one driver.
+ * `providerId` alone could not tell those apart.
+ */
+export interface StepProvenance {
+    readonly providerId: string;
+    readonly model: string;
+    /** 0 is the head, i.e. the provider the run was configured with. */
+    readonly chainIndex: number;
+}
 export interface StepToolResult {
     toolCallId: string;
     toolName: string;

package/dist/types/run/step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAC1B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,SAAS,CAAA;IACpB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC9B,uDAAuD;IACvD,WAAW,EAAE,SAAS,cAAc,EAAE,CAAA;IACtC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,2DAA2D;IAC3D,KAAK,EAAE,UAAU,CAAA;IACjB,0EAA0E;IAC1E,SAAS,EAAE,QAAQ,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAErF,MAAM,WAAW,kBAAkB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;CAC5B;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAG7D;AAED,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,CAOnE"}
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAC1B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,SAAS,EAAE,SAAS,CAAA;IACpB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC9B,uDAAuD;IACvD,WAAW,EAAE,SAAS,cAAc,EAAE,CAAA;IACtC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,2DAA2D;IAC3D,KAAK,EAAE,UAAU,CAAA;IACjB,0EAA0E;IAC1E,SAAS,EAAE,QAAQ,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAErF,MAAM,WAAW,kBAAkB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;CAC5B;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAG7D;AAED,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,CAOnE"}

package/dist/types/run/step.js.map

@@ -1 +1 @@
-{"version":3,"file":"step.js","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AAqEA,0CAA0C;AAC1C,MAAM,UAAU,WAAW,CAAC,CAAS;IACpC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAe;IAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,KAAK,CAAC,GAAG,UAA2B;IACnD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACtB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACpC,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;QACxC,CAAC;QACD,OAAO,KAAK,CAAA;IACb,CAAC,CAAA;AACF,CAAC"}
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AA2HA,0CAA0C;AAC1C,MAAM,UAAU,WAAW,CAAC,CAAS;IACpC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAe;IAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,KAAK,CAAC,GAAG,UAA2B;IACnD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACtB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACpC,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;QACxC,CAAC;QACD,OAAO,KAAK,CAAA;IACb,CAAC,CAAA;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "17.0.0",
+  "version": "18.1.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/manager/run/persistence.ts

@@ -286,6 +286,20 @@ export class RunPersistence {
 		this.run.steps = steps
 	}
 
+	/**
+	 * Record that a provider chain advanced, so the run record stops naming a
+	 * member that did not serve.
+	 *
+	 * Last writer wins on purpose: a chain of four can advance three times in
+	 * one run, and `metadata.servingProvider` answers "who was serving when
+	 * this ended", not "who was ever asked". The full sequence is in the
+	 * transcript's `provider_fallback` events and, per turn, in
+	 * `steps[].servedBy`.
+	 */
+	setServingProvider(providerId: string): void {
+		this.run.metadata.servingProvider = providerId
+	}
+
 	clearLastPromptTokens(): void {
 		this._lastPromptTokens = undefined
 		this._lastPromptMessageCount = undefined

package/src/provider/fallback.ts

@@ -45,8 +45,75 @@ export interface ProviderChainMember {
 	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
 }
 
 /**
@@ -199,10 +266,22 @@ export function withProviderFallback(
 	// 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 (;;) {
@@ -213,6 +292,15 @@ export function withProviderFallback(
 			// 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 {

package/src/provider/index.ts

@@ -36,4 +36,8 @@ export {
 export { DEFAULT_PROVIDER_RETRY, withProviderRetry } from './retry.js'
 export type { ProviderRetryConfig, WithProviderRetryOptions } from './retry.js'
 export { withProviderFallback } from './fallback.js'
-export type { ProviderChainMember, WithProviderFallbackOptions } 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/runtime/query/index.ts

@@ -16,7 +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, withProviderFallback } from '../../provider/fallback.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 {
@@ -566,9 +570,28 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		params.retry === false
 			? 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() },
+		{
+			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({
@@ -898,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 } : {}),

package/src/runtime/query/iteration/index.ts

@@ -32,6 +32,7 @@ import type { AnswerReview } from '../../../types/run/answer-review.js'
 import type {
 	PrepareStepResult,
 	RunEvent,
+	StepProvenance,
 	StepResult,
 	StopReason,
 } from '../../../types/run/index.js'
@@ -425,6 +426,40 @@ export class IterationOrchestrator {
 						iterSpan,
 					)
 
+					// Who answered THIS turn.
+					//
+					// The read is exact at this point and stays exact: a chain that
+					// has produced output cannot fall over again inside the same
+					// request, so the member at the cursor when the stream ends is
+					// the one whose bytes are in `response`.
+					//
+					// It is taken here rather than at `recordStep` several hundred
+					// lines below, and the honest account of that is defence in
+					// depth, not a defect it currently prevents. Moving it down
+					// fails no test, because nothing between the two asks this
+					// provider for anything: compaction and working memory run
+					// BEFORE the turn, the advisory phase runs after the step is
+					// already recorded, and the only thing in between is tool
+					// execution. That is a fact about today's phase order, which a
+					// later phase inserted here would change silently — and the
+					// symptom would be a step attributed to a member that first
+					// served the turn after it, which is the class of wrongness
+					// this whole field exists to end.
+					const servedBy: StepProvenance = ((): StepProvenance => {
+						const member = this.ctx.servingMember?.() ?? {
+							index: 0,
+							providerId: this.ctx.provider.id,
+						}
+						return {
+							providerId: member.providerId,
+							// A member declared without a model asked for the model the
+							// step named — which is what the decorator does with the
+							// request, so this is a reading of it and not a guess.
+							model: member.model ?? stepModel,
+							chainIndex: member.index,
+						}
+					})()
+
 					// Main-loop turn: also records the prompt size compaction reads.
 					runMgr.recordTurnUsage(response.usage)
 
@@ -746,7 +781,12 @@ export class IterationOrchestrator {
 					// and a caller reconstructing cost per step must see it.
 					this.recordStep({
 						stepNumber: iterationNum,
-						model,
+						// The model this step ASKED for. It used to be `model`, the
+						// run's own — so a `prepareStep` that routed one step to a
+						// cheaper model was recorded as the expensive one, with no
+						// provider chain involved.
+						model: stepModel,
+						servedBy,
 						messageId,
 						response,
 						toolResults: reviewOutcome.results,
@@ -1201,6 +1241,7 @@ export class IterationOrchestrator {
 	private recordStep(input: {
 		stepNumber: number
 		model: string
+		servedBy: StepProvenance
 		messageId: MessageId
 		response: ChatCompletionResponse
 		toolResults: readonly ToolCallOutcome[]
@@ -1216,6 +1257,7 @@ export class IterationOrchestrator {
 		const step: StepResult = {
 			stepNumber: input.stepNumber,
 			model: input.model,
+			servedBy: input.servedBy,
 			messageId: input.messageId,
 			content: input.response.message.content,
 			toolCalls,

package/src/runtime/query/iteration/phases/context.ts

@@ -6,6 +6,7 @@ import type { CompactionConfig } from '../../../../config/runtime.js'
 import type { CompletionInbox } from '../../../../gateway/completion-inbox.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
+import type { ServingMember } from '../../../../provider/fallback.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
 import type { TaskGateway } from '../../../../types/agent/gateway.js'
 import type { WorkingMemoryProvider } from '../../../../types/agent/working-memory.js'
@@ -37,6 +38,22 @@ import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface IterationContext {
 	readonly provider: LLMProvider
+	/**
+	 * Which chain member `provider` will route the NEXT request to.
+	 *
+	 * `provider` cannot answer this itself: `withProviderFallback` keeps its
+	 * `id` transparently equal to the head's, deliberately, because that is
+	 * what capability negotiation and the run's `gen_ai.system` attribute are
+	 * about. Asking the wrapper who it is gets the declaration; this gets the
+	 * observation.
+	 *
+	 * Optional because a host may build an `IterationContext` without a chain
+	 * at all. Absent, the loop attributes each step to `provider.id` and the
+	 * model it requested, which is exactly right when nothing can fall over —
+	 * and exactly wrong when something can, so the wiring from `query()` is
+	 * covered end-to-end rather than by a unit test on this accessor.
+	 */
+	readonly servingMember?: () => ServingMember
 	/**
 	 * The run's `invoke_agent` span, so each iteration can parent itself to
 	 * it. Explicit rather than ambient because this loop is an async

package/src/types/provider/interface.ts

@@ -38,6 +38,41 @@ export interface LLMProvider {
 
 	listModels?(): Promise<ModelInfo[]>
 
+	/**
+	 * Establish whether this credential actually works. Resolves if it does,
+	 * throws if it does not.
+	 *
+	 * Separate from `listModels` because the two answer different questions, and
+	 * conflating them is a defect measured rather than imagined. `listModels`
+	 * builds a MENU: "what can I offer this operator to choose from?" — a stale
+	 * hardcoded list is a degraded but legitimate answer, since someone offline
+	 * still has to pick a model. This builds a PROBE: "did this key work?" — and
+	 * for that a list is not a degraded answer, it is no answer, because it
+	 * arrives whether the key is right, wrong, expired or never sent.
+	 *
+	 * Two drivers proved a menu cannot stand in for a probe, and they failed
+	 * differently. One caught a real `401` and returned its hardcoded catalogue,
+	 * so the truth existed and was thrown away. The other has no fallback at all
+	 * and is entirely honest about its menu — its listing endpoint simply does
+	 * not authenticate, so ANY string returned the real catalogue. That second
+	 * case is why this is a separate method rather than a rule about writing
+	 * `listModels` more carefully: no amount of care in a menu makes it a probe.
+	 *
+	 * The probe is per-driver by nature — one has an authenticated call whose
+	 * failure is real, another needs a different endpoint than its menu — so it
+	 * is DECLARED, never inferred. A driver that does not implement this is
+	 * reported as unverifiable, never as verified, and that has to hold for the
+	 * driver nobody has written yet: inheriting a generic path silently is how
+	 * this defect returns.
+	 *
+	 * Throw so the caller can tell the two failures apart. A rejection from the
+	 * server (`401`/`403`) means the credential is genuinely bad; anything else
+	 * — a timeout, DNS, a proxy — means nothing was learned, and reporting that
+	 * as a bad key would tell an operator on broken wifi to go and rotate a
+	 * credential that is fine.
+	 */
+	probeCredential?(): Promise<void>
+
 	healthCheck?(): Promise<boolean>
 
 	/**

package/src/types/run/entity.ts

@@ -11,7 +11,45 @@ export interface RunStateMetadata {
 	agentId: string
 	agentName: string
 	config: AgentRunConfig
+	/**
+	 * The provider the run was CONFIGURED with — the head of the chain, and
+	 * the counterpart of `config.model` beside it.
+	 *
+	 * It is a declaration, not an observation, and it stays one. After a
+	 * provider chain falls over it still names the head, which is correct for
+	 * a field that answers "what was asked for"; it was only ever misleading
+	 * because nothing else answered "what served". See {@link servingProvider}
+	 * for the run-level answer and `steps[].servedBy` for the per-step one.
+	 */
 	provider: string
+	/**
+	 * The chain member the run was routed to at the end, when that is not the
+	 * one it was configured with.
+	 *
+	 * Absent means the declared provider served every call. That reading holds
+	 * for stored records too, with one bounded exception: the sdk major that
+	 * shipped the chain could fall over without recording it, so a run from
+	 * that release reads as "no swap" whether or not there was one. Its
+	 * transcript still carries the `provider_fallback` events. The exception
+	 * is one release wide and it is stated rather than migrated away, because
+	 * a migration would have to invent the answer for exactly the records that
+	 * do not have it.
+	 *
+	 * **This is the durable half.** `RunDiskStore.writeRunMeta` writes
+	 * `metadata` and not `steps`, so on the built-in store this field is the
+	 * whole of what survives the process. `steps[].servedBy` is the finer
+	 * record — the one to read for "which member answered turn 4" — and it
+	 * reaches a host only on the returned `Run`.
+	 *
+	 * It also covers the case no step ledger can: a run that falls over and
+	 * then dies before a single step is recorded still has to be able to say
+	 * whose failure ended it. That is why the wording is "routed to" and not
+	 * "served by" — this member was asked, and on that path it answered with
+	 * an error. It is never a member that was merely selected: the chain
+	 * announces a replacement when it issues its request, not when it picks
+	 * it, so a run cancelled at the swap notice does not name one.
+	 */
+	servingProvider?: string
 }
 
 export type SessionMetadata = RunStateMetadata

package/src/types/run/step.ts

@@ -15,7 +15,46 @@ import type { ToolCall } from '../message/index.js'
 export interface StepResult {
 	/** 1-based, matching `iteration` on the run events. */
 	stepNumber: number
+	/**
+	 * The model this step ASKED for: the run's configured model, or the
+	 * override a `prepareStep` hook returned for this step.
+	 *
+	 * It used to be the run's model unconditionally — the loop passed its own
+	 * `model` here while building the request from `step.model ?? model` a few
+	 * lines above — so a host that routed one step to a cheaper model read the
+	 * expensive one back out of the ledger. No chain was needed to see it.
+	 *
+	 * What was asked for and what answered are two facts, and after a provider
+	 * chain falls over they differ. This is the first; {@link servedBy} is the
+	 * second.
+	 */
 	model: string
+	/**
+	 * Who actually answered, and with which model.
+	 *
+	 * Equal to {@link model} and to `run.metadata.provider` on every run
+	 * without a chain, which is most of them; it diverges exactly when
+	 * `withProviderFallback` advanced. Recorded even when it agrees, because a
+	 * ledger that carries the fact only when it is surprising cannot be read as
+	 * evidence — a reader could not tell "the head served" from "nobody wrote
+	 * it down".
+	 *
+	 * Optional only for records that predate the field. Absence means "not
+	 * recorded", and it is left meaning that rather than backfilled: the sdk
+	 * shipped a chain that could fall over one release before it recorded
+	 * which member did, so filling those in from the declared head would state
+	 * as fact the exact thing that release got wrong, on exactly the runs
+	 * where it was wrong. Every step this build produces has it.
+	 *
+	 * **Reaches a host through the returned `Run`, not through `run.json`.**
+	 * `RunDiskStore.writeRunMeta` persists the metadata and the counters and
+	 * does not write `steps` at all, so the built-in store carries the
+	 * run-level {@link
+	 * import('./entity.js').RunStateMetadata.servingProvider} and none of
+	 * this. A host that wants per-step provenance on disk persists the `Run`
+	 * it is handed.
+	 */
+	servedBy?: StepProvenance
 	messageId: MessageId
 	/** Assistant text for this step, if any. */
 	content: string | null
@@ -34,6 +73,21 @@ export interface StepResult {
 	toolExecutionMs: number
 }
 
+/**
+ * The chain member that served one step.
+ *
+ * `chainIndex` is a position in the chain the host declared, and it is here
+ * rather than derived from `providerId` because a chain may legitimately name
+ * the same provider twice — two models, or two credentials, on one driver.
+ * `providerId` alone could not tell those apart.
+ */
+export interface StepProvenance {
+	readonly providerId: string
+	readonly model: string
+	/** 0 is the head, i.e. the provider the run was configured with. */
+	readonly chainIndex: number
+}
+
 export interface StepToolResult {
 	toolCallId: string
 	toolName: string