@namzu/zen 3.1.0 → 4.0.0

package/src/experimental-identity.ts

@@ -1,10 +1,73 @@
+import { execFileSync } from 'node:child_process'
 import { createHash, randomBytes } from 'node:crypto'
 
 const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
 
-/** Pinned to the OpenCode request shape observed in the 2026-09-28 trial. */
-export const EXPERIMENTAL_OPENCODE_USER_AGENT =
-	'opencode/1.18.32 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14'
+/**
+ * The floor the free-tier gate enforces: `OpenCode 1.18.0 or newer is required
+ * to use the free tier`. Anything older answers HTTP 426 `UpgradeRequired`.
+ * This pin is only a fallback for a host with no installed OpenCode — the
+ * version actually advertised is resolved from the installed CLI when one can
+ * be found, so this constant is never the reason a request is refused.
+ */
+export const FALLBACK_OPENCODE_VERSION = '1.18.35'
+
+/**
+ * The four tool names the free-tier gate requires in every anonymous request
+ * body. A request missing any one of them — or carrying an empty or absent
+ * `tools` — is refused with HTTP 403 `FreeTierError`. The names are the ones
+ * OpenCode itself always registers, so a host that already offers tools under
+ * these names needs nothing injected.
+ */
+export const ZEN_FREE_TIER_TOOL_NAMES = Object.freeze(['bash', 'glob', 'grep', 'read'] as const)
+
+/** `OpenCode <version> (…)` as the installed CLI reports it. */
+export function parseOpenCodeVersion(stdout: string): string | undefined {
+	const match = /(\d+\.\d+\.\d+)/.exec(stdout)
+	return match?.[1]
+}
+
+let resolvedUserAgent: string | undefined
+
+function readInstalledOpenCodeVersion(): string | undefined {
+	// A provider must not spawn a process per request, so the lookup runs once
+	// per process and every failure — no binary, no permission, a version that
+	// does not parse — falls through to the pinned floor. The stdin is closed
+	// so a CLI that would prompt cannot hang the caller.
+	try {
+		const output = execFileSync('opencode', ['--version'], {
+			timeout: 2_000,
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return parseOpenCodeVersion(output)
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * The User-Agent an anonymous Zen request advertises.
+ *
+ * Resolution order: `OPENCODE_UA` verbatim, then the installed OpenCode CLI's
+ * version, then {@link FALLBACK_OPENCODE_VERSION}. The free-tier gate reads the
+ * version out of this header and refuses anything below 1.18, so a host that
+ * has OpenCode installed stands in for the version it actually has.
+ */
+export function experimentalOpenCodeUserAgent(): string {
+	if (resolvedUserAgent !== undefined) return resolvedUserAgent
+	const override = process.env.OPENCODE_UA?.trim()
+	const version = override || readInstalledOpenCodeVersion() || FALLBACK_OPENCODE_VERSION
+	resolvedUserAgent = override
+		? override
+		: `opencode/${version} ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14`
+	return resolvedUserAgent
+}
+
+/** Test seam: forget the memoized User-Agent so the next call re-resolves it. */
+export function resetExperimentalOpenCodeUserAgent(): void {
+	resolvedUserAgent = undefined
+}
 
 function timeHex(value: bigint): string {
 	const time = Buffer.alloc(6)
@@ -15,10 +78,15 @@ function timeHex(value: bigint): string {
 }
 
 function base62(bytes: Uint8Array): string {
-	return Array.from(bytes, (byte) => ALPHABET[byte % ALPHABET.length]).join('')
+	return Array.from(bytes, (byte) => ALPHABET[byte % 62]).join('')
 }
 
-/** Stable when the CLI constructs a new provider for each turn of one conversation. */
+/**
+ * A session id in the exact descending shape OpenCode emits, which is the
+ * shape the free-tier gate parses: `ses_`, 12 lowercase hex digits carrying
+ * the inverted timestamp with its low 12 bits as `0xfff − counter`, then 14
+ * base62 characters. The counter is 1, well inside the gate's 0–63 window.
+ */
 export function experimentalOpenCodeSessionId(namzuSessionId: string): string {
 	const hash = createHash('sha256').update(namzuSessionId).digest()
 	const uuidTime = /^([0-9a-f]{8})-([0-9a-f]{4})-7[0-9a-f]{3}-/i.exec(namzuSessionId)

package/src/models.review.json

@@ -1,36 +1,27 @@
 {
 	"omissions": {
 		"go/deepseek-flash": "Served by the Go service and named by no route row on either page; models.dev carries no entry for it either, so neither a wire nor its limits can be derived.",
-		"go/glm-5": "Served by Go and no longer routed by the Go page, which routes GLM 5.2, 5.3 and 5.3 Flash. The Zen page still routes this id, and one service's route is not the other's, so none is taken from it.",
 		"go/glm-5.1": "Still served by Go, but the current Go page states neither a route nor a price for it. The /models answer states no wire, so the old bundled route is not carried without current evidence.",
-		"go/grok-4.5": "Served by Go and absent from the Go page, which routes Grok 4.6. models.dev states an npm package for it, and that field is deliberately not used as a route, so none is carried.",
-		"go/hy3-preview": "Served by Go and named by no route row on either page; models.dev carries no entry for it, so neither a wire nor its limits can be derived.",
-		"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.7 Plus, 3.8 Flash and 3.8 Max. The Zen page routes this id on Messages, and one service's route is not the other's, so none is taken from it.",
 		"go/qwen3.6-plus": "Still served by Go, but the current Go page states neither a route nor a price for it. The /models answer states no wire, and the old bundled Messages route conflicts with the reference client's Chat route, so it is not carried by guessing.",
 		"go/qwen3.7-max": "Still served by Go, but the current Go page states neither a route nor a price for it. The /models answer states no wire, so the old bundled route is not carried without current evidence.",
-		"zen/claude-sonnet-4": "Served by Zen and named by no route row on either page: the Zen page routes Claude Sonnet 4.5 and 4.6. models.dev states an npm package for it, and that field is deliberately not used as a route, so none is carried.",
-		"zen/deepseek-v4-flash-free": "Served by Zen and absent from the Zen page, which routes DeepSeek V4 Flash. models.dev states a name and limits for this free id and no wire, so none is carried.",
+		"zen/claude-opus-5-5-backup": "Served by the Zen /models answer as a failover twin of a routed model and named by no route row on either page. A backup id carries no route of its own, so no wire can be derived and a caller that needs it must name the protocol explicitly.",
+		"zen/gemini-4-argon": "Routed by the Zen page, which states neither a price row nor a free-list entry for it. A price that cannot be read is never defaulted to zero, so it is not carried — least of all anonymously.",
 		"zen/glm-5": "Superseded by GLM 5.1, 5.2 and 5.3, which are all carried. The page still lists it.",
 		"zen/gpt-5-codex": "Superseded Codex generation; gpt-5.3-codex and gpt-5.3-codex-spark are carried.",
 		"zen/gpt-5.1-codex": "Superseded Codex generation; gpt-5.3-codex and gpt-5.3-codex-spark are carried.",
 		"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/mistral-large-4": "Routed by the Zen page, which states neither a price row nor a free-list entry for it. A price that cannot be read is never defaulted to zero, so it is not 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.",
-		"zen/qwen3.7-plus": "models.dev carries no entry for it, so its context window, limits and tool support cannot be derived and are never invented."
+		"zen/qwen3.7-max": "Routed by the Zen page, but models.dev carries no entry for it and the Zen service's /models answer does not serve it, so nothing states that it can be called and it is not carried. It is carried with conservative limits as soon as the service serves it.",
+		"zen/qwen3.7-plus": "Routed by the Zen page, but models.dev carries no entry for it and the Zen service's /models answer does not serve it, so nothing states that it can be called and it is not carried. It is carried with conservative limits as soon as the service serves it.",
+		"zen/test": "Served by the Zen /models answer and named by no route row on either page, and its id reads as an endpoint fixture rather than a model. No wire can be derived, and nothing about it should ever be carried or admitted anonymously."
 	}
 }

package/src/models.ts

@@ -22,6 +22,8 @@ export interface ZenModel {
 	readonly supportsStreaming: boolean
 	/** True only for verified direct-anonymous Zen models; zero price does not grant access. */
 	readonly supportsAnonymousAccess?: boolean
+	/** False: the limits are conservative placeholders models.dev has not published. */
+	readonly limitsVerified?: false
 	/** Exact advertised selectable effort levels; empty means no effort selector. */
 	readonly effortLevels?: readonly ReasoningEffort[]
 }
@@ -35,7 +37,7 @@ export interface ZenModel {
  * derived is an edit to src/catalogue/derive.ts. Both survive regeneration; a
  * hand edit here does not.
  *
- * Refreshed: 2026-09-28
+ * Refreshed: 2026-10-13
  *
  * 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
@@ -116,6 +118,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
 	},
+	{
+		id: 'gpt-6.1-sol',
+		name: 'GPT 6.1 Sol',
+		protocol: 'responses',
+		contextWindow: 1050000,
+		maxOutputTokens: 128000,
+		inputModalities: ['text', 'image', 'document'],
+		inputPrice: 2.0,
+		outputPrice: 10.0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
 	{
 		id: 'gpt-6-luna',
 		name: 'GPT 6 Luna',
@@ -428,6 +443,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['low', 'medium', 'high'],
 	},
+	{
+		id: 'claude-sonnet-5-5',
+		name: 'Claude Sonnet 5.5',
+		protocol: 'messages',
+		contextWindow: 1000000,
+		maxOutputTokens: 128000,
+		inputModalities: ['text', 'image', 'document'],
+		inputPrice: 2.0,
+		outputPrice: 10.0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
 	{
 		id: 'claude-sonnet-5',
 		name: 'Claude Sonnet 5',
@@ -467,6 +495,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: [],
 	},
+	{
+		id: 'claude-haiku-5-5',
+		name: 'Claude Haiku 5.5',
+		protocol: 'messages',
+		contextWindow: 1000000,
+		maxOutputTokens: 128000,
+		inputModalities: ['text', 'image', 'document'],
+		inputPrice: 0.1,
+		outputPrice: 0.5,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
 	{
 		id: 'claude-haiku-4-5',
 		name: 'Claude Haiku 4.5',
@@ -571,6 +612,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['minimal', 'low', 'medium', 'high'],
 	},
+	{
+		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',
@@ -884,6 +938,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
 	},
+	{
+		id: 'cat-jam-free',
+		name: 'Cat Jam Free',
+		protocol: 'chat',
+		contextWindow: 262144,
+		maxOutputTokens: 131072,
+		inputModalities: ['text'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
 	{
 		id: 'longcat-2.5-preview-free',
 		name: 'LongCat 2.5 Preview Free',
@@ -897,6 +964,45 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: [],
 	},
+	{
+		id: 'step-5-preview-free',
+		name: 'Step 5 Preview Free',
+		protocol: 'chat',
+		contextWindow: 1000000,
+		maxOutputTokens: 65536,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high'],
+	},
+	{
+		id: 'exo-free',
+		name: 'Exo Free',
+		protocol: 'chat',
+		contextWindow: 1048576,
+		maxOutputTokens: 131072,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['high'],
+	},
+	{
+		id: 'mimo-v2.6-flash-free',
+		name: 'MiMo-V2.6-Flash Free',
+		protocol: 'chat',
+		contextWindow: 200000,
+		maxOutputTokens: 32000,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: [],
+	},
 	{
 		id: 'mimo-v2.5-free',
 		name: 'MiMo-V2.5 Free',
@@ -910,6 +1016,19 @@ const ZEN_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: [],
 	},
+	{
+		id: 'ling-3.1-flash-free',
+		name: 'Ling 3.1 Flash Free',
+		protocol: 'chat',
+		contextWindow: 262144,
+		maxOutputTokens: 32768,
+		inputModalities: ['text'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: [],
+	},
 	{
 		id: 'ling-3.0-flash-fin-free',
 		name: 'Ling 3.0 Flash Fin Free',
@@ -1017,6 +1136,19 @@ const GO_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
 	},
+	{
+		id: 'claude-haiku-5-5',
+		name: 'Claude Haiku 5.5',
+		protocol: 'messages',
+		contextWindow: 1000000,
+		maxOutputTokens: 128000,
+		inputModalities: ['text', 'image', 'document'],
+		inputPrice: 0.1,
+		outputPrice: 0.5,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
 	{
 		id: 'glm-5.3-flash',
 		name: 'GLM-5.3-Flash',
@@ -1108,19 +1240,6 @@ const GO_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: [],
 	},
-	{
-		id: 'longcat-2.5-preview-free',
-		name: 'LongCat 2.5 Preview Free',
-		protocol: 'chat',
-		contextWindow: 1000000,
-		maxOutputTokens: 131072,
-		inputModalities: ['text', 'image'],
-		inputPrice: 0,
-		outputPrice: 0,
-		supportsToolUse: true,
-		supportsStreaming: true,
-		effortLevels: [],
-	},
 	{
 		id: 'deepseek-v4.1-flash',
 		name: 'DeepSeek V4.1 Flash',
@@ -1173,6 +1292,32 @@ const GO_MODELS = freezeModels([
 		supportsStreaming: true,
 		effortLevels: ['low', 'high', 'max'],
 	},
+	{
+		id: 'mimo-v2.6-flash',
+		name: 'MiMo-V2.6-Flash',
+		protocol: 'chat',
+		contextWindow: 1048576,
+		maxOutputTokens: 131072,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0.14,
+		outputPrice: 0.28,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: [],
+	},
+	{
+		id: 'mimo-v2.6-pro',
+		name: 'MiMo-V2.6-Pro',
+		protocol: 'chat',
+		contextWindow: 1048576,
+		maxOutputTokens: 131072,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0.435,
+		outputPrice: 0.87,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: [],
+	},
 	{
 		id: 'mimo-v2.5',
 		name: 'MiMo-V2.5',
@@ -1317,12 +1462,51 @@ const GO_MODELS = freezeModels([
 		effortLevels: ['none', 'low', 'high'],
 	},
 	{
-		id: 'space-bunny-free',
-		name: 'Space Bunny Free',
+		id: 'space-bunny',
+		name: 'Space Bunny',
 		protocol: 'chat',
 		contextWindow: 1048576,
 		maxOutputTokens: 524288,
 		inputModalities: ['text', 'image'],
+		inputPrice: 0.15,
+		outputPrice: 0.6,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+	},
+	{
+		id: 'longcat-2.5-preview-free',
+		name: 'LongCat 2.5 Preview Free',
+		protocol: 'chat',
+		contextWindow: 1000000,
+		maxOutputTokens: 131072,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: [],
+	},
+	{
+		id: 'step-5-preview-free',
+		name: 'Step 5 Preview Free',
+		protocol: 'chat',
+		contextWindow: 1000000,
+		maxOutputTokens: 65536,
+		inputModalities: ['text', 'image'],
+		inputPrice: 0,
+		outputPrice: 0,
+		supportsToolUse: true,
+		supportsStreaming: true,
+		effortLevels: ['low', 'medium', 'high'],
+	},
+	{
+		id: 'cat-jam-free',
+		name: 'Cat Jam Free',
+		protocol: 'chat',
+		contextWindow: 262144,
+		maxOutputTokens: 131072,
+		inputModalities: ['text'],
 		inputPrice: 0,
 		outputPrice: 0,
 		supportsToolUse: true,
@@ -1338,37 +1522,28 @@ const GO_MODELS = freezeModels([
  */
 export const ZEN_OMITTED_MODELS: readonly string[] = Object.freeze([
 	'go/deepseek-flash',
-	'go/glm-5',
 	'go/glm-5.1',
-	'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',
 	'go/qwen3.6-plus',
 	'go/qwen3.7-max',
-	'zen/claude-sonnet-4',
-	'zen/deepseek-v4-flash-free',
+	'zen/claude-opus-5-5-backup',
+	'zen/gemini-4-argon',
 	'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/mistral-large-4',
 	'zen/muse-spark-1.2-contributor-free',
 	'zen/qwen3.7-max',
 	'zen/qwen3.7-plus',
+	'zen/test',
 ])
 
 /** Supported metadata; actual account availability is established by live discovery. */

package/src/options.ts

@@ -1,6 +1,7 @@
 import { getModelCapabilities as getMessagesCapabilities } from '@ai-sdk/anthropic/internal'
 import type { LanguageModelV3CallOptions, SharedV3ProviderOptions } from '@ai-sdk/provider'
 import { type ChatCompletionParams, ProviderRequestError, type ProviderRoute } from '@namzu/sdk'
+import { ZEN_FREE_TIER_TOOL_NAMES } from './experimental-identity.js'
 import type { ZenModel, ZenProtocol, ZenService } from './models.js'
 import { isMuseSparkResponsesModel, toModelPrompt } from './prompt.js'
 
@@ -28,8 +29,15 @@ export function createCallOptions(
 			detail,
 		})
 	}
-	let maxOutputTokens = params.maxTokens ?? 4096
-	if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0)
+	// Optional wire fields can still select a small upstream default when
+	// absent. Request the advertised model ceiling when known; do not invent
+	// a ceiling for an unknown model. Messages also checks its native ceiling.
+	let maxOutputTokens =
+		params.maxTokens ?? (protocol === 'messages' ? undefined : known?.maxOutputTokens)
+	if (
+		maxOutputTokens !== undefined &&
+		(!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0)
+	)
 		refuse('maxTokens must be a positive integer.')
 	if (
 		params.effort !== undefined &&
@@ -133,6 +141,18 @@ export function createCallOptions(
 		case 'messages': {
 			const thinking = params.thinking
 			const capabilities = getMessagesCapabilities(params.model)
+			// Messages requires max_tokens. Use the actual model ceiling, not
+			// the native adapter's conservative fallback for unknown models.
+			if (maxOutputTokens === undefined) {
+				const modelCeiling =
+					known?.maxOutputTokens ??
+					(capabilities.isKnownModel ? capabilities.maxOutputTokens : undefined)
+				if (modelCeiling === undefined)
+					return refuse('This messages model has no known output limit; set maxTokens explicitly.')
+				maxOutputTokens = capabilities.isKnownModel
+					? Math.min(modelCeiling, capabilities.maxOutputTokens)
+					: modelCeiling
+			}
 			const isThinking = thinking?.type === 'enabled' || thinking?.type === 'adaptive'
 			if (
 				(isThinking || capabilities.rejectsSamplingParameters) &&
@@ -245,7 +265,7 @@ export function createCallOptions(
 	const enforced = new Set(params.enforceToolInputSchema)
 	return {
 		prompt: toModelPrompt(params, route, service, protocol),
-		maxOutputTokens,
+		...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
 		...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
 		...(params.topP !== undefined ? { topP: params.topP } : {}),
 		...(params.topK !== undefined ? { topK: params.topK } : {}),
@@ -294,3 +314,83 @@ export function createCallOptions(
 		providerOptions: options,
 	}
 }
+
+/**
+ * The tool definitions the Zen free-tier gate requires on the wire.
+ *
+ * The gate admits a request only when its `tools` carry all four of `bash`,
+ * `glob`, `grep` and `read`, so a caller that registers none of them — a text
+ * turn, or an agent whose tools happen to use other names — would be refused
+ * before the model ever saw the prompt. These are the gap-fillers, and only
+ * the gaps: a name the caller already registered keeps its own definition,
+ * description and schema untouched.
+ */
+function zenFreeTierTools(): readonly NonNullable<LanguageModelV3CallOptions['tools']>[number][] {
+	return ZEN_FREE_TIER_TOOL_NAMES.map((name) => ({
+		type: 'function' as const,
+		name,
+		description:
+			name === 'bash'
+				? 'Execute a shell command and return its standard output and error.'
+				: name === 'glob'
+					? 'List filesystem paths matching a glob pattern.'
+					: name === 'grep'
+						? 'Search file contents for a regular expression and return the matches.'
+						: 'Read a UTF-8 text file and return its contents.',
+		inputSchema: {
+			type: 'object' as const,
+			properties:
+				name === 'bash'
+					? { command: { type: 'string' as const, description: 'The shell command to run.' } }
+					: name === 'glob'
+						? { pattern: { type: 'string' as const, description: 'The glob pattern to match.' } }
+						: name === 'grep'
+							? {
+									pattern: {
+										type: 'string' as const,
+										description: 'The regular expression to search for.',
+									},
+								}
+							: { path: { type: 'string' as const, description: 'The file to read.' } },
+			required: [
+				name === 'bash'
+					? 'command'
+					: name === 'glob'
+						? 'pattern'
+						: name === 'grep'
+							? 'pattern'
+							: 'path',
+			],
+		},
+	}))
+}
+
+/**
+ * Admit an anonymous Zen request through the free-tier gate.
+ *
+ * `enabled` is the gate path — anonymous access on the official host. When a
+ * caller registered no tool at all, the injected names also pin tool choice to
+ * `none`: the four names are present because the gate reads them, and the
+ * model is still told not to call any of them, so a turn that never asked for
+ * tools never receives one it cannot execute. `honoursNone` is false on a wire
+ * that rejects the choice — Muse Spark's Answers endpoint accepts only
+ * `auto` — where the tools travel without a choice and the kernel's ordinary
+ * unknown-tool answer covers a call to a name it does not hold.
+ * A caller that did register tools keeps its own choice.
+ */
+export function withZenFreeTierTools(
+	options: LanguageModelV3CallOptions,
+	enabled: boolean,
+	honoursNone = true,
+): LanguageModelV3CallOptions {
+	if (!enabled) return options
+	const existing = options.tools ?? []
+	const held = new Set(existing.flatMap((tool) => (tool.type === 'function' ? [tool.name] : [])))
+	const missing = zenFreeTierTools().filter((tool) => !held.has(tool.name))
+	if (missing.length === 0) return options
+	return {
+		...options,
+		tools: [...existing, ...missing],
+		...(existing.length === 0 && honoursNone ? { toolChoice: { type: 'none' as const } } : {}),
+	}
+}