@prismshadow/penguin-server 0.2.15 → 0.2.17

package/dist/machine-status.js

@@ -1,12 +1,12 @@
 import {
   MachinesRepo
-} from "./chunk-HMTT2PX4.js";
+} from "./chunk-2LZDP26O.js";
 import {
   liveServerLock
 } from "./chunk-GOO5VUAB.js";
 import {
   openDatabaseReadOnly
-} from "./chunk-NVWAYYRX.js";
+} from "./chunk-HPOHMZCH.js";
 import "./chunk-B5IP37ZQ.js";
 
 // src/machine-status.ts

package/dist/model-catalog.d.ts

@@ -0,0 +1,610 @@
+import { ModelPricing, ModelRef, ProviderTable, ModelEntry } from '@prismshadow/penguin-core';
+import { ModelCredentialShape, ProviderConnectionShape } from '@prismshadow/penguin-core/model-connection';
+export { routedClientType } from '@prismshadow/mmsp/credentials';
+
+/** Model provider info (used for web grouping/logo and the "API key blank falls back to env var" hint). */
+/**
+ * A provider that mints API keys through an authorization page instead of a console visit.
+ * Present only on providers that publish such a flow; its absence is what makes the harness
+ * refuse to start one.
+ */
+interface ModelProviderOAuth {
+    /** Authorization page the user is sent to; the flow's parameters ride on its query string. */
+    authorizeUrl: string;
+    /** Endpoint that trades an authorization code for a newly minted key. */
+    exchangeUrl: string;
+    /** Name recorded on the minted key, and the app name the authorization page displays. */
+    keyName: string;
+}
+/**
+ * A group whose credential the App obtains through its own authorization flow rather than by
+ * asking the vendor: the client registers a one-time code and device secret with an external
+ * bridge, sends the user to the page that bridge hands back, and polls until the bridge
+ * delivers the credential. Distinct from `oauth`, where the App itself speaks the vendor's
+ * PKCE page — here the App never reaches the vendor at all, because the bridge holds the
+ * client secret that conversation would need.
+ *
+ * The bridge's own address is deliberately NOT here: this file is bundled for the browser and
+ * cannot read configuration, so the App resolves the bridge server-side from its environment
+ * (PENGUIN_GO_ORIGIN / MODELSCOPE_BRIDGE_URL), keyed by the group's id.
+ */
+interface ModelProviderBridgeAuth {
+    /**
+     * Which App-side flow serves this group — one route family and one service per value, so
+     * the Web App picks from the group's descriptor rather than from its id.
+     */
+    flow: "penguin-go" | "modelscope";
+}
+/**
+ * An account-balance endpoint the vendor publishes, called with the group's own API key as a
+ * Bearer token. The server makes that call (the key never reaches the browser); the endpoint
+ * is the vendor's, like the OAuth one above, so it can live in this browser-bundled file.
+ */
+interface ModelProviderBalance {
+    /** GET endpoint answering the balance of the account the key belongs to. */
+    url: string;
+    /**
+     * How to read the answer, one reader per published response shape:
+     * - `tokendance`: `{ balance: { credits, credits_used, balance } }`, integers in micro-yuan
+     *   (1 CNY = 1,000,000);
+     * - `deepseek`: `{ is_available, balance_infos: [{ currency, total_balance, … }] }`, one entry
+     *   per currency the account holds.
+     * - `penguin-go`: `{ balance: { units, currency } }`, a CNY ledger integer in 10^-12 yuan.
+     */
+    format: "tokendance" | "deepseek" | "penguin-go";
+}
+interface ModelProviderInfo {
+    id: string;
+    /** Display name (brand name, shared by Chinese and English UI). */
+    label: string;
+    /**
+     * API key env var name: the variable MMSP's client for this group's rows reads when handed no
+     * key, which it does only for its own default endpoint (PRN-021, MMSP's rule). A gateway group
+     * records OPENAI_* because that is what its generic client reads, and its rows carry the
+     * gateway's base URL, so that client never reads it for them.
+     */
+    envKey: string;
+    /** base URL env var name. */
+    envBaseUrlKey: string;
+    /** Console URL for obtaining an API key (frontend links it beside the API key field of the group key dialog and the model dialog); none for custom. */
+    apiKeyUrl?: string;
+    /** Vendor's model list / docs page URL (frontend's "add model" dialog links this as "get model id"); none for custom. */
+    modelsUrl?: string;
+    /**
+     * Gateway's OpenAI-compatible endpoint (openrouter / siliconflow / qwen-token-plan / …): what
+     * a new Project writes as the group's `[providers.<id>]` base URL (catalogGroupConnection),
+     * so every row of the group — a model added by hand included — follows it without storing
+     * the address itself. A reference value: nothing reads it when a request is built. Left
+     * blank for direct vendors, custom and vLLM (whose rows name the local server's address).
+     */
+    gatewayBaseUrl?: string;
+    /**
+     * Authorization flow that mints a key for the user (see ModelProviderOAuth); absent for
+     * every provider whose keys are only obtainable from its console.
+     */
+    oauth?: ModelProviderOAuth;
+    /**
+     * The App-side authorization flow that obtains this group's credential (see
+     * ModelProviderBridgeAuth); absent for every group whose credential comes from a console or
+     * from the vendor's own page. Declaring it is what puts the "authorize a key" action on the
+     * group in the Web App.
+     */
+    bridgeAuth?: ModelProviderBridgeAuth;
+    /**
+     * The vendor's account-balance endpoint (see ModelProviderBalance); absent for every group
+     * whose vendor publishes none. Declaring it is what puts the balance in the group's header.
+     */
+    balance?: ModelProviderBalance;
+    /**
+     * The group takes models the user adds by hand: `custom` and vLLM, whose rows point at an
+     * endpoint the catalog cannot know, and the four gateways whose catalogs list a fraction of
+     * what they serve — OpenRouter, TokenDance, SiliconFlow and Atlas Cloud — where an added
+     * model follows the group's connection (its endpoint, key and protocol) exactly as the
+     * presets do. Every other built-in group carries its catalog presets and the rows it already
+     * stores, and nothing else. Read it through isAddableGroup, which also answers for
+     * user-defined groups.
+     */
+    addable?: boolean;
+    /**
+     * The MMSP protocol EVERY entry in this group speaks, models the user adds included.
+     *
+     * Set it where the group itself decides the answer for a row the catalog does not list:
+     * every group that takes hand-added models and speaks one protocol (vLLM, OpenRouter,
+     * TokenDance, SiliconFlow, Atlas Cloud). The other gateways hold catalog rows only, each
+     * carrying its own pin, and `custom` / user-defined groups deliberately declare nothing —
+     * their whole point is that the protocol is detected from the endpoint or picked by hand,
+     * and a pin here would take that choice away.
+     *
+     * Where it IS set, a new Project writes it as the group's `[providers.<id>]` protocol
+     * (catalogGroupConnection), and the rows — models added by hand included — follow that
+     * table. A reference value like gatewayBaseUrl: what the app reads at runtime is the file's
+     * table. Read it through providerClientType rather than reaching for the field.
+     */
+    clientType?: string;
+    /**
+     * The group the product recommends, captioned as such on the models page. It marks the
+     * GROUP, not a position: a user who drags the group elsewhere keeps the caption with it,
+     * and the default sequence below is what places it first for everyone else.
+     */
+    recommended?: boolean;
+}
+/** A single built-in model's catalog entry (`modelId` is the upstream id; paired with `provider` it forms the catalog's unique key). */
+interface ModelCatalogEntry {
+    modelId: string;
+    displayName: string;
+    /** Provider id (one of MODEL_PROVIDERS). */
+    provider: string;
+    contextWindow?: number;
+    pricing?: ModelPricing;
+    /**
+     * Fraction off the list price the seller is currently running (0.5 = 50% off), applied to
+     * every bucket. `pricing` stays the LIST price whatever promotion is live, so a lapsed
+     * promotion is one field to delete rather than three numbers to reconstruct;
+     * effectivePricing is the rate actually billed. A Project stores the list price too: the
+     * fraction is seeded beside it as a promotion (presetPromotions), which the cost center
+     * applies when it prices usage, so it charges what the seller charges.
+     */
+    discount?: number;
+    /**
+     * A discount that is only live outside a weekly set of peak windows — a vendor billing
+     * cheaper off-hours. `pricing` holds the PEAK price, the one billed inside the windows, and
+     * the rate applies everywhere else.
+     *
+     * Like `discount`, this one is never baked into a Project, and here there is no choice: it
+     * changes twice a day. `presetModelEntries` writes the peak price and the rate is applied
+     * when a price is read.
+     * A number on disk that silently meant something different at 09:00 than at 08:00 would be
+     * unreadable, and re-syncing presets would rewrite prices by the clock. A seller that also
+     * takes something off on top of the schedule, in both tiers, declares it in `discount`: it is
+     * seeded like any promotion, and the two multiply, as a Project's promotion and schedule do
+     * wherever a price is read.
+     */
+    offPeakDiscount?: OffPeakDiscount;
+    /** Whether image input (vision modality) is supported. */
+    supportsVision: boolean;
+    /** MMSP client type: required when an id cannot be auto-routed or a shared protocol must be pinned. */
+    clientType?: string;
+    /**
+     * Preset base URL, so only an API key is required. A new Project stores it once: on the
+     * group's `[providers.<id>]` table when it is the group's endpoint (catalogGroupConnection),
+     * else on the row itself (catalogModelEntry). Never read when a request is built.
+     */
+    baseUrl?: string;
+    /**
+     * No longer a preset (superseded or withdrawn), but saved Projects still carry it: a
+     * row a Project has is never deleted by "Add new models", and several of these were the
+     * default model of new Projects. A retired row is not a preset — `presetModelEntries` and
+     * `presetPromotions` skip it, so a new Project never gets it or a promotion for it, a sync
+     * never adds it, and "Restore defaults" deletes it with every other row that is not a preset —
+     * but it is still in `catalogModelEntries`, and lookups by `(provider, modelId)` still find
+     * it. Projects carrying it keep its display name and vision flag, and their usage on it is
+     * priced on its off-peak schedule whenever the row stores the catalog's price: the tier only
+     * applies to that price. The schedule is the part that matters: cost is priced when it is
+     * read, so deleting a scheduled row would reprice every off-peak record already on those
+     * Projects at the peak rate.
+     *
+     * Compatibility, not catalog data: remove a retired row only after its seller has stopped
+     * accepting the id AND the release notes have told users that usage recorded on it will be
+     * priced without its schedule from then on. Whoever does the catalog refresh that finds the
+     * id rejected makes that call.
+     */
+    retired?: true;
+    /**
+     * This row is, or once was, the default model of new Projects (PRESET_DEFAULT_MODEL). Usage
+     * recorded on it stays priced after a Project stops storing the row — "Restore defaults"
+     * deletes every row that is not a preset, retired ones included, and a former default is
+     * often most of an older Project's history: retainedCatalogPricing gives the cost path this
+     * row's `pricing` for it. Moving the default sets this on the new row and leaves it on the
+     * old one, which also keeps the old row in the catalog (retired once it stops being a preset)
+     * for as long as anyone may have recorded usage on it.
+     */
+    wasDefault?: true;
+}
+declare const PENGUIN_GO_BASE_URL = "https://go.penguin.ooo/api/v1";
+/** Provider id for the preconfigured Penguin Go relay group. */
+declare const PENGUIN_GO_PROVIDER_ID = "penguin-go";
+/**
+ * The protocol a group is fixed to, or undefined where the group's protocol is the user's to
+ * choose. Penguin Go's platform endpoint speaks MMSP alone, so neither its group nor its rows
+ * offer a protocol: the Web App shows MMSP without a picker, and the server's model writes and
+ * the CLI refuse any other value (fixedClientTypeRefuses).
+ */
+declare function fixedClientType(providerId: string): string | undefined;
+/**
+ * Whether writing `next` as the protocol of a group (`target: "group"`) or of one of its rows
+ * (`"row"`) is refused because the group's protocol is fixed (fixedClientType). `next` is the
+ * value written, blank or absent for none; `stored` is what that group, or that same row in that
+ * same group, stores now.
+ *
+ * The fixed protocol is always accepted, and so is `stored` written back unchanged: a row a user
+ * pointed at their own proxy on another protocol before the protocol was fixed (left alone by
+ * migratePenguinGoRoutes) keeps it, and a whole-table save carrying it is not refused. A row
+ * with no protocol of its own follows its group, so clearing a row's is accepted; clearing the
+ * group's would leave its rows routed by model id, and is refused.
+ */
+declare function fixedClientTypeRefuses(providerId: string, target: "group" | "row", next: string | null | undefined, stored: string | undefined): boolean;
+/** Provider id for the ModelScope group. */
+declare const MODELSCOPE_PROVIDER_ID = "modelscope";
+/**
+ * Provider list (web model page groups in this order BY DEFAULT — a user's dragged
+ * arrangement is stored per Project and wins over this sequence; see the web's
+ * model-group-order.ts). The sequence is a hand-curated display order: TokenDance leads as
+ * the recommended group, Penguin Go follows, then OpenCode Go, then DeepSeek as the default
+ * model's provider, and custom
+ * (custom OpenAI-protocol models) is always last; in between, gateways and first-party
+ * vendors are interleaved by expected use rather than sorted by kind. Only this default
+ * moves when the curation changes: a Project that has ever reordered its groups has every
+ * key stored already, so it keeps the arrangement its user built.
+ *
+ * The eight gateway groups — OpenRouter, Fireworks AI, SiliconFlow, Atlas Cloud, TokenDance,
+ * OpenCode Go, Qwen Pay-As-You-Go and Qwen Token Plan — reach their models through MMSP's generic
+ * protocol clients (`openai-responses` for OpenRouter, `openai-chat` for the rest, and all
+ * three generic clients within OpenCode Go). Those clients read the vendor variables
+ * (**OPENAI_API_KEY / OPENAI_BASE_URL**, and ANTHROPIC_* for OpenCode Go's `ant-messages`
+ * rows) when the credential is blank, not the gateway's own variable names, so every gateway
+ * group records the OPENAI_* pair as the fact it is. A new Project writes each gateway's base
+ * URL on its group, so MMSP refuses a keyless gateway row rather than reading a variable: the
+ * variable holds the user's OpenAI (or Anthropic) key, and a gateway is neither. ModelScope
+ * also records the OPENAI_* pair; its group credential is an api-inference access token taken
+ * from the config alone.
+ */
+declare const MODEL_PROVIDERS: ModelProviderInfo[];
+/**
+ * A weekly peak/off-peak billing schedule, written in a fixed-offset zone.
+ *
+ * Only fixed offsets are expressible, which is the whole of what the catalog needs: the vendors
+ * that bill this way publish their windows in a single national zone that does not observe DST
+ * (Beijing is UTC+8 year round). A vendor on a DST zone would need a real tz database, and the
+ * honest move then is to add one rather than to approximate.
+ */
+interface OffPeakDiscount {
+    /** Fraction off the peak price outside the windows below (0.5 = half price). */
+    rate: number;
+    /** Minutes east of UTC the windows are written in (Beijing = 480). */
+    utcOffsetMinutes: number;
+    /** Days the windows apply to, ISO numbering: 1 = Monday … 7 = Sunday. Days not listed are off-peak all day. */
+    peakDays: readonly number[];
+    /** Peak windows as [startHour, endHour) in the zone's local hours — end-exclusive, so 12:00 is already off-peak. */
+    peakHours: readonly (readonly [number, number])[];
+}
+/**
+ * Whether `now` falls outside every peak window, i.e. whether the discount is live.
+ *
+ * Computed in UTC arithmetic rather than through the host's local time: the schedule belongs to
+ * the vendor's zone, and a server in Los Angeles must reach the same answer as one in Shanghai.
+ */
+declare function offPeakAt(schedule: OffPeakDiscount, now: Date): boolean;
+/** DeepSeek's official off-peak tier: half price outside Beijing weekday 09:00–12:00 and 14:00–18:00. */
+declare const DEEPSEEK_OFF_PEAK: OffPeakDiscount;
+/**
+ * Qwen's off-peak tier on the time-banded models it sells (www.qianwenai.com/models/<id>, read
+ * 2026-09-16): half price from 22:00 to 08:00 Beijing time, every day of the week, and the peak
+ * price at every other hour. Each model page shows the two tiers as separate price tabs, and
+ * every bucket's off-peak figure is exactly half its peak one.
+ */
+declare const QWEN_OFF_PEAK: OffPeakDiscount;
+/**
+ * The catalog's time-based schedules, each with the references that carry it.
+ *
+ * The cost center needs this to split an aggregation by tier before it prices anything: the
+ * rate a request ran at is a fact about when it ran, and only the catalog knows which rows have
+ * two rates at all. Grouped by schedule so a second vendor's windows cost one entry, not a
+ * second query.
+ */
+declare function offPeakScheduledRefs(): Array<{
+    schedule: OffPeakDiscount;
+    refs: Array<{
+        provider: string;
+        modelId: string;
+    }>;
+}>;
+/**
+ * What the seller actually bills for an entry at `now`: its list `pricing` less any running
+ * `discount` and any live off-peak tier, the two multiplied, on every bucket. Rounded to the six
+ * decimals cny() already stores at, so a promotional rate reads as a price rather than as a
+ * float artifact. An entry with nothing off (or no pricing at all) is returned untouched.
+ *
+ * Nothing writes this rate into a Project: `presetModelEntries` writes the list price (a
+ * scheduled row's peak price), a flat promotion is stored beside it as a fraction, and which
+ * tier a request ran in is decided from that request's own timestamp when the usage is
+ * aggregated.
+ */
+declare function effectivePricing(entry: ModelCatalogEntry, now?: Date): ModelPricing | undefined;
+/**
+ * Built-in model catalog, clustered by provider. Within each provider, entries are in
+ * dictionary order by model id, except that newer versions of the same series come first
+ * (e.g. gpt-5.6-* before gpt-5.5, claude-opus-4.8 before 4.7, glm-5.2 before glm-5). The
+ * order is precomputed by hand right here — no runtime sorting anywhere.
+ *
+ * The clusters run in their own sequence, which is the row order a new Project's
+ * `[[models]]` table is written in. It is not MODEL_PROVIDERS' display order and does not
+ * have to track it: nothing renders a catalog row outside its provider group, and the page
+ * takes the group sequence from MODEL_PROVIDERS.
+ */
+declare const MODEL_CATALOG: ModelCatalogEntry[];
+/** Looks up a catalog entry by (provider, upstream id) pair (**the sole catalog-matching entry point**); returns undefined if not in the catalog. */
+declare function catalogEntryFor(provider: string, upstreamId: string): ModelCatalogEntry | undefined;
+/** Looks up provider info by provider id; returns undefined for an unknown id. */
+declare function providerInfo(providerId: string): ModelProviderInfo | undefined;
+/**
+ * The protocol a group pins on every one of its entries (ModelProviderInfo.clientType), or
+ * undefined when the group pins none — an unknown id (a user-defined group) included.
+ *
+ * Five groups pin: vLLM, whose models are served by the user's own vLLM adapter,
+ * OpenRouter, whose models all speak the Responses API OpenRouter serves at its preset base
+ * URL, and TokenDance, SiliconFlow and Atlas Cloud, whose models all speak Chat Completions.
+ *
+ * A reference value, read when a file is written from the catalog (catalogGroupConnection:
+ * a new Project, "Add new models" for a group new to the file, "Restore defaults") and by
+ * nothing that builds or judges a request: at runtime a group's protocol is its
+ * `[providers.<id>]` table's.
+ */
+declare function providerClientType(providerId: string): string | undefined;
+/**
+ * A first-party vendor group: one this catalog knows, that is not `custom`, carries no
+ * gateway endpoint and pins no protocol of its own — DeepSeek, Google, OpenAI, Anthropic,
+ * Z.AI, Moonshot, MiniMax, and the Penguin Go relay.
+ *
+ * What distinguishes it is that nothing in it decides a protocol: its entries persist no
+ * `client_type`, so MMSP places every one of them by the spelling of the upstream model
+ * id alone — the vendor family it begins with. An id of no known family cannot be started at
+ * all, whatever else is configured on the entry (the Penguin Go rows pin their protocol
+ * instead: the relay serves Gemini through generateContent, not the API a `gemini-` id routes
+ * to). Every
+ * surface that has to answer "is this one routable?" reads the group's shape through this one
+ * predicate rather than re-deriving it: the models page's cards and its config dialog, the
+ * models PUT, and the CLI's `config model add`. Whether a model may be added to the group at
+ * all is a separate, wider rule: isAddableGroup.
+ *
+ * Every other group answers the protocol question by itself and therefore routes any id the
+ * endpoint serves: `custom` and user-defined groups detect or pick it, and a gateway's or
+ * vLLM's rows speak the protocol their group's `[providers.<id>]` table or the row itself
+ * stores (a new Project writes it there).
+ */
+declare function isVendorGroup(providerId: string): boolean;
+/**
+ * Whether this entry would be written into a vendor group with an id MMSP cannot place —
+ * the configuration that produces `No client for model "<id>": its family is not known` on
+ * the first request, and nothing before it.
+ *
+ * MMSP's `routedClientType` is the authority: AutoLLMClient routes through it, and it returns
+ * null on exactly the entries that client rejects. A blank id is not a routing failure — the
+ * entry is still being typed, and the required-field validation is what has something to say
+ * about it.
+ */
+declare function unroutableVendorModel(provider: string, modelId: string, clientType?: string): boolean;
+/**
+ * The official MMSP client a first-party vendor group's unpinned rows route to: the vendor's
+ * own, the official client that reads the variable the group records (`envKey`; MMSP's
+ * credentials module). Undefined for every other group, whose protocol its table or its rows
+ * decide.
+ */
+declare function vendorClientType(providerId: string): string | undefined;
+/**
+ * Whether models may be added to this group by hand: `custom`, vLLM, OpenRouter, TokenDance,
+ * SiliconFlow, Atlas Cloud (ModelProviderInfo.addable) and every user-defined group, i.e. an
+ * id this catalog does not know. Every other built-in group — the first-party vendors and the
+ * other gateways — carries its catalog presets and the rows it already stores: the models page
+ * offers no add-model entry point there, and the models PUT and the CLI's `config model add`
+ * refuse a new row that is not a preset (unaddableModel).
+ */
+declare function isAddableGroup(providerId: string): boolean;
+/**
+ * Whether writing this pair as a NEW row of its group would add a model by hand where the group
+ * takes none: a group isAddableGroup refuses, and a `(provider, model_id)` pair that is not one
+ * of the catalog's rows for it. A preset passes, so "Sync presets" can put a deleted one back;
+ * a row the table already stores is not a new one, and the callers never ask about it.
+ */
+declare function unaddableModel(provider: string, modelId: string): boolean;
+/**
+ * The price usage on a model is costed at when the Project no longer stores the model's row:
+ * the catalog's list `pricing` of a row that is or was the default of new Projects
+ * (ModelCatalogEntry.wasDefault), and undefined for every other pair — a row the Project does
+ * store is priced from the file, never from here. No promotion applies: a Project's promotion
+ * goes with its row. An off-peak schedule still does, since this is the catalog's own peak price.
+ */
+declare function retainedCatalogPricing(provider: string, modelId: string): ModelPricing | undefined;
+/**
+ * The model's own homepage/detail page for the frontend's model-card link. Gateway groups
+ * have a stable per-model URL pattern (works for user-added ids in those groups too);
+ * direct-vendor models link to the vendor's model list/docs page; custom and user-defined
+ * groups have no page to vouch for.
+ */
+declare function modelHomepageUrl(provider: string, modelId: string): string | undefined;
+
+/**
+ * The wire protocol that carries MMSP's `fast_mode` on a client: `"openai"` for the clients
+ * that send `service_tier: "priority"` (the OpenAI protocols, and Google's Interactions API
+ * and MiniMax alike), `"anthropic"` for those that send `speed: "fast"` plus the
+ * `fast-mode-2026-02-01` beta header. The two differ in what the user must be warned about,
+ * not just in wire shape.
+ */
+type FastModeProtocol = "openai" | "anthropic";
+/**
+ * What the UI shows about each MMSP client, which MMSP exports nothing for: the path it appends
+ * to its base URL (the models page's endpoint hint) and the protocol that carries `fast_mode`
+ * (absent = the client rejects it, or the harness cannot tell what it does with it). Keyed by
+ * the canonical client type MMSP's routedClientType returns; the catalog test holds it to the
+ * client types MMSP's credentials module knows.
+ */
+declare const CLIENT_PROTOCOLS: Readonly<Record<string, {
+    path: string;
+    fastMode?: FastModeProtocol;
+}>>;
+/**
+ * Whether a model can carry fast mode at all, and on which protocol - `undefined` means no.
+ *
+ * The fast tier is a property of the **client MMSP routes to** (MMSP's routedClientType), never of
+ * the catalog row: the registry carries no fast-tier capability flag, but the routing is
+ * deterministic, so the answer is too. This reports what the selected client does with the
+ * parameter:
+ *
+ * - maps it -> the protocol, and the toggle may be offered;
+ * - raises UnsupportedParameterError (the Z.AI, Moonshot, DeepSeek, google-genai and
+ *   embedding clients, and anthropic-official on Bedrock or for the generations that reject
+ *   the `speed` parameter) -> `undefined`;
+ * - forwards it to an MMSP server, whose upstream client decides what it does with it (mmsp)
+ *   -> `undefined`: the harness cannot say on which protocol, or whether at all;
+ * - routes nowhere (AutoLLMClient throws for an id it cannot place) -> `undefined` as well,
+ *   since a model that cannot run has no fast tier either.
+ *
+ * A rule rather than a per-model list on purpose: catalog rows added later inherit the right
+ * answer without anyone remembering to update a table.
+ *
+ * `"anthropic"` is reported for every Claude the client serves, including ids outside the
+ * research preview's Opus allowlist: Anthropic answers those with a 429 at request time, which
+ * is something to warn about before enabling, not grounds to hide the setting.
+ *
+ * Two runtime inputs stay invisible to a pure function of the config and can still flip the
+ * answer: the server's `CLIENT_TYPE` env var names the client for an entry that pins none, and
+ * `ANTHROPIC_BASE_URL` supplies the base URL when the entry leaves it blank (so a `bedrock://`
+ * there sends Claude to Bedrock, which has no fast tier). Third-party OpenAI-compatible
+ * endpoints are a third: they accept `service_tier` and may quietly serve the standard tier.
+ * That residue is why llm/generative-model.ts still handles the rejection at runtime.
+ */
+declare function fastModeProtocol(modelId: string, clientType?: string, baseUrl?: string): FastModeProtocol | undefined;
+
+/**
+ * The variable MMSP's client of this type reads its key from when handed none at this base URL
+ * (environmentCredential), or undefined: the client refuses that URL, calls it keyless, or is
+ * not one MMSP has. With no base URL it is always the client's own `*_API_KEY`.
+ */
+declare function clientEnvKey(clientType: string, baseUrl: string | undefined): string | undefined;
+/** The variables MMSP's routed client reads for a row as configured (see modelEnvironment). */
+interface ModelEnvironment {
+    /** The key's variable: only for a row with no key in the file. */
+    apiKeyEnv?: string;
+    /** The endpoint's variable: only for a row with no base URL in the file. */
+    baseUrlEnv?: string;
+    /**
+     * Where that row's requests go while `baseUrlEnv` is unset: the routed client's default
+     * endpoint, as MMSP's credentials table records it. Present exactly when `baseUrlEnv` is.
+     */
+    defaultBaseUrl?: string;
+}
+/**
+ * What a row takes from the environment, as MMSP decides it (PRN-021). The row's effective
+ * connection (core's effectiveConnection) picks the client MMSP routes it to (`routedClientType`)
+ * and the base URL that client is handed; `environmentCredential` then says what the client
+ * reads. With no key in the file it reads its `*_API_KEY` only for no base URL or its own default
+ * endpoint, and with no base URL in the file it goes where its `*_BASE_URL` points, key or not.
+ * A row MMSP refuses (no key and another base URL), an open MMSP server and a row nothing routes
+ * read nothing. With no base URL in the file the row also names the endpoint its requests go to
+ * while that variable is unset (`defaultBaseUrl`). `entry` is the row's OWN values, key
+ * included, and `group` its `[providers.<id>]` table.
+ */
+declare function modelEnvironment(entry: ModelCredentialShape & {
+    apiKey?: string | undefined;
+}, group: ProviderConnectionShape | undefined): ModelEnvironment;
+/**
+ * The variable a row with no key in the file authenticates with, or undefined: modelEnvironment's
+ * `apiKeyEnv`. The server's `GET /models` preview, the web dialog's hint and the CLI's list read
+ * this, so none of them can disagree with what a Session does.
+ */
+declare function modelEnvPreviewKey(entry: ModelCredentialShape & {
+    apiKey?: string | undefined;
+}, group: ProviderConnectionShape | undefined): string | undefined;
+/**
+ * The variable a group's settings may present as covering a blank group key, or undefined —
+ * the group dialog's hint: what MMSP's client for the group (groupClientType) reads when handed
+ * no key at the group's base URL (clientEnvKey). A group with no one client names nothing.
+ */
+declare function providerEnvFallbackKey(providerId: string, group: Pick<ProviderConnectionShape, "baseUrl" | "clientType"> | undefined): string | undefined;
+/**
+ * Whether a group with no key, and its client's variable unset, has its rows called without a
+ * key — the group dialog's "send no key" hint: MMSP's client for the group (groupClientType) at
+ * the group's base URL calls it keyless (calledKeyless). A group with no one client, and one
+ * keyed by a sign-in flow, answers no.
+ */
+declare function providerCalledKeyless(providerId: string, group: Pick<ProviderConnectionShape, "baseUrl" | "clientType"> | undefined): boolean;
+/**
+ * Whether a row with no key of its own or its group's, and its client's variable unset, is
+ * called without a key — the model dialog's "send no key" hint: its routed client at its
+ * effective base URL calls it keyless (calledKeyless). A row of a sign-in-keyed group, and one
+ * nothing routes, answers no. `entry` is the row's OWN values, and `group` its table.
+ */
+declare function modelCalledKeyless(entry: ModelCredentialShape & {
+    apiKey?: string | undefined;
+}, group: ProviderConnectionShape | undefined): boolean;
+
+/**
+ * The catalog as a Project config seeds it: each built-in group's `[providers.<id>]` table, the
+ * preset rows (storing a protocol or endpoint only where it differs from the table beside it),
+ * the default model and the flat promotions — what the server writes when a Project is created,
+ * on "Add new models" and on "Restore defaults". Reference values: nothing reads them when a
+ * request is built.
+ */
+
+/**
+ * The connection the catalog gives a built-in group when a file is written from it — a new
+ * Project, "Add new models" for a group new to the file, "Restore defaults": its gateway
+ * endpoint (`gatewayBaseUrl`, else the one base URL every catalog row of the group carries)
+ * and its one protocol (the group's pin, providerClientType, else the one pin every catalog
+ * row of the group carries; canonical spelling). Retired rows count: the Projects that still
+ * carry one store its difference from the same table.
+ *
+ * Undefined for `custom` (it holds the user's own endpoints), for an id the catalog does not
+ * know, and for a group with neither — the first-party vendors, whose rows go to the
+ * client's defaults, so their keyless rows are handed no key and MMSP's client reads the
+ * vendor's environment variable (PRN-021). A reference value: nothing reads it when a request
+ * is built.
+ */
+declare function catalogGroupConnection(providerId: string): {
+    base_url?: string;
+    client_type?: string;
+} | undefined;
+/**
+ * The default model of a new Project: DeepSeek V4.1 Flash, which the vendor serves under the
+ * bare name `deepseek-flash` — the current generation of the Flash series, at the same price
+ * and schedule as the V4 rows it replaces, and it reads images, so a new Project can take a
+ * pasted screenshot without anyone having to notice why it could not. The bare id begins with
+ * the `deepseek-` family, so MMSP routes it to DeepSeek's official client without a pin. A
+ * Project's default is copied in at creation (the server's seed, and "Restore defaults") and
+ * owned by it from then on, so this reaches new Projects alone; an existing one keeps whatever
+ * it stored, and "Add new models" never touches the stored default. Its catalog row carries
+ * `wasDefault`, as every former default's does.
+ */
+declare const PRESET_DEFAULT_MODEL: Readonly<ModelRef>;
+/**
+ * `[providers.<id>]` for every built-in group with a catalogGroupConnection, in the catalog's
+ * group order — what a new Project's file stores beside presetModelEntries' rows. A fresh
+ * object on every call, so a caller may change it.
+ */
+declare function presetProviderTable(): ProviderTable;
+/**
+ * Catalog -> preset ModelEntry list (what the server seeds a new Project with and what
+ * "Add new models" and "Restore defaults" write, avoiding duplicate hand-written copies). `provider` and `model_id` are persisted as
+ * separate fields (`model_id` is the plain upstream id). The facts a row stores are the
+ * context window, the price and `vision = false`, plus the row's protocol and endpoint where
+ * they differ from its group's table in `groups` (catalogModelEntry): beside those tables, the
+ * file alone says where every request goes, and nothing is left for a resolver to fill from
+ * the catalog. `groups` is the `[providers]` table the rows will sit beside — a new Project's
+ * (presetProviderTable, the default), or the file's own when "Add new models" adds rows to an
+ * existing Project, so each added row resolves to its catalog connection whatever the user
+ * has set on its group. No secrets are included, so only an API key is needed.
+ *
+ * Pricing is written as the LIST price the catalog records (a scheduled row's PEAK price),
+ * never a discounted number. What is on disk then stays true whatever promotion is live and
+ * whatever hour the Project is created or re-synced in: a flat promotion is stored beside the
+ * file as a per-Project fraction (presetPromotions), and both it and an off-peak tier are
+ * applied when the price is read, by the models page and by the cost center alike.
+ */
+declare function presetModelEntries(groups?: ProviderTable): ModelEntry[];
+/**
+ * Every catalog row as a ModelEntry, retired rows included, in the shape presetModelEntries
+ * writes: what a Project carrying a retired row stores for it beside a new Project's group
+ * tables (see ModelCatalogEntry.retired). `groups` as in presetModelEntries.
+ */
+declare function catalogModelEntries(groups?: ProviderTable): ModelEntry[];
+/**
+ * The catalog's flat promotions, as a new Project is seeded with them: every row whose `discount`
+ * is a fraction in (0, 1). A retired row is skipped like it is in presetModelEntries: a new
+ * Project never carries it, so there is nothing for its promotion to apply to.
+ */
+declare function presetPromotions(): Array<{
+    provider: string;
+    modelId: string;
+    discount: number;
+}>;
+
+export { CLIENT_PROTOCOLS, DEEPSEEK_OFF_PEAK, type FastModeProtocol, MODELSCOPE_PROVIDER_ID, MODEL_CATALOG, MODEL_PROVIDERS, type ModelCatalogEntry, type ModelEnvironment, type ModelProviderBalance, type ModelProviderBridgeAuth, type ModelProviderInfo, type ModelProviderOAuth, type OffPeakDiscount, PENGUIN_GO_BASE_URL, PENGUIN_GO_PROVIDER_ID, PRESET_DEFAULT_MODEL, QWEN_OFF_PEAK, catalogEntryFor, catalogGroupConnection, catalogModelEntries, clientEnvKey, effectivePricing, fastModeProtocol, fixedClientType, fixedClientTypeRefuses, isAddableGroup, isVendorGroup, modelCalledKeyless, modelEnvPreviewKey, modelEnvironment, modelHomepageUrl, offPeakAt, offPeakScheduledRefs, presetModelEntries, presetPromotions, presetProviderTable, providerCalledKeyless, providerClientType, providerEnvFallbackKey, providerInfo, retainedCatalogPricing, unaddableModel, unroutableVendorModel, vendorClientType };