@namzu/sdk 27.1.0 → 28.0.0

package/src/prompt/contributions.ts

@@ -0,0 +1,173 @@
+import { renderSkillsSection } from '../persona/assembler.js'
+import type { AgentRuntimeContext } from '../types/agent/base.js'
+import type { Skill } from '../types/skills/index.js'
+
+/**
+ * A seam for putting something in the system prompt.
+ *
+ * The prompt was closed. `PromptBuilder` assembled a fixed list — base
+ * prompt, persona or system prompt, skills, tool section, tier guidance,
+ * environment — and every one of those was a branch written into the
+ * builder. A capability that needed the model to know something (web tools
+ * and their citation rules, a plugin's conventions, a host's house style)
+ * had exactly two options: convince somebody to add a branch, or splice it
+ * into `systemPrompt` and lose whatever was there.
+ *
+ * Skills is the first contributor through this seam, and deliberately so:
+ * it was already a special case in four places in the builder, so making it
+ * one is the smallest change that proves the seam carries a real one rather
+ * than a shape invented to fit.
+ */
+
+export interface PromptContributionContext {
+	readonly workingDirectory?: string
+	readonly runtimeContext?: AgentRuntimeContext
+	readonly skills?: readonly Skill[]
+	/** The tools this turn may call, if the turn was narrowed. */
+	readonly allowedTools?: readonly string[]
+	/**
+	 * Which iteration this is, 1-based — present only for `turn`.
+	 *
+	 * Absent for `static` and `dynamic`, and that absence is the type
+	 * saying what the placement means: a contribution that needs to know
+	 * which turn it is cannot be part of a prompt assembled once and
+	 * cached.
+	 */
+	readonly iteration?: number
+}
+
+/**
+ * Which half of the prompt this lands in.
+ *
+ * Not cosmetic, and the wrong answer is expensive in a way nothing reports.
+ * `static` is the segment the prompt cache keeps and a provider caches
+ * across turns; `dynamic` is re-sent every iteration. A contributor whose
+ * text varies per turn but declares `static` either invalidates the cached
+ * prefix on every iteration — paying full price for a cache that never
+ * hits — or, worse, gets served the first turn's text forever.
+ *
+ * The rule: `static` iff the output depends only on things that cannot
+ * change inside one run.
+ */
+export type PromptPlacement = 'static' | 'dynamic' | 'turn'
+
+/**
+ * `turn` is a third thing, not a looser `dynamic`.
+ *
+ * `static` and `dynamic` are both parts of the SYSTEM PROMPT: assembled
+ * once per request, sent as system messages, and — for `static` — cached by
+ * the provider across turns. `turn` is not in the system prompt at all. It
+ * rides the ephemeral trailing message that a step's guidance, its skills
+ * and the approval-policy notice already use: appended to the request,
+ * never pushed onto the run's history, and gone the moment the request is
+ * sent.
+ *
+ * That is the placement for state that changes DURING a run — a budget
+ * running down, a queue draining, a policy that just moved. Putting such a
+ * thing in `static` serves the first iteration's value forever; putting it
+ * in `dynamic` re-sends it in a position the model reads as part of its
+ * standing instructions rather than as a status.
+ *
+ * The cost of `turn` is real and worth stating: every iteration pays for it
+ * in tokens, and it lands after the cached prefix so it cannot be cached.
+ * The approval-policy notice is the shape to copy — it returns text only
+ * when something actually changed, and `null` on every other turn.
+ */
+
+export interface PromptContribution {
+	/**
+	 * Stable and unique. Registration refuses a duplicate rather than
+	 * letting the second silently win, because "my guidance stopped
+	 * appearing" is the least debuggable failure this registry could have.
+	 */
+	readonly id: string
+	readonly placement: PromptPlacement
+	/** `null` for "nothing to say this time", which is not an error. */
+	render(context: PromptContributionContext): string | null
+}
+
+/** Two contributions claiming one id. */
+export class PromptContributionCollisionError extends Error {
+	readonly details: { id: string }
+
+	constructor(details: { id: string }) {
+		super(`A prompt contribution with id "${details.id}" is already registered.`)
+		this.name = 'PromptContributionCollisionError'
+		this.details = details
+	}
+}
+
+/**
+ * What goes in the prompt beyond what the builder knows about.
+ *
+ * Registration order is the rendering order, and that is the contract: an
+ * ordering derived from something else — priority numbers, id sort — would
+ * have every contributor arguing about a number, and the prompt is read
+ * top to bottom by a model that weights early text more.
+ */
+export class PromptContributionRegistry {
+	private readonly byId = new Map<string, PromptContribution>()
+
+	register(contribution: PromptContribution): void {
+		if (this.byId.has(contribution.id)) {
+			throw new PromptContributionCollisionError({ id: contribution.id })
+		}
+		this.byId.set(contribution.id, contribution)
+	}
+
+	/** Replace one already registered, for a host that owns both. */
+	replace(contribution: PromptContribution): void {
+		this.byId.set(contribution.id, contribution)
+	}
+
+	has(id: string): boolean {
+		return this.byId.has(id)
+	}
+
+	/** In registration order. */
+	list(): readonly PromptContribution[] {
+		return [...this.byId.values()]
+	}
+
+	/**
+	 * Every contribution for one placement, rendered, with the empty ones
+	 * dropped.
+	 *
+	 * Dropping `null` here rather than at each call site is the point: a
+	 * contributor that has nothing to say this turn must not leave a blank
+	 * section behind, and four separate `if (x) parts.push(x)` sites is four
+	 * chances for one of them to forget.
+	 */
+	render(placement: PromptPlacement, context: PromptContributionContext): readonly string[] {
+		return this.list()
+			.filter((contribution) => contribution.placement === placement)
+			.map((contribution) => contribution.render(context))
+			.filter((text): text is string => typeof text === 'string' && text.trim().length > 0)
+	}
+}
+
+/** The id the built-in skills contribution registers under. */
+export const SKILLS_CONTRIBUTION_ID = 'namzu.skills'
+
+/**
+ * Skills, as a contribution.
+ *
+ * `static`, because a run's skill set is fixed for the run — a STEP's
+ * skills are a different thing entirely and ride the ephemeral trailing
+ * system message, which is what keeps them out of the cached prefix.
+ *
+ * The persona path does not use this. `assembleSystemPrompt(persona,
+ * skills)` renders skills INSIDE the persona's own section ordering, which
+ * is a persona-assembler decision about where skills belong relative to
+ * constraints and output discipline. Moving it out here would silently
+ * reorder every persona-driven prompt in the estate to buy uniformity
+ * nobody asked for. So this contribution serves the branches that render
+ * skills standalone, and the persona branch keeps its own — stated here
+ * because two renderers for one concept is exactly the kind of thing that
+ * looks like an oversight later.
+ */
+export const skillsContribution: PromptContribution = {
+	id: SKILLS_CONTRIBUTION_ID,
+	placement: 'static',
+	render: (context) => renderSkillsSection(context.skills ? [...context.skills] : undefined),
+}

package/src/prompt/index.ts

@@ -0,0 +1,15 @@
+// A seam for putting something in the system prompt. The prompt was closed:
+// every section was a branch inside `PromptBuilder`, so a capability that
+// needed the model to know something had to argue for a branch or splice
+// into `systemPrompt` and lose whatever was there.
+export {
+	PromptContributionCollisionError,
+	PromptContributionRegistry,
+	SKILLS_CONTRIBUTION_ID,
+	skillsContribution,
+} from './contributions.js'
+export type {
+	PromptContribution,
+	PromptContributionContext,
+	PromptPlacement,
+} from './contributions.js'

package/src/provider/attribution.ts

@@ -0,0 +1,57 @@
+import { VERSION } from '../version.js'
+
+/**
+ * Who is calling, said once.
+ *
+ * No driver identified this kernel to a provider. The only user-agent
+ * anywhere was on one OAuth code path, set so a token-exchange endpoint
+ * would accept the request — that is load-bearing impersonation, not
+ * attribution, and it must not be touched.
+ *
+ * What attribution buys is not vanity. A provider reading its own logs can
+ * tell a kernel's traffic from a browser's; a rate-limit or an abuse
+ * investigation lands on the right party; and a driver bug reported by a
+ * vendor arrives with something to search for. None of that is possible
+ * from an unlabelled request.
+ *
+ * ## One header, and only one
+ *
+ * Every additional header is a thing a proxy may strip, a vendor may
+ * reject, and a reader has to reconcile. The helper returns exactly one
+ * key and a test asserts the count — a driver wanting to send something of
+ * its own sends it at its own seam rather than growing this.
+ */
+
+export interface AppIdentity {
+	/** Product name, as it should appear in a vendor's logs. */
+	readonly product: string
+	/** Version of the product. Read, never hand-copied. */
+	readonly version: string
+	/** Where a vendor can find out what this is. */
+	readonly url: string
+}
+
+/**
+ * `version` comes from `VERSION`, which is read from the package manifest
+ * — a hand-copied literal here would be wrong from the first release after
+ * somebody forgot it, and wrong in the one place a vendor is reading to
+ * decide which build has the bug.
+ */
+export const NAMZU_APP_IDENTITY: AppIdentity = {
+	product: 'namzu',
+	version: VERSION,
+	url: 'https://github.com/cogitave/namzu',
+}
+
+/**
+ * The single header a driver merges at its own seam.
+ *
+ * Pure, and takes the identity as an argument, so a host embedding this
+ * kernel in its own product can say so — and so a driver cannot hardcode
+ * the constant and quietly ignore what the host asked for.
+ */
+export function attributionHeaders(
+	identity: AppIdentity = NAMZU_APP_IDENTITY,
+): Record<string, string> {
+	return { 'User-Agent': `${identity.product}/${identity.version} (+${identity.url})` }
+}

package/src/provider/{collect.ts → collect-chat-completion.ts}

@@ -10,7 +10,7 @@ import type { StreamChunk } from '../types/provider/stream.js'
  * four internal callers that genuinely need the aggregated view (advisory
  * executor, RouterAgent's deterministic routing decision, compaction's
  * verifier, the instrumentation wrapper) replace `provider.chat(p)` with
- * `collect(provider.chatStream(p))`.
+ * `collectChatCompletion(provider.chatStream(p))`.
  *
  * Behaviour matches the pre-removal `chat()` contract:
  * - text content is concatenated in delta order;
@@ -23,7 +23,9 @@ import type { StreamChunk } from '../types/provider/stream.js'
  * The orchestrator does NOT call this helper — it consumes the stream
  * directly so it can emit per-delta `RunEvent`s.
  */
-export async function collect(stream: AsyncIterable<StreamChunk>): Promise<ChatCompletionResponse> {
+export async function collectChatCompletion(
+	stream: AsyncIterable<StreamChunk>,
+): Promise<ChatCompletionResponse> {
 	let id = ''
 	const model = ''
 	let content = ''

package/src/provider/conformance.ts

@@ -0,0 +1,189 @@
+import type {
+	ConformanceDescribe,
+	ConformanceExpect,
+	ConformanceIt,
+} from '../store/run/conformance.js'
+import type { LLMProvider } from '../types/provider/interface.js'
+import type { ProviderRetryConfig } from './retry.js'
+
+/**
+ * The driver contract, as a suite every driver package runs.
+ *
+ * Seven packages implement `LLMProvider` and there was nowhere to write a
+ * rule binding all of them. Each carried a hand-written error-taxonomy
+ * test covering the same ground differently, and every provider finding in
+ * the audit was a behaviour present in exactly ONE driver and absent from
+ * the other six — which is what you get when a contract lives in seven
+ * copies of a test rather than in one place. Nothing failed when an eighth
+ * package appeared implementing none of it.
+ *
+ * The mechanism already existed for a different interface: the checkpoint
+ * store publishes its contract at `@namzu/sdk/testing` and takes its
+ * runner as an argument. This copies that shape exactly, for the same two
+ * reasons — the SDK gains no test dependency from publishing a suite, and
+ * a caller can pass a RECORDING `describe`/`it` and run the whole contract
+ * as ordinary code, which is how a deliberately wrong driver is shown to
+ * fail it.
+ *
+ * ## What is in it, and what is deliberately not
+ *
+ * Seeded only with rules that pass for every driver today. A suite that
+ * ships red is a suite somebody switches off in its first week, and the
+ * point of it is to hold the line while the four known gaps are closed one
+ * at a time — each of which adds a rule here in the commit that fixes it.
+ *
+ * ## Consuming it
+ *
+ * ```typescript
+ * import { describe, expect, it } from 'vitest'
+ * import { defineProviderDriverConformance } from '@namzu/sdk/testing'
+ *
+ * defineProviderDriverConformance({
+ *   describe, it, expect,
+ *   label: 'anthropic',
+ *   registryType: 'anthropic',
+ *   makeProvider: () => new AnthropicProvider({ apiKey: 'test' }),
+ * })
+ * ```
+ */
+
+/** The contract revision a driver declares itself written against. */
+export const PROVIDER_DRIVER_CONTRACT_VERSION = 1
+
+export interface ProviderDriverConformanceOptions {
+	readonly describe: ConformanceDescribe
+	readonly it: ConformanceIt
+	readonly expect: ConformanceExpect
+	/**
+	 * The string this driver is registered under. Asserted to equal `id`,
+	 * because the two are used interchangeably at call sites — a chain
+	 * member names one and a `ProviderRegistry` lookup uses the other — and
+	 * a driver where they differ resolves for some callers and not others.
+	 */
+	readonly registryType: string
+	/**
+	 * Built once per case. No case may depend on another's state, and a
+	 * driver that holds a connection gets a fresh one rather than a shared
+	 * instance the suite would then have to clean.
+	 */
+	readonly makeProvider: () => LLMProvider | Promise<LLMProvider>
+	/**
+	 * What this driver declares as its retry defaults, restated here.
+	 *
+	 * REQUIRED, and required as a value rather than inferred from the
+	 * driver, so a new package cannot skip the decision by not thinking
+	 * about it. `undefined` is a legitimate answer — it means the generic
+	 * default suits this vendor — but it has to be written down, which is
+	 * the difference between a decision and an omission.
+	 */
+	readonly retryDefaults: Partial<ProviderRetryConfig> | undefined
+	/**
+	 * Whether this driver identifies the kernel to its vendor, and if not
+	 * why not.
+	 *
+	 * REQUIRED for the same reason `retryDefaults` is: a package that never
+	 * decided should not typecheck. `'unsupported'` is a legitimate answer
+	 * — one vendor's client speaks a websocket protocol with no header seam
+	 * — but it has to carry a reason, so the next reader learns whether it
+	 * is impossible or merely undone.
+	 */
+	readonly attribution: { kind: 'header' } | { kind: 'unsupported'; reason: string }
+	/** Names the driver in test output. Defaults to `provider driver`. */
+	readonly label?: string
+}
+
+export function defineProviderDriverConformance(options: ProviderDriverConformanceOptions): void {
+	const { describe, it, expect, makeProvider, registryType } = options
+	const label = options.label ?? 'provider driver'
+
+	describe(`${label} — driver contract v${PROVIDER_DRIVER_CONTRACT_VERSION}`, () => {
+		it('has a non-empty id and name', async () => {
+			// Both reach a human or a log line. An empty one produces a
+			// provider-chain entry that names nothing, which is worse than a
+			// wrong name because there is nothing to search for.
+			const provider = await makeProvider()
+
+			expect(typeof provider.id).toBe('string')
+			expect(provider.id.length > 0).toBe(true)
+			expect(typeof provider.name).toBe('string')
+			expect(provider.name.length > 0).toBe(true)
+		})
+
+		it('has an id equal to the string it is registered under', async () => {
+			// A chain member names the registry type; a lookup uses `id`. A
+			// driver where they differ resolves through one path and not the
+			// other, and the failure appears at whichever call site the host
+			// happens to reach second.
+			const provider = await makeProvider()
+
+			expect(provider.id).toBe(registryType)
+		})
+
+		it('exposes chatStream as a function', async () => {
+			// The single entry point. Asserted because a driver can satisfy
+			// the type by declaring it and still ship an object literal that
+			// forgot it — the interface is structural.
+			const provider = await makeProvider()
+
+			expect(typeof provider.chatStream).toBe('function')
+		})
+
+		it('declares capabilities honestly or not at all', async () => {
+			// Optional BY DESIGN: an absent declaration resolves to the
+			// permissive default, which is the behaviour every driver had
+			// before the field existed. What is not allowed is a declaration
+			// that is present and not a capability record — that reaches the
+			// runtime as "supports nothing" and silently strips tool surfaces.
+			const provider = await makeProvider()
+			if (provider.capabilities === undefined) return
+
+			expect(typeof provider.capabilities.supportsTools).toBe('boolean')
+			expect(typeof provider.capabilities.supportsStreaming).toBe('boolean')
+			expect(typeof provider.capabilities.supportsFunctionCalling).toBe('boolean')
+		})
+
+		// NOT A RULE HERE, and the reason is worth keeping.
+		//
+		// NZ-PROV-05 makes `contextWindow`/`maxOutputTokens` optional so a
+		// driver stops writing `0` for "I do not know" — zero is not a
+		// window, and it reads to every consumer as a measurement of a model
+		// that can hold nothing.
+		//
+		// The obvious place to enforce that is here, reading `listModels`.
+		// It was here, and it was worse than nothing twice over. For every
+		// in-tree driver `listModels` needs a live service, so the rule
+		// returned early and asserted NOTHING in CI — verified by putting a
+		// zero back and watching the driver's run stay green. And lmstudio's
+		// does not throw, it HANGS: the rule timed out that package's whole
+		// conformance run. A check that cannot fail, attached to a suite it
+		// can take down.
+		//
+		// The reintroduction of a literal zero is caught by a source scan in
+		// `provider/__tests__/conformance-fails-a-wrong-driver.test.ts`,
+		// which depends on reaching nothing.
+
+		it('declares the retry defaults its conformance run says it does', async () => {
+			// The option above forces the decision; this asserts the answer is
+			// TRUE of the driver. Without it a package could declare one thing
+			// in its test and ship another, which is the same gap as no
+			// declaration at all with an extra place to look.
+			const provider = await makeProvider()
+
+			expect(JSON.stringify(provider.retryDefaults ?? null)).toBe(
+				JSON.stringify(options.retryDefaults ?? null),
+			)
+		})
+
+		it('builds a second instance independent of the first', async () => {
+			// The property the suite itself relies on, and one a driver can
+			// break by caching a client on the module. Every case above calls
+			// `makeProvider` again; if that returned a shared object, a
+			// driver's state would leak between cases and this suite would
+			// report on whichever one ran first.
+			const a = await makeProvider()
+			const b = await makeProvider()
+
+			expect(a === b).toBe(false)
+		})
+	})
+}

package/src/provider/errors.ts

@@ -29,6 +29,7 @@
  *    the failure from the layer that should decide.
  */
 
+import { LOG_SECRET_PATTERNS } from '../constants/secret-patterns.js'
 import type { ProviderErrorKind, ProviderRequestErrorInit } from '../types/provider/error.js'
 export type {
 	ProviderErrorInfo,
@@ -96,15 +97,14 @@ const DETAIL_MAX = 400
  * error body can echo the request, and a request can carry a key. The answer
  * is to scrub what looks like a credential rather than to throw away the
  * sentence that names the broken field.
+ *
+ * The pattern set itself now lives in `constants/secret-patterns.ts`, as
+ * `LOG_SECRET_PATTERNS` — the union of this table and the narrower one
+ * `runtime/query/guardrail-presets.ts` matches model OUTPUT against. A
+ * false positive here only redacts a word out of a diagnostic `detail`
+ * nobody reads as the credential itself, which is why this call site gets
+ * the wider set and the output guardrail does not.
  */
-const SECRET_PATTERNS: readonly RegExp[] = [
-	/\b(?:sk|pk|rk)[-_][A-Za-z0-9_-]{12,}/g,
-	/\bnpm_[A-Za-z0-9]{20,}/g,
-	/\bgh[pousr]_[A-Za-z0-9]{20,}/g,
-	/\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi,
-	/\bAKIA[0-9A-Z]{16}\b/g,
-	/("(?:api[_-]?key|authorization|token|secret|password)"\s*:\s*)"[^"]*"/gi,
-]
 
 /**
  * The provider's own account of what was wrong, safe to log.
@@ -134,10 +134,11 @@ export function vendorDetail(body: unknown): string | undefined {
 
 export function redactSecrets(text: string): string {
 	let out = text
-	for (const pattern of SECRET_PATTERNS) {
-		out = out.replace(pattern, (_match, prefix?: string) =>
-			prefix === undefined ? '[redacted]' : `${prefix}"[redacted]"`,
-		)
+	for (const [label, pattern] of LOG_SECRET_PATTERNS) {
+		// Whole match replaced with the label, never the matched text — same
+		// convention `secretRedactionGuardrail` already uses, so a `[REDACTED:…]`
+		// marker means the same thing wherever it is read.
+		out = out.replace(pattern, `[REDACTED:${label}]`)
 	}
 	return out
 }
@@ -366,6 +367,20 @@ function vendorRetryAfter(err: unknown): string | undefined {
  * attached as `cause`. A `cause` is exactly what a structured logger walks, so
  * keeping one for debuggability would reintroduce the leak it is meant to close.
  *
+ * `utils/log/exception.ts` now walks a `cause` chain for whatever DOES carry
+ * one, to put `exception.stacktrace` in a log record instead of just the
+ * caught error's own message. That mapper existing is not a reason to start
+ * attaching one here: every one of the six drivers in `packages/providers/*`
+ * (openai, anthropic, ollama, bedrock, openrouter, lmstudio) throws through
+ * this function specifically because none of them can otherwise avoid
+ * handing a structured logger the credential a vendor SDK just echoed back.
+ * Each driver's own `error-taxonomy.test.ts` asserts `'cause' in (err as
+ * object)` is `false` on ITS OWN thrown error, not just on this function in
+ * isolation — that is what would catch a driver that stops going through
+ * `providerVendorError`/`providerHttpError` and attaches one directly.
+ * `packages/sdk/src/provider/__tests__/errors.test.ts` pins the same thing
+ * against this shared function directly. See `docs/conventions/index.md`.
+ *
  * `name` is checked too, because AWS models its failures as distinct classes
  * (`ThrottlingException`, `ValidationException`, `AccessDeniedException`) rather
  * than as status codes.

package/src/provider/fallback.ts

@@ -21,6 +21,7 @@
  * host assemble it in whichever order it happens to pick.
  */
 
+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 { Logger } from '../utils/logger.js'
@@ -80,7 +81,7 @@ export interface WithProviderFallbackOptions {
 	 *
 	 *  - 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
+	 *  - a side call that aggregates the stream through `collectChatCompletion()` — 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
@@ -322,9 +323,9 @@ export function withProviderFallback(
 				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
+						[GENAI.SYSTEM]: member.provider.id,
+						'namzu.provider.position': cursor,
+						'namzu.provider.reason': produced
 							? 'stream already produced output — cannot restart without duplicating it'
 							: !to
 								? 'chain exhausted'
@@ -336,12 +337,12 @@ export function withProviderFallback(
 				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,
+					'namzu.provider.from': member.provider.id,
+					'namzu.provider.from_position': cursor - 1,
+					'namzu.provider.to': to.provider.id,
+					'namzu.provider.to_position': cursor,
+					'namzu.provider.code': classified.code,
+					'namzu.provider.status': classified.status,
 				})
 
 				// In-band, exactly like the retry notice and for the same reason: the
@@ -390,5 +391,26 @@ export function withProviderFallback(
 		...(first.provider.doctorCheck
 			? { doctorCheck: (model?: string) => first.provider.doctorCheck?.(model) }
 			: {}),
+		// The HEAD's answer, like every other member here, and that is the
+		// right reading rather than a limitation: the window is resolved once
+		// at the start of a run, when the head is what is serving. A chain
+		// that swaps mid-run has bigger differences between its members than
+		// a context size, and re-resolving on every swap would put a network
+		// call on the recovery path — which is the last place that can afford
+		// one.
+		...(first.provider.effortLevelsFor
+			? {
+					effortLevelsFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['effortLevelsFor']>>[1],
+					) => first.provider.effortLevelsFor?.(model, thinking) ?? [],
+				}
+			: {}),
+		...(first.provider.resolveContextWindow
+			? {
+					resolveContextWindow: (model: string, signal?: AbortSignal) =>
+						first.provider.resolveContextWindow?.(model, signal) ?? Promise.resolve(undefined),
+				}
+			: {}),
 	} as LLMProvider
 }