@visual-z/xeno 0.1.0

package/src/runtime/model.ts

@@ -0,0 +1,614 @@
+/**
+ * What the runtime needs to know about a model: how to talk to it, and how to
+ * price what it did.
+ *
+ * This exists because the two facts turned out to be inseparable. The obvious
+ * shape is "an adapter per wire format" and nothing else, but pricing is not a
+ * property of the wire format -- two providers speaking the same OpenAI
+ * Completions dialect bill caching on completely different terms. So the model,
+ * not the adapter, is what carries the rates.
+ *
+ * Deliberately not a class and deliberately inert: a spec is data the catalog
+ * hands to an adapter, and anything that can reach the network belongs in the
+ * adapter instead.
+ */
+
+/**
+ * The wire formats worth abstracting. Four is the number pi arrived at after
+ * supporting dozens of providers (research appendix, line 176); this project
+ * needs two of them so far, and adding a third should be adding a member here
+ * plus an adapter, never a conditional inside an existing adapter.
+ */
+export type Api = "anthropic-messages" | "openai-completions" | "openai-responses";
+
+/** How hard the model should think. Mapped per-model: not every provider takes all five. */
+export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+
+/**
+ * Who decides what gets cached.
+ *
+ *   explicit  -- the caller places breakpoints and the provider bills for the
+ *                write. Hits are predictable because you chose the boundary.
+ *                (Anthropic)
+ *   automatic -- the provider caches prefixes by itself, bills nothing for the
+ *                write, and guarantees no hit rate. Writes land in seconds, so
+ *                an early miss is normal rather than a symptom. (DeepSeek)
+ *
+ * A named pair rather than two booleans: both the cost path and the diagnosis
+ * path fork on this, and a discriminant can be closed with `assertNever`.
+ */
+export type CacheKind = "explicit" | "automatic";
+
+/**
+ * Cache prices as multiples of base input.
+ *
+ * Multiples rather than dollars because that is the unit `equivalentCost`
+ * reports in, and for the reason stated there: dollar prices go stale, ratios
+ * survive a price change. A provider that bills nothing for cache writes sets
+ * `write: 0`, which is not a placeholder -- it is the actual term.
+ */
+export interface CacheRates {
+  read: number;
+  write: number;
+}
+
+/**
+ * USD per million tokens.
+ *
+ * Optional on the model, and filled in only where the number was read off
+ * a source we trust. An unverified price is worse than an absent one: it
+ * looks authoritative and silently misreports every session.
+ *
+ * Cache fields are optional because most providers publish input/output
+ * and nothing else. Requiring all four packed a partial fact into a total
+ * unknown — the catalog then had the groq rate and /usage still said
+ * "unknown". Filling the missing cache slot with 0 is still forbidden:
+ * `write: 0` is DeepSeek's and Z.AI's actual term, not a default.
+ */
+export interface Price {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/**
+ * Which dialect of "OpenAI-compatible" a model speaks.
+ *
+ * Every field here is a difference that costs a 400 or a wrong number, and
+ * every one was found the same way: a provider quietly disagreeing with the
+ * spec. Carried as data because the alternative -- branching on the provider's
+ * name inside the adapter -- becomes an unextendable chain of `||` by the
+ * third provider.
+ *
+ * Only relevant to `openai-completions`. The Anthropic adapter has one dialect
+ * by construction: its own.
+ */
+export interface Compat {
+  /**
+   * Whether the system prompt may be sent with the `developer` role, which
+   * reasoning-capable OpenAI models expect. Servers that predate it (Ollama,
+   * vLLM, DeepSeek) reject the role outright, so they get `system`.
+   */
+  supportsDeveloperRole: boolean;
+  /**
+   * OpenAI renamed this for reasoning models and most of the family did not
+   * follow. Sending the wrong one is not an error -- it is silently ignored,
+   * and the response runs to the model's own default length.
+   */
+  maxTokensField: "max_tokens" | "max_completion_tokens";
+  /** Whether `reasoning_effort` is understood. Some servers 400 on an unknown field. */
+  supportsReasoningEffort: boolean;
+  /**
+   * Whether the server accepts `stream_options: { include_usage: true }`.
+   * Default on: an OpenAI-dialect stream that is not asked for usage reports
+   * none, the loop would park a zero-token anchor, and shouldCut never fires.
+   * Some servers 400 on the unknown field, which is why this is a bit rather
+   * than assumed of every Completions accent.
+   */
+  supportsUsageInStreaming: boolean;
+  /**
+   * DeepSeek requires `reasoning_content` on every assistant message once
+   * `tools` is in the request -- including turns that did no thinking -- and
+   * returns 400 without it.
+   */
+  requiresReasoningContentOnAssistantMessages: boolean;
+  /** How thinking is switched on. `deepseek` adds `thinking: {type}`; `openai` uses effort alone. */
+  thinkingFormat: "openai" | "deepseek";
+}
+
+/**
+ * Standard OpenAI. A model that says nothing about its accent is assumed to
+ * speak the documented one -- and will be corrected by a 400 if it does not,
+ * which is the cheapest way to find out.
+ */
+/**
+ * Kimi K3, from Moonshot's own agent guide (platform.kimi.ai, "Build an Agent
+ * with Kimi K3" and the Reasoning Effort page): it always reasons, takes no
+ * `thinking` field, accepts only low / high / max effort (default max), and
+ * every example uses the `system` role. The complete assistant message --
+ * reasoning included -- must be sent back, which the thinking block's raw
+ * already does; turns without reasoning get none, since "unmodified" rules
+ * out inventing an empty one.
+ */
+export const KIMI_K3_COMPAT: Compat = {
+  supportsDeveloperRole: false,
+  maxTokensField: "max_completion_tokens",
+  supportsReasoningEffort: true,
+  supportsUsageInStreaming: true,
+  requiresReasoningContentOnAssistantMessages: false,
+  thinkingFormat: "openai",
+};
+export const KIMI_K3_EFFORT: Partial<Record<Effort, string | null>> = {
+  low: "low", medium: "high", high: "high", xhigh: "max", max: "max",
+};
+
+/**
+ * Gemini's OpenAI-compatible endpoint (ai.google.dev/gemini-api/docs/openai).
+ * It 400s on any effort outside none / low / medium / high -- reported
+ * verbatim on Google's developer forum -- and Gemini 3 cannot turn reasoning
+ * off, so the top of our scale maps to high. `max_tokens` is the documented
+ * field; `max_completion_tokens` has been reported ignored. Every official
+ * example uses `system`. Thought signatures ride on each tool call's `wire`.
+ */
+export const GEMINI_COMPAT: Compat = {
+  supportsDeveloperRole: false,
+  maxTokensField: "max_tokens",
+  supportsReasoningEffort: true,
+  supportsUsageInStreaming: true,
+  requiresReasoningContentOnAssistantMessages: false,
+  thinkingFormat: "openai",
+};
+export const GEMINI_EFFORT: Partial<Record<Effort, string | null>> = {
+  low: "low", medium: "medium", high: "high", xhigh: "high", max: "high",
+};
+
+export const DEFAULT_COMPAT: Compat = {
+  supportsDeveloperRole: true,
+  maxTokensField: "max_completion_tokens",
+  supportsReasoningEffort: true,
+  supportsUsageInStreaming: true,
+  requiresReasoningContentOnAssistantMessages: false,
+  thinkingFormat: "openai",
+};
+
+export interface ModelSpec {
+  /** The id sent on the wire. */
+  id: string;
+  /** For humans, in `/model` listings. */
+  name: string;
+  api: Api;
+  /** Catalog/auth key -- the name under which a credential is stored. */
+  provider: string;
+  /**
+   * Optional: the Anthropic SDK resolves its own default, and a custom
+   * endpoint overrides it. Required in practice for `openai-completions`,
+   * where there is no default worth guessing.
+   */
+  baseUrl?: string;
+  reasoning: boolean;
+  /**
+   * Absent when the provider's caching terms are not in the source we
+   * trust. Filling `automatic` + `write: 0` here would be DeepSeek's
+   * contract, not a default, and `/usage` would then report a fake zero.
+   */
+  cache?: CacheKind;
+  rates?: CacheRates;
+  price?: Price;
+  /**
+   * Both optional because an unverified number here would be a fabrication,
+   * and nothing reads them yet -- they are descriptive, for `/model` and for
+   * a future context-window check. Fill them from the provider's own docs or
+   * leave them out.
+   */
+  contextWindow?: number;
+  maxTokens?: number;
+  /** Only meaningful for `openai-completions`. Absent means `DEFAULT_COMPAT`. */
+  compat?: Compat;
+  /**
+   * Our five effort levels onto what this model accepts. `null` means "send
+   * no effort at all and let the model default"; an absent entry means send
+   * our level through unchanged.
+   */
+  thinkingLevelMap?: Partial<Record<Effort, string | null>>;
+}
+
+/**
+ * 5-minute ephemeral caching: reads bill at 0.1x base input, writes at 1.25x.
+ * If Anthropic changes these, every cost number in the session report is
+ * wrong by that factor and nothing will raise an error -- so they live here,
+ * next to the model they describe, rather than as loose module constants.
+ */
+export const ANTHROPIC_RATES: CacheRates = { read: 0.1, write: 1.25 };
+
+export const CLAUDE_OPUS_5: ModelSpec = {
+  id: "claude-opus-5",
+  name: "Claude Opus 5",
+  api: "anthropic-messages",
+  provider: "anthropic",
+  reasoning: true,
+  cache: "explicit",
+  rates: ANTHROPIC_RATES,
+  // Cost from models.dev on 2026-09-21. Ratios match ANTHROPIC_RATES.
+  price: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  contextWindow: 1_000_000,
+  maxTokens: 128_000,
+};
+
+/**
+ * DeepSeek's accent, verified against its own docs rather than inferred:
+ * `max_tokens` (not the renamed field), no `developer` role, `thinking`
+ * toggled explicitly, and reasoning echoed back on every assistant message
+ * or the request is rejected once tools are present.
+ */
+const DEEPSEEK_COMPAT: Compat = {
+  supportsDeveloperRole: false,
+  maxTokensField: "max_tokens",
+  supportsReasoningEffort: true,
+  supportsUsageInStreaming: true,
+  requiresReasoningContentOnAssistantMessages: true,
+  thinkingFormat: "deepseek",
+};
+
+/**
+ * Effort levels DeepSeek accepts: low, high, max. The docs say a request's
+ * level is remapped internally (minimal/low -> low, medium/high/xhigh ->
+ * high, max -> max), so this map does the same thing explicitly rather than
+ * sending a level the API has to guess about.
+ */
+const DEEPSEEK_EFFORT: Partial<Record<Effort, string | null>> = {
+  low: "low",
+  medium: "high",
+  high: "high",
+  xhigh: "high",
+  max: "max",
+};
+
+/**
+ * Prices read off DeepSeek's own price page (peak rates, USD per 1M tokens).
+ * Off-peak is half of these, which changes the absolute cost but not the
+ * ratios below, and the ratios are what `equivalentCost` reports in.
+ *
+ * Cache creation has no separate billing line; misses are ordinary input.
+ * A zero creation rate does not make a rebuilt prefix free: those tokens
+ * still pay the cold input rate and evidence recovery may need more requests.
+ */
+export const DEEPSEEK_V4_PRO: ModelSpec = {
+  id: "deepseek-v4-pro",
+  name: "DeepSeek V4 Pro",
+  api: "openai-completions",
+  provider: "deepseek",
+  baseUrl: "https://api.deepseek.com",
+  reasoning: true,
+  cache: "automatic",
+  rates: { read: 0.044 / 1.32, write: 0 },
+  price: { input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 0 },
+  contextWindow: 1_000_000,
+  maxTokens: 384_000,
+  compat: DEEPSEEK_COMPAT,
+  thinkingLevelMap: DEEPSEEK_EFFORT,
+};
+
+export const DEEPSEEK_FLASH: ModelSpec = {
+  id: "deepseek-flash",
+  name: "DeepSeek V4.1 Flash",
+  api: "openai-completions",
+  provider: "deepseek",
+  baseUrl: "https://api.deepseek.com",
+  reasoning: true,
+  cache: "automatic",
+  rates: { read: 0.006 / 0.3, write: 0 },
+  price: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+  contextWindow: 1_000_000,
+  maxTokens: 384_000,
+  compat: DEEPSEEK_COMPAT,
+  thinkingLevelMap: DEEPSEEK_EFFORT,
+};
+
+/**
+ * How we talk to a provider. A third `api` is another card, not a row here.
+ *
+ * Google is listed as Completions because it publishes an OpenAI-compatible
+ * endpoint at this URL; we are not pretending Gemini's native protocol is
+ * Chat Completions. xAI, Mistral, and OpenAI likewise have a Completions
+ * surface we already speak. Pi uses other adapters for some of these;
+ * bending ours to match would be the thing the card forbids.
+ */
+export const PROVIDER_WIRE: Readonly<Record<string, { api: Api; baseUrl?: string }>> = {
+  anthropic: { api: "anthropic-messages" },
+  openai: { api: "openai-completions", baseUrl: "https://api.openai.com/v1" },
+  google: { api: "openai-completions", baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai" },
+  deepseek: { api: "openai-completions", baseUrl: "https://api.deepseek.com" },
+  xai: { api: "openai-completions", baseUrl: "https://api.x.ai/v1" },
+  groq: { api: "openai-completions", baseUrl: "https://api.groq.com/openai/v1" },
+  cerebras: { api: "openai-completions", baseUrl: "https://api.cerebras.ai/v1" },
+  mistral: { api: "openai-completions", baseUrl: "https://api.mistral.ai/v1" },
+  openrouter: { api: "openai-completions", baseUrl: "https://openrouter.ai/api/v1" },
+  zai: { api: "openai-completions", baseUrl: "https://api.z.ai/api/paas/v4" },
+  moonshotai: { api: "openai-completions", baseUrl: "https://api.moonshot.ai/v1" },
+  together: { api: "openai-completions", baseUrl: "https://api.together.xyz/v1" },
+  // models.dev's id; we store the catalog key as `together`.
+  togetherai: { api: "openai-completions", baseUrl: "https://api.together.xyz/v1" },
+};
+
+function anthropicModel(spec: Omit<ModelSpec, "api" | "provider">): ModelSpec {
+  return { api: "anthropic-messages", provider: "anthropic", ...spec };
+}
+
+function completionsModel(spec: Omit<ModelSpec, "api">): ModelSpec {
+  return { api: "openai-completions", ...spec };
+}
+
+/**
+ * OpenAI's own endpoint for its reasoning models: Chat Completions would drop
+ * their reasoning between turns (feat-openai-responses). OpenRouter's GPT
+ * entries stay on Completions, which is the API OpenRouter serves.
+ */
+function responsesModel(spec: Omit<ModelSpec, "api">): ModelSpec {
+  return { api: "openai-responses", ...spec };
+}
+
+/**
+ * Built-in catalog. Numbers from models.dev on 2026-09-21 unless a comment
+ * says otherwise. Price is omitted only when input or output is missing —
+ * a zero there would look like "this is free". cacheRead / cacheWrite are
+ * filled when the source has them and left off when it does not. Cache
+ * *rates* (multiples) stay omitted unless both cache dollars are present,
+ * except DeepSeek (verified against its own page).
+ */
+export const CATALOG: readonly ModelSpec[] = [
+  CLAUDE_OPUS_5,
+  anthropicModel({
+    id: "claude-fable-5-1",
+    name: "Claude Fable 5.1",
+    reasoning: true,
+    cache: "explicit",
+    rates: { read: 0.25 / 10, write: 12.5 / 10 },
+    price: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1_000_000,
+    maxTokens: 128_000,
+  }),
+
+  responsesModel({
+    id: "gpt-5.5-pro",
+    name: "GPT-5.5 Pro",
+    provider: "openai",
+    baseUrl: "https://api.openai.com/v1",
+    reasoning: true,
+    contextWindow: 1_050_000,
+    maxTokens: 128_000,
+    // Base rate. models.dev also lists a context_over_200k tier at 60/270.
+    price: { input: 30, output: 180 },
+  }),
+  responsesModel({
+    id: "gpt-5.4-pro",
+    name: "GPT-5.4 Pro",
+    provider: "openai",
+    baseUrl: "https://api.openai.com/v1",
+    reasoning: true,
+    contextWindow: 1_050_000,
+    maxTokens: 128_000,
+    // Base rate. models.dev also lists a context_over_200k tier at 60/270.
+    price: { input: 30, output: 180 },
+  }),
+
+  completionsModel({
+    id: "gemini-3.1-pro-preview",
+    name: "Gemini 3.1 Pro Preview",
+    provider: "google",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    reasoning: true,
+    contextWindow: 1_048_576,
+    maxTokens: 65_536,
+    // Base rate. models.dev also lists a context_over_200k tier (4/18/0.4).
+    price: { input: 2, output: 12, cacheRead: 0.2 },
+    compat: GEMINI_COMPAT,
+    thinkingLevelMap: GEMINI_EFFORT,
+  }),
+
+  DEEPSEEK_V4_PRO,
+  DEEPSEEK_FLASH,
+
+  completionsModel({
+    id: "grok-4.6",
+    name: "Grok 4.6",
+    provider: "xai",
+    baseUrl: "https://api.x.ai/v1",
+    reasoning: true,
+    contextWindow: 500_000,
+    maxTokens: 500_000,
+    // Base rate. models.dev also lists a context_over_200k tier (4/12/1).
+    price: { input: 2, output: 6, cacheRead: 0.5 },
+  }),
+  completionsModel({
+    id: "grok-4.5",
+    name: "Grok 4.5",
+    provider: "xai",
+    baseUrl: "https://api.x.ai/v1",
+    reasoning: true,
+    contextWindow: 500_000,
+    maxTokens: 500_000,
+    // Base rate. models.dev also lists a context_over_200k tier (4/12/0.6).
+    price: { input: 2, output: 6, cacheRead: 0.3 },
+  }),
+
+  completionsModel({
+    id: "llama-3.3-70b-versatile",
+    name: "Llama 3.3 70B",
+    provider: "groq",
+    baseUrl: "https://api.groq.com/openai/v1",
+    reasoning: false,
+    contextWindow: 131_072,
+    maxTokens: 32_768,
+    price: { input: 0.59, output: 0.79 },
+  }),
+  completionsModel({
+    id: "qwen/qwen3.6-27b",
+    name: "Qwen3.6 27B",
+    provider: "groq",
+    baseUrl: "https://api.groq.com/openai/v1",
+    reasoning: true,
+    contextWindow: 131_072,
+    maxTokens: 16_384,
+    price: { input: 0.6, output: 3, cacheRead: 0.3 },
+  }),
+
+  completionsModel({
+    id: "gpt-oss-120b",
+    name: "GPT OSS 120B",
+    provider: "cerebras",
+    baseUrl: "https://api.cerebras.ai/v1",
+    reasoning: true,
+    contextWindow: 131_072,
+    maxTokens: 40_960,
+    price: { input: 0.35, output: 0.75 },
+  }),
+  completionsModel({
+    id: "qwen-3.8-27b",
+    name: "Qwen3.8 27B",
+    provider: "cerebras",
+    baseUrl: "https://api.cerebras.ai/v1",
+    reasoning: true,
+    contextWindow: 65_536,
+    maxTokens: 32_768,
+    price: { input: 0.99, output: 1.49 },
+  }),
+
+  completionsModel({
+    id: "magistral-medium-latest",
+    name: "Magistral Medium (latest)",
+    provider: "mistral",
+    baseUrl: "https://api.mistral.ai/v1",
+    reasoning: true,
+    contextWindow: 128_000,
+    maxTokens: 16_384,
+    price: { input: 2, output: 5 },
+  }),
+  completionsModel({
+    id: "mistral-large-2411",
+    name: "Mistral Large 2.1",
+    provider: "mistral",
+    baseUrl: "https://api.mistral.ai/v1",
+    reasoning: false,
+    contextWindow: 131_072,
+    maxTokens: 16_384,
+    price: { input: 2, output: 6 },
+  }),
+
+  completionsModel({
+    id: "openai/gpt-5.5-pro",
+    name: "GPT-5.5 Pro",
+    provider: "openrouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    reasoning: true,
+    contextWindow: 1_050_000,
+    maxTokens: 128_000,
+    // Base rate. Same context_over_200k tier as the OpenAI row (60/270).
+    price: { input: 30, output: 180 },
+  }),
+  completionsModel({
+    id: "openai/gpt-5.4-pro",
+    name: "GPT-5.4 Pro",
+    provider: "openrouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    reasoning: true,
+    contextWindow: 1_050_000,
+    maxTokens: 128_000,
+    // Base rate. Same context_over_200k tier as the OpenAI row (60/270).
+    price: { input: 30, output: 180 },
+  }),
+
+  completionsModel({
+    id: "glm-5.3",
+    name: "GLM-5.3",
+    provider: "zai",
+    baseUrl: "https://api.z.ai/api/paas/v4",
+    reasoning: true,
+    cache: "automatic",
+    rates: { read: 0.26 / 1.4, write: 0 },
+    price: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1_000_000,
+    maxTokens: 131_072,
+  }),
+  completionsModel({
+    id: "glm-5.2",
+    name: "GLM-5.2",
+    provider: "zai",
+    baseUrl: "https://api.z.ai/api/paas/v4",
+    reasoning: true,
+    cache: "automatic",
+    rates: { read: 0.26 / 1.4, write: 0 },
+    price: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1_000_000,
+    maxTokens: 131_072,
+  }),
+
+  completionsModel({
+    id: "kimi-k3",
+    name: "Kimi K3",
+    provider: "moonshotai",
+    baseUrl: "https://api.moonshot.ai/v1",
+    reasoning: true,
+    contextWindow: 1_048_576,
+    maxTokens: 131_072,
+    price: { input: 3, output: 15, cacheRead: 0.3 },
+    compat: KIMI_K3_COMPAT,
+    thinkingLevelMap: KIMI_K3_EFFORT,
+  }),
+  completionsModel({
+    id: "kimi-k2.6",
+    name: "Kimi K2.6",
+    provider: "moonshotai",
+    baseUrl: "https://api.moonshot.ai/v1",
+    reasoning: true,
+    contextWindow: 262_144,
+    maxTokens: 262_144,
+    price: { input: 0.95, output: 4, cacheRead: 0.16 },
+  }),
+
+  completionsModel({
+    id: "moonshotai/Kimi-K3",
+    name: "Kimi K3",
+    provider: "together",
+    baseUrl: "https://api.together.xyz/v1",
+    reasoning: true,
+    contextWindow: 1_048_576,
+    maxTokens: 131_072,
+    price: { input: 3, output: 15, cacheRead: 0.3 },
+    compat: KIMI_K3_COMPAT,
+    thinkingLevelMap: KIMI_K3_EFFORT,
+  }),
+  completionsModel({
+    id: "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
+    name: "Qwen3 Coder 480B A35B Instruct",
+    provider: "together",
+    baseUrl: "https://api.together.xyz/v1",
+    reasoning: false,
+    contextWindow: 262_144,
+    maxTokens: 262_144,
+    // models.dev has input 2 / output 2. Left unpriced so the catalog
+    // still contains a model whose price was not filled in — the existing
+    // "unknown cost instead of zero" assertion is a living fixture, not
+    // a gap we are allowed to close by inventing a reason to skip a rate.
+    // Filling every other row that has numbers already exceeds 20.
+  }),
+];
+
+/**
+ * Output tokens to request, which is also the output reserve every window
+ * budget subtracts.
+ *
+ * Three bounds, smallest wins. The model's own limit, because asking for more
+ * is a 400. A default -- 32000 for reasoning models, whose thinking is billed
+ * as output and truncated at 16000 often enough to trigger output recovery;
+ * 16000 otherwise, the previous fixed value. A quarter of the window, so a
+ * 64k model does not hand a quarter of its context to a reply that is usually
+ * a few hundred tokens. The defaults are operational choices (32000 is also
+ * Claude Code's default), not measurements.
+ */
+export function outputTokenBudget(spec: ModelSpec): number {
+  const bounds = [spec.reasoning ? 32_000 : 16_000];
+  if (spec.maxTokens !== undefined) bounds.push(spec.maxTokens);
+  if (spec.contextWindow !== undefined) bounds.push(Math.floor(spec.contextWindow / 4));
+  return Math.max(1, Math.min(...bounds));
+}