@namzu/sdk 16.0.0 → 18.0.0

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/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/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/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

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