@namzu/zen 2.3.0 → 2.5.0

package/src/catalogue/fetch.ts

@@ -0,0 +1,229 @@
+/**
+ * Reading the Zen catalogue's sources over the network — the one module in
+ * this package that does, and only when a caller invokes it. Importing it,
+ * constructing a provider or reading the bundled snapshot fetches nothing.
+ */
+
+import type { ZenService } from '../models.js'
+import {
+	type BuildZenCatalogueOptions,
+	type ZenCatalogueResult,
+	type ZenCatalogueSources,
+	buildZenCatalogue,
+} from './catalogue.js'
+import { SERVICE_PREFIX, ZenCatalogueSourceError } from './derive.js'
+
+/** The branch of OpenCode's repository the two documentation pages are read from. */
+export const ZEN_DOCS_REF = 'dev'
+export const ZEN_MODELS_DEV_URL = 'https://models.dev/api.json'
+/** The host both services' own `/models` endpoints hang off. */
+export const ZEN_SERVICE_BASE = 'https://opencode.ai'
+
+/** Byte ceilings per source. A source past its ceiling is refused, never truncated. */
+export interface ZenCatalogueLimits {
+	/** Each documentation page. Default 1 MiB (the live pages are ~32 KB). */
+	readonly pageBytes?: number
+	/** models.dev's whole document. Default 32 MiB (measured 4.8 MB on 2026-09-22). */
+	readonly modelsDevBytes?: number
+	/** Each `/models` answer. Default 1 MiB, the driver's own `listModels` ceiling. */
+	readonly servedBytes?: number
+}
+
+export interface FetchZenCatalogueOptions {
+	/** Defaults to the global `fetch`. */
+	readonly fetch?: typeof fetch
+	/** Aborts every outstanding read; the call then rejects with the signal's reason. */
+	readonly signal?: AbortSignal
+	/** Deadline for each source read, in milliseconds. Default 15,000. */
+	readonly timeoutMs?: number
+	/** Tries per source; a 404 is never retried. Default 1. */
+	readonly attempts?: number
+	readonly limits?: ZenCatalogueLimits
+	/** OpenCode branch for the two pages. Default `dev`. */
+	readonly docsRef?: string
+	readonly modelsDevUrl?: string
+	/** Host for the two `/models` answers. Default `https://opencode.ai`. */
+	readonly serviceBase?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000
+const MIB = 1024 * 1024
+
+function docsBase(ref: string): string {
+	return `https://raw.githubusercontent.com/anomalyco/opencode/${encodeURIComponent(ref)}/packages/web/src/content/docs`
+}
+
+/** The models-list endpoint of one service. */
+export function zenServedUrl(service: ZenService, serviceBase = ZEN_SERVICE_BASE): string {
+	return `${serviceBase.replace(/\/+$/, '')}${SERVICE_PREFIX[service]}models`
+}
+
+function positive(value: number | undefined, fallback: number, name: string): number {
+	if (value === undefined) return fallback
+	if (!Number.isSafeInteger(value) || value <= 0)
+		throw new RangeError(`${name} must be a positive integer.`)
+	return value
+}
+
+async function readBounded(response: Response, limit: number, url: string): Promise<string> {
+	const declared = Number(response.headers.get('content-length'))
+	if (Number.isFinite(declared) && declared > limit) {
+		await response.body?.cancel().catch(() => {})
+		throw new ZenCatalogueSourceError(
+			`${url} declares ${declared} bytes, past its ${limit}-byte limit.`,
+		)
+	}
+	const reader = response.body?.getReader()
+	if (!reader) throw new ZenCatalogueSourceError(`${url} answered with no body.`)
+	const chunks: Uint8Array[] = []
+	let bytes = 0
+	try {
+		while (true) {
+			const next = await reader.read()
+			if (next.done) break
+			bytes += next.value.byteLength
+			if (bytes > limit) {
+				throw new ZenCatalogueSourceError(`${url} exceeds its ${limit}-byte limit.`)
+			}
+			chunks.push(next.value)
+		}
+	} finally {
+		await reader.cancel().catch(() => {})
+		reader.releaseLock()
+	}
+	const body = new Uint8Array(bytes)
+	let offset = 0
+	for (const chunk of chunks) {
+		body.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+	try {
+		return new TextDecoder('utf-8', { fatal: true }).decode(body)
+	} catch {
+		throw new ZenCatalogueSourceError(`${url} is not UTF-8 text.`)
+	}
+}
+
+/**
+ * One source, as text, inside its deadline and its byte ceiling.
+ *
+ * Redirects are refused: every source is a fixed URL that answers directly, and
+ * a source that starts redirecting has moved. A 404 is a branch or a path that
+ * moved and is not retried; a caller's abort is not retried either.
+ */
+export async function readZenSource(
+	url: string,
+	limit: number,
+	options: Pick<FetchZenCatalogueOptions, 'fetch' | 'signal' | 'timeoutMs' | 'attempts'> = {},
+): Promise<string> {
+	const fetchFn = options.fetch ?? globalThis.fetch
+	const timeoutMs = positive(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs')
+	const attempts = positive(options.attempts, 1, 'attempts')
+	let lastError: unknown
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		options.signal?.throwIfAborted()
+		try {
+			const signal = AbortSignal.any([
+				AbortSignal.timeout(timeoutMs),
+				...(options.signal ? [options.signal] : []),
+			])
+			const response = await fetchFn(url, { signal, redirect: 'error' })
+			if (response.ok) return await readBounded(response, limit, url)
+			await response.body?.cancel().catch(() => {})
+			if (response.status === 404) {
+				throw new ZenCatalogueSourceError(`${url} answered 404 — the branch or the path moved.`)
+			}
+			throw new Error(`${url} answered ${response.status}.`)
+		} catch (error) {
+			if (options.signal?.aborted) throw options.signal.reason
+			if (error instanceof ZenCatalogueSourceError) throw error
+			lastError = error
+			if (attempt < attempts) await delay(500 * attempt, options.signal)
+		}
+	}
+	throw new ZenCatalogueSourceError(
+		`${url} could not be read after ${attempts} attempt${attempts === 1 ? '' : 's'}: ${
+			lastError instanceof Error ? lastError.message : String(lastError)
+		}`,
+	)
+}
+
+function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(done, ms)
+		function done() {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}
+		function onAbort() {
+			clearTimeout(timer)
+			reject(signal?.reason)
+		}
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
+}
+
+/** The two `/models` answers, as text. */
+export async function fetchZenServedRosters(
+	options: FetchZenCatalogueOptions = {},
+): Promise<Record<ZenService, string>> {
+	const limit = positive(options.limits?.servedBytes, MIB, 'limits.servedBytes')
+	const [zen, go] = await Promise.all([
+		readZenSource(zenServedUrl('zen', options.serviceBase), limit, options),
+		readZenSource(zenServedUrl('go', options.serviceBase), limit, options),
+	])
+	return { zen, go }
+}
+
+/**
+ * All five sources, as text: the two documentation pages, models.dev and the
+ * two `/models` answers. Rejects on the first source that cannot be read.
+ */
+export async function fetchZenCatalogueSources(
+	options: FetchZenCatalogueOptions = {},
+): Promise<ZenCatalogueSources> {
+	const pageLimit = positive(options.limits?.pageBytes, MIB, 'limits.pageBytes')
+	const modelsDevLimit = positive(options.limits?.modelsDevBytes, 32 * MIB, 'limits.modelsDevBytes')
+	const base = docsBase(options.docsRef ?? ZEN_DOCS_REF)
+	const failFast = new AbortController()
+	const scoped: FetchZenCatalogueOptions = {
+		...options,
+		signal: AbortSignal.any([failFast.signal, ...(options.signal ? [options.signal] : [])]),
+	}
+	const read = <T>(promise: Promise<T>): Promise<T> =>
+		promise.catch((error) => {
+			// One unreadable source decides the result, so the others stop
+			// downloading rather than finishing for nothing.
+			failFast.abort(error)
+			throw error
+		})
+	try {
+		const [zen, go, modelsDev, served] = await Promise.all([
+			read(readZenSource(`${base}/zen.mdx`, pageLimit, scoped)),
+			read(readZenSource(`${base}/go.mdx`, pageLimit, scoped)),
+			read(readZenSource(options.modelsDevUrl ?? ZEN_MODELS_DEV_URL, modelsDevLimit, scoped)),
+			read(fetchZenServedRosters(scoped)),
+		])
+		return { docs: { zen, go }, modelsDev, served }
+	} catch (error) {
+		if (options.signal?.aborted) throw options.signal.reason
+		// A sibling aborted by `failFast` rejects with the first failure as its
+		// reason, which is the error worth reporting.
+		throw failFast.signal.aborted ? failFast.signal.reason : error
+	}
+}
+
+/**
+ * Read every source and derive a catalogue from them, or reject.
+ *
+ * Opt-in by construction: nothing in this package calls it. A rejection is a
+ * `ZenCatalogueSourceError` for a source that could not be read or no longer
+ * parses, or the caller's abort reason; there is no partial result.
+ */
+export async function fetchZenCatalogue(
+	options: FetchZenCatalogueOptions & BuildZenCatalogueOptions = {},
+): Promise<ZenCatalogueResult> {
+	const sources = await fetchZenCatalogueSources(options)
+	options.signal?.throwIfAborted()
+	return buildZenCatalogue(sources, options)
+}

package/src/catalogue/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `@namzu/zen/catalogue`: derive the Zen and Go roster at run time.
+ *
+ * Opt-in. Nothing here runs unless called, and only `fetchZenCatalogue` and
+ * `fetchZenCatalogueSources` touch the network. A host that wants a fresher
+ * roster than the bundled snapshot calls `fetchZenCatalogue()`, stores the
+ * result if it likes, and hands it to `ZenProvider` through
+ * `ZenConfig.catalogue`.
+ *
+ * The parsing rules themselves (`./derive.js`) are not part of this subpath:
+ * they are shared with the repository's snapshot generator, which imports the
+ * built module directly, and are free to change shape between releases.
+ */
+
+export {
+	type BuildZenCatalogueOptions,
+	ZEN_CATALOGUE_VERSION,
+	type ZenCatalogue,
+	ZenCatalogueFormatError,
+	type ZenCatalogueReport,
+	type ZenCatalogueResult,
+	type ZenCatalogueSources,
+	buildZenCatalogue,
+	findZenCatalogueModel,
+	isUnroutedZenModel,
+	parseZenCatalogue,
+} from './catalogue.js'
+export { ZenCatalogueSourceError, type ZenOmissions } from './derive.js'
+export {
+	type FetchZenCatalogueOptions,
+	ZEN_DOCS_REF,
+	ZEN_MODELS_DEV_URL,
+	ZEN_SERVICE_BASE,
+	type ZenCatalogueLimits,
+	fetchZenCatalogue,
+	fetchZenCatalogueSources,
+} from './fetch.js'

package/src/client.ts

@@ -26,7 +26,12 @@ import {
 	providerHttpError,
 	providerVendorError,
 } from '@namzu/sdk'
-import { type ZenService, findZenModel } from './models.js'
+import {
+	type ZenCatalogue,
+	findZenCatalogueModel,
+	isUnroutedZenModel,
+} from './catalogue/catalogue.js'
+import type { ZenModel, ZenService } from './models.js'
 import { createCallOptions } from './options.js'
 import { createReplayState, toReasoningBlocks } from './prompt.js'
 import type { ZenConfig, ZenGoConfig } from './types.js'
@@ -64,6 +69,12 @@ export class ZenProvider implements LLMProvider {
 		if (service !== 'zen' && service !== 'go') throw new Error('Unknown service.')
 		if (config.protocol && !['chat', 'responses', 'messages', 'google'].includes(config.protocol))
 			throw new Error('Unknown model protocol.')
+		if (
+			config.catalogue !== undefined &&
+			typeof config.catalogue !== 'function' &&
+			(typeof config.catalogue !== 'object' || config.catalogue === null)
+		)
+			throw new Error('catalogue must be a Zen catalogue or a function returning one.')
 		this.id = service === 'go' ? 'zen-go' : 'zen'
 		this.name = service === 'go' ? 'Zen Go' : 'Zen'
 		if (config.apiKey !== undefined && typeof config.apiKey !== 'string')
@@ -111,7 +122,8 @@ export class ZenProvider implements LLMProvider {
 			params.model ||
 			this.config.model ||
 			(this.anonymous ? 'muse-spark-1.3-contributor-free' : 'glm-5.3-flash')
-		const info = findZenModel(this.service, model)
+		const catalogue = this.runtimeCatalogue()
+		const info = findZenCatalogueModel(catalogue, this.service, model)
 		if (this.anonymous && info?.supportsAnonymousAccess !== true)
 			throw new ProviderRequestError({
 				providerId: this.id,
@@ -124,8 +136,9 @@ export class ZenProvider implements LLMProvider {
 			throw new ProviderRequestError({
 				providerId: this.id,
 				kind: 'bad_request',
-				detail:
-					'This model has no known wire format. Update the provider or configure protocol explicitly.',
+				detail: isUnroutedZenModel(catalogue, this.service, model)
+					? 'The service serves this model, but no source states its wire format. Configure protocol explicitly.'
+					: 'This model has no known wire format. Update the provider or configure protocol explicitly.',
 			})
 		const route = params.providerRoute ?? { providerId: this.id, model, chainIndex: 0 }
 		const controller = new AbortController()
@@ -452,13 +465,27 @@ export class ZenProvider implements LLMProvider {
 				throw new Error('The model catalogue returned an invalid response.')
 			const result: ModelInfo[] = []
 			const seen = new Set<string>()
+			const catalogue = this.runtimeCatalogue()
 			for (const item of body.data) {
 				if (!item || typeof item !== 'object' || typeof item.id !== 'string' || seen.has(item.id))
 					continue
 				seen.add(item.id)
-				const model = findZenModel(this.service, item.id)
-				if (model && (!this.anonymous || model.supportsAnonymousAccess === true))
-					result.push({ ...model })
+				const model = findZenCatalogueModel(catalogue, this.service, item.id)
+				if (model) {
+					if (!this.anonymous || model.supportsAnonymousAccess === true) result.push({ ...model })
+					continue
+				}
+				// Served, and named by the runtime catalogue as having no known wire:
+				// listed as exactly that, so an operator can see it exists, and
+				// callable only with an explicit protocol. Never anonymous, and
+				// nothing about it — price, limits, tools — is invented.
+				if (!this.anonymous && isUnroutedZenModel(catalogue, this.service, item.id))
+					result.push({
+						id: item.id,
+						name: `${item.id} (no known wire format)`,
+						supportsToolUse: false,
+						supportsStreaming: true,
+					})
 			}
 			return result
 		} catch (error) {
@@ -472,12 +499,23 @@ export class ZenProvider implements LLMProvider {
 		model: string,
 		_thinking?: ThinkingConfig,
 	): readonly ReasoningEffort[] | undefined {
-		return findZenModel(this.service, model)?.effortLevels
+		return this.model(model)?.effortLevels
 	}
 
 	async resolveContextWindow(model: string, signal?: AbortSignal): Promise<number | undefined> {
 		signal?.throwIfAborted()
-		return findZenModel(this.service, model)?.contextWindow
+		return this.model(model)?.contextWindow
+	}
+
+	/** The injected runtime catalogue as it stands now, or undefined for the bundled one alone. */
+	private runtimeCatalogue(): ZenCatalogue | undefined {
+		const source = this.config.catalogue
+		return typeof source === 'function' ? source() : source
+	}
+
+	/** Exact lookup: the runtime catalogue first, then the bundled snapshot. */
+	private model(id: string): ZenModel | undefined {
+		return findZenCatalogueModel(this.runtimeCatalogue(), this.service, id)
 	}
 
 	/**

package/src/index.ts

@@ -25,8 +25,9 @@ export {
 	ZenGoProvider,
 } from './client.js'
 export type { ZenConfig, ZenGoConfig, ZenProviderConfig, ZenGoProviderConfig } from './types.js'
-export { getZenModels, findZenModel } from './models.js'
+export { ZEN_OMITTED_MODELS, getZenModels, findZenModel } from './models.js'
 export type { ZenModel, ZenProtocol, ZenService } from './models.js'
+export type { ZenCatalogue } from './catalogue/catalogue.js'
 export type {
 	ChatCompletionParams,
 	ModelInfo,

package/src/models.review.json

@@ -7,6 +7,8 @@
 		"go/kimi-k2.5": "Served by Go and absent from the Go page, which routes Kimi K2.6, K2.7 Code and K3. The Zen page still routes this id, and one service's route is not the other's, so none is taken from it.",
 		"go/mimo-v2-omni": "Served by Go and absent from the Go page, which routes MiMo V2.5 and V2.5 Pro. models.dev states a name and limits for it and no wire, so none is carried.",
 		"go/mimo-v2-pro": "Served by Go and absent from the Go page, which routes MiMo V2.5 and V2.5 Pro. models.dev states a name and limits for it and no wire, so none is carried.",
+		"go/mimo-v2.6-flash": "Routed by the Go page since 2026-09-21, and models.dev carries no `opencode-go` entry for it yet, so its limits cannot be derived and it is not carried.",
+		"go/mimo-v2.6-pro": "Routed by the Go page since 2026-09-21, and models.dev carries no `opencode-go` entry for it yet, so its limits cannot be derived and it is not carried.",
 		"go/minimax-m2.5": "Superseded on Go by MiniMax M2.7 and M3, which are both carried. The page still lists it.",
 		"go/omen-alpha": "Served by Go and no longer routed by the Go page, which is why this release dropped it from the catalogue. No source states a wire for it any more, so a caller that needs it must name the protocol itself.",
 		"go/qwen3.5-plus": "Served by Go and absent from the Go page, which routes Qwen 3.6 Plus and later. The Zen page routes this id on Messages, and one service's route is not the other's, so none is taken from it.",
@@ -18,9 +20,11 @@
 		"zen/gpt-5.1-codex-max": "Superseded Codex generation; gpt-5.3-codex and gpt-5.3-codex-spark are carried.",
 		"zen/gpt-5.1-codex-mini": "Superseded Codex generation; gpt-5.3-codex and gpt-5.3-codex-spark are carried.",
 		"zen/gpt-5.2-codex": "Superseded Codex generation; gpt-5.3-codex and gpt-5.3-codex-spark are carried.",
+		"zen/grok-4.7": "Routed by the Zen page since 2026-09-21, and models.dev carries no `opencode` entry for it yet, so its limits cannot be derived and it is not carried.",
 		"zen/jev-1.13": "Routed by the Zen page on an endpoint whose AI SDK package column carries a dash, the marker that page uses for a cell with no value: no wire is stated for it, so none can be carried. The service serves the id, and models.dev carries a name and limits for it and no package either.",
 		"zen/jev-1.13-free": "Routed by the Zen page on an endpoint whose AI SDK package column carries a dash, the marker that page uses for a cell with no value: no wire is stated for it, so none can be carried. The service serves the id and the page's free-model list names it, and models.dev carries a name and limits for it and no package either.",
 		"zen/kimi-k2.5": "Superseded by Kimi K2.6, K2.7 Code and K3, which are all carried.",
+		"zen/mimo-v2.6-flash-free": "Routed by the Zen page since 2026-09-21, and models.dev carries no `opencode` entry for it yet, so its limits cannot be derived and it is not carried.",
 		"zen/minimax-m2.5": "Superseded by MiniMax M2.7 and M3, which are both carried.",
 		"zen/muse-spark-1.2-contributor-free": "Served by Zen under an id no page routes: the Zen page's free-model list names the 1.3 contributor model, and Go's 1.2 contributor row is a different id on the other service. models.dev states an npm package for it, and that field is deliberately not used as a route, so none is carried.",
 		"zen/qwen3.7-max": "models.dev carries no entry for it, so its context window, limits and tool support cannot be derived and are never invented.",

package/src/models.ts

@@ -29,13 +29,18 @@ export interface ZenModel {
 /*
  * GENERATED FILE — do not edit. Regenerate with:
  *
- *   node scripts/generate-zen-models.mjs
+ *   pnpm --filter @namzu/zen build && node scripts/generate-zen-models.mjs
  *
  * A curation decision is an edit to src/models.review.json, and how a field is
- * derived is an edit to the script. Both survive regeneration; a hand edit here
- * does not, and the CI gate "Zen catalogue matches its source" fails on one.
+ * derived is an edit to src/catalogue/derive.ts. Both survive regeneration; a
+ * hand edit here does not.
  *
- * Refreshed: 2026-09-19
+ * Refreshed: 2026-09-21
+ *
+ * This is the BUNDLED snapshot: what the driver knows with no network. A host
+ * can derive a fresher roster at run time from the same sources, by the same
+ * rules, through `@namzu/zen/catalogue` and hand it to the provider as
+ * `ZenConfig.catalogue`; the CLI does that in the background on every launch.
  *
  * Routes come from each service's own documentation page, as the pair
  * (endpoint, AI SDK package) that page states per model; both halves must agree
@@ -53,12 +58,11 @@ export interface ZenModel {
  *
  * Not every model either service serves is carried here. A model that is
  * documented and not carried is omitted by name, with a reason, in
- * src/models.review.json — and the CI gate fails on any documented model that
- * is neither carried nor omitted, so a new upstream model is a decision someone
- * makes rather than a row that arrives by itself. The gate also reads what the
- * two services' own `/models` answers say they serve: an id served and
- * documented nowhere has no derivable wire, so it is reported as a decision
- * too, rather than dropped by the driver in silence.
+ * src/models.review.json, and the generator refuses to write while a
+ * documented model is neither carried nor omitted. It also reads what the two
+ * services' own `/models` answers say they serve: an id served and documented
+ * nowhere has no derivable wire, so it is reported as a decision too, rather
+ * than dropped by the driver in silence.
  *
  * Prices are estimates, not invoices: context tiers, cache, Go peak/off-peak
  * rates, subscription allowances and promotions can change the effective cost.
@@ -887,6 +891,19 @@ const ZEN_MODELS = freezeModels([
 ])
 
 const GO_MODELS = freezeModels([
+	{
+		id: 'grok-4.7',
+		name: 'Grok 4.7',
+		protocol: 'responses',
+		contextWindow: 500000,
+		maxOutputTokens: 500000,
+		inputModalities: ['text', 'image', 'document'],
+		inputPrice: 2.0,
+		outputPrice: 6.0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh'],
+	},
 	{
 		id: 'grok-4.6',
 		name: 'Grok 4.6',
@@ -1240,6 +1257,43 @@ const GO_MODELS = freezeModels([
 	},
 ])
 
+/**
+ * Reviewed omissions, as `service/id`: models a source names that this
+ * snapshot deliberately does not carry. A runtime refresh through
+ * `@namzu/zen/catalogue` honours the same decisions by default.
+ */
+export const ZEN_OMITTED_MODELS: readonly string[] = Object.freeze([
+	'go/deepseek-flash',
+	'go/glm-5',
+	'go/grok-4.5',
+	'go/hy3-preview',
+	'go/kimi-k2.5',
+	'go/mimo-v2-omni',
+	'go/mimo-v2-pro',
+	'go/mimo-v2.6-flash',
+	'go/mimo-v2.6-pro',
+	'go/minimax-m2.5',
+	'go/omen-alpha',
+	'go/qwen3.5-plus',
+	'zen/claude-sonnet-4',
+	'zen/deepseek-v4-flash-free',
+	'zen/glm-5',
+	'zen/gpt-5-codex',
+	'zen/gpt-5.1-codex',
+	'zen/gpt-5.1-codex-max',
+	'zen/gpt-5.1-codex-mini',
+	'zen/gpt-5.2-codex',
+	'zen/grok-4.7',
+	'zen/jev-1.13',
+	'zen/jev-1.13-free',
+	'zen/kimi-k2.5',
+	'zen/mimo-v2.6-flash-free',
+	'zen/minimax-m2.5',
+	'zen/muse-spark-1.2-contributor-free',
+	'zen/qwen3.7-max',
+	'zen/qwen3.7-plus',
+])
+
 /** Supported metadata; actual account availability is established by live discovery. */
 export function getZenModels(service: ZenService): readonly ZenModel[] {
 	return service === 'zen' ? ZEN_MODELS : GO_MODELS

package/src/options.ts

@@ -177,7 +177,10 @@ export function createCallOptions(
 				...(params.parallelToolCalls !== undefined
 					? { disableParallelToolUse: !params.parallelToolCalls }
 					: {}),
-				...(params.cacheControl ? { cacheControl: { type: 'ephemeral' } } : {}),
+				// Cache breakpoints are block-level, placed by `toModelPrompt`:
+				// a request-level `cacheControl` would become Anthropic's
+				// automatic caching, whose breakpoint lands on the request-only
+				// context at the tail.
 			}
 			break
 		}

package/src/prompt.ts

@@ -384,9 +384,13 @@ function buildModelPrompt(
 ): LanguageModelV3Prompt {
 	const prompt: LanguageModelV3Prompt = []
 	const toolNames = new Map<string, string>()
+	let lastStatic = -1
+	let historyEnd: number | undefined
 	for (const [index, message] of params.messages.entries()) {
+		if (isRequestOnlyContext(message)) historyEnd ??= prompt.length
 		switch (message.role) {
 			case 'system':
+				if (message.cacheHint === 'cache') lastStatic = prompt.length
 				prompt.push({ role: 'system', content: message.content })
 				break
 			case 'user':
@@ -432,9 +436,56 @@ function buildModelPrompt(
 			}
 		}
 	}
+	if (protocol === 'messages' && params.cacheControl)
+		applyCacheBreakpoints(prompt, lastStatic, historyEnd ?? prompt.length)
 	return prompt
 }
 
+/**
+ * Request-only context the runtime appends after the conversation: a
+ * runtime-context user message of kind `step-context`. It changes from one
+ * request to the next. The same test as the Anthropic driver's.
+ */
+function isRequestOnlyContext(message: Message): boolean {
+	return (
+		message.role === 'user' &&
+		message.source?.type === 'runtime-context' &&
+		message.source.kind === 'step-context'
+	)
+}
+
+const BREAKPOINT = { anthropic: { cacheControl: { type: 'ephemeral' } } } as const
+
+/**
+ * Messages-protocol cache breakpoints, block-level: after the last static
+ * system message, and on the last non-system message before request-only
+ * context. The native adapter turns a message's `providerOptions` into
+ * `cache_control` on that message's last content block.
+ *
+ * Replaces the request-level `cacheControl` option, which the adapter sends
+ * as a top-level `cache_control` — Anthropic's automatic caching, which
+ * "applies the cache breakpoint to the last cacheable block"
+ * (platform.claude.com/docs/en/build-with-claude/prompt-caching). With
+ * request-only context at the tail that block is the context, which the
+ * next request replaces, so no later request read the cached history.
+ * System messages are passed over when walking back: a trailing system
+ * message is a step's guidance, which changes from step to step as well.
+ */
+function applyCacheBreakpoints(
+	prompt: LanguageModelV3Prompt,
+	lastStatic: number,
+	historyEnd: number,
+): void {
+	const staticMessage = lastStatic >= 0 ? prompt[lastStatic] : undefined
+	if (staticMessage) staticMessage.providerOptions = { ...BREAKPOINT }
+	for (let i = historyEnd - 1; i > lastStatic; i--) {
+		const message = prompt[i]
+		if (!message || message.role === 'system' || message.content.length === 0) continue
+		message.providerOptions = { ...BREAKPOINT }
+		return
+	}
+}
+
 export function toModelPrompt(
 	params: ChatCompletionParams,
 	route: ProviderRoute,

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ZenCatalogue } from './catalogue/catalogue.js'
 import type { ZenProtocol } from './models.js'
 
 export interface ZenConfig {
@@ -11,8 +12,17 @@ export interface ZenConfig {
 	baseURL?: string
 	/** Whole request timeout in milliseconds. Defaults to 120000. */
 	timeout?: number
-	/** Explicit wire format for a model absent from the bundled catalogue. */
+	/** Explicit wire format for a model absent from the catalogue. */
 	protocol?: ZenProtocol
+	/**
+	 * A runtime catalogue, from `@namzu/zen/catalogue`, consulted before the
+	 * bundled snapshot for every lookup: routing, anonymous admission, listing,
+	 * context windows and effort levels. A function is called at each lookup, so
+	 * a host can swap in a fresher catalogue for providers it already built;
+	 * returning `undefined` means the bundled snapshot alone. Omitted, the
+	 * provider uses the bundled snapshot and nothing is ever fetched for it.
+	 */
+	catalogue?: ZenCatalogue | (() => ZenCatalogue | undefined)
 }
 
 /** Go subscriptions require a real API key; anonymous Zen access does not apply. */