@ggui-ai/protocol 0.15.0 → 0.16.0

package/dist/types/domain-error-codes.js

@@ -0,0 +1,170 @@
+/**
+ * The Plane-2 registry — the ONLY list of domain-error slugs (ggui#880).
+ *
+ * SPEC §7.9 Plane 2: a recoverable, contract-level failure the caller can
+ * fix — a missing session or handshake, props that do not satisfy the
+ * contract, an undeclared channel. The MCP SDK ships a thrown handler error
+ * to the agent as `{content: [{type: 'text', text: error.message}],
+ * isError: true}` and nothing else, so the slug travels as the LEADING
+ * token of that text — `<code>: <detail>` — composed by the `DomainError`
+ * base in `../errors/domain-error` from a code in this registry. A reader
+ * branches on `text.startsWith(code + ': ')` for a registered code and on
+ * nothing else.
+ *
+ * Same posture as the refusal registry in `./refusal-codes`: `code === key`
+ * is forced at the definer, the code type is derived from the keys, and
+ * the two registries are disjoint (pinned) — one code names one plane.
+ */
+/**
+ * How a caller recovers from a Plane-2 failure.
+ *
+ * - `retry-same-id` — fix the input and retry on the SAME handshakeId /
+ *   sessionId; nothing was consumed.
+ * - `re-mint` — the id itself is gone (unknown, consumed, expired,
+ *   another app's); mint a fresh one (`ggui_handshake`, then `ggui_render`).
+ * - `later` — a dependency the server fetches was unavailable; time
+ *   restores it, the input was fine.
+ */
+export const DOMAIN_ERROR_RECOVERIES = ['retry-same-id', 're-mint', 'later'];
+/**
+ * The registry is the ONLY list of domain-error codes: {@link DomainErrorCode}
+ * is derived from the keys below, and this definer forces every row's
+ * `code` to equal its key at the type level.
+ */
+function defineDomainErrorRegistry(rows) {
+    return rows;
+}
+/**
+ * The registry with its per-key literal types kept (ggui#889):
+ * `DOMAIN_ERROR_ROWS.session_not_found.code` is `'session_not_found'`,
+ * its `recovery` is `'re-mint'`. {@link DOMAIN_ERROR_REGISTRY} is the
+ * same object read through the normalized row type.
+ */
+export const DOMAIN_ERROR_ROWS = /* @__PURE__ */ defineDomainErrorRegistry({
+    // ── identity ──────────────────────────────────────────────────────
+    session_not_found: {
+        code: 'session_not_found',
+        tools: [
+            'ggui_consume',
+            'ggui_get_session',
+            'ggui_get_render_source',
+            'ggui_update',
+            'ggui_amend',
+            'ggui_emit',
+            'ggui_runtime_pull',
+        ],
+        recovery: 're-mint',
+        emitter: 'the session lookup on every session-scoped tool',
+        description: 'The sessionId names no session this caller can reach — never minted, expired, closed, or owned by another app (cross-app access surfaces uniformly). Re-handshake and re-render to mint a fresh one.',
+    },
+    handshake_not_found: {
+        code: 'handshake_not_found',
+        tools: ['ggui_render'],
+        recovery: 're-mint',
+        emitter: 'the handshake-record lookup at ggui_render',
+        description: 'The handshakeId is unknown, already consumed by a render, or expired. Call ggui_handshake again for a fresh id, then render with the new pair.',
+    },
+    // ── the contract gate ─────────────────────────────────────────────
+    contract_violation: {
+        code: 'contract_violation',
+        tools: ['ggui_render', 'ggui_update', 'ggui_amend', 'ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: 'the props / payload validator against the contract',
+        description: "Props or a payload do not satisfy the contract's spec — a missing required prop included. Fix the values and retry with the same id; nothing was consumed.",
+    },
+    schema_mismatch_error: {
+        code: 'schema_mismatch_error',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the schema-compatibility check between the contract and the registered tool shapes',
+        description: "An actionSpec or streamSpec schema is not a subset of the named tool's registered shape. Adjust the contract or the tool, then retry with the same handshakeId.",
+    },
+    contract_validation_failed: {
+        code: 'contract_validation_failed',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the contract lint gate (shape, retired fields, schema metadata, cross-references, schema compatibility)',
+        description: 'The contract failed the lint gate; the detail names the category and the finding. Fix the contract and retry with the same handshakeId.',
+    },
+    override_contract_invalid: {
+        code: 'override_contract_invalid',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the override gate at ggui_render',
+        description: 'override.contract failed validation — an override commits the caller to a conforming contract. Drop the override and render the suggestion, or fix the draft.',
+    },
+    // ── the live channel ──────────────────────────────────────────────
+    channel_not_declared: {
+        code: 'channel_not_declared',
+        tools: ['ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: "ggui_emit's channel check against the contract's streamSpec",
+        description: "The channel is not declared by the session's contract. Emit on a declared channel; the detail lists them.",
+    },
+    invalid_complete: {
+        code: 'invalid_complete',
+        tools: ['ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: "ggui_emit's completion check",
+        description: 'A completion was signalled for a channel that cannot complete in its current state. Emit on the channel first, or omit the completion.',
+    },
+    // ── the gadget gate ───────────────────────────────────────────────
+    gadget_not_registered: {
+        code: 'gadget_not_registered',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: "A clientCapabilities.gadgets reference names an export the app's gadget registry does not carry. Drop the reference or fix the name; the detail suggests the nearest match.",
+    },
+    gadget_package_mismatch: {
+        code: 'gadget_package_mismatch',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: 'A gadget export is registered, but only under a different package than the contract requested. Request the registered package; the detail names it.',
+    },
+    gadget_public_env_missing: {
+        code: 'gadget_public_env_missing',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: "A registered wrapper requires a public-env key the app has not set. Set the key on the app's public env, then retry.",
+    },
+    duplicate_gadget_hook: {
+        code: 'duplicate_gadget_hook',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: 'Two gadget packages export the same name; the generated import would collide. Reference one of them.',
+    },
+    gadget_types_fetch_failed: {
+        code: 'gadget_types_fetch_failed',
+        tools: ['ggui_render'],
+        recovery: 'later',
+        emitter: 'the gadget type fetch before cold generation',
+        description: "Fetching a gadget package's types failed; the input was fine. Retry after a short delay.",
+    },
+    gadget_catalog_integrity: {
+        code: 'gadget_catalog_integrity',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: "the app's gadget catalog resolver at ggui_render",
+        description: "The app's gadget catalog is inconsistent with its registrations. Repair the catalog, then retry with the same handshakeId.",
+    },
+    // ── the blueprint registry ────────────────────────────────────────
+    blueprint_rejected: {
+        code: 'blueprint_rejected',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the blueprint registry on registration',
+        description: "The blueprint was rejected by the registry's error-level findings; the detail lists them. Fix the contract and retry with the same handshakeId.",
+    },
+});
+/** The registry consumers read. */
+export const DOMAIN_ERROR_REGISTRY = DOMAIN_ERROR_ROWS;
+/** Whether `value` is a registered domain-error code. */
+export function isDomainErrorCode(value) {
+    return Object.hasOwn(DOMAIN_ERROR_ROWS, value);
+}
+/** Every registered code, in registry order. */
+export const DOMAIN_ERROR_CODES = Object.keys(DOMAIN_ERROR_ROWS).filter(isDomainErrorCode);

package/dist/types/handshake-suggestion.d.ts

@@ -89,12 +89,12 @@ export interface BlueprintDraft {
         readonly seedPrompt?: string;
     };
     /**
-     * Generator slug hint (e.g. `'ui-gen-advanced-opus-4-7'`). The
+     * Generator identity hint (e.g. `'ui-gen-advanced'` — de-modeled, ggui#924). The
      * server resolves the effective generator as:
      *
      *   1. Operator app-pin (`App.pinnedGenerator`) — wins if set.
      *   2. This hint — if registered in the GeneratorRegistry.
-     *   3. Registry default (`ui-gen-default-haiku-4-5`).
+     *   3. Registry default (`ui-gen-default`).
      *
      * Hint-only; unknown slugs fall through to the registry default.
      */

package/dist/types/live-channel.d.ts

@@ -23,7 +23,7 @@ import type { JsonObject, JsonValue, StreamChannelMode } from './data-contract.j
 export interface SubscribePayload {
     sessionId: string;
     /**
-     * App (tenant) identity. OPTIONAL — absent ⇒ the server resolves the
+     * App identity — the `appId` the session belongs to. OPTIONAL — absent ⇒ the server resolves the
      * caller's identity-default app, the same resolution rule the MCP
      * route uses: a token binding (`wsToken` binds `(sessionId, appId)`)
      * wins, then the deployment's identity → appId mapping, then the

package/dist/types/llm-route.d.ts

@@ -52,7 +52,7 @@
  */
 export declare const MODELS: {
     readonly anthropic: readonly ["claude-fable-5-1", "claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-4-6", "claude-opus-4-7", "claude-opus-4-6"];
-    readonly openai: readonly ["gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.5-2026-04-23", "gpt-5.5-pro", "gpt-5.5-pro-2026-04-23", "gpt-5.4", "gpt-5.4-2026-03-05", "gpt-5.4-mini", "gpt-5.4-mini-2026-03-17", "gpt-5.4-nano", "gpt-5.4-nano-2026-03-17", "gpt-5.3-codex"];
+    readonly openai: readonly ["gpt-6-astra", "gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.5-2026-04-23", "gpt-5.5-pro", "gpt-5.5-pro-2026-04-23", "gpt-5.4", "gpt-5.4-2026-03-05", "gpt-5.4-mini", "gpt-5.4-mini-2026-03-17", "gpt-5.4-nano", "gpt-5.4-nano-2026-03-17", "gpt-5.3-codex"];
     readonly google: readonly ["gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-flash-latest", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview"];
     readonly bedrock: readonly ["anthropic.claude-fable-5-1", "anthropic.claude-fable-5", "anthropic.claude-opus-5", "anthropic.claude-sonnet-5", "anthropic.claude-opus-4-8", "us.anthropic.claude-haiku-4-5-20251001-v1:0", "eu.anthropic.claude-haiku-4-5-20251001-v1:0", "apac.anthropic.claude-haiku-4-5-20251001-v1:0", "global.anthropic.claude-haiku-4-5-20251001-v1:0", "us.anthropic.claude-sonnet-4-6", "eu.anthropic.claude-sonnet-4-6", "apac.anthropic.claude-sonnet-4-6", "us.anthropic.claude-opus-4-7", "eu.anthropic.claude-opus-4-7", "apac.anthropic.claude-opus-4-7", "global.anthropic.claude-opus-4-7", "us.anthropic.claude-opus-4-6-v1"];
     readonly openrouter: readonly ["anthropic/claude-fable-5", "anthropic/claude-opus-5", "anthropic/claude-sonnet-5", "anthropic/claude-haiku-4.5", "anthropic/claude-sonnet-4.6", "anthropic/claude-opus-4.7", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "openai/gpt-5.6-luna", "openai/gpt-5.5", "openai/gpt-5.5-pro", "openai/gpt-5.4-mini", "openai/gpt-5.4-nano", "google/gemini-3.6-flash", "google/gemini-3.5-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview", "google/gemini-3.1-flash-lite", "x-ai/grok-4.3", "meta-llama/llama-4-maverick", "meta-llama/llama-3.3-70b-instruct", "deepseek/deepseek-v4-pro", "deepseek/deepseek-r1-0528", "qwen/qwen3.7-max", "qwen/qwen3-coder", "mistralai/mistral-large-2512", "openai/gpt-oss-120b"];
@@ -189,6 +189,25 @@ export declare function serializeLlmRoute(route: LlmRoute): string;
  * Round-trip with {@link serializeLlmRoute}.
  */
 export declare function parseLlmRoute(serialized: string): LlmRoute | null;
+/**
+ * Map from LiteLLM transport prefix → our `LlmProvider` enum. Used by
+ * {@link parseLiteLlmString} to accept legacy ggui.json files and
+ * ecosystem inputs without forcing a migration on every operator.
+ *
+ * Note: LiteLLM separates `gemini/` (AI Studio) from `vertex_ai/`
+ * (enterprise Vertex). We don't have a Vertex variant in this slice;
+ * `vertex_ai/` parsing falls through to `null` until Vertex lands.
+ */
+/**
+ * The prefixes a {@link ModelRef} may start with — the LiteLLM spellings,
+ * and the model registry's. The single source: the prefix→provider map
+ * below is keyed by it (exhaustive by type), and the JSON-Schema-facing
+ * `pattern` in `llmBlueprintSourceSchema` is built from it.
+ */
+export declare const MODEL_REF_PREFIXES: readonly ["anthropic", "gemini", "openai", "bedrock", "openrouter"];
+export type ModelRefPrefix = (typeof MODEL_REF_PREFIXES)[number];
+/** Whether `s` is one of {@link MODEL_REF_PREFIXES}. */
+export declare function isModelRefPrefix(s: string): s is ModelRefPrefix;
 /**
  * Parse a LiteLLM-format string (`<prefix>/<model>` or
  * `<prefix>/<sub>/<model>` for OpenRouter) into an `LlmRoute`.
@@ -218,7 +237,7 @@ export declare function parseLiteLlmString(s: string): LlmRoute | null;
  * For models without an explicit LITELLM_TO_WIRE mapping (Gemini,
  * OpenAI, OpenRouter), serialization uses the wire model as-is.
  */
-export declare function toLiteLlmString(route: LlmRoute): string;
+export declare function toLiteLlmString(route: LlmRoute): ModelRef;
 /**
  * Single-entry parser that accepts both canonical (`provider:model`)
  * and LiteLLM (`prefix/model`) formats. Used at wire boundaries that
@@ -230,4 +249,42 @@ export declare function toLiteLlmString(route: LlmRoute): string;
  * format produces a valid route.
  */
 export declare function parseAnyLlmRoute(s: string): LlmRoute | null;
+/**
+ * A route rendered as ONE string in the model registry's spelling —
+ * the LiteLLM form `<prefix>/<model>` (#818: one model-id vocabulary,
+ * two separators). Every registry id (`ModelId`, e.g.
+ * `anthropic/claude-haiku-4-5`, `gemini/gemini-3.5-flash`) is the ref
+ * of the route it names, so `ModelId ⊂ ModelRef`; a bedrock inference
+ * profile or an unlisted OpenRouter model is a `ModelRef` the registry
+ * does not list. Where a wire model has a LiteLLM alias
+ * (`claude-haiku-4-5-20251001` ↔ `claude-haiku-4-5`) the ref is the
+ * ALIAS — the dated wire id is not a ref spelling.
+ *
+ * Split at the FIRST `/`: prefixes contain no slash, so
+ * `openrouter/anthropic/claude-3.5-sonnet` is unambiguous.
+ *
+ * Used where a record must say which model a run used and readers must
+ * recover the route: `LlmBlueprintSource.model`.
+ */
+export type ModelRef = `${ModelRefPrefix}/${string}`;
+/**
+ * The one composer of a {@link ModelRef}: render the route the run used,
+ * inverting the LiteLLM alias map so a resolved `{anthropic,
+ * claude-haiku-4-5-20251001}` renders as `anthropic/claude-haiku-4-5` —
+ * the registry id. Total: every `LlmRoute` has a ref. Feed it the ROUTE
+ * the call used; the ref is the same whether the route was configured
+ * as the alias or already resolved.
+ */
+export declare function modelRefOfRoute(route: LlmRoute): ModelRef;
+/**
+ * Recover the route from a {@link ModelRef}. `null` unless `s` is a
+ * LiteLLM-form string that parses ({@link parseLiteLlmString}) AND is
+ * the spelling {@link modelRefOfRoute} produces for that route — a ref
+ * has one spelling, so the dated wire id of an aliased model and a
+ * wrong prefix are refused here even though the lenient wire parsers
+ * accept them.
+ */
+export declare function parseModelRef(s: string): LlmRoute | null;
+/** Whether `s` is a {@link ModelRef} — see {@link parseModelRef}. */
+export declare function isModelRef(s: string): s is ModelRef;
 //# sourceMappingURL=llm-route.d.ts.map

package/dist/types/llm-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-route.d.ts","sourceRoot":"","sources":["../../src/types/llm-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,MAAM;;;;;;CAuJT,CAAC;AAMX;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,MAAM,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,WAAW,IAAI,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,WAAW,IAAI,CAAC,SAC1C,YAAY,GACZ,SAAS,GACT,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAC/B,YAAY,CAAC,CAAC,CAAC,CAAC;AAEpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,GAAG;KACpB,CAAC,IAAI,WAAW,GAAG;QAAE,QAAQ,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE;CACvD,CAAC,WAAW,CAAC,CAAC;AAMf;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,WAAW,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAChD,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAE1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CASxE;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAajE;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAgB7D;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAKvD;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D"}
+{"version":3,"file":"llm-route.d.ts","sourceRoot":"","sources":["../../src/types/llm-route.ts"],"names":[],"mappings":"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"}

package/dist/types/llm-route.js

@@ -78,6 +78,7 @@ export const MODELS = {
         // reasoning), `terra` (balanced), `luna` (fast/cost). The bare
         // `gpt-5.6` alias routes to Sol on OpenAI's side. No dated
         // siblings registered at adoption time.
+        'gpt-6-astra', // ggui#977 (2026-09-09): listed by `GET /v1/models/gpt-6-astra` → 200
         'gpt-5.6',
         'gpt-5.6-sol',
         'gpt-5.6-terra',
@@ -345,6 +346,13 @@ export function parseLlmRoute(serialized) {
  * (enterprise Vertex). We don't have a Vertex variant in this slice;
  * `vertex_ai/` parsing falls through to `null` until Vertex lands.
  */
+/**
+ * The prefixes a {@link ModelRef} may start with — the LiteLLM spellings,
+ * and the model registry's. The single source: the prefix→provider map
+ * below is keyed by it (exhaustive by type), and the JSON-Schema-facing
+ * `pattern` in `llmBlueprintSourceSchema` is built from it.
+ */
+export const MODEL_REF_PREFIXES = ['anthropic', 'gemini', 'openai', 'bedrock', 'openrouter'];
 const LITELLM_PROVIDER_PREFIX_MAP = {
     anthropic: 'anthropic',
     gemini: 'google',
@@ -352,6 +360,26 @@ const LITELLM_PROVIDER_PREFIX_MAP = {
     bedrock: 'bedrock',
     openrouter: 'openrouter',
 };
+/**
+ * Provider → its ONE LiteLLM prefix. Exhaustive by type: adding a
+ * provider to `MODELS` without a prefix here is a compile error, which
+ * is what makes {@link modelRefOfRoute} total.
+ */
+const PROVIDER_TO_LITELLM_PREFIX = {
+    anthropic: 'anthropic',
+    google: 'gemini',
+    openai: 'openai',
+    bedrock: 'bedrock',
+    openrouter: 'openrouter',
+};
+const MODEL_REF_PREFIX_LIST = MODEL_REF_PREFIXES;
+/** Whether `s` is one of {@link MODEL_REF_PREFIXES}. */
+export function isModelRefPrefix(s) {
+    return MODEL_REF_PREFIX_LIST.includes(s);
+}
+function liteLlmPrefixProvider(prefix) {
+    return isModelRefPrefix(prefix) ? LITELLM_PROVIDER_PREFIX_MAP[prefix] : undefined;
+}
 /**
  * LiteLLM canonical → wire-canonical model mappings for providers
  * whose LiteLLM-form differs from the wire-canonical form.
@@ -396,7 +424,7 @@ export function parseLiteLlmString(s) {
     if (firstSlash <= 0)
         return null;
     const prefix = s.substring(0, firstSlash);
-    const provider = LITELLM_PROVIDER_PREFIX_MAP[prefix];
+    const provider = liteLlmPrefixProvider(prefix);
     if (!provider)
         return null;
     // For OpenRouter the model is everything after the first slash
@@ -446,23 +474,10 @@ function getWireToLitellm() {
  * OpenAI, OpenRouter), serialization uses the wire model as-is.
  */
 export function toLiteLlmString(route) {
-    const prefix = providerLiteLlmPrefix(route.provider);
-    const inverseMap = getWireToLitellm()[route.provider];
-    const modelForLitellm = inverseMap?.[route.model] ?? route.model;
-    return `${prefix}/${modelForLitellm}`;
+    return modelRefOfRoute(route);
 }
 function providerLiteLlmPrefix(provider) {
-    // Find the LiteLLM prefix that maps to this provider. There's at
-    // most one prefix per provider in LITELLM_PROVIDER_PREFIX_MAP today.
-    for (const [prefix, p] of Object.entries(LITELLM_PROVIDER_PREFIX_MAP)) {
-        if (p === provider)
-            return prefix;
-    }
-    // Defensive: every provider in MODELS should have a LiteLLM prefix.
-    // If not, fall through to the provider's own name (degrades gracefully
-    // for observability — the trace just won't match LiteLLM's exact
-    // wording, but it still names the provider).
-    return provider;
+    return PROVIDER_TO_LITELLM_PREFIX[provider];
 }
 // ============================================================================
 // Combined parser (accepts either format)
@@ -480,3 +495,34 @@ function providerLiteLlmPrefix(provider) {
 export function parseAnyLlmRoute(s) {
     return parseLlmRoute(s) ?? parseLiteLlmString(s);
 }
+/**
+ * The one composer of a {@link ModelRef}: render the route the run used,
+ * inverting the LiteLLM alias map so a resolved `{anthropic,
+ * claude-haiku-4-5-20251001}` renders as `anthropic/claude-haiku-4-5` —
+ * the registry id. Total: every `LlmRoute` has a ref. Feed it the ROUTE
+ * the call used; the ref is the same whether the route was configured
+ * as the alias or already resolved.
+ */
+export function modelRefOfRoute(route) {
+    const inverseMap = getWireToLitellm()[route.provider];
+    const model = inverseMap?.[route.model] ?? route.model;
+    return `${providerLiteLlmPrefix(route.provider)}/${model}`;
+}
+/**
+ * Recover the route from a {@link ModelRef}. `null` unless `s` is a
+ * LiteLLM-form string that parses ({@link parseLiteLlmString}) AND is
+ * the spelling {@link modelRefOfRoute} produces for that route — a ref
+ * has one spelling, so the dated wire id of an aliased model and a
+ * wrong prefix are refused here even though the lenient wire parsers
+ * accept them.
+ */
+export function parseModelRef(s) {
+    const route = parseLiteLlmString(s);
+    if (route === null)
+        return null;
+    return modelRefOfRoute(route) === s ? route : null;
+}
+/** Whether `s` is a {@link ModelRef} — see {@link parseModelRef}. */
+export function isModelRef(s) {
+    return parseModelRef(s) !== null;
+}

package/dist/types/llm.d.ts

@@ -6,7 +6,7 @@
  *   - `MODEL_REGISTRY` here = LiteLLM-keyed pricing + capability
  *     metadata. Keys are LiteLLM strings (`"gemini/gemini-3.5-flash"`,
  *     `"openai/gpt-5.4-mini"`, …). Read by:
- *       - `cloud/ggui-protocol-pod` pricing-drift test (vendored
+ *       - a hosted deployment's pricing-drift test (vendored
  *         LiteLLM JSON pricing table)
  *       - `oss/misc/benchmark` runner (bench harness; picks model
  *         configs by LiteLLM key)
@@ -40,7 +40,7 @@
  * EXISTS, and `scripts/check-litellm-pricing-drift.ts` compares the
  * snapshot against upstream, never the registry. That gap let this
  * table sit four months stale while production routed to models it did
- * not even list. The pod's `pricing-tables.test.ts` now asserts every
+ * not even list. A hosted deployment's `pricing-tables.test.ts` now asserts every
  * entry's `costs` match the vendored rate (with an explicit, dated
  * PENDING_UPSTREAM allowlist for prices we learn before LiteLLM does).
  * Add a model here and you MUST re-vendor the snapshot in the same
@@ -336,6 +336,22 @@ declare const MODEL_ROWS: {
         readonly maxTokens: 1000000;
         readonly supportsTools: true;
     };
+    readonly "openai/gpt-6-astra": {
+        readonly id: "openai/gpt-6-astra";
+        readonly provider: "openai";
+        readonly displayName: "GPT-6 Astra";
+        readonly tier: "premium";
+        readonly state: "active";
+        readonly lineup: false;
+        readonly costs: {
+            readonly inputPer1M: 10;
+            readonly outputPer1M: 50;
+            readonly cacheWritePer1M: 12.5;
+            readonly cacheReadPer1M: 1;
+        };
+        readonly maxTokens: 922000;
+        readonly supportsTools: true;
+    };
     readonly "openai/gpt-5.6-sol": {
         readonly id: "openai/gpt-5.6-sol";
         readonly provider: "openai";
@@ -453,6 +469,10 @@ export interface ModelConfig extends ModelConfigBase {
  * {@link ModelId} and enforce `id === key`.
  */
 export declare const MODEL_REGISTRY: Readonly<Record<ModelId, ModelConfig>>;
+/** Whether `value` is a registry model id — provider-qualified, e.g. `anthropic/claude-haiku-4-5`. */
+export declare function isModelId(value: string): value is ModelId;
+/** Every registry model id, in registry order (ggui#924: the blueprint record's `model` is one of these). */
+export declare const MODEL_IDS: readonly ModelId[];
 /**
  * The curated "current lineup" — derived once from the rows' `lineup`
  * fact, in registry order. Pickers render this up front and put the

package/dist/types/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/types/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMlD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB;;;;WAIG;QACH,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB;;;;WAIG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAkBD,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Ud,CAAC;AAEH,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,UAAU,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAc,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,OAAO,EAEA,CAAC;AAE5C,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,OAAsC,CAAC"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/types/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMlD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB;;;;WAIG;QACH,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB;;;;WAIG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAkBD,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmWd,CAAC;AAEH,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,UAAU,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAc,CAAC;AAEjF,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,OAAO,CAEzD;AAED,6GAA6G;AAC7G,eAAO,MAAM,SAAS,EAAE,SAAS,OAAO,EAA8C,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,OAAO,EAEA,CAAC;AAE5C,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,OAAsC,CAAC"}

package/dist/types/llm.js

@@ -6,7 +6,7 @@
  *   - `MODEL_REGISTRY` here = LiteLLM-keyed pricing + capability
  *     metadata. Keys are LiteLLM strings (`"gemini/gemini-3.5-flash"`,
  *     `"openai/gpt-5.4-mini"`, …). Read by:
- *       - `cloud/ggui-protocol-pod` pricing-drift test (vendored
+ *       - a hosted deployment's pricing-drift test (vendored
  *         LiteLLM JSON pricing table)
  *       - `oss/misc/benchmark` runner (bench harness; picks model
  *         configs by LiteLLM key)
@@ -40,7 +40,7 @@
  * EXISTS, and `scripts/check-litellm-pricing-drift.ts` compares the
  * snapshot against upstream, never the registry. That gap let this
  * table sit four months stale while production routed to models it did
- * not even list. The pod's `pricing-tables.test.ts` now asserts every
+ * not even list. A hosted deployment's `pricing-tables.test.ts` now asserts every
  * entry's `costs` match the vendored rate (with an explicit, dated
  * PENDING_UPSTREAM allowlist for prices we learn before LiteLLM does).
  * Add a model here and you MUST re-vendor the snapshot in the same
@@ -307,6 +307,27 @@ const MODEL_ROWS = defineModelRegistry({
     // confirmed upstream LiteLLM has ingested both cuts, so these costs
     // now agree with the vendored snapshot (no PENDING_UPSTREAM
     // exemption needed).
+    // ggui#977 (2026-09-09) — Exp 008's founder-ruled second arm. Receipts on
+    // the issue: existence `GET /v1/models/gpt-6-astra` → 200; pricing from
+    // platform.openai.com/docs/pricing, standard short-context tier; context
+    // window and tool support from the model page. No retirement date is
+    // published → `retireNotBefore` unset. Not in the lineup (experiment arm).
+    "openai/gpt-6-astra": {
+        id: "openai/gpt-6-astra",
+        provider: "openai",
+        displayName: "GPT-6 Astra",
+        tier: "premium",
+        state: "active",
+        lineup: false,
+        costs: {
+            inputPer1M: 10.0,
+            outputPer1M: 50.0,
+            cacheWritePer1M: 12.5,
+            cacheReadPer1M: 1.0,
+        },
+        maxTokens: 922000,
+        supportsTools: true,
+    },
     "openai/gpt-5.6-sol": {
         id: "openai/gpt-5.6-sol",
         provider: "openai",
@@ -399,6 +420,12 @@ const MODEL_ROWS = defineModelRegistry({
  * {@link ModelId} and enforce `id === key`.
  */
 export const MODEL_REGISTRY = MODEL_ROWS;
+/** Whether `value` is a registry model id — provider-qualified, e.g. `anthropic/claude-haiku-4-5`. */
+export function isModelId(value) {
+    return Object.hasOwn(MODEL_ROWS, value);
+}
+/** Every registry model id, in registry order (ggui#924: the blueprint record's `model` is one of these). */
+export const MODEL_IDS = Object.keys(MODEL_ROWS).filter(isModelId);
 /**
  * The curated "current lineup" — derived once from the rows' `lineup`
  * fact, in registry order. Pickers render this up front and put the