@agentproto/model-catalog 0.5.0 → 0.7.0

package/dist/route-identity/index.d.ts

@@ -1,32 +1,62 @@
-import { c as LLMPricing } from '../catalog-BPDMuxzf.js';
-import '../base-C4kz9Dxc.js';
+import { c as LLMPricing } from '../catalog-BbfjJxKT.js';
+import '../base-B8IIoaqg.js';
 import 'zod';
 
 /**
  * Route-aware model identity.
  *
  * Canonical reference syntax:
- *   vendor/product[@route]
+ *   [route:]vendor/product[:pin][@route]
  *
  * A model product (who built it + what product) is separate from its serving
- * route (how we reach it / how we are billed).
+ * route (how we reach it / how we are billed) and from an optional `:pin` —
+ * an OpenRouter routing variant or an inference-provider selector.
+ *
+ * Three axes:
+ *
+ * | Axis               | Question it answers          | Example value            |
+ * |---------------------|------------------------------|---------------------------|
+ * | `vendor`            | who built the model          | `openai`, `anthropic`     |
+ * | `route`             | how we reach it / are billed | `openrouter`, `huggingface`, `openai` (direct) |
+ * | `inferenceProvider` / `variant` | who runs the GPUs behind a router, or which routing mode | `cerebras`, `groq` (provider); `free`, `nitro` (variant) |
  *
  * Examples:
- *   openai/gpt-4o              → vendor openai, product gpt-4o, route openai (direct)
- *   openai/gpt-4o@openrouter   → same product, routed through OpenRouter
- *   openai/gpt-4o@agentik-proxy → same product, operator-configured proxy route
+ *   openai/gpt-4o                    → vendor openai, product gpt-4o, route openai (direct)
+ *   openai/gpt-4o@openrouter         → same product, routed through OpenRouter
+ *   openai/gpt-4o@agentik-proxy      → same product, operator-configured proxy route
+ *   deepseek/deepseek-chat:free@openrouter → OpenRouter, variant "free"
+ *   openrouter:deepseek/deepseek-chat:free → legacy PREFIX form, same result
+ *   meta-llama/Llama-3.1-8B:cerebras@huggingface → HuggingFace, inference-provider pin "cerebras"
+ *
+ * `:pin` classification (per the resolved route):
+ *   - `openrouter` (or no explicit route) + pin ∈ {free, nitro, floor, online,
+ *     exacto} → `variant` (a routing mode, not a provider).
+ *   - anything else → `inferenceProvider` (HF inference provider / OpenRouter
+ *     provider pin).
  *
  * Design invariants:
  *   - `vendor` is who built the model; `route` is how we reach it.
  *   - `provider/model` strings parse as vendor/product with implicit route = vendor
  *     (backward-compatible reference form).
- *   - Unscoped `xx@yy` is rejected.
+ *   - Unscoped `xx@yy` is rejected; bare ids without a slash are rejected
+ *     (lenient handling belongs in consumers — see `tryParseModelRef`).
+ *   - The legacy `route:` PREFIX (colon before the first `/`, prefix must be a
+ *     known route name) parses; an explicit `@route` suffix wins on conflict.
+ *     `formatModelRef` always emits the canonical suffix form.
  *   - Route metadata (pricing, limits, transport, availability) is separate from
  *     product metadata and computed at resolution time.
  *   - The abstraction is generic across model kinds; only LLM has a concrete
  *     resolver today.
  */
 
+/**
+ * OpenRouter variant suffixes — a CLOSED list. A `:pin` matching one of
+ * these on the OpenRouter route (or on a route-less/implicit-route id) is a
+ * routing *variant*, never an inference-provider pin.
+ * @see https://openrouter.ai/docs/features/provider-routing
+ */
+declare const OPENROUTER_VARIANTS: readonly ["free", "nitro", "floor", "online", "exacto"];
+type OpenRouterVariant = (typeof OPENROUTER_VARIANTS)[number];
 interface ModelRef {
     /** The original, trimmed string. */
     raw: string;
@@ -36,6 +66,14 @@ interface ModelRef {
     product: string;
     /** Routing target — defaults to vendor for direct vendor access. */
     route: string;
+    /**
+     * Explicit `:pin` classified as an inference-provider selector (HF
+     * inference provider, or an OpenRouter provider pin outside the closed
+     * variant list) rather than a routing variant.
+     */
+    inferenceProvider?: string;
+    /** OpenRouter routing variant (`free`, `nitro`, `floor`, `online`, `exacto`) — a closed list, never a provider. */
+    variant?: string;
 }
 declare class InvalidModelRefError extends Error {
     readonly raw: string;
@@ -43,20 +81,120 @@ declare class InvalidModelRefError extends Error {
     constructor(raw: string, message: string);
 }
 /**
- * Parse a model reference in `vendor/product[@route]` form.
+ * Parse a model reference in `[route:]vendor/product[:pin][@route]` form.
  *
  * - `openai/gpt-4o` → `{ vendor: "openai", product: "gpt-4o", route: "openai" }`
  * - `openai/gpt-4o@openrouter` → route "openrouter"
+ * - `deepseek/deepseek-chat:free@openrouter` → route "openrouter", variant "free"
+ * - `meta-llama/Llama-3.1-8B:cerebras@huggingface` → route "huggingface", inferenceProvider "cerebras"
+ * - `openrouter:anthropic/claude-sonnet-4.5` → legacy prefix, route "openrouter"
  *
- * Rejects empty strings, unscoped `@` refs, missing segments, and segments
- * containing `/` or `@`.
+ * Rejects empty strings, unscoped `@` refs, bare ids without a slash, missing
+ * segments, and segments containing `/` or `@`. `@route` wins over the
+ * legacy prefix when both are present.
  */
 declare function parseModelRef(raw: string): ModelRef;
 /**
- * Format a {@link ModelRef} back to its canonical string.
- * Implicit direct routes omit the `@route` suffix.
+ * {@link parseModelRef}, but never throws — returns `undefined` for any
+ * input the strict grammar rejects (bare ids, malformed refs, …). Lenient
+ * handling of non-canonical ids belongs in callers; this just makes the
+ * strict parser safe to probe.
+ */
+declare function tryParseModelRef(raw: string): ModelRef | undefined;
+/**
+ * Format a {@link ModelRef} back to its canonical string
+ * `vendor/product[:pin][@route]`. Implicit direct routes omit the `@route`
+ * suffix. Always emits the canonical suffix form — never the legacy
+ * `route:` prefix — so `formatModelRef(parseModelRef(x))` is stable
+ * (idempotent under re-parse). Prefers `variant` over `inferenceProvider`
+ * when (implausibly) both are set, since parse only ever produces one.
  */
 declare function formatModelRef(ref: ModelRef): string;
+/**
+ * Strip a route-identity `@route` SUFFIX from a model id, returning the bare
+ * id that an UPSTREAM (the provider/gateway, via `ANTHROPIC_MODEL` or the wire
+ * `model`) actually understands. The `@route` suffix is a catalog-join
+ * annotation used to pin which serving route a picked model uses — the gateway
+ * itself never sees it (OpenRouter/Requesty/the llm-endpoint proxy don't
+ * recognise `z-ai/glm-5.2@openrouter`, only `z-ai/glm-5.2`). At spawn the route
+ * is already carried separately (`route.gateway` → base_url), so the suffix is
+ * redundant metadata that must not leak to the wire.
+ *
+ * - `z-ai/glm-5.2@openrouter`            → `z-ai/glm-5.2`
+ * - `deepseek/deepseek-chat:free@openrouter` → `deepseek/deepseek-chat:free` (variant kept)
+ * - `glm-5.2@llm-endpoint`               → `glm-5.2` (routeless proxy alias)
+ * - `claude-opus-4-8`                    → `claude-opus-4-8` (no route, unchanged)
+ * - `openai/gpt-4o`                      → `openai/gpt-4o` (direct route, unchanged)
+ *
+ * Prefers the strict parser so an id is only altered when the trailing token is
+ * a genuine explicit route (`route !== vendor`); the pin (`:variant` /
+ * `:inferenceProvider`) is preserved because gateways accept it. Falls back to
+ * removing only a trailing `@…` for ids the strict grammar rejects (e.g. the
+ * vendor-less `glm-5.2@llm-endpoint`): the SEGMENT grammar forbids `@`
+ * anywhere but the route separator, so the last `@` can only be that.
+ */
+declare function stripRouteSuffix(raw: string): string;
+/**
+ * Reduce a DIRECT-anthropic catalog ref to the BARE product id the native
+ * Anthropic wire expects (the `claude` ACP wrapper's `session/set_config_option`
+ * model selector, and claude-sdk's `env.ANTHROPIC_MODEL`) — both resolve only
+ * bare Anthropic ids (`claude-sonnet-4-5`), never the catalog's canonical
+ * `anthropic/claude-sonnet-4-5` route form. {@link stripRouteSuffix} only peels
+ * the `@route` SUFFIX and deliberately keeps `vendor/product`, so a
+ * direct-anthropic ref survives it prefixed and the wrapper mis-resolves it.
+ *
+ * ONLY a `anthropic/<product>` ref in DIRECT form (route === vendor, i.e. no
+ * gateway `@route`) collapses to `<product>`. Everything else falls through to
+ * {@link stripRouteSuffix} untouched:
+ *   - a GATEWAY-routed anthropic ref (`anthropic/claude-x@openrouter`) keeps its
+ *     `vendor/product` because the gateway needs it,
+ *   - other vendors (`z-ai/glm-5.2@openrouter`, `moonshot/kimi-k2.7-code@llm-endpoint`)
+ *     keep `vendor/product` — those same claude-code/claude-sdk adapters route
+ *     them through `base_url`, where the gateway rejects a bare product,
+ *   - already-bare ids (`claude-sonnet-5`) are unchanged.
+ *
+ * Callers MUST gate this on the adapter being Anthropic-NATIVE (claude-code /
+ * claude-sdk, `provider: "anthropic"`); a `derived-from-model` adapter (hermes,
+ * opencode, …) derives its route FROM the vendor prefix and needs it kept.
+ *
+ * - `anthropic/claude-sonnet-4-5`            → `claude-sonnet-4-5`
+ * - `anthropic/claude-sonnet-4-5@openrouter` → `anthropic/claude-sonnet-4-5`
+ * - `z-ai/glm-5.2@openrouter`                → `z-ai/glm-5.2`
+ * - `claude-sonnet-5`                        → `claude-sonnet-5`
+ */
+declare function stripAnthropicNativeVendor(raw: string): string;
+/**
+ * Generalized form of {@link stripAnthropicNativeVendor} — reduce a
+ * DIRECT-`vendor` catalog ref to the BARE product id a fixed-single-provider
+ * adapter's own wire expects, for ANY vendor, not just Anthropic. Every
+ * adapter whose manifest declares a FIXED `provider` and takes bare model ids
+ * on its native route (claude-code/claude-sdk → anthropic, codex → openai,
+ * gemini → google, …) hits this same class of bug: the catalog's canonical
+ * `vendor/product` form survives onto the wire and the adapter's own
+ * `models.allowed` enum — which declares bare ids — rejects it
+ * (`option_enum_violation`).
+ *
+ * ONLY a `<vendor>/<product>` ref in DIRECT form (route === vendor, i.e. no
+ * gateway `@route`) AND matching the given `vendor` collapses to `<product>`.
+ * Everything else falls through to {@link stripRouteSuffix} untouched:
+ *   - a GATEWAY-routed ref (`openai/gpt-5@openrouter`) keeps its
+ *     `vendor/product` because the gateway needs it,
+ *   - a ref for a DIFFERENT vendor (`z-ai/glm-5.2` handed to an
+ *     `openai`-fixed adapter) keeps `vendor/product` — stripping would
+ *     invent a wrong bare id for a model this adapter doesn't natively serve,
+ *   - already-bare ids (`gpt-5`) are unchanged.
+ *
+ * Callers MUST gate this on the adapter being a FIXED-single-provider,
+ * non-derived-from-model adapter (`routeSelection !== "derived-from-model"`
+ * AND a fixed `provider`); a `derived-from-model` adapter (hermes, pi,
+ * opencode, …) derives its route FROM the vendor prefix and needs it kept.
+ *
+ * - `openai/gpt-5`               (vendor "openai") → `gpt-5`
+ * - `openai/gpt-5@openrouter`    (vendor "openai") → `openai/gpt-5`
+ * - `z-ai/glm-5.2`               (vendor "openai") → `z-ai/glm-5.2` (mismatch, unchanged)
+ * - `gpt-5`                      (vendor "openai") → `gpt-5` (already bare)
+ */
+declare function stripFixedNativeVendor(raw: string, vendor: string): string;
 /** True when `raw` matches the `vendor/product[@route]` shape. */
 declare function isModelRefString(raw: string): boolean;
 interface ModelRouteLimits {
@@ -124,6 +262,7 @@ declare function clearCustomRoutes(): void;
  *   openai/gpt-4o            → direct OpenAI pricing / transport
  *   openai/gpt-4o@openrouter → OpenRouter route pricing / transport
  *   openai/gpt-4o@requesty   → Requesty route pricing / transport
+ *   meta-llama/Llama-3.1-8B:cerebras@huggingface → HuggingFace, pinned to the "cerebras" inference provider
  *   openai/gpt-4o@agentik-proxy → custom route config (if registered)
  *
  * Bare legacy ids (e.g. `gpt-4o`, `claude-sonnet-4-5`) are also accepted and
@@ -155,4 +294,4 @@ interface ModelRefDiagnostic {
  */
 declare function diagnoseModelRef(input: string | ModelRef): ModelRefDiagnostic | undefined;
 
-export { type CustomRouteConfig, InvalidModelRefError, type ModelProductMeta, type ModelRef, type ModelRefDiagnostic, type ModelRouteAvailability, type ModelRouteLimits, type ModelRouteMeta, type ModelRouteTransport, type ResolvedLlmModelRoute, type ResolvedModelRoute, clearCustomRoutes, diagnoseModelRef, formatModelRef, isModelRefString, parseModelRef, registerCustomRoute, resolveCustomRoute, resolveLlmModelRoute };
+export { type CustomRouteConfig, InvalidModelRefError, type ModelProductMeta, type ModelRef, type ModelRefDiagnostic, type ModelRouteAvailability, type ModelRouteLimits, type ModelRouteMeta, type ModelRouteTransport, OPENROUTER_VARIANTS, type OpenRouterVariant, type ResolvedLlmModelRoute, type ResolvedModelRoute, clearCustomRoutes, diagnoseModelRef, formatModelRef, isModelRefString, parseModelRef, registerCustomRoute, resolveCustomRoute, resolveLlmModelRoute, stripAnthropicNativeVendor, stripFixedNativeVendor, stripRouteSuffix, tryParseModelRef };