@molecule/api-resource-ai-models 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-resource-ai-models` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-resource-ai-models is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/handlers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './list.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/handlers/index.js

@@ -0,0 +1 @@
+export * from './list.js';

package/dist/handlers/list.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `GET /ai/models` — returns the catalog of available AI models.
+ *
+ * Filters the central `MODELS` list to only those whose provider is currently
+ * bonded under the `'ai'` category AND are not `disabled` (a retired model is
+ * never listed for selection, though `getModel` still prices it). No further
+ * projection is applied — every `ModelDefinition` field is fine to expose to
+ * authenticated clients today.
+ *
+ * Secure-by-default: this handler enforces authentication IN the handler
+ * (`res.locals.session.userId`) and fails closed with `401` for an
+ * unauthenticated request. It does NOT rely on the `'authenticate'` route
+ * middleware alone, because the codegen that emits generated apps can strip
+ * declared middleware — leaving the configured-model catalog (provider mix,
+ * pricing, capabilities) disclosed to anonymous callers. The in-handler check
+ * holds regardless of what happens to the route middleware.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * 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.
+ *
+ * @param _req - The request object (unused).
+ * @param res - The response object.
+ */
+export declare function list(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=list.d.ts.map

package/dist/handlers/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAK/E;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CActF"}

package/dist/handlers/list.js

@@ -0,0 +1,48 @@
+/**
+ * `GET /ai/models` — returns the catalog of available AI models.
+ *
+ * Filters the central `MODELS` list to only those whose provider is currently
+ * bonded under the `'ai'` category AND are not `disabled` (a retired model is
+ * never listed for selection, though `getModel` still prices it). No further
+ * projection is applied — every `ModelDefinition` field is fine to expose to
+ * authenticated clients today.
+ *
+ * Secure-by-default: this handler enforces authentication IN the handler
+ * (`res.locals.session.userId`) and fails closed with `401` for an
+ * unauthenticated request. It does NOT rely on the `'authenticate'` route
+ * middleware alone, because the codegen that emits generated apps can strip
+ * declared middleware — leaving the configured-model catalog (provider mix,
+ * pricing, capabilities) disclosed to anonymous callers. The in-handler check
+ * holds regardless of what happens to the route middleware.
+ *
+ * @module
+ */
+import { getAll } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+import { MODELS } from '../models.js';
+/**
+ * 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.
+ *
+ * @param _req - The request object (unused).
+ * @param res - The response object.
+ */
+export async function list(_req, res) {
+    const userId = res.locals.session?.userId;
+    if (!userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return;
+    }
+    const bondedProviders = new Set(getAll('ai').keys());
+    const models = MODELS.filter((m) => bondedProviders.has(m.provider) && !m.disabled);
+    const response = { models: [...models] };
+    res.json(response);
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```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)
+ * ```
+ *
+ * @remarks
+ * - **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.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './handlers/index.js';
+export * from './lookup.js';
+export * from './models.js';
+export * from './requestHandlerMap.js';
+export * from './routes.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```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)
+ * ```
+ *
+ * @remarks
+ * - **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.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './handlers/index.js';
+export * from './lookup.js';
+export * from './models.js';
+export * from './requestHandlerMap.js';
+export * from './routes.js';
+export * from './types.js';

package/dist/lookup.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Lookups over the AI model catalog.
+ *
+ * @module
+ */
+import type { AIProviderID, ModelDefinition } from './types.js';
+/**
+ * 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.
+ */
+export declare const MODEL_IDS: ReadonlySet<string>;
+/**
+ * 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*.
+ *
+ * @param id - The API model ID.
+ * @returns The model definition, or `undefined` if not found.
+ */
+export declare function getModel(id: string): ModelDefinition | undefined;
+/**
+ * Get all models for a specific provider.
+ *
+ * @param provider - The provider ID.
+ * @returns Array of model definitions for that provider.
+ */
+export declare function getModelsByProvider(provider: AIProviderID): readonly ModelDefinition[];
+/**
+ * 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.
+ *
+ * @param availableProviders - Set or array of provider IDs that have active bonds.
+ * @returns Non-disabled models whose provider is in the available set.
+ */
+export declare function getAvailableModels(availableProviders: ReadonlySet<AIProviderID> | readonly AIProviderID[]): readonly ModelDefinition[];
+/**
+ * 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.
+ *
+ * @param modelDef - The model definition (or undefined).
+ * @param at - The instant the request was made.
+ * @returns The multiplier (`1` outside peak windows or when none are declared).
+ */
+export declare function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date): number;
+/**
+ * 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).
+ *
+ * @param modelDef - The model definition (or undefined for unknown ids).
+ * @param requested - The user's per-model region choice, if any.
+ * @returns The effective region code.
+ */
+export declare function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?: string): string;
+/** The four per-MTok token rates a turn bills at (USD). */
+export 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;
+}
+/**
+ * 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.
+ *
+ * @param modelDef - The model definition.
+ * @param requested - The user's per-model region choice, if any.
+ * @returns The region-effective rates.
+ */
+export declare function modelRegionRates(modelDef: ModelDefinition, requested?: string): ModelTokenRates;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAEzC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,eAAe,EAAE,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,SAAS,YAAY,EAAE,GACtE,SAAS,eAAe,EAAE,CAI5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAYzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAGR;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,qBAAqB,EAAE,MAAM,CAAA;IAC7B,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,eAAe,CAiB/F"}

package/dist/lookup.js

@@ -0,0 +1,121 @@
+/**
+ * Lookups over the AI model catalog.
+ *
+ * @module
+ */
+import { MODELS } from './models.js';
+/**
+ * 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.
+ */
+export const MODEL_IDS = new Set(MODELS.filter((m) => !m.disabled).map((m) => m.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*.
+ *
+ * @param id - The API model ID.
+ * @returns The model definition, or `undefined` if not found.
+ */
+export function getModel(id) {
+    return MODELS.find((m) => m.id === id);
+}
+/**
+ * Get all models for a specific provider.
+ *
+ * @param provider - The provider ID.
+ * @returns Array of model definitions for that provider.
+ */
+export function getModelsByProvider(provider) {
+    return MODELS.filter((m) => m.provider === provider);
+}
+/**
+ * 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.
+ *
+ * @param availableProviders - Set or array of provider IDs that have active bonds.
+ * @returns Non-disabled models whose provider is in the available set.
+ */
+export function getAvailableModels(availableProviders) {
+    const providerSet = availableProviders instanceof Set ? availableProviders : new Set(availableProviders);
+    return MODELS.filter((m) => providerSet.has(m.provider) && !m.disabled);
+}
+/**
+ * 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.
+ *
+ * @param modelDef - The model definition (or undefined).
+ * @param at - The instant the request was made.
+ * @returns The multiplier (`1` outside peak windows or when none are declared).
+ */
+export function priceMultiplierAt(modelDef, at) {
+    const peak = modelDef?.peakPricing;
+    if (!peak || peak.windows.length === 0)
+        return 1;
+    const minute = at.getUTCHours() * 60 + at.getUTCMinutes();
+    for (const w of peak.windows) {
+        const inWindow = w.startMinuteUtc <= w.endMinuteUtc
+            ? minute >= w.startMinuteUtc && minute < w.endMinuteUtc
+            : minute >= w.startMinuteUtc || minute < w.endMinuteUtc;
+        if (inWindow)
+            return peak.multiplier;
+    }
+    return 1;
+}
+/**
+ * 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).
+ *
+ * @param modelDef - The model definition (or undefined for unknown ids).
+ * @param requested - The user's per-model region choice, if any.
+ * @returns The effective region code.
+ */
+export function effectiveModelRegion(modelDef, requested) {
+    const regions = modelDef?.regions ?? ['us'];
+    return requested && regions.includes(requested) ? requested : regions[0];
+}
+/**
+ * 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.
+ *
+ * @param modelDef - The model definition.
+ * @param requested - The user's per-model region choice, if any.
+ * @returns The region-effective rates.
+ */
+export function modelRegionRates(modelDef, requested) {
+    const region = effectiveModelRegion(modelDef, requested);
+    const override = modelDef.regionPricing?.[region];
+    if (!override) {
+        return {
+            inputPricePerMTok: modelDef.inputPricePerMTok,
+            outputPricePerMTok: modelDef.outputPricePerMTok,
+            cacheReadPricePerMTok: modelDef.cacheReadPricePerMTok,
+            cacheWritePricePerMTok: modelDef.cacheWritePricePerMTok,
+        };
+    }
+    return {
+        inputPricePerMTok: override.inputPricePerMTok,
+        outputPricePerMTok: override.outputPricePerMTok,
+        cacheReadPricePerMTok: override.cacheReadPricePerMTok ?? override.inputPricePerMTok,
+        cacheWritePricePerMTok: override.cacheWritePricePerMTok ?? override.inputPricePerMTok,
+    };
+}

package/dist/models.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Available AI models.
+ *
+ * This is the single source of truth for which models Synthase can use.
+ * Server-side code (chat handler, compaction) consumes the full definitions
+ * directly; clients receive the `PublicModel` projection from `GET /ai/models`.
+ *
+ * @module
+ */
+import type { ModelDefinition } from './types.js';
+/**
+ * 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+)
+ * - 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
+ *   (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)
+ * - 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.
+ */
+export declare const MODELS: readonly ModelDefinition[];
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +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"}