@blockrun/clawrouter 0.12.249 → 0.12.250

package/README.md

@@ -46,10 +46,10 @@ Every other LLM router was built for **human developers** — create an account,
 
 ClawRouter is built for the agent-first world:
 
-- **Starts at $0** — <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA models are free forever (incl. 1M-context DeepSeek V4 Flash + a vision-capable Nemotron Omni)
+- **Starts at $0** — <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA models are free forever (incl. reasoning-grade Step 3.7 Flash + a vision-capable Nemotron Omni)
 - **No accounts** — a wallet is generated locally, no signup
 - **No API keys** — your wallet signature IS authentication
-- **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring picks the right model automatically
+- **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring + constraint-first ranking ([router-core](https://github.com/BlockRunAI/router-core)) picks the right model automatically
 - **No credit cards** — agents pay per-request with USDC via [x402](https://x402.org)
 - **No trust required** — runs locally, <1ms routing, zero external dependencies
 
@@ -188,14 +188,12 @@ response = client.chat.completions.create(model="blockrun/auto", messages=[...])
 
 Choose your routing strategy with `/model <profile>`:
 
-| Profile       | Strategy           | Savings                                                                                                                                                                                                                                                                                           | Best For             |
-| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| `/model free` | Free NVIDIA models | **100%**                                                                                                                                                                                                                                                                                          | $0 balance, learning |
-| `/model auto` | Balanced (default) | † Withheld from `/v1/models` — the router still calls it by direct ID, but you will not find it on the public pricing page. See [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json), which prices the published savings claim on visible models only. |
-
-**<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->%** | General use |
-| `/model eco` | Cheapest possible | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Maximum savings |
-| `/model premium` | Best quality | 0% | Mission-critical |
+| Profile          | Strategy           | Savings                                                                            | Best For             |
+| ---------------- | ------------------ | ---------------------------------------------------------------------------------- | -------------------- |
+| `/model free`    | Free NVIDIA models | **100%**                                                                           | $0 balance, learning |
+| `/model auto`    | Balanced (default) | **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->%** | General use          |
+| `/model eco`     | Cheapest possible  | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%**   | Maximum savings      |
+| `/model premium` | Best quality       | 0%                                                                                 | Mission-critical     |
 
 **Shortcuts:** `/model grok`, `/model br-sonnet`, `/model gpt5`, `/model o3`
 
@@ -205,18 +203,31 @@ Choose your routing strategy with `/model <profile>`:
 
 **100% local routing. <1ms latency. Zero external API calls.**
 
-The scorer weighs <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions of the request:
+Routing decisions come from [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) — Router Core **V3.4**, the constraint-first portfolio router shared by every BlockRun product (ClawRouter, Franklin, the `@blockrun/llm` SDKs, ClawRouter-Hermes). ClawRouter inlines it at build time, pinned to an exact commit, and injects its live model catalog at startup.
 
 ```
-Request → Weighted Scorer → Tier → Best Model → Response
+Request → 15-dimension scorer → tier + task shape
+        → hard filters (tools · vision · context · max-output · structured output)
+        → rank survivors (quality · capability · cost · speed · reliability)
+        → winner + ordered fallback chain → Response
 ```
 
-| Tier      | ECO Model                               | AUTO Model                              | PREMIUM Model                |
-| --------- | --------------------------------------- | --------------------------------------- | ---------------------------- |
-| SIMPLE    | step-3.7-flash (**FREE**)               | gemini-2.5-flash ($0.30/$2.50)          | kimi-k2.7 † ($0.95/$4.00)    |
-| MEDIUM    | gemini-3.1-flash-lite ($0.25/$1.50)     | kimi-k2.7 ($0.95/$4.00)                 | gpt-5.3-codex ($1.75/$14.00) |
-| COMPLEX   | gemini-3.1-flash-lite ($0.25/$1.50)     | gemini-3.1-pro ($2/$12)                 | claude-fable-5 ($10/$50)     |
-| REASONING | grok-4-1-fast-reasoning † ($0.20/$0.50) | grok-4-1-fast-reasoning † ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15)   |
+1. **Classify** — a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension weighted scorer picks a tier (`SIMPLE` / `MEDIUM` / `COMPLEX` / `REASONING`); a task classifier labels the shape of the work (`code_agent`, `tool_agent`, `reasoning_math`, `long_context`, `vision`, …). Turns that actually need their tools switch to agent-tuned tiers automatically.
+2. **Filter** — every model that cannot satisfy the request is dropped _before_ anything is scored. A model that can't call tools, can't read the image, or can't hold the conversation never gets to win on price.
+3. **Rank** — survivors are scored on task quality, capability, estimated cost, speed and reliability, with per-profile weights (`eco` leans on cost, `premium` on quality and reliability).
+4. **Recover** — the whole ranked list rides along as the fallback chain, so a provider timeout or 5xx costs a retry, not the task.
+
+| Tier      | ECO Model                               | AUTO Model                              | PREMIUM Model                | AGENTIC Model ‡            |
+| --------- | --------------------------------------- | --------------------------------------- | ---------------------------- | -------------------------- |
+| SIMPLE    | step-3.7-flash (**FREE**)               | gemini-2.5-flash ($0.30/$2.50)          | kimi-k2.7 † ($0.95/$4.00)    | gpt-4o-mini ($0.15/$0.60)  |
+| MEDIUM    | gemini-3.1-flash-lite ($0.25/$1.50)     | kimi-k2.7 † ($0.95/$4.00)               | gpt-5.3-codex ($1.75/$14.00) | kimi-k2.7 † ($0.95/$4.00)  |
+| COMPLEX   | gemini-3.1-flash-lite ($0.25/$1.50)     | gemini-3.1-pro ($2/$12)                 | claude-fable-5 ($10/$50)     | claude-sonnet-4.6 ($3/$15) |
+| REASONING | grok-4-1-fast-reasoning † ($0.20/$0.50) | grok-4-1-fast-reasoning † ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15)   | claude-sonnet-4.6 ($3/$15) |
+
+† Withheld from `/v1/models` — the router still calls it by direct ID, but you will not find it on the public pricing page. See [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json), which prices the published savings claim on visible models only.
+‡ Auto-selected in any profile when the turn actually needs its attached tools; prefers models that keep going instead of stopping to ask.
+
+These are the curated primaries; every tier carries a benchmark-ordered fallback chain — full chains and per-profile ranking weights in [docs/routing-profiles.md](docs/routing-profiles.md). On router-core's frozen three-arm agent benchmark (τ-bench, BrowseComp, Terminal-Bench) the V3.4 policy completed **57%** of tasks vs **49%** for the previous rules router, at **6.4%** lower cost per successful task — and spent **8.9%** of the tokens a pinned flagship would have.
 
 **<!-- br:savings.autoVsBaselinePct -->88<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning Claude Opus 5** for the same traffic, on `auto`; **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** on `eco`.
 
@@ -227,6 +238,8 @@ answer. Models withheld from `/v1/models` are excluded from the mix — pricing
 public claim on a model you cannot look up is not defensible — which makes the
 number conservative.
 
+Rollback lever: `routing.strategy: "rules"` restores the V2 primary-first selector; `routing.shadow` compares both locally without a second paid call.
+
 ---
 
 ## Image Generation
@@ -434,7 +447,6 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
 | google/gemini-3-flash-preview               |     $0.50 |      $3.00 |    $0.0018 | 1M      | vision                                       |
 | moonshot/kimi-k2.5                          |     $0.60 |      $3.00 |    $0.0018 | 262K    | reasoning, vision, agentic, tools            |
 | moonshot/kimi-k2.7                          |     $0.95 |      $4.00 |    $0.0025 | 262K    | reasoning, vision, agentic, tools            |
-| moonshot/kimi-k3                            |     $3.00 |     $15.00 |    $0.0110 | 1M      | reasoning, vision, agentic, tools            |
 
 ### Mid-Range Models ($0.001–$0.01/request)
 
@@ -478,13 +490,14 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
 | openai/gpt-5.6-sol          |     $5.00 |     $30.00 |    $0.0175 | 1M      | reasoning, vision, agentic, tools |
 | openai/gpt-5.6-sol-pro      |     $5.00 |     $30.00 |    $0.0175 | 1M      | reasoning, vision, agentic, tools |
 | openai/gpt-5.5              |     $5.00 |     $30.00 |    $0.0175 | 1M      | reasoning, vision, agentic, tools |
+| moonshot/kimi-k3            |     $3.00 |     $15.00 |    $0.0110 | 1M      | reasoning, vision, agentic, tools |
 | openai/chat-latest          |     $5.00 |     $30.00 |    $0.0175 | 128K    | vision, tools                     |
 | openai/o1                   |    $15.00 |     $60.00 |    $0.0375 | 200K    | reasoning, tools                  |
 | openai/gpt-5.2-pro          |    $21.00 |    $168.00 |    $0.0945 | 400K    | reasoning, tools                  |
 | openai/gpt-5.4-pro          |    $30.00 |    $180.00 |    $0.1050 | 400K    | reasoning, tools                  |
 | openai/gpt-5.5-pro          |    $30.00 |    $180.00 |    $0.1050 | 1M      | reasoning, vision, tools          |
 
-> **Free tier:** several NVIDIA-hosted models cost nothing — `/model free` smart-routes across them, or pick one directly (e.g., `/model nemotron-omni` for vision, `/model step-flash` for reasoning, `/model mistral-nemotron` for instruction following).
+> **Free tier:** <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA-hosted models cost nothing — `/model free` pins the free default (`step-3.7-flash`, with the other four as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model nemotron-omni` for vision, `/model step-flash` for reasoning, `/model mistral-nemotron` for instruction following).
 > **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
 
 ---
@@ -700,7 +713,7 @@ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:m
 | [Documentation](https://blockrun.ai/docs)              | Full docs                                                               |
 | [Model Pricing](https://blockrun.ai/models)            | All models & prices                                                     |
 | [Image Generation & Editing](docs/image-generation.md) | API examples, <!-- br:models.image -->9<!-- /br:models.image --> models |
-| [Routing Profiles](docs/routing-profiles.md)           | ECO/AUTO/PREMIUM details                                                |
+| [Routing Profiles](docs/routing-profiles.md)           | ECO/AUTO/PREMIUM/AGENTIC tiers, fallback chains, ranking weights        |
 | [Architecture](docs/architecture.md)                   | Technical deep dive                                                     |
 | [Configuration](docs/configuration.md)                 | Environment variables                                                   |
 | [Troubleshooting](docs/troubleshooting.md)             | Common issues                                                           |

package/dist/cli.js

@@ -36894,12 +36894,16 @@ var init_models = __esm({
       "xai/grok-3-fast": "xai/grok-4-fast-reasoning",
       // delisted (too expensive)
       // NVIDIA — backward compat aliases (nvidia/xxx → free/xxx)
-      // Default free model is gpt-oss-120b (heavy user demand). New free models
-      // added 2026-04-29 — deepseek-v4-pro/flash, nemotron-omni — are additions,
-      // not replacements. Retired-with-redirect entries below mirror BlockRun
-      // server-side decommissioning of slow models (nemotron family, etc.).
-      nvidia: "free/gpt-oss-120b",
+      // Default free model is step-3.7-flash — the same model @blockrun/router-core
+      // opens the eco SIMPLE tier on. It replaced gpt-oss-120b on 2026-08-29:
+      // gpt-oss-120b went dead upstream on 2026-08-16 (NVIDIA still LISTS it, but a
+      // completion hangs until the client gives up — blockrun #391 retargeted its
+      // whole free cascade off it, and the gateway now answers 400 Unknown model
+      // for the `free/` id). Pins that NAME gpt-oss stay routable below — the
+      // gateway server-redirects them — but nothing generic may land on it.
+      nvidia: "free/step-3.7-flash",
       "gpt-120b": "free/gpt-oss-120b",
+      // names the model itself — gateway redirects
       "gpt-20b": "free/gpt-oss-20b",
       "nvidia/gpt-oss-120b": "free/gpt-oss-120b",
       "nvidia/gpt-oss-20b": "free/gpt-oss-20b",
@@ -36974,9 +36978,10 @@ var init_models = __esm({
       // no live free Llama left (maverick died 2026-07)
       // qwen3-coder-480b retired 2026-06-14 → seed-oss-36b, which then EOL'd 2026-08-03.
       // Follow the gateway's own retarget rather than chaining to a second dead model.
-      "qwen-coder": "free/gpt-oss-120b",
-      "qwen-coder-free": "free/gpt-oss-120b",
-      "qwen-thinking": "free/gpt-oss-120b",
+      "qwen-coder": "free/step-3.7-flash",
+      // no live free Qwen; follows the free default
+      "qwen-coder-free": "free/step-3.7-flash",
+      "qwen-thinking": "free/step-3.7-flash",
       // qwen3-next died 2026-07-17; no live free Qwen left
       "qwen3-next": "free/qwen3-next-80b-a3b-instruct",
       // explicit-ish pin — gateway redirects
@@ -36987,8 +36992,8 @@ var init_models = __esm({
       // seed-oss pins name the model itself — kept routable, the gateway redirects them.
       "seed-oss": "free/seed-oss-36b",
       "seed-oss-36b": "free/seed-oss-36b",
-      "coder-free": "free/gpt-oss-120b",
-      // generic "a free coder" → follows the gateway retarget
+      "coder-free": "free/step-3.7-flash",
+      // generic "a free coder" → follows the free default
       "mistral-nemotron": "free/mistral-nemotron",
       "step-flash": "free/step-3.7-flash",
       "step-3.7-flash": "free/step-3.7-flash",
@@ -37000,21 +37005,25 @@ var init_models = __esm({
       "nemotron-omni": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       "nano-omni": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       "vision-free": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
-      // Retired shorthand aliases redirect to live successors (2026-07-17 map:
-      // llama-4-maverick died, so the old catch-all target moved to gpt-oss-120b)
+      // Retired shorthand aliases redirect to live successors. The catch-all target
+      // moved llama-4-maverick → gpt-oss-120b (2026-07-17) → step-3.7-flash
+      // (2026-08-29, gpt-oss-120b hung upstream; see the NVIDIA block above).
       nemotron: "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       // strongest live Nemotron
-      "nemotron-ultra": "free/gpt-oss-120b",
-      "nemotron-253b": "free/gpt-oss-120b",
-      "nemotron-super": "free/gpt-oss-120b",
-      "nemotron-49b": "free/gpt-oss-120b",
-      "nemotron-120b": "free/gpt-oss-120b",
-      devstral: "free/gpt-oss-120b",
-      // seed-oss-36b EOL'd 2026-08-03; matches blockrun's own retarget
-      "devstral-2": "free/gpt-oss-120b",
+      "nemotron-ultra": "free/step-3.7-flash",
+      "nemotron-253b": "free/step-3.7-flash",
+      "nemotron-super": "free/step-3.7-flash",
+      "nemotron-49b": "free/step-3.7-flash",
+      "nemotron-120b": "free/step-3.7-flash",
+      devstral: "free/step-3.7-flash",
+      // seed-oss-36b EOL'd 2026-08-03
+      "devstral-2": "free/step-3.7-flash",
       maverick: "free/llama-4-maverick",
       // explicit-ish pin — gateway redirects
-      free: "free/gpt-oss-120b",
+      // `free` = the free-tier default. Must equal router-core's ecoTiers.SIMPLE
+      // primary and the head of proxy.ts FREE_MODELS so `/model free`, the eco
+      // profile and the budget-cap free fallback all agree on one live model.
+      free: "free/step-3.7-flash",
       // MiniMax (minimax → current flagship: M3)
       minimax: "minimax/minimax-m3",
       "minimax-m3": "minimax/minimax-m3",
@@ -37084,7 +37093,7 @@ var init_models = __esm({
       },
       {
         id: "free",
-        name: "Free \u2192 GPT-OSS 120B",
+        name: "Free \u2192 Step 3.7 Flash",
         inputPrice: 0,
         outputPrice: 0,
         contextWindow: 131072,
@@ -92833,20 +92842,18 @@ var init_proxy = __esm({
       "premium"
     ]);
     FREE_MODELS = /* @__PURE__ */ new Set([
-      "free/gpt-oss-120b",
-      "free/gpt-oss-20b",
-      "free/mistral-nemotron",
-      // strong instruction following
       "free/step-3.7-flash",
-      // reasoning-focused
+      // reasoning-focused — free-tier flagship
       "free/nemotron-nano-9b-v2",
-      // fast lightweight generalist
+      // fast lightweight generalist (~0.7s)
+      "free/mistral-nemotron",
+      // strong instruction following
       "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       // vision (text/image/video/audio)
       "free/nemotron-nano-12b-v2-vl"
       // vision-language (text + image)
     ]);
-    FREE_MODEL = "free/gpt-oss-120b";
+    FREE_MODEL = "free/step-3.7-flash";
     MAX_MESSAGES = 200;
     CONTEXT_LIMIT_KB = 5120;
     HEARTBEAT_INTERVAL_MS = 2e3;

package/dist/index.js

@@ -409,12 +409,16 @@ var init_models = __esm({
       "xai/grok-3-fast": "xai/grok-4-fast-reasoning",
       // delisted (too expensive)
       // NVIDIA — backward compat aliases (nvidia/xxx → free/xxx)
-      // Default free model is gpt-oss-120b (heavy user demand). New free models
-      // added 2026-04-29 — deepseek-v4-pro/flash, nemotron-omni — are additions,
-      // not replacements. Retired-with-redirect entries below mirror BlockRun
-      // server-side decommissioning of slow models (nemotron family, etc.).
-      nvidia: "free/gpt-oss-120b",
+      // Default free model is step-3.7-flash — the same model @blockrun/router-core
+      // opens the eco SIMPLE tier on. It replaced gpt-oss-120b on 2026-08-29:
+      // gpt-oss-120b went dead upstream on 2026-08-16 (NVIDIA still LISTS it, but a
+      // completion hangs until the client gives up — blockrun #391 retargeted its
+      // whole free cascade off it, and the gateway now answers 400 Unknown model
+      // for the `free/` id). Pins that NAME gpt-oss stay routable below — the
+      // gateway server-redirects them — but nothing generic may land on it.
+      nvidia: "free/step-3.7-flash",
       "gpt-120b": "free/gpt-oss-120b",
+      // names the model itself — gateway redirects
       "gpt-20b": "free/gpt-oss-20b",
       "nvidia/gpt-oss-120b": "free/gpt-oss-120b",
       "nvidia/gpt-oss-20b": "free/gpt-oss-20b",
@@ -489,9 +493,10 @@ var init_models = __esm({
       // no live free Llama left (maverick died 2026-07)
       // qwen3-coder-480b retired 2026-06-14 → seed-oss-36b, which then EOL'd 2026-08-03.
       // Follow the gateway's own retarget rather than chaining to a second dead model.
-      "qwen-coder": "free/gpt-oss-120b",
-      "qwen-coder-free": "free/gpt-oss-120b",
-      "qwen-thinking": "free/gpt-oss-120b",
+      "qwen-coder": "free/step-3.7-flash",
+      // no live free Qwen; follows the free default
+      "qwen-coder-free": "free/step-3.7-flash",
+      "qwen-thinking": "free/step-3.7-flash",
       // qwen3-next died 2026-07-17; no live free Qwen left
       "qwen3-next": "free/qwen3-next-80b-a3b-instruct",
       // explicit-ish pin — gateway redirects
@@ -502,8 +507,8 @@ var init_models = __esm({
       // seed-oss pins name the model itself — kept routable, the gateway redirects them.
       "seed-oss": "free/seed-oss-36b",
       "seed-oss-36b": "free/seed-oss-36b",
-      "coder-free": "free/gpt-oss-120b",
-      // generic "a free coder" → follows the gateway retarget
+      "coder-free": "free/step-3.7-flash",
+      // generic "a free coder" → follows the free default
       "mistral-nemotron": "free/mistral-nemotron",
       "step-flash": "free/step-3.7-flash",
       "step-3.7-flash": "free/step-3.7-flash",
@@ -515,21 +520,25 @@ var init_models = __esm({
       "nemotron-omni": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       "nano-omni": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       "vision-free": "free/nemotron-3-nano-omni-30b-a3b-reasoning",
-      // Retired shorthand aliases redirect to live successors (2026-07-17 map:
-      // llama-4-maverick died, so the old catch-all target moved to gpt-oss-120b)
+      // Retired shorthand aliases redirect to live successors. The catch-all target
+      // moved llama-4-maverick → gpt-oss-120b (2026-07-17) → step-3.7-flash
+      // (2026-08-29, gpt-oss-120b hung upstream; see the NVIDIA block above).
       nemotron: "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       // strongest live Nemotron
-      "nemotron-ultra": "free/gpt-oss-120b",
-      "nemotron-253b": "free/gpt-oss-120b",
-      "nemotron-super": "free/gpt-oss-120b",
-      "nemotron-49b": "free/gpt-oss-120b",
-      "nemotron-120b": "free/gpt-oss-120b",
-      devstral: "free/gpt-oss-120b",
-      // seed-oss-36b EOL'd 2026-08-03; matches blockrun's own retarget
-      "devstral-2": "free/gpt-oss-120b",
+      "nemotron-ultra": "free/step-3.7-flash",
+      "nemotron-253b": "free/step-3.7-flash",
+      "nemotron-super": "free/step-3.7-flash",
+      "nemotron-49b": "free/step-3.7-flash",
+      "nemotron-120b": "free/step-3.7-flash",
+      devstral: "free/step-3.7-flash",
+      // seed-oss-36b EOL'd 2026-08-03
+      "devstral-2": "free/step-3.7-flash",
       maverick: "free/llama-4-maverick",
       // explicit-ish pin — gateway redirects
-      free: "free/gpt-oss-120b",
+      // `free` = the free-tier default. Must equal router-core's ecoTiers.SIMPLE
+      // primary and the head of proxy.ts FREE_MODELS so `/model free`, the eco
+      // profile and the budget-cap free fallback all agree on one live model.
+      free: "free/step-3.7-flash",
       // MiniMax (minimax → current flagship: M3)
       minimax: "minimax/minimax-m3",
       "minimax-m3": "minimax/minimax-m3",
@@ -599,7 +608,7 @@ var init_models = __esm({
       },
       {
         id: "free",
-        name: "Free \u2192 GPT-OSS 120B",
+        name: "Free \u2192 Step 3.7 Flash",
         inputPrice: 0,
         outputPrice: 0,
         contextWindow: 131072,
@@ -92653,20 +92662,18 @@ var init_proxy = __esm({
       "premium"
     ]);
     FREE_MODELS = /* @__PURE__ */ new Set([
-      "free/gpt-oss-120b",
-      "free/gpt-oss-20b",
-      "free/mistral-nemotron",
-      // strong instruction following
       "free/step-3.7-flash",
-      // reasoning-focused
+      // reasoning-focused — free-tier flagship
       "free/nemotron-nano-9b-v2",
-      // fast lightweight generalist
+      // fast lightweight generalist (~0.7s)
+      "free/mistral-nemotron",
+      // strong instruction following
       "free/nemotron-3-nano-omni-30b-a3b-reasoning",
       // vision (text/image/video/audio)
       "free/nemotron-nano-12b-v2-vl"
       // vision-language (text + image)
     ]);
-    FREE_MODEL = "free/gpt-oss-120b";
+    FREE_MODEL = "free/step-3.7-flash";
     MAX_MESSAGES = 200;
     CONTEXT_LIMIT_KB = 5120;
     HEARTBEAT_INTERVAL_MS = 2e3;

package/docs/architecture.md

@@ -96,16 +96,28 @@ if (inflight) {
 // Extract user's last message
 const prompt = messages.findLast((m) => m.role === "user")?.content;
 
-// Run 15-dimension weighted scorer
+// Router Core V3.4 (@blockrun/router-core): 15-dimension scorer → hard
+// capability filters → portfolio ranking. Model capabilities come from the
+// live catalog, injected at proxy startup.
 const decision = route(prompt, systemPrompt, maxTokens, {
   config: DEFAULT_ROUTING_CONFIG,
   modelPricing,
+  modelCapabilities,
+  routingProfile: "auto",
+  hasTools,
+  toolCount,
+  toolNames,
+  hasVision,
 });
 
 // decision = {
 //   model: "google/gemini-2.5-flash",
 //   tier: "SIMPLE",
+//   taskType: "chat",
 //   confidence: 0.92,
+//   method: "portfolio",
+//   routerVersion: "v3-portfolio",
+//   candidates: ["google/gemini-2.5-flash", "google/gemini-3-flash-preview", ...],
 //   savings: 0.99,
 //   costEstimate: 0.0012,
 // }
@@ -235,17 +247,12 @@ data: [DONE]
 
 ## Routing Engine
 
-### Weighted Scorer
+The routing engine lives in [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) (Router Core V3.4), a product-neutral package shared by ClawRouter, Franklin, the `@blockrun/llm` SDKs and ClawRouter-Hermes. `src/router/index.ts` is a single `export * from "@blockrun/router-core"`; the package is a `devDependency` inlined by tsup at build time and pinned to an immutable commit SHA. Nothing in the decision path touches the network.
 
-The routing engine uses a 15-dimension weighted scorer that runs entirely locally:
+### 1. Classify — 15-dimension weighted scorer
 
 ```typescript
-function classifyByRules(
-  prompt: string,
-  systemPrompt: string | undefined,
-  tokenCount: number,
-  config: ScoringConfig,
-): ClassificationResult {
+function classifyByRules(prompt, systemPrompt, tokenCount, config): ClassificationResult {
   let score = 0;
   const signals: string[] = [];
 
@@ -262,51 +269,60 @@ function classifyByRules(
     signals.push("code");
   }
 
-  // ... 13 more dimensions
-
-  // Sigmoid calibration
-  const confidence = sigmoid(score, (k = 8), (midpoint = 0.5));
+  // ... 13 more dimensions (multiStepPatterns, technicalTerms, tokenCount,
+  //     creativeMarkers, questionComplexity, constraintCount, agenticTask, ...)
 
+  // Sigmoid calibration (steepness 12), ambiguous below 0.7
+  const confidence = sigmoid(score, config.confidenceSteepness);
   return { score, confidence, tier: selectTier(score, confidence), signals };
 }
 ```
 
-### Tier Selection
+Tier boundaries: `< 0.3` SIMPLE, `< 0.5` COMPLEX, else REASONING (2+ reasoning markers short-circuit to REASONING). Alongside the tier, a task classifier derives the _shape_ of the work from the prompt, the visible tool names/count, requested output size and language: `chat`, `extraction`, `code_edit`, `code_agent`, `tool_agent`, `tool_agent_parallel`, `debug`, `reasoning`, `reasoning_mcq`, `reasoning_math`, `long_context`, `vision`.
 
-```typescript
-function selectTier(score: number, confidence: number): Tier | null {
-  // Special case: 2+ reasoning markers → REASONING at high confidence
-  if (signals.includes("reasoning") && reasoningCount >= 2) {
-    return "REASONING";
-  }
+### 2. Filter — hard eligibility
 
-  if (confidence < 0.7) {
-    return null; // Ambiguous → default to MEDIUM
-  }
+The tier's curated chain (primary + fallbacks) is the candidate pool. Before anything is scored, candidates are removed that:
 
-  if (score < 0.3) return "SIMPLE";
-  if (score < 0.6) return "MEDIUM";
-  if (score < 0.8) return "COMPLEX";
-  return "REASONING";
-}
-```
+- lack tool calling on a turn that requires tools (`inferToolRequirement` — `tool_choice: "none"` is authoritative; host tool descriptions alone never create a requirement)
+- lack vision on image input
+- have too small a context window for the conversation, or too small a max-output for the requested length
+- take an incompatible structured-output path
+- are absent from the live catalog injected by the proxy (`modelCapabilities`)
 
-### Overrides
+Capability errors never reach the preference stage — the router fails closed rather than optimistically cheap.
 
-Certain conditions force tier assignment:
+### 3. Rank — portfolio scoring
+
+Survivors are scored on six bounded factors with per-profile weights (auto: quality 0.47 · capability 0.20 · cost 0.18 · speed 0.07 · reliability 0.03 · curated order 0.05; eco raises cost to 0.28, premium raises quality to 0.58). High-stakes turns boost quality and reliability, latency-sensitive turns boost speed; an `affinityFloorGap` stops a candidate far below the best task affinity from winning on price. Speed and reliability priors come from `model-profiles.generated.json` (BlockRun's gateway benchmark), decayed on a 30-day half-life.
+
+### 4. Recover — the fallback chain
+
+The full ranked list is returned as `decision.candidates`; the proxy walks it on timeouts and 5xx. The winner is chosen once per request — no mid-task drift, no auxiliary routing call.
+
+### Overrides
 
 ```typescript
 // Large context → COMPLEX
-if (tokenCount > 100000) {
+if (tokenCount > config.overrides.maxTokensForceComplex /* 100_000 */) {
   return { tier: "COMPLEX", method: "override:large_context" };
 }
 
-// Structured output (JSON/YAML) → min MEDIUM
-if (systemPrompt?.includes("json") || systemPrompt?.includes("yaml")) {
-  return { tier: Math.max(tier, "MEDIUM"), method: "override:structured" };
+// Structured output (JSON/YAML) → at least MEDIUM
+if (requiresStructuredOutput) {
+  return {
+    tier: max(tier, config.overrides.structuredOutputMinTier),
+    method: "override:structured",
+  };
 }
 ```
 
+### Escape hatches
+
+- `routing.strategy = "rules"` — one-line rollback to the V2 primary-first selector.
+- `routing.shadow = { strategy: "rules", sampleRate }` — recompute a comparison decision locally; reported on debug headers, never a second paid call.
+- `unavailableModels` — the host can hard-remove models it observed dead at the gateway from every chain before selection (router-core API; not yet wired in the proxy — free-model liveness is enforced at build time by `src/router/free-model-liveness.test.ts` instead).
+
 ---
 
 ## Payment System
@@ -538,22 +554,20 @@ src/
 ├── retry.ts              # Fetch retry with exponential backoff
 ├── version.ts            # Version from package.json
 └── router/
-    ├── index.ts          # route() entry point
-    ├── rules.ts          # 15-dimension weighted scorer (9-language)
-    ├── selector.ts       # Tier → model selection + fallback
-    ├── config.ts         # Default routing configuration (ECO/AUTO/PREMIUM/AGENTIC)
-    └── types.ts          # TypeScript type definitions
+    ├── index.ts                     # export * from "@blockrun/router-core" (Router Core V3.4)
+    ├── free-model-liveness.test.ts  # build-time guard: no chain names a dead free model
+    └── brand-numbers.test.ts        # README/SKILL brand markers stay in sync
 ```
 
 ### Key Files
 
-| File                 | Purpose                                                       |
-| -------------------- | ------------------------------------------------------------- |
-| `proxy.ts`           | Core request handling, SSE simulation, fallback chain         |
-| `wallet.ts`          | BIP-39 mnemonic generation, EVM + Solana (SLIP-10) derivation |
-| `router/rules.ts`    | 15-dimension weighted scorer, 9-language keyword sets         |
-| `x402.ts`            | EIP-712 typed data signing, payment header formatting         |
-| `balance.ts`         | USDC balance via Base RPC (EVM), caching, thresholds          |
-| `solana-balance.ts`  | USDC balance via Solana RPC (SPL Token), caching, retries     |
-| `payment-preauth.ts` | Pre-authorization cache (EVM; skipped for Solana)             |
-| `dedup.ts`           | SHA-256 hashing, 30s response cache                           |
+| File                 | Purpose                                                                             |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `proxy.ts`           | Core request handling, SSE simulation, fallback chain                               |
+| `wallet.ts`          | BIP-39 mnemonic generation, EVM + Solana (SLIP-10) derivation                       |
+| `router/index.ts`    | Re-exports `@blockrun/router-core` (scorer, filters, portfolio ranker, tier config) |
+| `x402.ts`            | EIP-712 typed data signing, payment header formatting                               |
+| `balance.ts`         | USDC balance via Base RPC (EVM), caching, thresholds                                |
+| `solana-balance.ts`  | USDC balance via Solana RPC (SPL Token), caching, retries                           |
+| `payment-preauth.ts` | Pre-authorization cache (EVM; skipped for Solana)                                   |
+| `dedup.ts`           | SHA-256 hashing, 30s response cache                                                 |

package/docs/configuration.md

@@ -307,12 +307,18 @@ const decision = route("Prove sqrt(2) is irrational", undefined, 4096, {
 
 console.log(decision);
 // {
-//   model: "deepseek/deepseek-reasoner",
+//   model: "xai/grok-4-1-fast-reasoning",
 //   tier: "REASONING",
+//   taskType: "reasoning_math",
 //   confidence: 0.97,
-//   method: "rules",
-//   savings: 0.994,
-//   costEstimate: 0.002,
+//   method: "portfolio",
+//   routerVersion: "v3-portfolio",
+//   profile: "auto",
+//   candidates: ["xai/grok-4-1-fast-reasoning", "xai/grok-4-fast-reasoning", "deepseek/deepseek-reasoner", ...],
+//   candidateScores: [{ model, score, quality, cost, speed, reliability }, ...],
+//   savings: 0.99,
+//   costEstimate: 0.0007,
+//   reasoning: "…",
 // }
 ```
 
@@ -354,6 +360,8 @@ const proxy = await startProxy({
 
 ## Routing Configuration
 
+Routing decisions are made by [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) (Router Core V3.4). The `routing` block is merged over router-core's `DEFAULT_ROUTING_CONFIG`: tier maps are merged per tier (override just `COMPLEX` without redefining the other three), `classifier` / `scoring` / `overrides` are merged per key, and `null` disables a tier set.
+
 ### Via openclaw.yaml
 
 ```yaml
@@ -378,22 +386,33 @@ plugins:
       # Their cost is charged via x402 micropayment directly and is not tracked per-session.
 
       routing:
-        # Override tier assignments
+        # Strategy. Default: portfolio (Router Core V3.4 — constraint-first ranking
+        # over the tier's chain). "rules" is the one-line rollback to the V2
+        # primary-first selector.
+        strategy: portfolio
+
+        # Optional shadow evaluation: recompute a comparison decision locally on a
+        # sample of requests and report it on the x-clawrouter-* debug headers.
+        # Never issues a second paid completion, never persists prompt content.
+        # shadow:
+        #   strategy: rules
+        #   sampleRate: 0.1
+
+        # Override tier chains (auto profile). Each tier is merged individually,
+        # so you can override just COMPLEX. Under the portfolio strategy the
+        # chain is the candidate pool: primary is the curated head, the ranker
+        # still enforces tool/vision/context constraints and may pick a fallback.
         tiers:
-          SIMPLE:
-            primary: "google/gemini-2.5-flash"
-            fallback: ["deepseek/deepseek-chat"]
-          MEDIUM:
-            primary: "deepseek/deepseek-chat"
-            fallback: ["openai/gpt-4o-mini"]
           COMPLEX:
-            primary: "anthropic/claude-sonnet-4.6"
-            fallback: ["openai/gpt-4o"]
-          REASONING:
-            primary: "deepseek/deepseek-reasoner"
-            fallback: ["openai/o3-mini"]
+            primary: "anthropic/claude-sonnet-5"
+            fallback: ["google/gemini-3.1-pro", "openai/gpt-5.6-terra"]
+
+        # Same shape for the other tier sets:
+        # ecoTiers: { ... }
+        # premiumTiers: { ... }
+        # agenticTiers: { ... }   # or `null` to disable agentic switching entirely
 
-        # Override scoring parameters
+        # Override scoring keywords
         scoring:
           reasoningKeywords: ["prove", "theorem", "formal", "derive"]
           codeKeywords: ["function", "class", "async", "import"]
@@ -402,38 +421,41 @@ plugins:
         # Override thresholds
         classifier:
           confidenceThreshold: 0.7
-          reasoningConfidence: 0.97
 
         # Context-based overrides
         overrides:
-          largeContextTokens: 100000 # Force COMPLEX above this
-          structuredOutput: true # Bump to min MEDIUM for JSON/YAML
+          maxTokensForceComplex: 100000 # Force COMPLEX above this many tokens
+          structuredOutputMinTier: MEDIUM # Bump to at least MEDIUM for JSON/YAML
+          ambiguousDefaultTier: MEDIUM # Where low-confidence requests land
+          # agenticMode: true | false   # force / disable the agentic tier set (default: auto-detect)
 ```
 
 ---
 
 ## Tier Overrides
 
-### Default Tier Mappings
+### Default Tier Mappings (auto profile)
+
+Curated primaries from router-core's `DEFAULT_ROUTING_CONFIG.tiers`; chains truncated. The full chains for every profile — and the eco / premium / agentic tier sets — are in [routing-profiles.md](./routing-profiles.md).
 
-| Tier      | Primary Model                 | Fallback Chain                                  |
-| --------- | ----------------------------- | ----------------------------------------------- |
-| SIMPLE    | `google/gemini-2.5-flash`     | `deepseek/deepseek-chat`                        |
-| MEDIUM    | `deepseek/deepseek-chat`      | `openai/gpt-4o-mini`, `google/gemini-2.5-flash` |
-| COMPLEX   | `anthropic/claude-sonnet-4.6` | `openai/gpt-4o`, `google/gemini-2.5-pro`        |
-| REASONING | `deepseek/deepseek-reasoner`  | `openai/o3-mini`, `anthropic/claude-sonnet-4.6` |
+| Tier      | Primary Model                 | Fallback Chain (head)                                        |
+| --------- | ----------------------------- | ------------------------------------------------------------ |
+| SIMPLE    | `google/gemini-2.5-flash`     | `google/gemini-3-flash-preview`, `deepseek/deepseek-chat`, … |
+| MEDIUM    | `moonshot/kimi-k2.7`          | `moonshot/kimi-k2.6`, `moonshot/kimi-k2.5`, …                |
+| COMPLEX   | `google/gemini-3.1-pro`       | `google/gemini-3-flash-preview`, `xai/grok-4-0709`, …        |
+| REASONING | `xai/grok-4-1-fast-reasoning` | `xai/grok-4-fast-reasoning`, `deepseek/deepseek-reasoner`, … |
 
 ### Fallback Chain
 
-When the primary model fails (rate limits, billing errors, provider outages), ClawRouter tries the next model in the fallback chain:
+The ranked candidate list is returned on every decision (`decision.candidates`). When the selected model fails (rate limits, billing errors, provider outages, timeouts), ClawRouter tries the next candidate:
 
 ```
-Request → gemini-2.5-flash (rate limited)
-       → deepseek-chat (billing error)
-       → gpt-4o-mini (success)
+Request → gemini-3.1-pro (503)
+       → gemini-3-flash-preview (rate limited)
+       → grok-4-0709 (success)
 ```
 
-Max fallback attempts: 3 models per request.
+Candidates that fail a hard constraint (no tool calling on a tool turn, no vision on image input, too small a context window) are removed before ranking, so a fallback never lands on a model that cannot serve the request.
 
 ### Custom Tier Configuration
 
@@ -441,10 +463,10 @@ Max fallback attempts: 3 models per request.
 routing:
   tiers:
     COMPLEX:
-      primary: "openai/gpt-4o" # Use GPT-4o instead of Claude
+      primary: "openai/gpt-5.6-terra" # Use GPT-5.6 Terra instead of Gemini 3.1 Pro
       fallback:
-        - "anthropic/claude-sonnet-4.6"
-        - "google/gemini-2.5-pro"
+        - "anthropic/claude-sonnet-5"
+        - "google/gemini-3.1-pro"
 ```
 
 ---
@@ -458,12 +480,12 @@ The 15-dimension weighted scorer determines query complexity:
 | `reasoningMarkers`    | 0.18   | "prove", "theorem", "step by step"       |
 | `codePresence`        | 0.15   | "function", "async", "import", "```"     |
 | `multiStepPatterns`   | 0.12   | "first...then", "step 1", numbered lists |
-| `agenticTask`         | 0.10   | "run", "test", "fix", "deploy", "edit"   |
 | `technicalTerms`      | 0.10   | "algorithm", "kubernetes", "distributed" |
 | `tokenCount`          | 0.08   | short (<50) vs long (>500)               |
 | `creativeMarkers`     | 0.05   | "story", "poem", "brainstorm"            |
 | `questionComplexity`  | 0.05   | Multiple question marks                  |
 | `constraintCount`     | 0.04   | "at most", "O(n)", "maximum"             |
+| `agenticTask`         | 0.04   | "run", "test", "fix", "deploy", "edit"   |
 | `imperativeVerbs`     | 0.03   | "build", "create", "implement"           |
 | `outputFormat`        | 0.03   | "json", "yaml", "schema"                 |
 | `simpleIndicators`    | 0.02   | "what is", "define", "translate"         |
@@ -500,10 +522,12 @@ The classifier uses sigmoid calibration to convert raw scores to confidence valu
 confidence = 1 / (1 + exp(-k * (score - midpoint)))
 ```
 
-Parameters:
+Parameters (router-core `classifier`):
 
-- `k = 8` — steepness of the sigmoid curve
-- `midpoint = 0.5` — score at which confidence = 50%
+- `confidenceSteepness = 12` — steepness of the sigmoid curve
+- `confidenceThreshold = 0.7` — below this the request is ambiguous and lands on `overrides.ambiguousDefaultTier` (MEDIUM)
+
+Tier boundaries on the weighted-score axis: `mediumComplex = 0.3`, `complexReasoning = 0.5`.
 
 ### Override Thresholds
 
@@ -512,9 +536,6 @@ routing:
   classifier:
     # Require higher confidence for tier assignment
     confidenceThreshold: 0.8 # Default: 0.7
-
-    # Force REASONING tier at lower confidence
-    reasoningConfidence: 0.90 # Default: 0.97
 ```
 
 ---

package/docs/routing-profiles.md

@@ -1,62 +1,106 @@
 # Routing Profiles & Pricing
 
-ClawRouter offers four routing profiles to balance cost vs quality. Prices are in **$/M tokens** (input/output). Tables show each tier's **primary** model — every tier also carries a benchmark-ordered fallback chain (see `src/router/config.ts`).
+ClawRouter offers four routing profiles to balance cost vs quality. Prices are in **$/M tokens** (input/output), taken from `src/models.ts` (which mirrors the live BlockRun catalog).
 
-## ECO (Absolute Cheapest)
+Routing decisions are made by [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) (Router Core **V3.4**, the constraint-first portfolio router), which ClawRouter inlines at build time and pins by commit SHA. `src/router/index.ts` simply re-exports it. Nothing below calls a network or a second model: classification, eligibility filtering and ranking all run locally in about a quarter of a millisecond.
+
+## How a request is routed
+
+1. **Classify.** A 15-dimension weighted scorer maps the request onto a capability tier — `SIMPLE`, `MEDIUM`, `COMPLEX` or `REASONING` — and a task classifier labels the _shape_ of the work (`chat`, `extraction`, `code_edit`, `code_agent`, `tool_agent`, `tool_agent_parallel`, `debug`, `reasoning`, `reasoning_math`, `long_context`, `vision`, …). Turns that actually need their attached tools switch to the **agentic** tier set automatically.
+2. **Filter.** The tier's curated chain (primary + fallbacks, below) is the candidate pool. Every model that cannot satisfy the request is removed **before** scoring: no tool calling on a tool-required turn, no vision on image input, too small a context window, too small a max-output, an incompatible structured-output path, or absent from the live catalog. Being cheap never compensates for failing the contract.
+3. **Rank.** Survivors are scored on task quality, capability, estimated cost, speed, reliability and a small curated-order prior. The weights differ per profile (see [Profile weights](#profile-weights)).
+4. **Recover.** The full ranked list stays on the decision as `candidates`. The proxy walks it on a timeout or 5xx, so a provider outage costs a retry, not the task.
+
+The tables show each tier's **curated primary** and its fallback chain as configured in router-core. Under the portfolio strategy the primary is the head of the candidate pool and carries the curated-order prior; it is the usual winner, not a guarantee — a request that needs vision or a 1M context can legitimately land on a fallback.
+
+---
 
-Use `blockrun/eco` for maximum cost savings.
+## AUTO (Balanced — Default)
 
-| Tier      | Primary Model                | Input | Output |
-| --------- | ---------------------------- | ----- | ------ |
-| SIMPLE    | free/gpt-oss-120b            | $0.00 | $0.00  |
-| MEDIUM    | google/gemini-3.1-flash-lite | $0.25 | $1.50  |
-| COMPLEX   | google/gemini-3.1-flash-lite | $0.25 | $1.50  |
-| REASONING | xai/grok-4-1-fast-reasoning  | $0.20 | $0.50  |
+Use `blockrun/auto` (or `/model auto`) for the best quality/price balance.
+
+| Tier      | Primary Model               | Input | Output | Fallback chain (in order)                                                                                                                                                     |
+| --------- | --------------------------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SIMPLE    | google/gemini-2.5-flash     | $0.30 | $2.50  | gemini-3-flash-preview → deepseek-chat → kimi-k2.5 → gemini-3.1-flash-lite → gemini-2.5-flash-lite → gpt-5.4-nano → grok-4-fast-non-reasoning → step-3.7-flash (free)         |
+| MEDIUM    | moonshot/kimi-k2.7          | $0.95 | $4.00  | kimi-k2.6 → kimi-k2.5 → gemini-3-flash-preview → deepseek-chat → gemini-2.5-flash → gemini-3.1-flash-lite → gemini-2.5-flash-lite → grok-4-1-fast-non-reasoning → grok-3-mini |
+| COMPLEX   | google/gemini-3.1-pro       | $2.00 | $12.00 | gemini-3-flash-preview → grok-4-0709 → gemini-2.5-pro → claude-sonnet-5 → claude-sonnet-4.6 → deepseek-chat → gemini-2.5-flash → gpt-5.6-terra → gpt-5.5 → gpt-5.4            |
+| REASONING | xai/grok-4-1-fast-reasoning | $0.20 | $0.50  | grok-4-fast-reasoning → deepseek-reasoner → deepseek-v4-pro → o4-mini → o3                                                                                                    |
 
 ---
 
-## AUTO (Balanced - Default)
+## ECO (Absolute Cheapest)
+
+Use `blockrun/eco` for maximum cost savings. The first stop is the free tier, so simple requests can cost $0.00.
 
-Use `blockrun/auto` for the best quality/price balance.
+| Tier      | Primary Model                | Input | Output | Fallback chain (in order)                                                                                             |
+| --------- | ---------------------------- | ----- | ------ | --------------------------------------------------------------------------------------------------------------------- |
+| SIMPLE    | free/step-3.7-flash          | $0.00 | $0.00  | nemotron-nano-9b-v2 (free) → gemini-3.1-flash-lite → gpt-5.4-nano → gemini-2.5-flash-lite → grok-4-fast-non-reasoning |
+| MEDIUM    | google/gemini-3.1-flash-lite | $0.25 | $1.50  | gpt-5.4-nano → gemini-2.5-flash-lite → grok-4-fast-non-reasoning → gemini-2.5-flash                                   |
+| COMPLEX   | google/gemini-3.1-flash-lite | $0.25 | $1.50  | gemini-2.5-flash-lite → grok-4-0709 → gemini-2.5-flash → deepseek-chat                                                |
+| REASONING | xai/grok-4-1-fast-reasoning  | $0.20 | $0.50  | grok-4-fast-reasoning → deepseek-reasoner → deepseek-v4-pro                                                           |
 
-| Tier      | Primary Model               | Input | Output |
-| --------- | --------------------------- | ----- | ------ |
-| SIMPLE    | google/gemini-2.5-flash     | $0.30 | $2.50  |
-| MEDIUM    | moonshot/kimi-k2.6          | $0.95 | $4.00  |
-| COMPLEX   | google/gemini-3.1-pro       | $2.00 | $12.00 |
-| REASONING | xai/grok-4-1-fast-reasoning | $0.20 | $0.50  |
+The two free rungs at the head of ECO SIMPLE follow NVIDIA's free hosting, which retires models without notice (deepseek-v4-flash 410'd 2026-08-12, seed-oss-36b 2026-08-03, gpt-oss-120b hung 2026-08-16). Each retirement retargets the free rungs to the current free tier; the paid rungs never move. `src/router/free-model-liveness.test.ts` fails the build if a chain names a free model the picker no longer lists.
 
 ---
 
 ## PREMIUM (Best Quality)
 
-Use `blockrun/premium` for maximum quality.
+Use `blockrun/premium` for maximum quality. Codex for complex coding, Kimi for simple coding, Sonnet for reasoning/instructions, Fable/Opus for architecture, audits and PM-grade work.
+
+| Tier      | Primary Model               | Input  | Output | Fallback chain (in order)                                                                                                                                                                                                                                          |
+| --------- | --------------------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SIMPLE    | moonshot/kimi-k2.7          | $0.95  | $4.00  | kimi-k2.6 → kimi-k2.5 → gemini-2.5-flash → claude-haiku-4.5 → gemini-2.5-flash-lite → deepseek-chat                                                                                                                                                                |
+| MEDIUM    | openai/gpt-5.3-codex        | $1.75  | $14.00 | kimi-k2.7 → kimi-k2.6 → kimi-k2.5 → gemini-2.5-flash → gemini-2.5-pro → grok-4-0709 → claude-sonnet-5 → claude-sonnet-4.6                                                                                                                                          |
+| COMPLEX   | anthropic/claude-fable-5    | $10.00 | $50.00 | claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-5 → claude-sonnet-4.6 → grok-4.5 → grok-4-0709 → kimi-k2.7 → kimi-k2.6 → kimi-k2.5 → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → deepseek-chat → step-3.7-flash (free) |
+| REASONING | anthropic/claude-sonnet-4.6 | $3.00  | $15.00 | claude-sonnet-5 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → grok-4-1-fast-reasoning → o4-mini → o3                                                                                                                                     |
+
+The premium COMPLEX chain is deliberately de-Gemini'd: Google's "high demand" 503s correlate with Anthropic outages (everyone falls back to Google at the same time), so the chain prefers the in-family Opus hot swaps, then xAI, Moonshot and OpenAI — providers on independent infrastructure.
+
+---
+
+## AGENTIC (Multi-Step Tool Use)
+
+Not a profile you pick — router-core switches to these tiers when the turn actually needs its attached tools (`inferToolRequirement`: `tool_choice: "none"` is authoritative, and host tool _descriptions_ alone do not trigger it). Primaries favour models that keep going instead of stopping to ask.
+
+| Tier      | Primary Model               | Input | Output | Fallback chain (in order)                                                                                                                                                                               |
+| --------- | --------------------------- | ----- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SIMPLE    | openai/gpt-4o-mini          | $0.15 | $0.60  | kimi-k2.5 → claude-haiku-4.5 → grok-4-1-fast-non-reasoning                                                                                                                                              |
+| MEDIUM    | moonshot/kimi-k2.7          | $0.95 | $4.00  | kimi-k2.6 → kimi-k2.5 → grok-4-1-fast-non-reasoning → gpt-4o-mini → claude-haiku-4.5 → deepseek-chat                                                                                                    |
+| COMPLEX   | anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | claude-sonnet-5 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → grok-4-0709 → kimi-k2.7 → kimi-k2.5 → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → deepseek-chat → step-3.7-flash (free) |
+| REASONING | anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | claude-sonnet-5 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → grok-4-1-fast-reasoning → deepseek-reasoner                                                                     |
+
+Set `routing.overrides.agenticMode: false` to disable the agentic tier set, or `true` to force it.
+
+---
+
+## FREE (`/model free`)
+
+`free` is an alias, not a routed profile: it pins the free-tier default, currently **`free/step-3.7-flash`** — the same model that opens ECO SIMPLE. If that model is excluded (`/exclude add step-flash`) or the budget cap forces a free fallback, the proxy walks the free cascade in this order: step-3.7-flash → nemotron-nano-9b-v2 → mistral-nemotron → nemotron-3-nano-omni-30b-a3b-reasoning (vision) → nemotron-nano-12b-v2-vl (vision). All five are NVIDIA-hosted, $0.00, and need no USDC.
 
-| Tier      | Primary Model        | Input  | Output |
-| --------- | -------------------- | ------ | ------ |
-| SIMPLE    | moonshot/kimi-k2.6   | $0.95  | $4.00  |
-| MEDIUM    | openai/gpt-5.3-codex | $1.75  | $14.00 |
-| COMPLEX   | claude-fable-5       | $10.00 | $50.00 |
-| REASONING | claude-sonnet-4.6    | $3.00  | $15.00 |
+Pin any of them directly with `/model step-flash`, `/model nemotron-nano`, `/model mistral-nemotron`, `/model nemotron-omni` (vision) or `/model nano-vl` (vision).
 
 ---
 
-## AGENTIC (Multi-Step Tasks)
+## Profile weights
 
-ClawRouter auto-detects agentic patterns (tool use, multi-step autonomy) and switches to agent-tuned primaries.
+How survivors are ranked, per profile (router-core `DEFAULT_ROUTING_CONFIG.portfolio`):
 
-| Tier      | Primary Model      | Input | Output |
-| --------- | ------------------ | ----- | ------ |
-| SIMPLE    | openai/gpt-4o-mini | $0.15 | $0.60  |
-| MEDIUM    | moonshot/kimi-k2.6 | $0.95 | $4.00  |
-| COMPLEX   | claude-sonnet-4.6  | $3.00 | $15.00 |
-| REASONING | claude-sonnet-4.6  | $3.00 | $15.00 |
+| Component     | AUTO |  ECO | PREMIUM | Role                                                    |
+| ------------- | ---: | ---: | ------: | ------------------------------------------------------- |
+| Task quality  | 0.47 | 0.36 |    0.58 | Prefer models validated for the detected task shape     |
+| Capability    | 0.20 | 0.20 |    0.20 | Preserve the request contract after hard filtering      |
+| Cost          | 0.18 | 0.28 |    0.08 | Reward efficient qualified candidates                   |
+| Speed         | 0.07 | 0.10 |    0.06 | Ordinary interactive latency                            |
+| Reliability   | 0.03 | 0.04 |    0.06 | Prefer stable candidates                                |
+| Curated order | 0.05 | 0.02 |    0.02 | A small, explainable prior toward the chain order above |
+
+High-stakes turns add `+0.08` quality / `+0.05` reliability; latency-sensitive turns add `+0.08` speed. An `affinityFloorGap` (auto 0.10, eco 0.22, premium 0.05) stops a candidate materially below the best task affinity from winning on price alone — which is why ECO can still climb to a paid model for work the free tier would botch.
 
 ---
 
 ## ECO vs AUTO Savings
 
-Combined input + output rate per 1M tokens:
+Combined input + output rate per 1M tokens, primaries only:
 
 | Tier      | ECO   | AUTO   | Savings  |
 | --------- | ----- | ------ | -------- |
@@ -65,21 +109,26 @@ Combined input + output rate per 1M tokens:
 | COMPLEX   | $1.75 | $14.00 | **88%**  |
 | REASONING | $0.70 | $0.70  | 0%       |
 
+The published savings claim (**88%** on `auto`, **98%** on `eco`, against pinning Claude Opus 5) is blended across a stated workload mix and priced on the live catalog — see [`savings-mix.json`](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json). Per-tier numbers above are illustrative; the blended figure is the one to quote.
+
 ---
 
 ## How Tiers Work
 
-ClawRouter automatically classifies your query into one of four tiers:
+- **SIMPLE**: factual lookups, greetings, translations, short responses
+- **MEDIUM**: summaries, explanations, data extraction, moderate code
+- **COMPLEX**: large context, multi-step analysis, substantial code generation
+- **REASONING**: proofs, formal logic, multi-step math, chain-of-thought
+
+Two overrides apply on top of the scorer: conversations above 100K tokens are forced to COMPLEX, and structured-output requests (JSON/YAML) are lifted to at least MEDIUM. Ambiguous requests (confidence < 0.7) default to MEDIUM.
 
-- **SIMPLE**: Basic questions, short responses, simple lookups
-- **MEDIUM**: Code generation, moderate complexity tasks
-- **COMPLEX**: Large context, multi-step reasoning, complex code
-- **REASONING**: Logic puzzles, math, chain-of-thought tasks
+## Rollback and shadow mode
 
-The router picks the cheapest model capable of handling your query's tier.
+- `routing.strategy: "rules"` reverts to the V2 tier selector (primary-first, no portfolio ranking) without a code change.
+- `routing.shadow: { strategy: "rules", sampleRate: 0.1 }` recomputes a comparison decision locally on a sample of requests and reports it on `x-clawrouter-*` debug headers. It never issues a second paid completion and never persists prompt content.
 
-There is also a `blockrun/free` pin that routes exclusively across the free NVIDIA-hosted fleet (gpt-oss-120b default) — no USDC required.
+See [configuration.md](./configuration.md#routing-configuration) for the YAML.
 
 ---
 
-_Last updated: v0.12.201_
+_Last updated: v0.12.250 — router-core V3.4 (commit `d7bc10c`)_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.249",
+  "version": "0.12.250",
   "description": "Smart LLM router — save 88% on inference costs. 71 models (5 free), one wallet, x402 micropayments.",
   "type": "module",
   "main": "dist/index.js",

package/skills/clawrouter/SKILL.md

@@ -86,7 +86,7 @@ ClawRouter does **not** collect or forward third-party provider API keys. You do
 | `walletKey` | Yes       | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. |
 | `solanaKey` | Yes       | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`.                                                                                 |
 | `gateway`   | No        | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs).                                       |
-| `routing`   | No        | Optional override of the default four-tier router.                                                                                                                                                         |
+| `routing`   | No        | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords).                                                                             |
 
 **How and where keys are stored:**
 
@@ -124,21 +124,27 @@ openclaw models set openai/gpt-4o
 
 ## How Routing Works
 
-ClawRouter classifies each request into one of four tiers:
+Routing is done locally by [`@blockrun/router-core`](https://github.com/BlockRunAI/router-core) (Router Core V3.4, constraint-first), inlined into ClawRouter and pinned by commit. No network call, no second model — about a quarter of a millisecond per request.
+
+1. A 15-dimension weighted scorer classifies each request into one of four tiers, and a task classifier labels the shape of the work (chat, extraction, code_edit, code_agent, tool_agent, reasoning_math, long_context, vision, …).
+2. Models that cannot satisfy the request — no tool calling, no vision, too small a context window or max-output, incompatible structured output — are removed before anything is scored.
+3. Survivors are ranked on task quality, capability, estimated cost, speed and reliability; the full ranked list is kept as the fallback chain for timeouts and 5xx.
+
+Curated primaries on the default `auto` profile:
 
 - **SIMPLE** — factual lookups, greetings, translations → gemini-2.5-flash ($0.30/$2.50)
 - **MEDIUM** — summaries, explanations, data extraction → kimi-k2.7 ($0.95/$4.00)
 - **COMPLEX** — code generation, multi-step analysis → gemini-3.1-pro ($2/$12)
 - **REASONING** — proofs, formal logic, multi-step math → grok-4-1-fast-reasoning ($0.20/$0.50)
 
-Prices are per 1M input/output tokens, on the default `auto` profile. Per-tier
+Turns that actually need their attached tools switch to agent-tuned tiers (gpt-4o-mini → kimi-k2.7 → claude-sonnet-4.6). `eco` opens on the free tier (step-3.7-flash); `premium` climbs to gpt-5.3-codex / claude-fable-5 / claude-sonnet-4.6. Full chains: [docs/routing-profiles.md](../../docs/routing-profiles.md).
+
+Prices are per 1M input/output tokens. Per-tier
 savings percentages are deliberately not quoted here: the published figure is
 blended across a stated workload mix, and a per-tier number invites comparing
 it against a baseline nobody wrote down. See
 [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json).
 
-Rules handle ~~80% of requests in <1ms. Only ambiguous queries hit the LLM classifier (~~$0.00003 per classification).
-
 ## Available Models
 
 <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models including: gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-4o, o3, claude-fable-5, claude-opus-5 [Anthropic flagship, 1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.5, grok-4.3, grok-build-0.1, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, hy3 [Tencent], mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and 5 free NVIDIA models (nemotron-3-nano-omni-30b-a3b-reasoning [vision], mistral-nemotron, step-3.7-flash, nemotron-nano-9b-v2, nemotron-nano-12b-v2-vl [vision]).