@blockrun/clawrouter 0.12.249 → 0.12.251

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.5 (@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.5), 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.5)
+    ├── 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`, `google/gemini-3.5-flash-lite`, … |
+| MEDIUM    | `google/gemini-3.5-flash`    | `google/gemini-3.6-flash`, `zai/glm-5.3-flash`, …                  |
+| COMPLEX   | `google/gemini-3.1-pro`      | `google/gemini-3.6-flash`, `google/gemini-3.5-flash`, …            |
+| REASONING | `deepseek/deepseek-reasoner` | `deepseek/deepseek-v4-pro`, `xai/grok-4.3`, …                      |
 
 ### 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 → gemini-3.5-flash-lite → deepseek-chat → gemini-3.1-flash-lite → gpt-5.6-luna → gpt-5.4-nano → gemini-2.5-flash-lite → step-3.7-flash (free)                                               |
+| MEDIUM    | google/gemini-3.5-flash    | $1.50 | $9.00  | gemini-3.6-flash → glm-5.3-flash → gpt-5.6-terra → gemini-3-flash-preview → deepseek-chat → gemini-2.5-flash → minimax-m3 → gemini-3.1-flash-lite → gpt-5.6-luna → gemini-2.5-flash-lite                           |
+| COMPLEX   | google/gemini-3.1-pro      | $2.00 | $12.00 | gemini-3.6-flash → gemini-3.5-flash → claude-sonnet-5 → grok-4.5 → gemini-2.5-pro → claude-sonnet-4.6 → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → glm-5.3 → kimi-k3 → deepseek-v4-pro → deepseek-chat → gemini-2.5-flash |
+| REASONING | deepseek/deepseek-reasoner | $0.14 | $0.28  | deepseek-v4-pro → grok-4.3 → qwen3.7-plus → gemini-3.5-flash → 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-2.5-flash-lite → glm-5.3-flash → gpt-5.6-luna → gpt-5.4-nano → gemini-3.1-flash-lite |
+| MEDIUM    | zai/glm-5.3-flash          | $0.15 | $0.50  | deepseek-chat → gemini-3.1-flash-lite → gpt-5.6-luna → gpt-5.4-nano → gemini-2.5-flash-lite → gemini-2.5-flash           |
+| COMPLEX   | zai/glm-5.3-flash          | $0.15 | $0.50  | deepseek-chat → minimax-m3 → deepseek-v4-pro → gemini-3.1-flash-lite → gemini-2.5-flash                                  |
+| REASONING | deepseek/deepseek-reasoner | $0.14 | $0.28  | deepseek-v4-pro → qwen3.7-plus → minimax-m3 → glm-5.3-flash                                                              |
 
-| 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, Gemini 3.5 Flash for simple work, Sonnet 5 for reasoning/instructions, Fable/Opus for architecture, audits and PM-grade work.
+
+| Tier      | Primary Model             | Input  | Output | Fallback chain (in order)                                                                                                                                                                                                            |
+| --------- | ------------------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SIMPLE    | google/gemini-3.5-flash   | $1.50  | $9.00  | gemini-3.6-flash → claude-haiku-4.5 → glm-5.3 → gemini-2.5-flash → gemini-3.5-flash-lite → deepseek-chat                                                                                                                             |
+| MEDIUM    | openai/gpt-5.3-codex      | $1.75  | $14.00 | claude-sonnet-5 → kimi-k3 → glm-5.3 → gemini-3.6-flash → gemini-3.5-flash → gemini-2.5-pro → grok-4.5 → claude-sonnet-4.6 → gpt-5.6-terra                                                                                            |
+| COMPLEX   | anthropic/claude-fable-5  | $10.00 | $50.00 | claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-sonnet-5 → claude-sonnet-4.6 → grok-4.5 → kimi-k3 → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → glm-5.3 → deepseek-v4-pro → deepseek-chat → step-3.7-flash (free) |
+| REASONING | anthropic/claude-sonnet-5 | $3.00  | $15.00 | claude-sonnet-4.6 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → grok-4.5 → deepseek-v4-pro → grok-4.3 → 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, OpenAI and Z.AI — 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  | gpt-5.6-luna → glm-5.3-flash → claude-haiku-4.5 → gemini-2.5-flash                                                                                                                                                 |
+| MEDIUM    | openai/gpt-5-mini         | $0.25 | $2.00  | gemini-3.5-flash → glm-5.3-flash → gpt-5.6-terra → gpt-4o-mini → claude-haiku-4.5 → deepseek-chat → kimi-k3                                                                                                        |
+| COMPLEX   | anthropic/claude-sonnet-5 | $3.00 | $15.00 | claude-sonnet-4.6 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → grok-4.5 → kimi-k3 → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → glm-5.3 → deepseek-v4-pro → deepseek-chat → step-3.7-flash (free) |
+| REASONING | anthropic/claude-sonnet-5 | $3.00 | $15.00 | claude-sonnet-4.6 → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → grok-4.5 → deepseek-v4-pro → 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.251",
   "description": "Smart LLM router — save 88% on inference costs. 71 models (5 free), one wallet, x402 micropayments.",
   "type": "module",
   "main": "dist/index.js",
@@ -111,7 +111,7 @@
     }
   },
   "devDependencies": {
-    "@blockrun/router-core": "https://codeload.github.com/BlockRunAI/router-core/tar.gz/d7bc10ce184b3daa40bcc115b523fd629d847a52",
+    "@blockrun/router-core": "https://codeload.github.com/BlockRunAI/router-core/tar.gz/5d911879d7f1eddf93d513b08798998320272cc8",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",
     "openclaw": "^2026.7.2-beta.7",

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]).