@oh-my-pi/pi-catalog 18.4.3 → 18.4.5

package/src/compat/rules/README.md

@@ -152,7 +152,7 @@ discovery {
 
 ## Cascade grammar
 
-A cascade document starts with `class`, `provider`, or `on-api`. Root `on-api` declares a transport contract independent of model identity and provider name. Every selector adds a conjunct to the current rule. `on` scopes by deployment provider; `on-api` scopes by request adapter, including custom provider names. Axis directives may appear directly in any permitted scope, and nested selector blocks may appear alongside them.
+A cascade document starts with `class`, `provider`, or `on-api`. Root `on-api` declares a transport contract independent of model identity and provider name. Every selector adds a conjunct to the current rule. `on` scopes by deployment provider; `on-api` scopes by request adapter, including custom provider names; `on-upstream` scopes by the actual upstream selected behind that deployment. An upstream never changes the deployment provider or imports that upstream's direct-host rules. Axis directives may appear directly in any permitted scope, and nested selector blocks may appear alongside them.
 
 ```kdl
 class "gemini" {
@@ -182,14 +182,15 @@ provider "openrouter" {
 | Selector   | Form                                     | Matching semantics                                                                                                                                                             |
 | ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `class`    | `class "id" { ... }`                     | Exact class ID. At document root it may contain `on`, `on-api`, `family`, `revision`, and `models`. Under `provider` it may contain `family`, `revision`, and `models`.        |
-| `provider` | `provider "id" { ... }`                  | Exact provider ID. It is root-only and may contain `class` and `models`.                                                                                                       |
+| `provider` | `provider "id" { ... }`                  | Exact provider ID. It is root-only and may contain `class`, `on-api`, and `models`.                                                                                           |
 | `on`       | `on "provider-a" "provider-b" { ... }`   | One or more provider IDs, combined as OR. It is allowed only under a root `class`, and may contain `family`, `revision`, and `models`.                                         |
-| `on-api`   | `on-api "adapter-a" "adapter-b" { ... }` | One or more request adapter IDs, combined as OR. At document root it may contain `class` and `models`; under a root `class` it may contain `family`, `revision`, and `models`. |
+| `on-api`   | `on-api "adapter-a" "adapter-b" { ... }` | One or more request adapter IDs, combined as OR. At document root it may contain `class` and `models`; under a root `class` or `provider` it may contain `family`, `revision`, and `models`. |
 | `family`   | `family "id" { ... }`                    | Exact classified family ID. It may contain `revision` and `models`. A target with no family does not match.                                                                    |
 | `revision` | `revision ">=2.5 <4" { ... }`            | A non-empty, whitespace-separated conjunction of comparisons. It may contain `models`. A target with no revision does not match.                                               |
-| `models`   | `models "id" "vendor/*" { ... }`         | One or more alternatives, combined as OR. It cannot contain another selector. `token="name"` matches an ASCII-case-insensitive token bounded by non-alphanumerics.             |
+| `models`   | `models "id" "vendor/*" { ... }`         | One or more alternatives, combined as OR. It may contain only `on-upstream`. `token="name"` matches an ASCII-case-insensitive token bounded by non-alphanumerics.                 |
+| `on-upstream` | `on-upstream "a" "b" { ... }`        | Exact selected upstream IDs, combined as OR. Allowed inside any selector scope once; preserves the containing scope's other permitted children. Absent upstream never matches. |
 
-Class, provider/`on`, `on-api`, and family selector values are compared exactly and case-sensitively to the structured resolve target. Revision operators are `>=`, `>`, `<=`, `<`, and `=`; operands have one to three dot-separated unsigned 8-bit components, omitted components zero.
+Every selector scope may additionally contain `on-upstream`; it cannot replace an already constrained upstream. Class, provider/`on`, `on-api`, `on-upstream`, and family values are compared exactly and case-sensitively to the structured resolve target. Revision operators are `>=`, `>`, `<=`, `<`, and `=`; operands have one to three dot-separated unsigned 8-bit components, omitted components zero.
 
 A `models` string without `*` is an exact, case-sensitive match against the provider-relative model identifier. A string containing `*` is an anchored, ASCII-case-insensitive wildcard match. Prefer taxonomy ranks; retain exact/glob lists only when they isolate the census member set exactly, and keep a `// residue:` comment explaining why ranks do not.
 
@@ -197,6 +198,8 @@ A `models` string without `*` is an exact, case-sensitive match against the prov
 
 `buildDiscoveredModel(spec, providerType)` resolves the catalog `discovery-api` axis before materializing compatibility. It preserves the credential-bearing provider ID and records `providerType` as the backend used for provider selectors on subsequent rebuilds. Ordinary `buildModel` preserves its input API. This lets custom-named llama.cpp deployments reuse the same rules without model-specific discovery code.
 
+`resolveModelPolicy(spec, { upstream })` resolves the selected route without mutating the model identity. Call it again when retry routing selects another upstream. Its typed `request` record carries request-shaping axes (reasoning history, disabled-effort semantics, Anthropic thinking mode, Responses options, and Google thinking dialect); shared transport fields remain in `compat`. Both records use the same per-axis cascade, precedence, ambiguity checks, and upstream-aware cache key. Request fields have the `request` applicability record in `axes.ts`, so they do not leak into shared transport compat objects. See [`providers/factory-droid.kdl`](providers/factory-droid.kdl) for the upstream-scoped consumer.
+
 ### Axis vocabulary and value shapes
 
 The directive vocabulary is closed and lives in **`src/compat/axes.ts`** — one table mapping each kebab-case directive to its resolved camelCase field, namespace (`wire` / `thinking` / `catalog`), value shape, applicable compat records, and (for enums) accepted values. The compiler rejects unknown directives and out-of-vocabulary values against that table; consult it rather than a duplicated table here.
@@ -204,12 +207,16 @@ The directive vocabulary is closed and lives in **`src/compat/axes.ts`** — one
 The three value shapes are:
 
 - **Scalar**: exactly one KDL boolean, integer, float, or string argument and no children. `#null` is rejected.
-- **Array**: one or more scalar arguments and no children; it resolves to a JSON array.
+- **Array**: one or more scalar arguments and no children; it resolves to a JSON array. Axes marked `emptyArray` in `axes.ts` also accept a bare directive, which assigns an explicit empty list (`region-upstreams-eu` with no arguments: the region never serves the model).
 - **Object**: no arguments and a child block, including an empty block. Child names are kebab-case: an axis-directive spelling compiles to its resolved axis key (`template-reasoning-effort` → `qwenTemplateReasoningEffort`), anything else converts mechanically (`input-threshold` → `inputThreshold`); camelCase names are a compile error. `extra-body` payloads (top-level or nested) are the exception — their child names are literal wire JSON keys copied verbatim (`enable_thinking`). Each child is either one scalar or another object; arrays are not representable inside an object payload.
 
 A rule cannot assign the same resolved axis twice in one block.
 One object axis carries a computed form: `long-context-cost` accepts either the absolute rates (`input-threshold` + `input`/`output`/`cache-read`/`cache-write`) or `input-threshold` + `multiplier` (with optional `input-threshold-inclusive`), which derives the tier from the row's live base price at build time so the rule tracks upstream list-price updates (xAI's SuperGrok 200K tier). Rows without a token price carry no tier.
 
+`context-window-authoritative #true` preserves a host's supplied context window through runtime model selection instead of applying inferred expansion or reference-price-tier caps. Explicit user context overrides still apply afterward. It applies to rows materialized through `buildModel` (discovery and regenerated bundles). See [`providers/factory-droid.kdl`](providers/factory-droid.kdl).
+
+The routed-subscription registry axes (`upstream-rotation`, `region-upstreams-global|us|eu`, `region-limits-eu`, `credit-rates`, `list-price-from`, `routing-family`, `policy-aliases`, `entitlement`, `default-reasoning-off`) describe a gateway whose proxy fans one model out to several upstreams. They are read through `src/compat/factory-droid.ts` by Factory Droid discovery and its request provider, not materialized by `buildModel`. A provider-wide `region-upstreams-*` rule is the upstream serving table and a model rule replaces it for that region. `list-price-from "<provider>" ["<id>"]` shows a bundled row's list price beside the subscription's own billing; unlike seed values it is resolved at runtime and degrades to the seed's zero cost when the row is gone. See [`providers/factory-droid.kdl`](providers/factory-droid.kdl), whose wire and billing pool per model are `api-routes` and `quota-tiers` rules in `runtime/behavior.kdl`.
+
 ### Time-based pricing
 
 The catalog object axis `time-based-cost` materializes into `ModelCost.timeBased`. It uses **named child objects**, not KDL arrays or repeated anonymous windows. For example, inside a matching provider/model scope:
@@ -258,7 +265,7 @@ Rules resolve independently per axis. A matching rule is ranked by:
 The tuple is compared lexicographically, greatest first:
 
 - model exactness is `2` when any matching `models` selector is exact, `1` when the best matching selector is a glob or token, and `0` when the rule has no `models` selector;
-- dimension count is the number of present dimensions among class, provider/`on`, API/`on-api`, family, revision, and models;
+- dimension count is the number of present dimensions among class, provider/`on`, API/`on-api`, upstream/`on-upstream`, family, revision, and models;
 - priority is the local block's `priority`, defaulting to `0`.
 
 The highest-ranked matching assignment wins for that axis. Two distinct rules that tie on all three components and assign the same axis are an ambiguity error even if their values are equal. File and declaration order never resolve the tie; add an explicit priority only after confirming the overlap is intentional.
@@ -417,6 +424,7 @@ A `seed` _defines_ bundled rows for providers whose catalog cannot be discovered
 | `always`   | Every regeneration. Same-id upstream/discovery rows win dedup.            |
 | `fallback` | Only when the provider's authoritative catalog discovery did not succeed. |
 | `empty`    | Only when no other source produced a row for the provider.                |
+| `never`    | Never; the provider's runtime model manager is the only consumer.         |
 
 `precedence="seed"` prepends the rows after the previous-snapshot merge and cross-provider reference fills, so the authored row wins dedup and same-id rows on other hosts never overwrite its name or capabilities (QwenCloud Token Plan, Meta). The default `upstream` precedence appends before the snapshot merge, so the current seed — not a stale snapshot copy — is the fallback row.
 

package/src/compat/rules/auth/_order.kdl

@@ -5,8 +5,8 @@ login-order "openai-codex" "anthropic" "zai" "zai-coding-plan" "kimi-code" "open
 	"cursor" "devin" "google-antigravity" "google-gemini-cli" "openai-codex-device" "xai" "xai-oauth" \
 	"gitlab-duo" "gitlab-duo-agent" "alibaba-coding-plan" "alibaba-token-plan" "aiand" "abliteration" "zhipu-coding-plan" \
 	"umans" "qwen-portal" "sakana" "minimax-code" "minimax-code-cn" "xiaomi" "xiaomi-token-plan-sgp" \
-	"xiaomi-token-plan-ams" "xiaomi-token-plan-cn" "firepass" "cline-pass" "commandcode" "charm-hyper" "deepseek" "stepfun" "muse-code" "meta" "moonshot" \
-	"cerebras" "baseten" "fireworks" "together" "nvidia" "novita" "deepinfra" "huggingface" "perplexity" \
+	"xiaomi-token-plan-ams" "xiaomi-token-plan-cn" "firepass" "cline-pass" "factory-droid" "commandcode" "charm-hyper" "deepseek" "stepfun" "muse-code" "meta" "moonshot" \
+	"cerebras" "baseten" "helmcode" "fireworks" "together" "nvidia" "novita" "deepinfra" "huggingface" "perplexity" \
 	"qianfan" "venice" "siliconflow" "siliconflow-cn" "synthetic" "nanogpt" "wafer-serverless" "coreweave" \
 	"vercel-ai-gateway" "cloudflare-ai-gateway" "litellm" "kilo" "zenmux" "opencode-zen" "opencode-go" \
 	"yolo-auto" "tavily" "kagi" "exa" "parallel" "typesafe" "ollama" "ollama-cloud" "lm-studio" "llama.cpp" "vllm" \

package/src/compat/rules/auth/factory-droid.kdl

@@ -0,0 +1,28 @@
+auth "factory-droid" {
+	name "Factory Droid"
+	org-scoped-identity #true
+	// WorkOS public client: the access token authorizes the Factory LLM proxy.
+	login "device-code" {
+		client-id "client_01HNM792M5G5G1A2THWPXKFMXB"
+		device url="https://api.workos.com/user_management/authorize/device" timeout-ms=15000 {
+			headers { Accept "application/json" }
+		}
+		token url="https://api.workos.com/user_management/authenticate" timeout-ms=15000 {
+			headers { Accept "application/json" }
+		}
+		credential {
+			expires "jwt" skew-ms=0 fallback-ms=86400000
+			email "user.email" claim="email"
+			account-id "user.id" claim="sub"
+			// WorkOS organization_id is internal; only this claim can be used as X-Factory-Org-Id.
+			org-id claim="external_org_id"
+		}
+		after-exchange hook="factory-droid-region"
+	}
+	refresh {
+		token url="https://api.workos.com/user_management/authenticate" timeout-ms=15000 {
+			headers { Accept "application/json" }
+		}
+		after-refresh hook="factory-droid-region"
+	}
+}

package/src/compat/rules/auth/helmcode.kdl

@@ -0,0 +1,9 @@
+auth "helmcode" {
+	name "Helmcode"
+	login "api-key" {
+		auth-url "https://cloud.helmcode.com"
+		instructions "Copy your API key from the Helmcode dashboard"
+		prompt "Paste your Helmcode API key" placeholder="sk-..."
+		validate "models-endpoint" label="Helmcode" url="https://api.helmcode.com/v1/models"
+	}
+}

package/src/compat/rules/classes/anthropic.kdl

@@ -7,11 +7,11 @@ class "anthropic" {
 			thinking-prefix-binding #true
 		}
 	}
-	// On-demand compaction (compact-2026-09-04) is available on the Claude
-	// API and Vertex, not Amazon Bedrock or unverified gateway deployments.
+	// On-demand compaction (compact-2026-09-04) works on the Claude API, Vertex,
+	// and Amazon Bedrock's `/anthropic` routes, not Bedrock Converse.
 	// Foundry / Claude Platform on AWS are first-party Anthropic routes whose
 	// effective URLs are checked at request time.
-	on "anthropic" "google-vertex" {
+	on "anthropic" "google-vertex" "amazon-bedrock" "bedrock-mantle" {
 		family "fable" {
 			revision ">=5" {
 				supports-server-compaction #true
@@ -68,6 +68,10 @@ class "anthropic" {
 	family "sonnet" {
 		revision ">=5.5 <6" {
 			supports-forced-tool-choice #false
+			// `thinking: {type: "disabled"}` is a 400; `between_tools` is the
+			// lowest thinking setting.
+			// https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking
+			supports-between-tools-thinking #true
 			// Signed thinking is bound to the exact preceding conversation.
 			thinking-prefix-binding #true
 		}
@@ -104,7 +108,6 @@ class "anthropic" {
 				supports-mid-conversation-tool-changes #true
 				supports-turn-scoped-system #true
 				supports-per-message-effort #true
-				supports-thinking-binding-controls #true
 			}
 		}
 		family "opus" {
@@ -118,6 +121,15 @@ class "anthropic" {
 			}
 		}
 	}
+	// Vertex rejects `thinking.block_binding` on Sonnet 5.5 with 400
+	// `thinking.adaptive.block_binding: Extra inputs are not permitted`.
+	on "anthropic" "cloudflare-ai-gateway" {
+		family "sonnet" {
+			revision ">=5.5" {
+				supports-thinking-binding-controls #true
+			}
+		}
+	}
 	on "aimlapi" "gitlab-duo" "kilo" "nanogpt" "venice" {
 		thinking-efforts "minimal" "low" "medium" "high" "xhigh"
 	}

package/src/compat/rules/providers/cursor.kdl

@@ -8,6 +8,11 @@ provider "cursor" {
 	}
 
 	thinking-mode "effort"
+	// Cursor's default route selects a differently priced backing model per request.
+	models "default" {
+		pricing-status "variable"
+	}
+
 	class "anthropic" {
 		family "fable" {
 			requires-cursor-tool-schema-projection #true
@@ -211,9 +216,10 @@ provider "cursor" {
 		}
 	}
 	// Claude Opus 5 Fast: the docs name the fast wire ids but publish no
-	// fast multiplier, so fast bills at the base Opus 5 card.
+	// fast rate. Discovery applies AvailableModels' declared fast multiplier
+	// (2x); the base card only seeds rows discovery left unpriced.
 	models "claude-opus-5-high-fast" "claude-opus-5-low-fast" "claude-opus-5-medium-fast" "claude-opus-5-thinking-max-fast" "claude-opus-5-thinking-xhigh-fast" {
-		cost-patch {
+		cost-fallback {
 			input 5.0
 			output 25.0
 			cache-read 0.5
@@ -231,9 +237,10 @@ provider "cursor" {
 		}
 	}
 	// Claude Opus 5.5 Fast: the docs name the fast wire id but publish no
-	// fast multiplier, so fast bills at the base Opus 5.5 card.
+	// fast rate. Discovery prices it from AvailableModels' declared fast
+	// multiplier; the base card only seeds rows discovery left unpriced.
 	models "claude-opus-5-5-fast" {
-		cost-patch {
+		cost-fallback {
 			input 4.0
 			output 20.0
 			cache-read 0.2
@@ -267,8 +274,9 @@ provider "cursor" {
 			cache-write 0
 		}
 	}
-	// Grok 4.5: $2/$6, cache read $0.50, no write fee.
-	models "cursor-grok-4.5" {
+	// Grok 4.5: $2/$6, cache read $0.50, no write fee. Legacy id plus the
+	// per-effort wire slugs AvailableModels serves.
+	models "cursor-grok-4.5" "cursor-grok-4.5-low" "cursor-grok-4.5-medium" "cursor-grok-4.5-high" {
 		cost-patch {
 			input 2.0
 			output 6.0
@@ -277,7 +285,7 @@ provider "cursor" {
 		}
 	}
 	// Grok 4.5 Fast: $4/$18, cache read $1.00. Output is 3x base per docs.
-	models "cursor-grok-4.5-fast" {
+	models "cursor-grok-4.5-fast" "cursor-grok-4.5-low-fast" "cursor-grok-4.5-medium-fast" "cursor-grok-4.5-high-fast" {
 		cost-patch {
 			input 4.0
 			output 18.0
@@ -285,8 +293,9 @@ provider "cursor" {
 			cache-write 0
 		}
 	}
-	// Grok 4.6: $2/$6, cache read $0.50, no write fee.
-	models "cursor-grok-4.6" {
+	// Grok 4.6: $2/$6, cache read $0.50, no write fee. Legacy id plus the
+	// per-effort wire slugs AvailableModels serves.
+	models "cursor-grok-4.6" "cursor-grok-4.6-low" "cursor-grok-4.6-medium" "cursor-grok-4.6-high" "cursor-grok-4.6-xhigh" {
 		cost-patch {
 			input 2.0
 			output 6.0
@@ -295,7 +304,8 @@ provider "cursor" {
 		}
 	}
 	// Grok 4.6 Fast: $4/$12, cache read $1.00.
-	models "cursor-grok-4.6-fast" {
+	models "cursor-grok-4.6-fast" "cursor-grok-4.6-low-fast" "cursor-grok-4.6-medium-fast" "cursor-grok-4.6-high-fast" \
+		"cursor-grok-4.6-xhigh-fast" {
 		cost-patch {
 			input 4.0
 			output 12.0
@@ -448,10 +458,10 @@ provider "cursor" {
 			cache-write 0
 		}
 	}
-	// GPT-5.2 Fast: the docs publish no fast multiplier, so fast bills at
-	// the base GPT-5.2 card.
+	// GPT-5.2 Fast: the docs publish no fast rate. Discovery applies the
+	// declared fast multiplier; the base card only seeds unpriced rows.
 	models "gpt-5.2-fast" "gpt-5.2-high-fast" "gpt-5.2-low-fast" "gpt-5.2-xhigh-fast" {
-		cost-patch {
+		cost-fallback {
 			input 1.75
 			output 14.0
 			cache-read 0.175
@@ -486,9 +496,10 @@ provider "cursor" {
 			cache-write 0
 		}
 	}
-	// GPT-5.3 Codex Fast: no fast multiplier published; base card applies.
+	// GPT-5.3 Codex Fast: no fast rate published; discovery applies the
+	// declared multiplier, and the base card only seeds unpriced rows.
 	models "gpt-5.3-codex-fast" "gpt-5.3-codex-high-fast" "gpt-5.3-codex-low-fast" "gpt-5.3-codex-xhigh-fast" {
-		cost-patch {
+		cost-fallback {
 			input 1.75
 			output 14.0
 			cache-read 0.175
@@ -543,9 +554,10 @@ provider "cursor" {
 			cache-write 0
 		}
 	}
-	// GPT-5.5 Fast: higher fast rates are unpublished; base card applies.
+	// GPT-5.5 Fast: fast rates are unpublished; discovery applies the declared
+	// multiplier, and the base card only seeds unpriced rows.
 	models "gpt-5.5-fast" {
-		cost-patch {
+		cost-fallback {
 			input 5.0
 			output 30.0
 			cache-read 0.5