@molecule/api-resource-ai-models 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,672 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-06T19:42:52.531Z
+-->
+
+# @molecule/api-resource-ai-models
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+AI model catalog resource.
+
+Server-side source of truth for available AI models plus an
+authentication-gated discovery endpoint (`GET /ai/models`). Server consumers
+(chat handler, compaction) import `MODELS` / `getModel` / `MODEL_IDS`
+directly; authenticated clients fetch the filtered projection over HTTP. The
+`list` handler enforces the session check itself and fails closed with `401`,
+so the configured-model catalog is never disclosed to an unauthenticated
+caller even if the route's `'authenticate'` middleware is stripped by codegen.
+
+## Quick Start
+
+```typescript
+import { getModel, MODEL_IDS } from '@molecule/api-resource-ai-models'
+
+// Server-side validation of a client-selected model id:
+if (!MODEL_IDS.has(requestedId)) {
+  throw new Error('Unknown or retired model')
+}
+const model = getModel(requestedId)! // full definition (pricing, effort levels)
+```
+
+## Type
+
+`resource`
+
+## Installation
+
+```bash
+npm install @molecule/api-resource-ai-models @molecule/api-bond @molecule/api-i18n @molecule/api-resource
+```
+
+## API
+
+### Interfaces
+
+#### `ListModelsResponse`
+
+Response shape returned by `GET /ai/models`.
+
+```typescript
+interface ListModelsResponse {
+  models: ModelDefinition[]
+  /**
+   * Per-mode server default model ids for the requester's tier. Optional —
+   * servers that don't compute tier-aware defaults omit it, and clients fall
+   * back to generic "default" labeling.
+   */
+  defaults?: ModeModelDefaults
+}
+```
+
+#### `ModelDefinition`
+
+Full server-side metadata for an AI model. Consumed directly by the chat
+handler, compaction, and any other server-side cost / budget logic.
+
+```typescript
+interface ModelDefinition {
+  /** API model ID (e.g. `'claude-sonnet-4-6'`, `'gpt-5.4'`). */
+  id: string
+  /** Which AI provider serves this model. */
+  provider: AIProviderID
+  /** Human-readable label (e.g. `'Claude Sonnet 4.6'`). */
+  label: string
+  /** Short description for UI display. */
+  description: string
+  /** Maximum input context window in tokens. */
+  contextWindow: number
+  /** Maximum output tokens per response. */
+  maxOutputTokens: number
+  /** Whether the model supports extended thinking / chain-of-thought. */
+  supportsThinking: boolean
+  /** Default thinking budget in tokens (only relevant when `supportsThinking` is true). */
+  thinkingBudgetTokens: number
+  /**
+   * Whether the thinking budget can be controlled via API params.
+   * When false, the model always reasons but does not accept a thinking / reasoning_effort param.
+   */
+  thinkingConfigurable: boolean
+  /**
+   * The model's OWN reasoning-effort levels, ordered ascending (least → most
+   * effort) — the exact values a user picks, that get persisted, and that the
+   * `/effort` command offers. There is NO abstract scale: these are the model's
+   * real levels.
+   *
+   * - **Native-effort models** (Anthropic `output_config.effort`, OpenAI
+   *   `reasoning_effort`, Gemini `thinking_level`, …) list their provider values
+   *   verbatim, e.g. `['low', 'high', 'xhigh', 'max']` — each value is sent as
+   *   the provider's effort param as-is.
+   * - **Budget-configurable models** (a raw thinking-token budget, no native
+   *   level names — e.g. Claude Haiku 4.5, Qwen3.7) list scaled-budget LABELS,
+   *   e.g. `['4K', '8K', '16K', '32K']`, with {@link effortBudgetTokens} mapping
+   *   each label to the actual token budget sent.
+   * - **Fixed-reasoning models** (DeepSeek executors, Kimi, …) omit this field
+   *   entirely — reasoning depth can't be tuned, so there is nothing to pick.
+   *
+   * A persisted value outside the active model's set degrades to the nearest one
+   * (`model-selection.ts` `resolveEffortForModel`). Absent → no effort choice.
+   */
+  supportedEffortLevels?: EffortLevel[]
+  /**
+   * The model's default effort value — the one used when the user hasn't chosen.
+   * MUST be a member of {@link supportedEffortLevels}. Absent only when the model
+   * has no effort levels (fixed reasoning).
+   */
+  defaultEffortLevel?: EffortLevel
+  /**
+   * For budget-configurable models ONLY: maps each label in
+   * {@link supportedEffortLevels} to the thinking-token budget it sends
+   * (e.g. `{ '4K': 4000, '8K': 8000, '16K': 16000, '32K': 32000 }`). Its
+   * presence is what marks a model as budget-driven rather than native-effort:
+   * a model WITH this map sends `budget_tokens`; a model WITHOUT it sends its
+   * chosen level as the provider's native effort param.
+   *
+   * CRITICAL for Anthropic 4.6+ models (Fable 5, Opus 4.8/4.6, Sonnet 5 / 4.6):
+   * these must NOT carry this map — they are native-effort models, and sending
+   * `budget_tokens` returns a 400 on Fable 5 / Opus 4.8 / Sonnet 5.
+   */
+  effortBudgetTokens?: Record<string, number>
+  /** Whether the model supports vision (images, documents, etc.). */
+  supportsVision: boolean
+  /** Whether the model supports prompt caching. */
+  supportsPromptCaching: boolean
+  /** Whether the model supports tool use / function calling. */
+  supportsTools: boolean
+  /**
+   * The model cannot combine function tools with ANY reasoning on the provider's
+   * chat-completions endpoint, so a request carrying tools must pin reasoning
+   * OFF or it is rejected outright.
+   *
+   * Set for the gpt-5.6 family, which answers a tools request with:
+   * `Function tools with reasoning_effort are not supported for <model> in
+   * /v1/chat/completions. To use function tools, use /v1/responses or set
+   * reasoning_effort to 'none'.` (400 — verified live, 2026-07-30). Omitting the
+   * effort field entirely does NOT help: the model applies its own default and
+   * still 400s. Only an explicit `'none'` works.
+   *
+   * This is a per-model API fact, so it lives in the catalogue rather than as a
+   * model-name branch inside a bond.
+   *
+   * **This is a workaround, not the fix.** Pinning reasoning off means an agentic
+   * caller — which always carries tools — never gets reasoning from these models.
+   * The real fix is migrating the OpenAI bond to `/v1/responses`, which supports
+   * both together; until then, working-without-reasoning beats 400.
+   */
+  toolsRequireReasoningOff?: boolean
+  /**
+   * Provider-specific server tool type for web search (e.g. `'web_search_20250305'`).
+   * When set, the chat handler sends this as a ServerTool alongside custom tools.
+   * Omit if the model / provider does not support native web search.
+   */
+  webSearchToolType?: string
+  /**
+   * Provider-specific server tool type for code execution (e.g. `'code_execution_20250825'`).
+   * Omit if the model / provider does not support native code execution.
+   */
+  codeExecutionToolType?: string
+  /**
+   * Provider-specific server tool type for web fetch / URL context (e.g. `'web_fetch_20260209'`).
+   * Omit if the model / provider does not support native web fetch.
+   */
+  webFetchToolType?: string
+  /** Whether this model is available on the free tier (only one model should be true). */
+  freeTier?: boolean
+  /**
+   * Regions in which this model is free-tier selectable even though the model
+   * as a whole is not `freeTier` — for models whose regional hosts price very
+   * differently (e.g. a cheap native host powering the free planner while its
+   * ~3× re-host stays paid-only). Ignored when `freeTier` is true (all regions
+   * free); omitted → no free-tier access outside `freeTier`.
+   */
+  freeTierRegions?: string[]
+  /**
+   * Processing regions this model can run in, as arbitrary region codes; the
+   * FIRST entry is the model's default region. Omit for `['us']` (the platform
+   * default — a single-region US model). A single-entry list pins the model to
+   * that region regardless of the user's per-model choice (e.g. `['cn']` for a
+   * model with no US re-host). Dispatch resolves a region to the
+   * `<provider>-<region>` named bond (`'us'` → the bare `<provider>` bond).
+   */
+  regions?: string[]
+  /**
+   * Per-region price overrides in USD per MTok, keyed by region code, for
+   * regions whose host bills differently from the base rates (e.g. a US
+   * re-host of a Chinese-origin model). The BASE `*PricePerMTok` fields always
+   * carry the native provider's list prices (what models.dev / the freshness
+   * gate verify); a region with no entry here bills at the base rates. Omitted
+   * cache fields fall back to the region's `inputPricePerMTok` (hosts with no
+   * cache discount / no write premium).
+   */
+  regionPricing?: Record<
+    string,
+    {
+      /** Region input price per million uncached tokens in USD. */
+      inputPricePerMTok: number
+      /** Region output price per million tokens in USD. */
+      outputPricePerMTok: number
+      /** Region prompt-cache read price per million tokens in USD. */
+      cacheReadPricePerMTok?: number
+      /** Region prompt-cache write price per million tokens in USD. */
+      cacheWritePricePerMTok?: number
+    }
+  >
+  /** Input price per million *uncached* (fresh) input tokens in USD. */
+  inputPricePerMTok: number
+  /** Output price per million tokens in USD. */
+  outputPricePerMTok: number
+  /**
+   * Price per million prompt-cache *read* (cache-hit) input tokens in USD.
+   *
+   * REQUIRED — never omit. Prompt caching is enabled for the agentic loop, so
+   * for a long conversation the cache-read tokens are the DOMINANT input
+   * category. Pricing them at `0` (the bug this field fixes) systematically
+   * under-measures real upstream spend and lets cost-gated budgets be blown
+   * past their caps. Conventionally a steep discount on `inputPricePerMTok`
+   * (e.g. Anthropic / OpenAI / DeepSeek bill cache reads at ~0.1×). MUST be
+   * `<= inputPricePerMTok` — a cache hit is never more expensive than fresh
+   * input.
+   */
+  cacheReadPricePerMTok: number
+  /**
+   * Price per million prompt-cache *write* (cache-creation) input tokens in USD.
+   *
+   * REQUIRED — never omit. The first time a prefix is cached the provider may
+   * charge a premium (Anthropic's 5-minute cache write is ~1.25× input);
+   * providers that auto-cache at no extra charge (OpenAI, DeepSeek) set this
+   * equal to `inputPricePerMTok`. MUST be `>= inputPricePerMTok` — a cache
+   * write is never cheaper than fresh input. Only the Anthropic bond currently
+   * emits `cacheCreationInputTokens`, but every model declares this so a new
+   * cache-emitting bond can never silently bill cache writes at `0`.
+   */
+  cacheWritePricePerMTok: number
+  /**
+   * Optional provider peak-hour pricing: during the listed UTC windows, ALL of
+   * this model's token prices (input, output, cache read/write) bill at
+   * `multiplier × ` the listed rates. Metering MUST price each request by its
+   * own timestamp via `priceMultiplierAt()` — never assume the flat rate — or
+   * peak-hour usage is under-metered and the platform eats the difference
+   * (e.g. DeepSeek's announced 2× Beijing-business-hours pricing).
+   *
+   * Windows are minutes-since-midnight UTC, half-open `[start, end)`; a window
+   * may wrap midnight (`start > end`).
+   */
+  peakPricing?: {
+    windows: { startMinuteUtc: number; endMinuteUtc: number }[]
+    multiplier: number
+  }
+  /**
+   * Fast-mode ("priority speed") pricing — the per-MTok rates billed when a
+   * request runs with the provider's fast/priority tier (e.g. Anthropic's
+   * `speed: "fast"` research preview: same model, up to ~2.5× output speed, at
+   * premium pricing). PRESENCE of this field is the capability flag: a model
+   * without it does not support fast mode, and metering/UI/dispatch all key off
+   * that. All four fields are required for the same never-under-meter reasons
+   * as the base rates. Metering MUST price a turn by the speed the provider
+   * REPORTS it ran at (`TokenUsage.speed`), not the speed requested — a
+   * fast-mode 429 that falls back to standard must not bill 2×.
+   */
+  fastPricing?: {
+    /** Fast-mode input price per million uncached tokens in USD. */
+    inputPricePerMTok: number
+    /** Fast-mode output price per million tokens in USD. */
+    outputPricePerMTok: number
+    /** Fast-mode prompt-cache read price per million tokens in USD. */
+    cacheReadPricePerMTok: number
+    /** Fast-mode prompt-cache write price per million tokens in USD. */
+    cacheWritePricePerMTok: number
+  }
+  /** Reliable knowledge cutoff date (YYYY-MM-DD). */
+  knowledgeCutoff: string
+  /**
+   * When the model was (or will be) deprecated (YYYY-MM-DD).
+   *
+   * Past dates: still selectable, but the picker tucks them into an "Older
+   * models" section so newcomers default to current entries. Saved selections
+   * (a user previously picked this) keep working. Future dates: still treated
+   * as current — useful for scheduling a deprecation in advance.
+   *
+   * Omit entirely for current models.
+   */
+  deprecatedAt?: string
+  /**
+   * Whether this model is fully disabled — removed from selection and the
+   * public listing while remaining priceable for historical usage.
+   *
+   * Stronger than {@link deprecatedAt}: a deprecated model is still selectable
+   * (the picker just tucks it into an "Older models" section), whereas a
+   * disabled model vanishes from every *exposure* surface — it is excluded from
+   * `MODEL_IDS`, `getAvailableModels()`, the `GET /ai/models` listing, and the
+   * client-side free-tier / deprecation-partition helpers. Use it for a model
+   * the provider has retired or deprecated (e.g. `grok-code-fast-1`).
+   *
+   * `getModel(id)` STILL returns a disabled entry so a saved selection or a
+   * historical usage row can always be priced — NEVER delete a disabled model,
+   * or its past usage silently meters as free. Omit entirely for active models.
+   */
+  disabled?: boolean
+}
+```
+
+#### `ModelTokenRates`
+
+The four per-MTok token rates a turn bills at (USD).
+
+```typescript
+interface ModelTokenRates {
+  /** Input price per million uncached tokens in USD. */
+  inputPricePerMTok: number
+  /** Output price per million tokens in USD. */
+  outputPricePerMTok: number
+  /** Prompt-cache read price per million tokens in USD. */
+  cacheReadPricePerMTok: number
+  /** Prompt-cache write price per million tokens in USD. */
+  cacheWritePricePerMTok: number
+}
+```
+
+#### `ModeModelDefaults`
+
+The model ids the SERVER falls back to per mode/job when the user hasn't
+picked one — already resolved for the requester's tier (a free-tier caller
+sees the free-tier clamp ids, a paid caller the paid defaults). Lets the
+client label an unset per-mode picker "Default (<model>)" instead of a
+vague "default" the user can't decode.
+
+```typescript
+interface ModeModelDefaults {
+  /** Model id used in plan mode when nothing is configured. */
+  plan: string
+  /** Model id used in execute mode when nothing is configured. */
+  execute: string
+  /** Model id used for commit-message generation when nothing is configured. */
+  commit: string
+  /** Model id used for conversation compaction when nothing is configured. */
+  compact: string
+}
+```
+
+### Types
+
+#### `AIProviderID`
+
+AI provider identifier.
+
+Maps to the bond category used at runtime (e.g. `bond('ai', 'anthropic', anthropicProvider)`).
+Adding a new provider here means a corresponding AI bond package must exist.
+
+```typescript
+type AIProviderID =
+  | 'anthropic'
+  | 'openai'
+  | 'google'
+  | 'xai'
+  | 'deepseek'
+  | 'meta'
+  | 'moonshot'
+  | 'minimax'
+  | 'alibaba'
+  | 'zhipu'
+  /**
+   * A model served by a USER-configured endpoint + key (bring-your-own AI)
+   * rather than a platform bond. Never appears in the static catalog — hosts
+   * synthesize these definitions at runtime from per-project provider config,
+   * with all prices 0 (the user pays their own provider directly).
+   */
+  | 'custom'
+```
+
+#### `EffortLevel`
+
+A reasoning-effort value — a model's OWN native effort level.
+
+There is no abstract cross-model scale: the value stored on a project and
+sent to the provider IS the model's real level (e.g. `'high'` / `'xhigh'` /
+`'max'` on current Claude models, `'medium'` on Grok, or a scaled
+thinking-budget label like `'16K'` on budget-configurable models). Each model
+declares its own ordered {@link ModelDefinition.supportedEffortLevels}; a
+value that isn't in the active model's set degrades to the nearest one (see
+`model-selection.ts`). Mirrored by the client-side `EffortLevel` in
+`@molecule/app-ai-models`; keep the two in sync. Re-declared (rather than
+imported) by the ide-react and molecule-dev consumers per the cross-stack
+rule, but this catalog is the canonical home.
+
+```typescript
+type EffortLevel = string
+```
+
+### Functions
+
+#### `effectiveModelRegion(modelDef, requested)`
+
+Resolve a model's effective processing region: the requested region when the
+model's {@link ModelDefinition.regions} list offers it, else the model's
+DEFAULT region (the first listed; `'us'` when the catalog omits regions,
+which also covers unknown model ids). A single-entry `regions` list pins the
+model regardless of the request (e.g. a model with no US re-host).
+
+```typescript
+function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?: string): string
+```
+
+- `modelDef` — The model definition (or undefined for unknown ids).
+- `requested` — The user's per-model region choice, if any.
+
+**Returns:** The effective region code.
+
+#### `getAvailableModels(availableProviders)`
+
+Get models that are currently usable — filtered to only providers that are available.
+
+The caller passes in which provider IDs are active (i.e. have a bond wired).
+`disabled` models are excluded — they are never offered for selection.
+
+```typescript
+function getAvailableModels(
+  availableProviders: ReadonlySet<AIProviderID> | readonly AIProviderID[],
+): readonly ModelDefinition[]
+```
+
+- `availableProviders` — Set or array of provider IDs that have active bonds.
+
+**Returns:** Non-disabled models whose provider is in the available set.
+
+#### `getModel(id)`
+
+Look up a model definition by ID.
+
+Returns `disabled` models too: a saved selection or a historical usage row
+may reference a since-retired model, and it must stay priceable. Use
+{@link MODEL_IDS} / {@link getAvailableModels} (which exclude disabled
+models) to decide what is _selectable_.
+
+```typescript
+function getModel(id: string): ModelDefinition | undefined
+```
+
+- `id` — The API model ID.
+
+**Returns:** The model definition, or `undefined` if not found.
+
+#### `getModelsByProvider(provider)`
+
+Get all models for a specific provider.
+
+```typescript
+function getModelsByProvider(provider: AIProviderID): readonly ModelDefinition[]
+```
+
+- `provider` — The provider ID.
+
+**Returns:** Array of model definitions for that provider.
+
+#### `list(_req, res)`
+
+Returns models whose `provider` has a bond registered under the `'ai'`
+category. When no AI providers are bonded the response is `{ models: [] }`,
+which signals a misconfigured server rather than masking the issue.
+
+Fails closed with `401` when there is no authenticated session, so the model
+catalog is never disclosed to an unauthenticated caller even if the route's
+`'authenticate'` middleware is dropped by codegen.
+
+```typescript
+function list(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>
+```
+
+- `_req` — The request object (unused).
+- `res` — The response object.
+
+#### `modelRegionRates(modelDef, requested)`
+
+The token rates for a model in a given processing region: the model's
+{@link ModelDefinition.regionPricing} override for the region when one
+exists, else the base rates (the native provider's list prices). Omitted
+cache fields in an override fall back to the override's input price (hosts
+with no cache discount / no write premium). The region is resolved via
+{@link effectiveModelRegion}, so callers may pass the raw user choice.
+
+```typescript
+function modelRegionRates(modelDef: ModelDefinition, requested?: string): ModelTokenRates
+```
+
+- `modelDef` — The model definition.
+- `requested` — The user's per-model region choice, if any.
+
+**Returns:** The region-effective rates.
+
+#### `priceMultiplierAt(modelDef, at)`
+
+The price multiplier in effect for a model at a given instant.
+
+Consults the model's {@link ModelDefinition.peakPricing} windows (UTC,
+half-open, may wrap midnight). Metering MUST call this with each request's
+own timestamp so peak-hour usage bills at the provider's real rate — pricing
+everything at the flat rate silently under-meters peak traffic.
+
+```typescript
+function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): number
+```
+
+- `modelDef` — The model definition (or undefined).
+- `at` — The instant the request was made.
+
+**Returns:** The multiplier (`1` outside peak windows or when none are declared).
+
+### Constants
+
+#### `MODEL_IDS`
+
+Set of _selectable_ model IDs for fast validation.
+
+Excludes `disabled` models so a retired model (e.g. `grok-code-fast-1`) can
+never be chosen for a new chat, while {@link getModel} still resolves it for
+historical pricing.
+
+```typescript
+const MODEL_IDS: ReadonlySet<string>
+```
+
+#### `MODELS`
+
+All available AI models, grouped by provider, ordered from most to least capable.
+
+To add or remove a model, edit this array. Both the server-side validation
+and the public discovery endpoint will update automatically.
+
+Effort is each model's OWN native value — there is no abstract scale (see
+{@link ModelDefinition.supportedEffortLevels}):
+
+- A model driven by a provider-native effort/level param lists its provider
+  values verbatim in `supportedEffortLevels` (ascending), with
+  `defaultEffortLevel` = the provider's default/recommended level for agentic
+  coding. NO `effortBudgetTokens`.
+- A model with a controllable token budget but no native level names (e.g.
+  Claude Haiku 4.5's `budget_tokens`, Qwen's `thinking_budget`) lists
+  scaled-budget labels (`['4K', '8K', '16K', '32K']`) with `effortBudgetTokens`
+  mapping each label to the token budget it sends.
+- A model whose reasoning is fixed (always-on or on/off only, no depth
+  control) carries `thinkingConfigurable: false` and OMITS both fields —
+  there is nothing to tune.
+
+Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
+2026-07-30 GPT-5.6 repricing — cross-check prices against models.dev with
+`npm run check:model-freshness` from the workspace root):
+
+- Anthropic: https://platform.claude.com/docs/en/about-claude/models/overview
+  - /docs/en/build-with-claude/effort (fable-5 / opus-5 / sonnet-5 current;
+    opus-4-8 superseded by opus-5 at identical pricing but still served — it is
+    the recommended refusal-fallback model; effort ladder on all three current
+    models is low|medium|high|xhigh|max; budget_tokens 400s on 4.7+)
+    (re-verified 2026-08-06: added opus-4-7 — legacy but Active, $5/$25,
+    cache $0.50/$6.25, 1M ctx / 128K out per the overview + pricing pages;
+    models.dev first listed it 2026-08-06)
+- OpenAI: https://developers.openai.com/api/docs/pricing (GPT-5.6 family GA
+  2026-07-09; REPRICED 2026-07-30: -luna cut 80% to $0.20/$1.20, -terra cut
+  20% to $2/$12, -sol unchanged $5/$30; cache read 0.1× input; gpt-5.5/
+  gpt-5.4 still listed as current; long-context 2× variants exist upstream —
+  not modeled, same as the Gemini/Grok tiers; Sol "Fast mode" 2.5× speed at
+  2× price announced 2026-07-30 — not yet modeled)
+- Google: https://ai.google.dev/gemini-api/docs/pricing (gemini-3.6-flash GA
+  2026-07-21 $1.50/$7.50 supersedes 3.5-flash as the agentic flagship;
+  gemini-3.1-pro-preview still the pro tier — "3.5 Pro" has NOT shipped as
+  of 2026-07-28 despite the coming-soon badge; do not add until it has an id)
+- xAI: https://docs.x.ai/developers/models + /developers/grok-4-5
+  (grok-4.5 flagship 2026-07-08: $2/$6, 500K ctx, ≥200K prompts bill 2× —
+  not modeled; reasoning_effort low|medium|high default high, image input;
+  grok-4.3 still served at $1.25/$2.50 with the bigger 1M window;
+  grok-code-fast-1 no longer listed — retires 2026-08-15)
+- DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (unchanged V4
+  Pro/Flash pricing; legacy deepseek-chat/-reasoner ids fully retired
+  2026-07-24 — never in this catalog; the announced peak-hour 2× surcharge is
+  still NOT active as of 2026-07-28, see the entries)
+- Moonshot: https://platform.kimi.ai/docs/models (kimi-k3 flagship 2026-07-16
+  — 2.8T MoE, 1M ctx, $3/$15 — NOT added: thinking is forced-on with
+  reasoning_content that must be replayed through tool loops, the same
+  constraint that keeps kimi-k2.7-code out; add BOTH once the moonshot bond
+  supports preserved thinking + reasoning_effort low|high|max. kimi-k2.6
+  remains the newest model the bond can run correctly.)
+- MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
+  minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
+- Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
+  (qwen3.8-max GA'd 2026-08-03 on the pay-as-you-go international API and is
+  IN the catalog — verified 2026-08-04: flat $2/$6 per MTok on
+  help.aliyun.com/en/model-studio/model-pricing (Singapore International
+  CNY 14.988/44.965 at the same fixed conversion that maps qwen3.7-max's
+  CNY 18.736/56.207 to its $2.50/$7.50 list), 1M ctx, hybrid thinking,
+  tools. Cache rates come from the ZH context-cache doc
+  (help.aliyun.com/zh/model-studio/context-cache), which lists qwen3.8-max
+  as supported in every region under the unconditional standard table
+  (implicit: hit 20% of input, creation 100%; explicit: hit 10%, creation
+  125%) — the EN edition of that doc simply lags (zero qwen3.8 mentions),
+  which an earlier pass misread as "excepted/console-only". qwen3.7-max
+  still runs its 50%-off promo — billed here at list, $2.50/$7.50)
+- Zhipu: https://docs.z.ai/guides/overview/pricing (unchanged; glm-5.2 is
+  the newest — "GLM-5.3/5.5" rumors have no released ids as of 2026-07-28)
+
+Knowledge-cutoff dates on non-Anthropic entries are best-effort estimates
+where the provider doesn't publish one; the provider sources above verify
+id / pricing / context window.
+
+```typescript
+const MODELS: readonly ModelDefinition[]
+```
+
+#### `requestHandlerMap`
+
+Map of request handlers for the AI model catalog routes.
+
+```typescript
+const requestHandlerMap: { readonly list: typeof list }
+```
+
+#### `routes`
+
+Route array for the AI model catalog: GET list of available models.
+
+```typescript
+const routes: readonly [
+  {
+    readonly method: 'get'
+    readonly path: '/ai/models'
+    readonly handler: 'list'
+    readonly middlewares: readonly ['authenticate']
+  },
+]
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-i18n` ^1.0.1
+- `@molecule/api-resource` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-i18n`
+- `@molecule/api-resource`
+
+- **No database, no migration — the catalog is code.** Add/retire models by
+  editing `models.ts`; validation (`MODEL_IDS`) and the discovery endpoint
+  update automatically.
+- **`GET /ai/models` only lists models whose provider is BONDED.** The handler
+  intersects `MODELS` with the names registered under the `'ai'` bond category,
+  so `bond('ai', '<name>', provider)` names must equal
+  `ModelDefinition.provider` ids. An empty `{ models: [] }` response means no
+  AI bond is wired — fix the wiring; never hardcode a model list client-side.
+- **Disabled models stay resolvable on purpose.** `getModel(id)` returns
+  retired models so historical usage still prices correctly; gate what a user
+  may SELECT with `MODEL_IDS` / `getAvailableModels()`, never with `getModel()`.
+- The list handler enforces authentication in-handler (fails closed 401) — if
+  you fork it, keep that check; route middleware alone can be stripped by
+  codegen.

package/dist/models.d.ts

@@ -36,6 +36,9 @@ import type { ModelDefinition } from './types.js';
  *   opus-4-8 superseded by opus-5 at identical pricing but still served — it is
  *   the recommended refusal-fallback model; effort ladder on all three current
  *   models is low|medium|high|xhigh|max; budget_tokens 400s on 4.7+)
+ *   (re-verified 2026-08-06: added opus-4-7 — legacy but Active, $5/$25,
+ *   cache $0.50/$6.25, 1M ctx / 128K out per the overview + pricing pages;
+ *   models.dev first listed it 2026-08-06)
  * - OpenAI: https://developers.openai.com/api/docs/pricing (GPT-5.6 family GA
  *   2026-07-09; REPRICED 2026-07-30: -luna cut 80% to $0.20/$1.20, -terra cut
  *   20% to $2/$12, -sol unchanged $5/$30; cache read 0.1× input; gpt-5.5/
@@ -64,9 +67,18 @@ import type { ModelDefinition } from './types.js';
  * - MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
  *   minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
  * - Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
- *   (unchanged; qwen3.8-max-preview, 2026-07-19, is Token-Plan-subscriber-only
- *   — not on the pay-as-you-go API, so it cannot be added yet; qwen3.7-max
- *   currently runs a 50%-off promo — still billed here at list, $2.50/$7.50)
+ *   (qwen3.8-max GA'd 2026-08-03 on the pay-as-you-go international API and is
+ *   IN the catalog — verified 2026-08-04: flat $2/$6 per MTok on
+ *   help.aliyun.com/en/model-studio/model-pricing (Singapore International
+ *   CNY 14.988/44.965 at the same fixed conversion that maps qwen3.7-max's
+ *   CNY 18.736/56.207 to its $2.50/$7.50 list), 1M ctx, hybrid thinking,
+ *   tools. Cache rates come from the ZH context-cache doc
+ *   (help.aliyun.com/zh/model-studio/context-cache), which lists qwen3.8-max
+ *   as supported in every region under the unconditional standard table
+ *   (implicit: hit 20% of input, creation 100%; explicit: hit 10%, creation
+ *   125%) — the EN edition of that doc simply lags (zero qwen3.8 mentions),
+ *   which an earlier pass misread as "excepted/console-only". qwen3.7-max
+ *   still runs its 50%-off promo — billed here at list, $2.50/$7.50)
  * - Zhipu: https://docs.z.ai/guides/overview/pricing (unchanged; glm-5.2 is
  *   the newest — "GLM-5.3/5.5" rumors have no released ids as of 2026-07-28)
  *

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EA6oCnC,CAAA"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EAmtCnC,CAAA"}

package/dist/models.js

@@ -35,6 +35,9 @@
  *   opus-4-8 superseded by opus-5 at identical pricing but still served — it is
  *   the recommended refusal-fallback model; effort ladder on all three current
  *   models is low|medium|high|xhigh|max; budget_tokens 400s on 4.7+)
+ *   (re-verified 2026-08-06: added opus-4-7 — legacy but Active, $5/$25,
+ *   cache $0.50/$6.25, 1M ctx / 128K out per the overview + pricing pages;
+ *   models.dev first listed it 2026-08-06)
  * - OpenAI: https://developers.openai.com/api/docs/pricing (GPT-5.6 family GA
  *   2026-07-09; REPRICED 2026-07-30: -luna cut 80% to $0.20/$1.20, -terra cut
  *   20% to $2/$12, -sol unchanged $5/$30; cache read 0.1× input; gpt-5.5/
@@ -63,9 +66,18 @@
  * - MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
  *   minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
  * - Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
- *   (unchanged; qwen3.8-max-preview, 2026-07-19, is Token-Plan-subscriber-only
- *   — not on the pay-as-you-go API, so it cannot be added yet; qwen3.7-max
- *   currently runs a 50%-off promo — still billed here at list, $2.50/$7.50)
+ *   (qwen3.8-max GA'd 2026-08-03 on the pay-as-you-go international API and is
+ *   IN the catalog — verified 2026-08-04: flat $2/$6 per MTok on
+ *   help.aliyun.com/en/model-studio/model-pricing (Singapore International
+ *   CNY 14.988/44.965 at the same fixed conversion that maps qwen3.7-max's
+ *   CNY 18.736/56.207 to its $2.50/$7.50 list), 1M ctx, hybrid thinking,
+ *   tools. Cache rates come from the ZH context-cache doc
+ *   (help.aliyun.com/zh/model-studio/context-cache), which lists qwen3.8-max
+ *   as supported in every region under the unconditional standard table
+ *   (implicit: hit 20% of input, creation 100%; explicit: hit 10%, creation
+ *   125%) — the EN edition of that doc simply lags (zero qwen3.8 mentions),
+ *   which an earlier pass misread as "excepted/console-only". qwen3.7-max
+ *   still runs its 50%-off promo — billed here at list, $2.50/$7.50)
  * - Zhipu: https://docs.z.ai/guides/overview/pricing (unchanged; glm-5.2 is
  *   the newest — "GLM-5.3/5.5" rumors have no released ids as of 2026-07-28)
  *
@@ -213,6 +225,40 @@ export const MODELS = [
         cacheWritePricePerMTok: 3.75,
         knowledgeCutoff: '2026-01-01',
     },
+    {
+        id: 'claude-opus-4-7',
+        provider: 'anthropic',
+        label: 'Claude Opus 4.7',
+        description: 'Older Opus — long-horizon agentic work, knowledge work & vision',
+        contextWindow: 1_000_000,
+        maxOutputTokens: 128_000,
+        supportsThinking: true,
+        thinkingBudgetTokens: 16_000,
+        thinkingConfigurable: true,
+        supportedEffortLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
+        defaultEffortLevel: 'high',
+        // Adaptive thinking only — budget_tokens is REJECTED (400); xhigh effort
+        // debuted on this model. Unlike opus-5, omitting `thinking` runs WITHOUT
+        // thinking — set {type:"adaptive"} explicitly. First model on the new
+        // tokenizer (~30% more tokens than 4.6 for the same text).
+        supportsVision: true,
+        supportsPromptCaching: true,
+        supportsTools: true,
+        webSearchToolType: 'web_search_20260209',
+        codeExecutionToolType: 'code_execution_20250825',
+        webFetchToolType: 'web_fetch_20260209',
+        inputPricePerMTok: 5,
+        outputPricePerMTok: 25,
+        // Anthropic 5-minute prompt cache: read 0.1× input, write 1.25× input.
+        cacheReadPricePerMTok: 0.5,
+        cacheWritePricePerMTok: 6.25,
+        knowledgeCutoff: '2026-01-01',
+        // Superseded by claude-opus-4-8 (launched 2026-05-28) at identical pricing;
+        // still Active upstream (deprecations page 2026-08-06: retires no sooner
+        // than 2027-04-16). Selectable under "Older models". NO fast mode —
+        // speed:"fast" on 4.7 returns an error (pricing page, fast-mode section).
+        deprecatedAt: '2026-05-28',
+    },
     {
         id: 'claude-opus-4-6',
         provider: 'anthropic',
@@ -1097,6 +1143,42 @@ export const MODELS = [
     // Prices are DashScope international list rates (the bond calls DashScope,
     // not OpenRouter; a 50%-off promo currently applies — billed at list).
     // ---------------------------------------------------------------------------
+    // qwen3.8-max (GA 2026-08-03) succeeds qwen3.7-max as the agentic flagship,
+    // priced BELOW it at $2/$6 (intl CNY 14.988/44.965, same fixed conversion).
+    // Same hybrid thinking mechanism as the 3.7 series (enable_thinking default
+    // ON + thinking_budget; preserve_thinking supported). Context cache uses the
+    // standard implicit rates — see the Sources block for the ZH-doc citation.
+    {
+        id: 'qwen3.8-max',
+        provider: 'alibaba',
+        label: 'Qwen3.8 Max',
+        description: 'Alibaba agentic flagship — 1M context, hybrid thinking',
+        contextWindow: 1_000_000,
+        // Alibaba's public pages don't state a max-output figure; models.dev says
+        // 131,072 — kept at the 3.7-max figure until the provider publishes one
+        // (understating only shortens completions; overstating would error).
+        maxOutputTokens: 65_536,
+        supportsThinking: true,
+        thinkingBudgetTokens: 8_000,
+        thinkingConfigurable: true,
+        supportedEffortLevels: ['4K', '8K', '16K', '32K'],
+        defaultEffortLevel: '8K',
+        effortBudgetTokens: { '4K': 4000, '8K': 8000, '16K': 16000, '32K': 32000 },
+        // models.dev claims image+video input, but Alibaba's own model catalog
+        // lists qwen3.8-max under text generation (VL remains a separate line) —
+        // false until the provider's page says otherwise.
+        supportsVision: false,
+        supportsPromptCaching: true,
+        supportsTools: true,
+        inputPricePerMTok: 2,
+        outputPricePerMTok: 6,
+        // Implicit context cache: read = 20% of input, no write premium.
+        cacheReadPricePerMTok: 0.4,
+        cacheWritePricePerMTok: 2,
+        regions: ['us', 'cn'],
+        // Not published by Alibaba — best-effort estimate.
+        knowledgeCutoff: '2026-04-01',
+    },
     {
         id: 'qwen3.7-max',
         provider: 'alibaba',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-ai-models",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AI model catalog — server-side source of truth plus an authentication-gated discovery endpoint",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -26,17 +27,17 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@molecule/api-bond": "1.0.0",
-    "@molecule/api-i18n": "1.0.0",
-    "@molecule/api-resource": "1.0.0",
+    "@molecule/api-bond": "1.0.1",
+    "@molecule/api-i18n": "1.0.1",
+    "@molecule/api-resource": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "@molecule/api-bond": "^1.0.0",
-    "@molecule/api-i18n": "^1.0.0",
-    "@molecule/api-resource": "^1.0.0"
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-i18n": "^1.0.1",
+    "@molecule/api-resource": "^1.0.1"
   },
   "peerDependenciesMeta": {
     "@molecule/api-i18n": {