@namzu/zen 2.4.0 → 2.5.2

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'
@@ -45,6 +50,22 @@ export const ZEN_CAPABILITIES: ProviderCapabilities = {
 export const ZEN_BASE_URL = 'https://opencode.ai/zen/v1'
 export const ZEN_GO_BASE_URL = 'https://opencode.ai/zen/go/v1'
 
+/**
+ * The words a backend's own finish reason uses, in `LanguageModelV3FinishReason.raw`,
+ * for "the model's context window, not its output-token budget, is what ran
+ * out" — Anthropic's `model_context_window_exceeded` (folded, with
+ * `max_tokens`, into `unified: 'length'` by `@ai-sdk/anthropic`'s
+ * `mapAnthropicStopReason`) and the words other OpenAI-compatible backends
+ * use (see `@namzu/http`'s `mapOpenAIFinish`), since Zen also routes through
+ * `@ai-sdk/openai-compatible`.
+ */
+const CONTEXT_WINDOW_RAW_FINISH_REASONS = new Set([
+	'model_context_window_exceeded',
+	'model_length',
+	'context_length',
+	'context_length_exceeded',
+])
+
 /** A provider instance belongs to one conversation; it never owns an agent loop. */
 export class ZenProvider implements LLMProvider {
 	readonly id: 'zen' | 'zen-go'
@@ -64,6 +85,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 +138,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 +152,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()
@@ -410,6 +439,11 @@ export class ZenProvider implements LLMProvider {
 				id,
 				delta: {},
 				finishReason,
+				...(finishReason === 'length' &&
+				finish.finishReason.raw &&
+				CONTEXT_WINDOW_RAW_FINISH_REASONS.has(finish.finishReason.raw)
+					? { finishDetail: 'context_window' as const }
+					: {}),
 				usage: mapUsage(finish.usage),
 				replayState: createReplayState(
 					{ ...params, model },
@@ -452,13 +486,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 +520,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.ts

@@ -29,14 +29,19 @@ 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-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
  * or the run stops. Prices come from that page's per-1M-token table at the base
@@ -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.
@@ -1253,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/prompt.ts

@@ -137,7 +137,14 @@ function prefixDigest(messages: readonly Message[]): string {
 					chainIndex: message.source.chainIndex,
 				},
 			}),
+			// Bookkeeping the kernel stamps, not content the prefix is defined
+			// by: `id` names which durable record a message came from, and two
+			// requests built from the exact same prefix disagree on it whenever
+			// one side is a fresh, never-recorded copy of the other (or a
+			// fork's copy, carrying a different session's id for identical
+			// content).
 			timestamp: undefined,
+			id: undefined,
 		})),
 	)
 }

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