@kdejaeger/pi-model-router 0.4.1 → 0.4.2

package/README.md

@@ -1,41 +1,32 @@
 # pi-model-router
 
 [![npm version](https://img.shields.io/npm/v/@kdejaeger/pi-model-router)](https://www.npmjs.com/package/@kdejaeger/pi-model-router)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Intelligent per-turn model router extension** (forked from [yeliu84/pi-model-router](https://github.com/yeliu84/pi-model-router)) for the [pi-coding-agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent). Automatically selects between high, medium, and low-tier LLMs on every turn based on task intent and context size — with automatic fallbacks, image-aware rerouting, context truncation, and classifier-based tier selection.
+> Think of pi-model-router as an automatic transmission for your LLM — it shifts gears up or down depending on what you're doing, so you never waste compute on a trivial task or run out of reasoning power on a complex one.
 
-> Think of it as an automatic transmission for your LLM -- it shifts gears up or down depending on what you're doing, so you never waste compute on a trivial task or run out of reasoning power on a complex one.
-
----
+This extension (forked from [yeliu84/pi-model-router](https://github.com/yeliu84/pi-model-router)) for the [pi-coding-agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) automatically selects between high, medium, and low-tier LLMs on every few turns. It considers conversation history, context size and thresholds, image presence, manual tier pins, tool-result continuation patterns, previous routing decisions, and automatic fallbacks — with context truncation as a last resort.
 
 ## Table of Contents
 
-- [How It Works](#how-it-works)
+- [Overview](#overview)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+- [Activating the Router](#activating-the-router)
 - [Commands](#commands)
 - [How Routing Works](#how-routing-works)
-- [Example Configurations](#example-configurations)
 - [Architecture](#architecture)
-- [License](#license)
-
----
+- [Documentation](#documentation)
 
-## How It Works
 
-The pi-model-router registers itself as a **custom logical provider** (`router`) via `pi.registerProvider`. Each profile becomes a stable model (e.g., `router/balanced`). **The model shown in your footer stays fixed** while the underlying LLM changes per turn based on task complexity:
+## Overview
 
-```
-  footer shows: router/balanced
+The pi-model-router registers itself as a **custom logical provider** (`router`) via `pi.registerProvider`. Each profile becomes a stable model (e.g., `router/cheap`). The model shown in your footer on the left stays fixed, while the underlying LLM changes per turn based on task complexity.
 
-  Turn 1: "Plan the architecture for the new API" → openai/gpt-5.4-pro       (high)
-  Turn 2: "Yes, go ahead"                  → openai/gpt-5.4-pro       (high)
-  Turn 3: "Implement the API handlers"     → google/gemini-flash      (med)
-```
+![Router footer](docs/footer.png)
+![Router screenshot](docs/screenshot.png)
 
----
+For the full decision pipeline, see [How Routing Works](#how-routing-works).
 
 ## Installation
 
@@ -59,30 +50,95 @@ Or load directly for a single run:
 pi -e ./extensions/index.ts
 ```
 
----
-
 ## Quick Start
 
 1. **Install** the package (see above).
 
-2. **Create a config file** at `.pi/model-router.json` in your project (bigger example configs later in this document):
-
-   ```json
-   {
-     "profiles": {
-       "balanced": {
-         "high":    { "model": "openai/gpt-5.4-pro",          "thinking": "high" },
-         "medium":  { "model": "google/gemini-flash-latest",  "thinking": "medium" },
-         "low":     { "model": "openai/gpt-5.4-nano",         "thinking": "low" }
-       },
-       "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" }
-       }
-     }
-   }
-   ```
+2. **Create a config file** at `.pi/model-router.json`. Here is an example.
+
+```json
+{
+  "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,
+    "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,
+    "openrouter/moonshotai/kimi-k2.6": 70,
+    "openrouter/moonshotai/kimi-k2.7-code": 60,
+    "openrouter/minimax/minimax-m3": 50,
+    "openrouter/z-ai/glm-5.2": 50,
+    "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,
+    "openrouter/anthropic/claude-opus-4.8": 65,
+    "openrouter/x-ai/grok-4.5": 50
+  },
+  "profiles": {
+    "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" }
+    }
+  }
+}
+```
 
 3. **Activate the router** -- choose one approach:
 
@@ -99,7 +155,127 @@ pi -e ./extensions/index.ts
    /router
    ```
 
----
+## How Routing Works
+
+For every turn, the router executes this ordered pipeline:
+
+```
+GATE 0: GOOGLE LOCK
+  Google thinking used last turn AND this is a tool continuation?
+  → Freeze the exact model/tier (skip everything below)
+
+GATE 1: CLASSIFIER GATING
+  Manual pin active?       → Use pinned tier (skip classifier)
+  New user message?       → Run classifier from scratch
+  Tool-result continuation?
+  ├─ Initial tool results back after user prompt?   → Run classifier
+  ├─ Multiple tool failures in a row?               → Run classifier
+  ├─ Periodic check due?                            → Run classifier
+  └─ Otherwise                                      → Reuse previous routing decision
+
+POST-ROUTE CORRECTIONS (always apply)
+  Image doesn't fit?  → Search current and higher tiers for a model supporting images
+  Context too full?   → Search current and higher tiers for a model with a bigger context window
+
+EXECUTION
+  Context window too small?   → Trim oldest messages to fit the target model
+  Model failed?       → Try fallbacks in order, then surface the error
+  Model got swapped?  → Re-assert the router model after the turn
+```
+
+### Classifier Gating
+
+When the router has an LLM classifier configured (`classifierModels`), it doesn't run on every turn. Instead, the classifier is gated by smart triggers that avoid waste while catching real tier mismatches. The classifier has final say on tier (post-route corrections like image escalation).
+
+| Gate | Trigger                                                                                     | Reason |
+|---|---------------------------------------------------------------------------------------------|---|
+| **Google lock** | Previous model was Google with thinking, and this is a tool-result continuation             | Freezes to the same model — any change breaks thought-signature replay |
+| **Fresh feedback** | Tool-continuation count first reaches or exceeds `classifierRunOnceAfterToolCount` (default: 3) | Captures the assistant's first response + tool result after a new user message |
+| **Tool failures** | Consecutive failed tool results (from the tail) ≥ `classifierRunAfterToolFailures` (default: 2)   | Model is struggling — reclassify to potentially upgrade tier |
+| **Interval** | Tool-continuation count % `classifierInterval` === 0 (default: 10)                           | Periodic re-check for long-running turns where initial assessment might be stale |
+
+All counters reset per user turn — each new user message is treated as a fresh task. The tool failures gate counts **consecutive** failures from the tail: one successful tool result resets the count to 0, so it only fires when failures are actually piling up.
+
+When the classifier is skipped, the **previous routing decision** is reused directly. Post-route corrections (image escalation) still apply regardless.
+
+### Context Controls
+
+Modern models offer large context windows, but filling them to 100% before a tier switch is rarely desirable. Some models also increase pricing after a certain token threshold (e.g., double the input/output cost beyond 250K tokens). The context threshold lets you define the percentage of a model's window at which the router considers escalating to a higher tier.
+
+**Context & Image Requirements** (`defaultContextThresholdPercent`): When the conversation context exceeds this percentage of a model's window, the router searches for a suitable model in the current or higher tiers.
+
+**Per-Model Overrides** (`contextThresholdPercentOverrides`): Tune the context threshold for specific models. Keys are canonical model refs in `"provider/model"` format. Values are percentages; lower values cause the router to consider upgrading sooner.
+
+```json
+{
+  "defaultContextThresholdPercent": 80,
+  "contextThresholdPercentOverrides": {
+    "openrouter/deepseek/deepseek-v4-flash": 60,
+    "openrouter/deepseek/deepseek-v4-pro": 50,
+    "openai-codex/gpt-5.5": 60,
+    "openrouter/google/gemini-3.1-pro-preview": 18
+  }
+}
+```
+
+### Fallback Chains
+
+Each tier can define `fallbacks` -- an ordered list of alternative models. If the primary model fails, the router retries each fallback in sequence before surfacing an error.
+
+```json
+{
+  "profiles": {
+    "auto": {
+      "high": {
+        "model": "openai/gpt-5.4-pro",
+        "fallbacks": ["anthropic/claude-3-5-sonnet-20241022", "google/gemini-2.5-pro-latest"]
+      }
+    }
+  }
+}
+```
+
+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 **once** (2 total attempts) before moving to the next fallback in the chain.
+
+### Image-Aware Auto-Routing
+
+When the user attaches an image, the router checks whether the routed model supports image inputs. If not, it searches for another model in the same tier that does. If none are found, it escalates to higher tiers until a suitable model is found.
+
+> **Note:** The search ensures that the selected model also fits the current context window requirements. To avoid landing on a model that can see images but not the full conversation, make sure your models have adequate context windows and image support configured.
+
+### Google Thinking Tool Continuation
+
+When using Google models with thinking enabled, tool-result continuations require the **same model** to avoid thought-signature replay errors. The router detects this pattern and preserves the exact model/tier for the continuation turn.
+
+### Auto-Context Truncation
+
+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.
+
+Conservative estimation: **4 characters = 1 token**.
+
+This is a rough last-resort cut, not a replacement for pi's built-in session compaction (`/compact`).
+
+### Session & Debugging
+
+**Persistent State:** Router state persists across agent restarts AND conversation branches via `pi.appendEntry` with a custom `router-state` entry type. Pins, debug mode, 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 as a single line in the pi TUI status bar, e.g.:
+```
+⇋  medium -> google/gemini-flash-latest
+```
+
+The status line may show decision flags in brackets when applicable:
+- `[fallback]` — a fallback model was used
+- `[context]` — context threshold triggered an upgrade
+
+**Debug Notifications:** With `/router debug on`, routing decisions and classifier runs are logged as notifications with timestamps. 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) - 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.
+```
 
 ## Configuration
 
@@ -112,15 +288,7 @@ Config is loaded from two locations and **merged**:
 | Global | User-wide | `~/.pi/agent/model-router.json` |
 | Project | Per-project | `.pi/model-router.json` |
 
-### Config Merging Order
-
-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.
-
-**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.
-
-
+For details on merging order and validation, see [Config Merging Order](docs/ARCHITECTURE.md#config-merging-order) in the architecture doc.
 
 ### Configuration Fields
 
@@ -133,7 +301,6 @@ Project config values override global values, which override built-in defaults.
 | `classifierRunAfterToolFailures` | `number` | `2` | Run the classifier after this many consecutive tool failures (counting from the tail of the current turn). Default: 2.                                                                                                                                                                                                                                                                                                  |
 | `classifierInterval` | `number` | `10` | Run the classifier every N tool continuations as a periodic re-check (crossed interval buckets). Default: 10. Set to 0 to disable.                                                                                                                                                                                                                                                                                             |
 | `defaultContextThresholdPercent` | `number` | `90`         | Default percentage threshold of a model's context window. If session context usage exceeds this percentage, the router searches for a suitable model in the current or higher tiers.                                                                                                                                                                                                                |
-| `contextThresholdPercentOverrides` | `Record<string, number>` | -- | **Optional.** Per-model context threshold overrides. Keys are canonical model refs in `"provider/model"` format. Values are the percentage of that model's context window that triggers an upgrade search. These take precedence over `defaultContextThresholdPercent`. Unknown keys produce a warning on provider registration. See [Context Threshold Overrides](#context-threshold-overrides). |
 | `profiles` | `object` | _(required)_ | Map of profile definitions.                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Profile Definitions
@@ -148,35 +315,6 @@ Each profile defines three **tiers** (`high`, `medium`, `low`). Each tier config
 
 **Valid thinking levels** (from least to most reasoning): `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
 
-### Context Threshold Overrides
-
-Use `contextThresholdPercentOverrides` to tune the context threshold for specific models. Keys must be canonical model refs in `"provider/model"` format. Values are percentages; lower values cause the router to consider upgrading sooner.
-
-```json
-{
-  "contextThresholdPercentOverrides": {
-    "openrouter/deepseek/deepseek-v4-flash": 60,
-    "openrouter/deepseek/deepseek-v4-pro": 50,
-    "openai-codex/gpt-5.5": 60,
-    "openrouter/google/gemini-3.1-pro-preview": 18
-  }
-}
-```
-
-
-
-### Config Validation
-
-The config system performs thorough validation on reload/startup and surfaces warnings via the notification system:
-
-- Validates all profile model refs are in `provider/model` format
-- Validates thinking levels against allowed values
-- Reports missing/invalid profiles with fallback resolution
-- Normalizes `defaultContextThresholdPercent` to positive values only
-- Validates `contextThresholdPercentOverrides` keys against known models; unknown keys produce a warning on provider registration
-
----
-
 ## Activating the Router
 
 When you define profiles in your config, each profile is registered as a model with the `router` provider — e.g., `router/balanced`, `router/cheap`. These models appear in pi's model list and are available for selection in pi's model switcher, just like any other model.
@@ -233,15 +371,13 @@ Valid pin values: `high`, `medium`, `low`, `clear`.
 
 
 
-### `/router debug <on|off|show|clear>`
+### `/router debug <on|off>`
 
-Control turn-by-turn routing debug notifications and history. Debug history stores the last 12 routing decisions.
+Control turn-by-turn routing debug notifications.
 
 ```bash
 /router debug on       # Enable
 /router debug off      # Disable
-/router debug show     # Show the last 12 routing decisions
-/router debug clear    # Clear history
 /router debug          # Toggle
 ```
 
@@ -261,229 +397,8 @@ Show a comprehensive help listing of all subcommands.
 
 ```bash
 /router help
-/router ?
-```
-
----
-
-## How Routing Works
-
-For every turn, the router executes this ordered pipeline:
-
-```
-GATE 0: GOOGLE LOCK
-  - Google thinking tool continuation? → preserve exact model/tier
-     (skips EVERYTHING below)
-
-GATE 1: CLASSIFIER GATING (only when classifierModels is configured)
-  - Manual pin set → use pinned tier, classifier is skipped entirely
-  - No classifier result yet → default to `medium`
-  - New user message → run classifier
-  - Tool-result continuation?
-     ├─ contCount >= classifierRunOnceAfterToolCount (first crossing)? → run once
-     ├─ Consecutive failures >= classifierRunAfterToolFailures? → run (crisis)
-     ├─ contCount % classifierInterval === 0? → run (periodic)
-     └─ Otherwise → reuse previous decision
-
-POST-ROUTE CORRECTIONS (always apply)
-  - Image-aware escalation: upgrade tier if routed model
-     doesn't support image attachments
-  - Context threshold enforcement: if context usage exceeds
-     threshold, re-search for a suitable model in current or
-     higher tiers (strict pass first, truncation pass as fallback)
-
-EXECUTION
-  - Auto-context truncation: trim oldest messages if target
-     model's window is smaller than the profile's maximum window
-  - Fallback chain: retry fallback models if primary fails
-  - Post-turn re-assert: re-select the router model after each turn if it was changed
-```
-
-
-
-### Classifier Gating
-
-When the router has an LLM classifier configured (`classifierModels`), it doesn't run on every turn. Instead, the classifier is gated by smart triggers that avoid waste while catching real tier mismatches. **The classifier has final say on tier** (post-route corrections like image escalation).
-
-| Gate | Trigger                                                                                     | Reason |
-|---|---------------------------------------------------------------------------------------------|---|
-| **Google lock** | Previous model was Google with thinking, and this is a tool-result continuation             | Freezes to the same model — any change breaks thought-signature replay |
-| **Fresh feedback** | Tool-continuation count first reaches or exceeds `classifierRunOnceAfterToolCount` (default: 3) | Captures the assistant's first response + tool result after a new user message |
-| **Crisis** | Consecutive failed tool results (from the tail) ≥ `classifierRunAfterToolFailures` (default: 2)   | Model is struggling — reclassify to potentially upgrade tier |
-| **Interval** | Tool-continuation count % `classifierInterval` === 0 (default: 10)                           | Periodic re-check for long-running turns where initial assessment might be stale |
-
-All counters reset per user turn — each new user message is treated as a fresh task. The crisis gate counts **consecutive** failures from the tail: one successful tool result resets the count to 0, so it only fires when failures are actually piling up.
-
-When the classifier is skipped, the **previous routing decision** is reused directly. Post-route corrections (image escalation) still apply regardless.
-
-### Context Controls
-
-**Context & Image Requirements** (`defaultContextThresholdPercent`): When the conversation context exceeds this percentage of a model's window, or when images are detected, the router searches for a suitable model in the current or higher tiers. This check happens on every turn, but since context usage usually only grows across turns (unless compaction reduces it), the router will often stay in higher tiers once pushed there.
-
-
-
-### Fallback Chains
-
-Each tier can define `fallbacks` -- an ordered list of alternative models. If the primary model fails, the router retries each fallback in sequence before surfacing an error.
-
-```json
-{
-  "profiles": {
-    "auto": {
-      "high": {
-        "model": "openai/gpt-5.4-pro",
-        "fallbacks": ["anthropic/claude-3-5-sonnet-20241022", "google/gemini-2.5-pro-latest"]
-      }
-    }
-  }
-}
-```
-
-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 **once** (2 total attempts) before moving to the next fallback in the chain.
-
-### Image-Aware Auto-Routing
-
-When the user attaches an image, the router checks whether the routed model supports image inputs. If not, it searches for another model in the same tier that does. If none are found, it escalates to higher tiers until a suitable model is found.
-
-> **Note:** The search ensures that the selected model also fits the current context window requirements. To avoid landing on a model that can see images but not the full conversation, make sure your models have adequate context windows and image support configured.
-
-### Google Thinking Tool Continuation
-
-When using Google models with thinking enabled, tool-result continuations require the **same model** to avoid thought-signature replay errors. The router detects this pattern and preserves the exact model/tier for the continuation turn.
-
-### Auto-Context Truncation
-
-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.
-
-Conservative estimation: **4 characters = 1 token**.
-
-This is a rough last-resort cut, not a replacement for pi's built-in session compaction (`/compact`).
-
-### Session & Debugging
-
-**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 as a single line in the pi TUI status bar, e.g.:
-```
-⇋  medium -> google/gemini-flash-latest
-```
-
-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 runs are logged with timestamps. View with `/router debug show` to see the routing history:
-
-```
-Running router classifier — init(≥3), interval(%10) (cont:5) ...
 ```
 
-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) - 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 Configuration
-
-```json
-{
-  "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,
-
-    "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,
-
-    "openrouter/moonshotai/kimi-k2.6": 70,
-    "openrouter/moonshotai/kimi-k2.7-code": 60,
-
-    "openrouter/minimax/minimax-m3": 50,
-
-    "openrouter/z-ai/glm-5.2": 50,
-
-    "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,
-
-    "openrouter/anthropic/claude-opus-4.8": 65,
-
-    "openrouter/x-ai/grok-4.5": 50
-  },
-  "profiles": {
-    "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" }
-    }
-  }
-}
-```
-
----
-
 ## 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.

package/docs/ARCHITECTURE.md

@@ -49,6 +49,36 @@ session_start / model_select / turn_end (index.ts)
         they do not perform routing themselves.
 ```
 
+## Config Merging Order
+
+Config is loaded from two locations and **merged**:
+
+| Location | Scope | Path |
+|---|---|---|
+| Global | User-wide | `~/.pi/agent/model-router.json` |
+| Project | Per-project | `.pi/model-router.json` |
+
+The merge order is: **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.
+
+**When no config file exists**, the router loads with an empty profile list and no active models.
+
+### Why Two Config Locations?
+
+- **Global config** (`~/.pi/agent/model-router.json`) lets you set cross-project defaults — profile definitions, classifier preferences, and context thresholds you want everywhere.
+- **Project config** (`.pi/model-router.json`) lets you override per-project — different profile choices, tighter context budgets, or debug flags for development.
+
+This is handled by `extensions/config.ts`, which normalizes and validates the merged result.
+
+### Config Validation
+
+On reload/startup, the config system validates:
+- Profile model refs are in `provider/model` format
+- Thinking levels are valid (`off` → `max`)
+- `defaultContextThresholdPercent` is positive
+- `contextThresholdPercentOverrides` keys match known models (unknown keys produce a warning on provider registration)
+
 ## State & Persistence
 
 Router state is persisted using `pi.appendEntry` with a custom type `router-state`. This allows the router to:
@@ -66,10 +96,8 @@ Router state is persisted using `pi.appendEntry` with a custom type `router-stat
 | `debugEnabled` | `boolean` | Debug mode state |
 | `lastDecision` | `RoutingDecision` | Most recent routing decision |
 | `lastNonRouterModel` | `string` | Last model used before switching to router |
-| `debugHistory` | `RoutingDecision[]` | Recent routing decisions |
-
-> **Branch safety**: Because state is saved via `pi.appendEntry`, each conversation branch gets its own independent state. Switching branches restores the pins and history that were active on that branch.
+> **Branch safety**: Because state is saved via `pi.appendEntry`, each conversation branch gets its own independent state. Switching branches restores the pins and state that were active on that branch.
 
-### Debug History
+### Debug Mode
 
-The debug history stores the last 12 routing decisions. When debug mode is enabled (`/router debug on`), each decision is appended to `debugHistory` and `/router debug show` prints the full history.
+Use `/router debug on` to enable debug notifications for routing decisions and classifier runs.

package/extensions/commands.ts

@@ -16,7 +16,6 @@ import {
 } from './config';
 import {
   formatPinSummary,
-  formatDecision,
 } from './ui';
 
 export const registerCommands = (
@@ -29,7 +28,6 @@ export const registerCommands = (
     readonly lastDecision: RoutingDecision | undefined;
     lastNonRouterModel: string | undefined;
     debugEnabled: boolean;
-    readonly debugHistory: RoutingDecision[];
     readonly lastConfigWarnings: string[];
   },
   actions: {
@@ -53,7 +51,7 @@ export const registerCommands = (
     { name: 'pin', desc: 'Pin routing for a profile to a tier, or clear' },
     { name: 'disable', desc: 'Disable the router and restore last model' },
 
-    { name: 'debug', desc: 'Toggle or clear router debug history' },
+    { name: 'debug', desc: 'Toggle router debug notifications on/off' },
     { name: 'reload', desc: 'Reload the model router configuration' },
     { name: 'help', desc: 'Show usage help for subcommands' },
   ];
@@ -120,7 +118,6 @@ export const registerCommands = (
       `Available profiles: ${profileNames(state.currentConfig).join(', ')}`,
       `Last non-router model: ${state.lastNonRouterModel ?? 'none'}`,
       `Debug: ${state.debugEnabled ? 'on' : 'off'}`,
-      `Debug history: ${state.debugHistory.length} decisions`,
     ];
     if (state.lastDecision) {
       lines.push(
@@ -261,22 +258,13 @@ export const registerCommands = (
 
   const handleDebug = async (args: string[], ctx: ExtensionContext) => {
     if (args.length > 1) {
-      ctx.ui.notify('Usage: /router debug <on|off|show|clear>', 'error');
+      ctx.ui.notify('Usage: /router debug <on|off>', 'error');
       return;
     }
     const cmd = args[0]?.toLowerCase();
     if (cmd === 'on') state.debugEnabled = true;
     else if (cmd === 'off') state.debugEnabled = false;
-    else if (cmd === 'clear') state.debugHistory.length = 0;
-    else if (cmd === 'show') {
-      if (state.debugHistory.length === 0) {
-        ctx.ui.notify('No recent routing decisions.', 'info');
-      } else {
-        const history = state.debugHistory.map(formatDecision).join('\n');
-        ctx.ui.notify(`Recent Routing Decisions:\n${history}`, 'info');
-      }
-      return;
-    } else {
+    else {
       state.debugEnabled = !state.debugEnabled;
     }
     actions.persistState();
@@ -363,7 +351,7 @@ export const registerCommands = (
         }
         case 'debug': {
           const debugPrefix = subArgs[0] ?? '';
-          const items = ['on', 'off', 'toggle', 'clear', 'show']
+          const items = ['on', 'off', 'toggle']
             .filter((v) => v.startsWith(debugPrefix))
             .map((v) => ({
               value: `debug ${v}`,
@@ -401,7 +389,6 @@ export const registerCommands = (
           await handleStatus(subArgs, ctx);
           break;
         case 'help':
-        case '?':
           if (subArgs.length > 0) {
             ctx.ui.notify('Usage: /router help (no arguments)', 'error');
             return;
@@ -413,9 +400,9 @@ export const registerCommands = (
               '  profile [name]              Switch to a profile (enables router if off). Lists available if no name.',
               '  pin [profile] <tier|clear>   Pin to a tier (high|medium|low) or clear the pin.',
               '  disable                     Disable the router and restore the last used non-router model.',
-              '  debug <on|off|show|clear>   Control routing debug logging to notifications and history.',
+              '  debug <on|off>            Enable/disable routing debug notifications.',
               '  reload                      Hot-reload the configuration JSON from .pi/model-router.json.',
-              '  help, ?                     Show this help message.',
+              '  help                         Show this help message.',
             ].join('\n'),
             'info',
           );

package/extensions/index.ts

@@ -28,7 +28,6 @@ const routerExtension = (pi: ExtensionAPI) => {
   let selectedProfile: string | undefined;
   let lastLoadedModelKeys = '';
   let pinnedTierByProfile: RouterPinByProfile = {};
-  let debugHistory: RoutingDecision[] = [];
   let lastNonRouterModel: string | undefined;
   let lastExtensionContext: ExtensionContext | undefined;
   let lastConfigWarnings: string[] = [];
@@ -47,18 +46,12 @@ const routerExtension = (pi: ExtensionAPI) => {
     }
   };
 
-  const MAX_DEBUG_HISTORY = 12;
-  const recordDebugDecision = (decision: RoutingDecision) => {
-    debugHistory = [...debugHistory, decision].slice(-MAX_DEBUG_HISTORY);
-  };
-
   const persistState = () => {
     const state = buildPersistedState(
       routerEnabled,
       selectedProfile,
       pinnedTierByProfile,
       debugEnabled,
-      debugHistory,
       lastDecision,
       lastNonRouterModel,
     );
@@ -68,10 +61,6 @@ const routerExtension = (pi: ExtensionAPI) => {
       lastDecision: state.lastDecision
         ? { ...state.lastDecision, timestamp: 0 }
         : undefined,
-      debugHistory: state.debugHistory?.map((decision) => ({
-        ...decision,
-        timestamp: 0,
-      })),
     });
     if (snapshot === lastPersistedSnapshot) {
       return;
@@ -210,7 +199,6 @@ const routerExtension = (pi: ExtensionAPI) => {
         },
         {
           persistState,
-          recordDebugDecision,
           updateStatus: actions.updateStatus,
         },
       );
@@ -234,7 +222,6 @@ const routerExtension = (pi: ExtensionAPI) => {
       ctx.model?.provider === 'router' ? ctx.model.id : selectedProfile,
     );
     pinnedTierByProfile = {};
-    debugHistory = [];
     lastNonRouterModel =
       ctx.model && ctx.model.provider !== 'router'
         ? `${ctx.model.provider}/${ctx.model.id}`
@@ -267,9 +254,6 @@ const routerExtension = (pi: ExtensionAPI) => {
         pinnedTierByProfile[selectedProfile] = savedState.pinTier;
       }
       debugEnabled = savedState.debugEnabled ?? debugEnabled;
-      debugHistory = savedState.debugHistory
-        ? [...savedState.debugHistory].slice(-MAX_DEBUG_HISTORY)
-        : [];
       lastNonRouterModel = savedState.lastNonRouterModel ?? lastNonRouterModel;
     }
 
@@ -335,9 +319,7 @@ const routerExtension = (pi: ExtensionAPI) => {
       set debugEnabled(v) {
         debugEnabled = v;
       },
-      get debugHistory() {
-        return debugHistory;
-      },
+      
       get lastConfigWarnings() {
         return lastConfigWarnings;
       },

package/extensions/provider.ts

@@ -85,7 +85,6 @@ export const registerRouterProvider = (
   },
   actions: {
     persistState: () => void;
-    recordDebugDecision: (decision: RoutingDecision) => void;
     updateStatus: (ctx: ExtensionContext) => void;
   },
 ) => {
@@ -413,8 +412,6 @@ export const registerRouterProvider = (
             }
           }
 
-          actions.recordDebugDecision(decision);
-
           if (!success) {
             const errorMsg = `Failed to delegate to any model in the chain.${failureReasons.length > 0 ? ' Reasons: ' + failureReasons.filter(Boolean).join('; ') + '.' : ''}`;
             const combinedError = lastError ? new Error(`${(lastError as Error).message} — ${errorMsg}`) : new Error(errorMsg);

package/extensions/state.ts

@@ -23,7 +23,6 @@ export const buildPersistedState = (
   selectedProfile: string | undefined,
   pinnedTierByProfile: RouterPinByProfile,
   debugEnabled: boolean,
-  debugHistory: RoutingDecision[],
   lastDecision?: RoutingDecision,
   lastNonRouterModel?: string,
 ): RouterPersistedState => ({
@@ -32,7 +31,6 @@ export const buildPersistedState = (
   pinTier: selectedProfile ? pinnedTierByProfile[selectedProfile] : undefined,
   pinByProfile: { ...pinnedTierByProfile },
   debugEnabled,
-  debugHistory,
   lastDecision,
   lastNonRouterModel,
   timestamp: Date.now(),

package/extensions/types.ts

@@ -51,7 +51,6 @@ export interface RouterPersistedState {
   pinTier?: RouterTier;
   pinByProfile?: RouterPinByProfile;
   debugEnabled?: boolean;
-  debugHistory?: RoutingDecision[];
   lastDecision?: RoutingDecision;
   lastNonRouterModel?: string;
   timestamp: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kdejaeger/pi-model-router",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "description": "Intelligent per-turn model router extension for the pi coding agent",
   "keywords": [
@@ -33,7 +33,8 @@
   "pi": {
     "extensions": [
       "./extensions/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/kdejaeger/pi-model-router/main/docs/icon.svg"
   },
   "scripts": {
     "tsc": "tsc --noEmit",

package/model-router.example.json

@@ -1,48 +0,0 @@
-{
-  "debug": false,
-  "classifierModels": ["google/gemini-flash-lite-latest", "openrouter/deepseek/deepseek-v4-flash"],
-  "classifierModelThinking": "off",
-  "classifierRunOnceAfterToolCount": 3,
-  "classifierRunAfterToolFailures": 2,
-  "classifierInterval": 10,
-  "defaultContextThresholdPercent": 70,
-  "contextThresholdPercentOverrides": {
-    "openrouter/deepseek/deepseek-v4-flash": 60,
-    "openrouter/deepseek/deepseek-v4-pro": 50,
-    "openrouter/google/gemma-4-31b-it": 50,
-    "openrouter/google/gemini-3-flash-preview": 80,
-    "openrouter/openai/gpt-5.4-nano": 30
-  },
-  "profiles": {
-    "auto": {
-      "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" }
-    },
-    "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" }
-    },
-    "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" }
-    },
-    "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" }
-    }
-  }
-}