@kdejaeger/pi-model-router 0.3.1 → 0.4.1

package/README.md

@@ -65,7 +65,7 @@ pi -e ./extensions/index.ts
 
 1. **Install** the package (see above).
 
-2. **Create a config file** at `.pi/model-router.json` in your project:
+2. **Create a config file** at `.pi/model-router.json` in your project (bigger example configs later in this document):
 
    ```json
    {
@@ -114,9 +114,9 @@ Config is loaded from two locations and **merged**:
 
 ### Config Merging Order
 
-Configs are merged: **Fallback defaults <- Global config <- Project config**.
+Configs are merged: **Base defaults <- Global config <- Project config**.
 
-Project config values override global values, which override built-in defaults. Profiles are merged **deeply** -- if you define only a `high` tier override for a profile in your project config, the `medium` and `low` tiers are inherited from the global config (or fallback defaults).
+Project config values override global values, which override built-in defaults. Profiles are merged **deeply** -- if you define only a `high` tier override for a profile in your project config, the `medium` and `low` tiers are inherited from the global config.
 
 **When no config file exists**, the router loads with an empty profile list and no active models. Create a `.pi/model-router.json` with at least one profile to use the router.
 
@@ -127,7 +127,7 @@ Project config values override global values, which override built-in defaults.
 | Field | Type | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                         |
 |---|---|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `debug` | `boolean` | `false`      | Enable debug mode. Equivalent to running `/router debug on` at startup.                                                                                                                                                                                                                                                                                                                             |
-| `classifierModels` | `string[]` | --           | Array of fast model refs (e.g. `["google/gemini-flash-latest"]`) used to classify user intent via LLM. Models are tried in order, providing fallback if one hits an error. When set, the classifier has final say on tier selection (gated by triggers below). Omit to use fast local heuristics only.                                                                                              |
+| `classifierModels` | `string[]` | --           | Array of fast model refs (e.g. `["google/gemini-flash-latest"]`) used to classify user intent via LLM. Models are tried in order, providing fallback if one hits an error. When set, the classifier has final say on tier selection (gated by triggers below). Omit to always default to `medium` tier (no automatic tier switching).                                                                                              |
 | `classifierModelThinking` | `ThinkingLevel` | `off` | Reasoning/thinking level for the classifier model calls. Defaults to `off` (no extended reasoning) to keep calls fast and cheap.                                                                                                                                                                                                                                                                    |
 | `classifierRunOnceAfterToolCount` | `number` | `3` | Run the classifier once after this many tool continuations (only after the first user message of a turn). Default: 3. Set to 0 to disable.                                                                                                                                                                                                                                                                                                        |
 | `classifierRunAfterToolFailures` | `number` | `2` | Run the classifier after this many consecutive tool failures (counting from the tail of the current turn). Default: 2.                                                                                                                                                                                                                                                                                                  |
@@ -146,7 +146,7 @@ Each profile defines three **tiers** (`high`, `medium`, `low`). Each tier config
 | `thinking` | `ThinkingLevel` | -- | **Optional.** Reasoning/thinking level for this tier. |
 | `fallbacks` | `string[]` | -- | **Optional.** Ordered list of fallback model refs. If the primary model fails, the router retries each fallback in sequence before surfacing an error. |
 
-**Valid thinking levels** (from least to most reasoning): `off`, `minimal`, `low`, `medium`, `high`, `xhigh`
+**Valid thinking levels** (from least to most reasoning): `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
 
 ### Context Threshold Overrides
 
@@ -341,7 +341,7 @@ Each tier can define `fallbacks` -- an ordered list of alternative models. If th
 
 When a fallback is used, `decision.isFallback` is set to `true` and shown in the status. The tier's configured thinking level (or runtime override) applies to all fallback models -- if a fallback doesn't support the requested level, pi silently clamps it.
 
-If a model fails during a turn, the router retries it up to **2 times** before moving to the next fallback in the chain.
+If a model fails during a turn, the router retries it **once** (2 total attempts) before moving to the next fallback in the chain.
 
 ### Image-Aware Auto-Routing
 
@@ -357,7 +357,7 @@ When using Google models with thinking enabled, tool-result continuations requir
 
 The router reports the **largest context window across all models in a profile** (scanning all tiers and their fallbacks for the maximum). When routing to a model with a smaller window, the router trims oldest messages (preserving the system prompt and the most recent message) to fit within the target model's limit.
 
-Estimated using a conservative heuristic: **4 characters = 1 token**.
+Conservative estimation: **4 characters = 1 token**.
 
 This is a rough last-resort cut, not a replacement for pi's built-in session compaction (`/compact`).
 
@@ -365,91 +365,118 @@ This is a rough last-resort cut, not a replacement for pi's built-in session com
 
 **Persistent State:** Router state persists across agent restarts AND conversation branches via `pi.appendEntry` with a custom `router-state` entry type. Pins, debug mode, debug history, the last routing decision, and the last non-router model are all preserved. State is **branch-safe** -- different conversation branches maintain independent state using `sessionManager.getBranch()`.
 
-**Status Line:** The router shows its status in the pi TUI status bar:
+**Status Line:** The router shows its status as a single line in the pi TUI status bar, e.g.:
 ```
-Router: enabled
-Profile: balanced (active)
-Pin: none
-Route: medium -> google/gemini-flash-latest
+⇋  medium -> google/gemini-flash-latest
 ```
 
-The `Route:` line may show decision flags in brackets when applicable:
-- `[classifier]` — routed by the LLM classifier
-
+The status line may show decision flags in brackets when applicable:
 - `[fallback]` — a fallback model was used
 - `[context]` — context threshold triggered an upgrade
 
-**Debug History:** With `/router debug on`, routing decisions and classifier gating decisions are logged with timestamps. View with `/router debug show` to see the routing history:
+**Debug History:** With `/router debug on`, routing decisions and classifier runs are logged with timestamps. View with `/router debug show` to see the routing history:
 
 ```
-RUN classifier — init(≥3), interval(%10) (cont:5)
-SKIP classifier (cont:2, fail:0)
+Running router classifier — init(≥3), interval(%10) (cont:5) ...
 ```
 
-The classifier gating notifications show why the classifier ran or was skipped (`cont` = tool-result continuations since the last user message, `fail` = consecutive recent tool failures).
+The classifier notification shows why the classifier was triggered (`cont` = tool-result continuations since the last user message, `fail` = consecutive recent tool failures).
 ```
-[10:32:15 AM] high -> openai/gpt-5.4-pro (high) - Detected planning from keywords.
-[10:33:42 AM] medium -> google/gemini-flash-latest (medium) - Detected implementation work.
-[10:34:10 AM] low -> openai/gpt-5.4-nano (low) - Detected a short read-only lookup request.
+[10:32:15 AM] high -> openai/gpt-5.4-pro (high) - Classifier: multi-file architecture change across 4 services requires careful trade-off analysis.
+[10:33:42 AM] medium -> google/gemini-flash-latest (medium) - Classifier: implementing a well-defined feature with clear acceptance criteria.
+[10:34:10 AM] low -> openai/gpt-5.4-nano (low) - Classifier: simple field rename with no behavioral changes.
 ```
 
 ---
 
-## Example Configurations
-
-### Balanced (`balanced`)
+## Example Configuration
 
 ```json
 {
-  "classifierModels": ["google/gemini-flash-latest"],
-  "defaultContextThresholdPercent": 70,
-  "profiles": {
-    "balanced": {
-      "high":    { "model": "openai/gpt-5.4-pro", "thinking": "high", "fallbacks": ["anthropic/claude-3-5-sonnet-20241022"] },
-      "medium":  { "model": "google/gemini-flash-latest", "thinking": "medium" },
-      "low":     { "model": "openai/gpt-5.4-nano", "thinking": "low" }
-    }
-  }
-}
-```
+  "debug": true,
+  "classifierModels": ["openrouter/deepseek/deepseek-v4-flash"],
+  "classifierModelThinking": "high",
+  "defaultContextThresholdPercent": 80,
+  "contextThresholdPercentOverrides": {
+    "opencode/deepseek-v4-flash-free": 60,
+    "openrouter/deepseek/deepseek-v4-flash": 60,
+    "openrouter/deepseek/deepseek-v4-pro": 50,
 
-### Budget-Conscious (`cheap`)
+    "openrouter/google/gemma-4-31b-it": 50,
+    "openrouter/google/gemini-3-flash-preview": 80,
+    "openrouter/google/gemini-3.5-flash": 80,
+    "openrouter/google/gemini-3.1-pro-preview": 18,
 
-```json
-{
-  "profiles": {
-    "cheap": {
-      "high":   { "model": "google/gemini-flash-latest",     "thinking": "low" },
-      "medium": { "model": "openai/gpt-5.4-nano",            "thinking": "off" },
-      "low":    { "model": "google/gemini-flash-lite-latest", "thinking": "off" }
-    }
-  }
-}
-```
+    "openrouter/moonshotai/kimi-k2.6": 70,
+    "openrouter/moonshotai/kimi-k2.7-code": 60,
 
-### Deep Reasoning (`deep`)
+    "openrouter/minimax/minimax-m3": 50,
 
-```json
-{
-  "profiles": {
-    "deep": {
-      "high":   { "model": "openai/o1-preview",          "thinking": "xhigh" },
-      "medium": { "model": "openai/gpt-5.4-pro",         "thinking": "medium" },
-      "low":    { "model": "google/gemini-flash-latest", "thinking": "low" }
-    }
-  }
-}
-```
+    "openrouter/z-ai/glm-5.2": 50,
 
-### Anthropic-Only (`anthropic`)
+    "openai-codex/gpt-5.4-mini": 60,
+    "openai-codex/gpt-5.5": 60,
+    "openai-codex/gpt-5.6-luna": 65,
+    "openai-codex/gpt-5.6-terra": 65,
+    "openai-codex/gpt-5.6-sol": 65,
+    "openrouter/openai/gpt-5.4-nano": 30,
 
-```json
-{
+    "openrouter/anthropic/claude-opus-4.8": 65,
+
+    "openrouter/x-ai/grok-4.5": 50
+  },
   "profiles": {
-    "anthropic": {
-      "high":   { "model": "anthropic/claude-3-5-sonnet-20241022", "thinking": "high" },
-      "medium": { "model": "anthropic/claude-3-5-sonnet-20241022", "thinking": "medium" },
-      "low":    { "model": "anthropic/claude-3-haiku-20240307",    "thinking": "low" }
+    "cheap": {
+      "high": {
+        "model": "openrouter/deepseek/deepseek-v4-flash", "thinking": "xhigh",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      },
+      "medium": {
+        "model": "openrouter/deepseek/deepseek-v4-flash", "thinking": "high",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      },
+      "low": {
+        "model": "openrouter/deepseek/deepseek-v4-flash", "thinking": "off",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      }
+    },
+    "balanced": {
+      "high": {
+        "model": "openrouter/z-ai/glm-5.2", "thinking": "xhigh",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      },
+      "medium": {
+        "model": "openrouter/deepseek/deepseek-v4-flash", "thinking": "xhigh",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      },
+      "low": {
+        "model": "openrouter/deepseek/deepseek-v4-flash", "thinking": "off",
+        "fallbacks": ["openrouter/minimax/minimax-m3"]
+      }
+    },
+    "expensive": {
+      "high": {
+        "model": "openrouter/z-ai/glm-5.2", "thinking": "max",
+        "fallbacks": ["openrouter/x-ai/grok-4.5", "openai/gpt-5.6-luna"]
+      },
+      "medium": {
+        "model": "openrouter/z-ai/glm-5.2", "thinking": "max",
+        "fallbacks": ["openai/gpt-5.6-luna", "openrouter/x-ai/grok-4.5"]
+      },
+      "low": {
+        "model": "openrouter/minimax/minimax-m3", "thinking": "off",
+        "fallbacks": ["openrouter/z-ai/glm-5.2"]
+      }
+    },
+    "gpt-5.6": {
+      "high": {   "model": "openai/gpt-5.6-sol", "thinking": "medium" },
+      "medium": { "model": "openai/gpt-5.6-terra", "thinking": "high" },
+      "low": {    "model": "openai/gpt-5.6-luna", "thinking": "high" }
+    },
+    "opus-4.8": {
+      "high": {   "model": "openrouter/anthropic/claude-opus-4.8", "thinking": "medium" },
+      "medium": { "model": "openrouter/anthropic/claude-opus-4.8", "thinking": "low" },
+      "low": {    "model": "openrouter/anthropic/claude-opus-4.8", "thinking": "off" }
     }
   }
 }
@@ -460,9 +487,3 @@ The classifier gating notifications show why the classifier ran or was skipped (
 ## Architecture
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a detailed architectural deep dive, including the decision flow, module responsibilities, state persistence, and fallback chain design.
-
----
-
-## License
-
-MIT (c) Ye Liu

package/docs/ARCHITECTURE.md

@@ -62,7 +62,7 @@ Router state is persisted using `pi.appendEntry` with a custom type `router-stat
 | Field | Type | Description |
 |---|---|---|
 | `selectedProfile` | `string` | Active profile name |
-| `pinnedTierByProfile` | `Record<string, TierLevel>` | Manual tier pins per profile |
+| `pinnedTierByProfile` | `Record<string, RouterTier>` | Manual tier pins per profile |
 | `debugEnabled` | `boolean` | Debug mode state |
 | `lastDecision` | `RoutingDecision` | Most recent routing decision |
 | `lastNonRouterModel` | `string` | Last model used before switching to router |

package/extensions/config.ts

@@ -14,7 +14,7 @@ import type {
 
 export const ROUTER_TIERS = ['high', 'medium', 'low'] as const;
 
-const THINKING_LEVELS: readonly ThinkingLevel[] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh'];  
+const THINKING_LEVELS: readonly ThinkingLevel[] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];  
 export const ROUTER_PIN_VALUES = ['clear', 'high', 'medium', 'low'] as const;
 
 const isObjectRecord = (

package/extensions/provider.ts

@@ -6,8 +6,8 @@ import {
   createAssistantMessageEventStream,
   type Model,
   type SimpleStreamOptions,
-  streamSimple
 } from '@earendil-works/pi-ai';
+import { streamSimple } from '@earendil-works/pi-ai/compat';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { RouterConfig, RouterPinByProfile, RouterTier, RoutingDecision } from './types';
 import { createOpenRouterOnPayload, OPENROUTER_ATTR_HEADERS, parseCanonicalModelRef, profileNames, resolveModelFromRef, ROUTER_TIERS } from './config';
@@ -95,7 +95,7 @@ export const registerRouterProvider = (
   const models = profileNames(currentConfig).map((name) => {
     const profile = currentConfig.profiles[name];
     let maxContextWindow = 0;
-    let maxOutputTokens = 0;
+    let maxTokens = 0;
 
     if (state.currentModelRegistry) {
       for (const tier of ROUTER_TIERS) {
@@ -108,7 +108,7 @@ export const registerRouterProvider = (
             const currentContextWindow = model.contextWindow ?? 0;
             if (currentContextWindow > maxContextWindow) {
               maxContextWindow = currentContextWindow;
-              maxOutputTokens = model.maxTokens ?? 120_000;
+              maxTokens = model.maxTokens ?? 120_000;
             }
           }
         }
@@ -116,7 +116,7 @@ export const registerRouterProvider = (
     }
 
     if (maxContextWindow === 0) maxContextWindow = 1_000_000;
-    if (maxOutputTokens === 0) maxOutputTokens = 120_000;
+    if (maxTokens === 0) maxTokens = 120_000;
 
     const profileSupportsReasoning = state.currentModelRegistry
       ? ROUTER_TIERS.some((tier) => {
@@ -138,7 +138,7 @@ export const registerRouterProvider = (
       input: ['text', 'image'] as ('text' | 'image')[],
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
       contextWindow: maxContextWindow,
-      maxTokens: maxOutputTokens,
+      maxTokens,
     };
   });
 
@@ -417,8 +417,8 @@ export const registerRouterProvider = (
 
           if (!success) {
             const errorMsg = `Failed to delegate to any model in the chain.${failureReasons.length > 0 ? ' Reasons: ' + failureReasons.filter(Boolean).join('; ') + '.' : ''}`;
-            const combined = lastError ? new Error(`${(lastError as Error).message} — ${errorMsg}`) : new Error(errorMsg);
-            throw combined;
+            const combinedError = lastError ? new Error(`${(lastError as Error).message} — ${errorMsg}`) : new Error(errorMsg);
+            throw combinedError;
           }
 
           stream.end();

package/extensions/routing.ts

@@ -1,4 +1,5 @@
-import { type Context, type Message, streamSimple } from '@earendil-works/pi-ai';
+import { streamSimple } from '@earendil-works/pi-ai/compat';
+import type { Context, Message } from '@earendil-works/pi-ai';
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { RouterConfig, RouterProfile, RouterTier, RoutingDecision } from './types';
 import { createOpenRouterOnPayload, OPENROUTER_ATTR_HEADERS, parseCanonicalModelRef, resolveModelFromRef } from './config';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kdejaeger/pi-model-router",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "description": "Intelligent per-turn model router extension for the pi coding agent",
   "keywords": [
@@ -41,10 +41,10 @@
     "prepublishOnly": "npm run tsc"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Ye Liu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.