ultimate-pi 0.2.7 → 0.3.1

package/.pi/scripts/harness-sync-model-router.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * After `.pi/model-router.json` exists, set sensible Pi defaults (`router` / `auto`)
+ * when the project has no `defaultProvider`. Does **not** add/remove npm packages
+ * — model routing ships vendored inside ultimate-pi.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+function loadSettings(settingsPath) {
+	if (!existsSync(settingsPath)) {
+		return null;
+	}
+	try {
+		return JSON.parse(readFileSync(settingsPath, "utf8"));
+	} catch {
+		console.error("[harness-model-router] Invalid JSON:", settingsPath);
+		process.exit(1);
+	}
+}
+
+function saveSettings(settingsPath, data) {
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(
+		settingsPath,
+		`${JSON.stringify(data, null, "\t")}\n`,
+		"utf8",
+	);
+}
+
+function main() {
+	const root = process.cwd();
+	const configPath = join(root, ".pi", "model-router.json");
+	const settingsPath = join(root, ".pi", "settings.json");
+	const hasConfig = existsSync(configPath);
+
+	const settings = loadSettings(settingsPath);
+	if (!settings) {
+		console.warn(
+			"[harness-model-router] No .pi/settings.json — skipping (merge Step 3 first)",
+		);
+		process.exit(0);
+	}
+
+	let changed = false;
+
+	if (!hasConfig) {
+		if (settings.defaultProvider === "router") {
+			delete settings.defaultProvider;
+			delete settings.defaultModel;
+			changed = true;
+		}
+		if (changed) {
+			saveSettings(settingsPath, settings);
+			console.warn(
+				"⚠ No .pi/model-router.json — cleared router defaultProvider if present",
+			);
+		} else {
+			console.log("[harness-model-router] No config file; nothing to do");
+		}
+		process.exit(0);
+	}
+
+	const noProjectDefault =
+		settings.defaultProvider == null || settings.defaultProvider === "";
+
+	if (noProjectDefault) {
+		settings.defaultProvider = "router";
+		settings.defaultModel = "auto";
+		changed = true;
+	}
+
+	if (changed) {
+		saveSettings(settingsPath, settings);
+		console.log(
+			"✓ Router defaults set (`router` / `auto`) — run /reload in pi when ready",
+		);
+	} else {
+		console.log("[harness-model-router] Defaults unchanged (user set defaultProvider)");
+	}
+}
+
+main();

package/.pi/scripts/harness-verify.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * harness:verify — deterministic harness contract checks (no LLM).
+ * harness-verify — deterministic harness contract checks (no LLM).
  */
 
 import { readFile, access } from "node:fs/promises";
@@ -122,12 +122,14 @@ async function checkSentruxRules() {
 		"--check",
 	]);
 	if (checkCode !== 0) {
-		fail(checkOut.trim() || "sentrux rules.toml out of date — run harness:sentrux-sync");
+		fail(checkOut.trim() || "sentrux rules.toml out of date — run node \"$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs\" --force (see .pi/scripts/README.md for UP_PKG)");
 	}
 	ok("sentrux rules.toml in sync with manifest");
 
 	if (!(await fileExists(SENTRUX_RULES))) {
-		fail("missing .sentrux/rules.toml — run npm run harness:sentrux-sync");
+		fail(
+			"missing .sentrux/rules.toml — run node \"$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs\" --force (resolve UP_PKG via .pi/scripts/README.md)",
+		);
 	}
 	ok(".sentrux/rules.toml present");
 }

package/.pi/scripts/sentrux-rules-sync.mjs

@@ -80,7 +80,7 @@ function renderManagedBlock(manifest) {
 function mergeRules(existing, managedBlock) {
 	const header = `# Sentrux rules — ${new Date().toISOString().slice(0, 10)}
 # Docs: https://sentrux.dev/docs/rules-engine/
-# Sync: npm run harness:sentrux-sync (or /harness-sentrux-sync in pi)
+# Sync: node $UP_PKG/.pi/scripts/sentrux-rules-sync.mjs --force (see .pi/scripts/README.md for UP_PKG) or /harness-sentrux-sync in pi
 #
 # Custom rules: add TOML below the managed block; they are preserved on sync.
 
@@ -168,7 +168,7 @@ async function main() {
 		if (checkOnly) process.exit(0);
 	} else if (checkOnly) {
 		fail(
-			"rules.toml out of date — run npm run harness:sentrux-sync",
+			"rules.toml out of date — run node \"$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs\" --force (see .pi/scripts/README.md for UP_PKG)",
 		);
 	} else {
 		await mkdir(join(ROOT, ".sentrux"), { recursive: true });

package/.pi/scripts/vendor-sync-pi-model-router.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Re-fetch upstream pi-model-router and re-apply ultimate-pi patches.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+VEND="$ROOT/vendor/pi-model-router"
+
+rm -rf "$VEND"
+git clone --depth 1 https://github.com/yeliu84/pi-model-router.git "$VEND"
+COMMIT="$(git -C "$VEND" rev-parse HEAD)"
+rm -rf "$VEND/.git"
+
+for f in "$VEND"/extensions/*.ts; do
+	sed -i \
+		-e "s|'@earendil-works/pi-agent-core'|'@mariozechner/pi-agent-core'|g" \
+		-e "s|'@earendil-works/pi-ai'|'@mariozechner/pi-ai'|g" \
+		-e "s|'@earendil-works/pi-coding-agent'|'@mariozechner/pi-coding-agent'|g" \
+		-e "s|'@earendil-works/pi-tui'|'@mariozechner/pi-tui'|g" \
+		"$f"
+done
+
+# Align package.json peers with @mariozechner (upstream lists @earendil-works)
+sed -i \
+	-e 's|"@earendil-works/pi-agent-core"|"@mariozechner/pi-agent-core"|g' \
+	-e 's|"@earendil-works/pi-ai"|"@mariozechner/pi-ai"|g' \
+	-e 's|"@earendil-works/pi-coding-agent"|"@mariozechner/pi-coding-agent"|g' \
+	-e 's|"@earendil-works/pi-tui"|"@mariozechner/pi-tui"|g' \
+	"$VEND/package.json"
+
+python3 -c "
+import re, pathlib
+for p in pathlib.Path('$VEND/extensions').glob('*.ts'):
+    t = p.read_text()
+    t2 = re.sub(r\"from '\\./([^']+)'\", lambda m: f\"from './{m.group(1)}.js'\" if not m.group(1).endswith('.js') else m.group(0), t)
+    p.write_text(t2)
+"
+
+cat >"$VEND/UPSTREAM_PIN.md" <<EOF
+# Vendored \`pi-model-router\`
+
+- **Repository:** https://github.com/yeliu84/pi-model-router
+- **License:** MIT (\`LICENSE\` in this tree)
+- **Pinned upstream commit:** \`$COMMIT\`
+- **Local changes:** \`extensions/*.ts\` imports use \`@mariozechner/*\` and relative paths end in \`.js\` for TypeScript nodenext.
+EOF
+
+rm -f "$VEND/package-lock.json"
+echo "✓ Vendor refreshed at $VEND (commit $COMMIT)"

package/.pi/settings.example.json

@@ -8,7 +8,6 @@
 		"npm:@posthog/pi",
 		"npm:context-mode",
 		"npm:@tintinweb/pi-subagents",
-		"npm:@yeliu84/pi-model-router",
 		"npm:@sting8k/pi-vcc"
 	]
 }

package/.sentrux/rules.toml

@@ -1,6 +1,6 @@
 # Sentrux rules — 2026-05-15
 # Docs: https://sentrux.dev/docs/rules-engine/
-# Sync: npm run harness:sentrux-sync (or /harness-sentrux-sync in pi)
+# Sync: node $UP_PKG/.pi/scripts/sentrux-rules-sync.mjs --force (see .pi/scripts/README.md for UP_PKG) or /harness-sentrux-sync in pi
 #
 # Custom rules: add TOML below the managed block; they are preserved on sync.
 

package/AGENTS.md

@@ -26,7 +26,7 @@ Created: 2026-05-14
 - Graph before grep — always consult the knowledge graph first
 - ./raw/ is source storage for graphify
 - ADRs in docs/adr/ (repo) and .pi/harness/docs/adrs/ (harness) with structured format
-- `npm run harness:verify` for deterministic harness contract checks
+- `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` for deterministic harness contract checks (`UP_PKG` — see `.pi/scripts/README.md`)
 - Harness context: **context-mode only** — never lean-ctx on harness paths (see harness-context skill)
 - `graphify update .` after significant code changes
 - ast-grep (`sg`) is the default code search tool — use `sg -p 'pattern'` for structural search, never grep for code

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to this project are documented in this file.
 
+## [v0.3.1] — 2026-05-15
+
+### 🐛 Fixes
+
+- **External `/harness-setup`**: policy gate no longer forces **plan** phase because the setup doc mentions `harness-plan` (e.g. `gh label create "harness-plan"`).
+- **Harness specs in consumer repos**: copy `*.schema.json` and specs `README` from the package via `harness-seed-project-contracts.mjs` as part of setup (so `plan-packet.schema.json` exists before planning).
+- **Strict LLM gateways**: new `provider-payload-sanitize` extension removes disallowed top-level fields (`reasoning`, etc.) from `messages` before provider requests (avoids 400 “Extra inputs … reasoning” on some OpenAI-compatible APIs).
+
+## [v0.3.0] — 2026-05-15
+
+### 📦 Release
+
+- First tag-driven npm / GitHub Packages publish since **v0.2.2**; intermediate history remains under **v0.2.3–v0.2.10** below.
+
+### ✨ Features
+
+- Vendored [**pi-model-router**](https://github.com/yeliu84/pi-model-router) with harness gate and `npm run vendor:sync-router`
+- Sentrux **`rules.toml`** sync from `architecture.manifest.json` plus Phase 2 harness telemetry / governance scaffolding (see ADRs)
+- Document **`UP_PKG`** resolution and direct **`$UP_PKG/.pi/scripts/*`** invocation for external installs (no `harness:*` entries in consumer `package.json`)
+
+### 🐛 Fixes
+
+- **`pi update`** / global installs: complete `koffi` tree; Node 22–compatible dependency graph
+- Harness-setup: Graphify bootstrap + CLI verification improvements (system deps, installers)
+
+### 🔧 Chores
+
+- Drop external **`npm:@yeliu84/pi-model-router`** dependency; add **`THIRD_PARTY_NOTICES.md`**
+- Align publish **`files`** allowlist and **graphify-out** refresh
+
+## [v0.2.10] — 2026-05-15
+
+### 🔧 Chores
+
+- Harness scripts must be invoked from `.pi/scripts/` (or `$UP_PKG/.pi/scripts/` for consumers); root `npm run harness:*` scripts removed so `pi install npm:ultimate-pi` works in external repos without mirroring npm script entries
+
+
+### ✨ Features
+
+- Vendor [`yeliu84/pi-model-router`](https://github.com/yeliu84/pi-model-router) under `vendor/pi-model-router/` with a harness gate in `.pi/extensions/pi-model-router-harness.ts` (no `router/auto` until `.pi/model-router.json` exists after `/harness-setup`)
+- `npm run vendor:sync-router` to refresh upstream + apply import patches (see `vendor/pi-model-router/UPSTREAM_PIN.md`)
+
+### 🔧 Chores
+
+- Remove `npm:@yeliu84/pi-model-router` from package dependencies; add `THIRD_PARTY_NOTICES.md`
+- `harness-sync-model-router.mjs` adjusts Pi defaults only (no package toggling)
+- `check:ts` uses ES2023; devDependency on `@mariozechner/pi-ai`, `pi-tui`, `pi-agent-core` for vendored typecheck
+
+### 🐛 Fixes
+
+- Avoid npm package conflicts — router always comes from the bundled vendor tree
+
+## [v0.2.8] — 2026-05-15
+
+### ✨ Features
+
+- Gate `pi-model-router`: shipped `.pi/settings.example.json` no longer lists `npm:@yeliu84/pi-model-router` until `/harness-setup` Step 3.5 creates `.pi/model-router.json` and runs `harness-sync-model-router.mjs` (adds the package, sets `router` / `auto` when project `defaultProvider` is unset, strips stale router entries when config is missing)
+
+### 🐛 Fixes
+
+- Remove extension bootstrap that auto-wrote `.pi/model-router.json` on every start (router config is harness-owned only; avoids `router/auto` + built-in `gpt-5.4-pro` before setup)
+
 ## [v0.2.7] — 2026-05-15
 
 ### 🐛 Fixes

package/README.md

@@ -66,7 +66,7 @@ Use this when you want each step separate:
 
 ## Defaults you should know
 
-- **Model routing is opt-in** — install does not force `router/auto` or `gpt-5.4-pro`. Enable with `/router profile auto` after `/harness-setup` generates `.pi/model-router.json`, or copy [`.pi/model-router.example.json`](.pi/model-router.example.json).
+- **Model routing (vendored + gated)** — [`pi-model-router`](https://github.com/yeliu84/pi-model-router) ships inside this package (`vendor/pi-model-router/`). [`.pi/extensions/pi-model-router-harness.ts`](.pi/extensions/pi-model-router-harness.ts) activates it **only after** `.pi/model-router.json` exists (generation: `/harness-setup` Step 3.5), so **`router/auto` does not appear** beforehand. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). [`.pi/scripts/harness-sync-model-router.mjs`](.pi/scripts/harness-sync-model-router.mjs) may set **`defaultProvider`/`defaultModel`** to **`router`/`auto`** when the project sets no default — run **`/reload`** afterward. Do **not** add `npm:@yeliu84/pi-model-router` to `.pi/settings.json`; it duplicates the fork. Maintainer refresh: **`npm run vendor:sync-router`**.
 - **Plan before mutate** — write/edit/shell that changes the repo is blocked until execute phase.
 - **No auto-merge** — you decide when to open or merge a PR.
 - **Structured runs** — each run writes artifacts under `.pi/harness/runs/` for replay and audit.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,8 @@
+# Third-party notices
+
+## pi-model-router (vendored)
+
+- **Project:** https://github.com/yeliu84/pi-model-router  
+- **License:** MIT ([vendor/pi-model-router/LICENSE](vendor/pi-model-router/LICENSE))  
+- **Pinned revision:** See [vendor/pi-model-router/UPSTREAM_PIN.md](vendor/pi-model-router/UPSTREAM_PIN.md)  
+- ultimate-pi loads it from [`vendor/pi-model-router`](vendor/pi-model-router); import specifiers were adapted for `@mariozechner/pi-coding-agent` and related Pi packages.

package/biome.json

@@ -11,7 +11,8 @@
 		"includes": [
 			"**/*.{ts,tsx,js,jsx,json,jsonc,css}",
 			"!graphify-out/**/*",
-			"!graphify-books-out/**/*"
+			"!graphify-books-out/**/*",
+			"!vendor/**/*"
 		]
 	},
 	"formatter": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.2.7",
+	"version": "0.3.1",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -12,7 +12,6 @@
 		"knowledge-base",
 		"context-compression",
 		"agent-skills",
-		"cursor-sdk",
 		"firecrawl",
 		"context-mode",
 		"vcc"
@@ -68,18 +67,16 @@
 		"AGENTS.md",
 		"biome.json",
 		"CHANGELOG.md",
-		"README.md"
+		"README.md",
+		"THIRD_PARTY_NOTICES.md",
+		"vendor/pi-model-router"
 	],
 	"peerDependencies": {
 		"@mariozechner/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2022 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/model-router-bootstrap.ts .pi/extensions/harness-telemetry.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts",
-		"harness:graphify-bootstrap": "bash .pi/scripts/harness-graphify-bootstrap.sh",
-		"harness:cli-verify": "bash .pi/scripts/harness-cli-verify.sh",
-		"harness:verify": "node .pi/scripts/harness-verify.mjs",
-		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
-		"harness:meta-optimizer": "node .pi/harness/evolution/meta-optimizer.mjs",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts",
+		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
 		"lint": "biome check",
 		"lint:fix": "biome check --fix",
 		"format": "biome format --write",
@@ -90,7 +87,10 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.4.14",
+		"@mariozechner/pi-agent-core": "0.73.0",
+		"@mariozechner/pi-ai": "0.73.0",
 		"@mariozechner/pi-coding-agent": "0.73.0",
+		"@mariozechner/pi-tui": "0.73.0",
 		"@sinclair/typebox": "^0.34.49",
 		"lefthook": "2.1.6",
 		"typescript": "^6.0.3"
@@ -99,7 +99,6 @@
 		"@posthog/pi": "latest",
 		"@sting8k/pi-vcc": "^0.3.12",
 		"@tintinweb/pi-subagents": "latest",
-		"@yeliu84/pi-model-router": "latest",
 		"asciify-image": "^0.1.10",
 		"jimp": "^1.6.1",
 		"posthog-node": "^5.30.6"

package/vendor/pi-model-router/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.git
+.pi

package/vendor/pi-model-router/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": true
+}

package/vendor/pi-model-router/AGENTS.md

@@ -0,0 +1,39 @@
+# Pi Model Router: Core Mandates
+
+## Project Overview
+The `pi-model-router` is an extension-first model router for the `pi` coding agent. It registers a custom logical provider (`router`) that exposes "profiles" as models (e.g., `router/auto`). For every turn, the router intelligently selects an underlying concrete model based on task complexity, conversation phase, and user-defined rules.
+
+## Architectural Principles
+- **Extension-First**: All functionality must be implemented as a `pi` extension without modifying `pi` core.
+- **Custom Provider**: Use `pi.registerProvider` to hook into the model lifecycle. The logical model (e.g., `router/auto`) should remain stable while the underlying model changes transparently.
+- **Modularized Design**: Strictly follow the modular structure defined in Phase 3:
+  - `extensions/types.ts`: All interfaces and type definitions.
+  - `extensions/config.ts`: Configuration loading, normalization, and merging.
+  - `extensions/routing.ts`: Core routing logic (heuristics, classifier, rule matching).
+  - `extensions/provider.ts`: Custom `router` provider registration and delegation stream.
+  - `extensions/state.ts`: Session-persisted state management and snapshotting.
+  - `extensions/ui.ts`: UI status line and widget rendering logic.
+  - `extensions/commands.ts`: CLI command registrations and completions.
+  - `extensions/index.ts`: Main entry point (orchestrator).
+
+## Routing Decision Logic
+Routing follows a tiered system (`high`, `medium`, `low`) and an ordered decision flow:
+1. **Budget Check**: Downgrade to `medium` if `maxSessionBudget` is exceeded.
+2. **Context Trigger**: Upgrade to `high` if `largeContextThreshold` is reached.
+3. **Manual Pin**: Use tier pinned via `/router pin` or `/router fix`.
+4. **Custom Rules**: Check keyword-based rules against the user prompt.
+5. **LLM Classifier (Optional)**: Call `classifierModel` for intent categorization.
+6. **Heuristics (Fallback)**: Use local heuristics if the classifier is off/fails.
+7. **Phase Bias**: Apply stickiness to maintain a consistent tier during multi-turn tasks.
+
+## Coding Standards
+- **TypeScript**: Strictly adhere to TypeScript. NEVER use the `any` type; prefer specific types or `unknown`.
+- **Functions**: Always use arrow functions (`const myFunc = () => ...`) instead of function statements (`function myFunc() ...`) for consistency and lexical scoping.
+- **Imports**: Use top-level static imports over inline `import()` or `require()` calls for consistency and cleaner ESM code.
+- **State Management**: Persist router state via `pi.appendEntry` with a custom `router-state` entry type to ensure branch-safe behavior.
+- **Error Handling**: Implement robust fallback chains for model failures (retrying with alternative models).
+
+## Documentation Reference
+- `docs/ARCHITECTURE.md`: Detailed architectural deep dive.
+- `README.md`: Usage and installation guide.
+- `model-router.example.json`: Reference for configuration structure.

package/vendor/pi-model-router/LICENSE

@@ -0,0 +1,21 @@
+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.

package/vendor/pi-model-router/README.md

@@ -0,0 +1,99 @@
+# pi-model-router
+
+Intelligent per-turn model router extension 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 based on task intent, session budget, context size, and custom rules — with automatic fallbacks and phase awareness.
+
+## What it does
+
+- **Logical Router Provider**: Registers a `router` provider that exposes stable profiles (e.g., `router/auto`) as models.
+- **Per-Turn Routing**: Intelligently chooses between `high`, `medium`, and `low` tiers for every turn based on task intent and complexity.
+- **Task-Aware Heuristics**: Detects planning vs. implementation vs. lightweight tasks using keyword analysis, word count, and conversation history.
+- **Advanced Controls**: Includes built-in support for:
+  - **LLM Intent Classifier**: Optionally use a fast model to categorize intent (overrides heuristics).
+  - **Custom Rules**: Define keyword-based tier overrides for specific patterns (e.g., `deploy` → `high`).
+  - **Context Trigger**: Automatically upgrade to high-tier when token usage exceeds a threshold.
+  - **Cost Budgeting**: Set a session spend limit; high tier downgrades to medium once exceeded.
+  - **Fallback Chains**: Automatic retry with alternative models if the primary choice fails.
+- **Phase Memory**: Biased stickiness to keep you in the same tier during multi-turn planning or implementation work.
+- **Thinking Control**: Full control over reasoning/thinking levels per tier and profile.
+- **Persistent State**: Pins, profiles, costs, and debug history are remembered across agent restarts and conversation branches.
+
+## Installation
+
+### As a user
+
+Install from npm:
+
+```bash
+pi install npm:@yeliu84/pi-model-router
+```
+
+### For development
+
+Clone this repo and install from source:
+
+```bash
+pi install .
+```
+
+Or load directly for one run:
+
+```bash
+pi -e ./extensions/index.ts
+```
+
+## Configuration
+
+Copy the example config to one of:
+
+- `~/.pi/agent/model-router.json` (Global)
+- `.pi/model-router.json` (Project-specific)
+
+### Basic Config Shape
+
+```json
+{
+  "defaultProfile": "auto",
+  "classifierModel": "google/gemini-flash-latest",
+  "maxSessionBudget": 1.0,
+  "profiles": {
+    "auto": {
+      "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" }
+    }
+  }
+}
+```
+
+### Configuration Fields
+
+| Field                   | Description                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `defaultProfile`        | The profile to use when starting a new session.                                   |
+| `classifierModel`       | (Optional) Model used to categorize intent. If omitted, fast heuristics are used. |
+| `maxSessionBudget`      | (Optional) USD budget for the session. Forces `medium` tier once exceeded.        |
+| `largeContextThreshold` | (Optional) Token count trigger to force `high` tier for large contexts.           |
+| `phaseBias`             | (0.0 - 1.0) Stickiness of the current phase. Higher = more stable. Default `0.5`. |
+| `rules`                 | List of custom keyword rules (e.g. `{ "matches": "deploy", "tier": "high" }`).    |
+| `profiles`              | Map of profile definitions, each containing `high`, `medium`, and `low` tiers.    |
+
+## Commands
+
+| Command                     | Description                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------- |
+| `/router`                   | Show detailed status, current profile, spend, and settings.                     |
+| `/router status`            | Alias for `/router` (show current status).                                      |
+| `/router profile [name]`    | Switch to a profile or list available ones (enables router if off).             |
+| `/router pin [prof] <t\|a>` | Pin a tier (high/medium/low/auto) for the current or specified profile.         |
+| `/router fix <tier>`        | Correct the _last_ decision and pin that tier for the current profile.          |
+| `/router thinking ...`      | Override thinking levels (e.g. `/router thinking low xhigh`).                   |
+| `/router disable`           | Disable the router and switch back to the last non-router model.                |
+| `/router widget <on\|off>`  | Toggle the persistent state widget (supports `toggle`).                         |
+| `/router debug <on\|off>`   | Toggle turn-by-turn routing notifications (supports `toggle`, `clear`, `show`). |
+| `/router reload`            | Hot-reload the configuration JSON.                                              |
+| `/router help`              | Show usage help for all subcommands.                                            |
+
+## Documentation
+
+- [Architecture Guide](docs/ARCHITECTURE.md): Deep dive into the routing logic and modular design.
+- [Sample Configuration](model-router.example.json): Diverse profile examples (`cheap`, `deep`, `balanced`).

package/vendor/pi-model-router/UPSTREAM_PIN.md

@@ -0,0 +1,8 @@
+# Vendored `pi-model-router`
+
+- **Repository:** https://github.com/yeliu84/pi-model-router
+- **License:** MIT (`LICENSE` in this tree)
+- **Pinned upstream commit:** `8c60095da0e753c242c4be9bb617b85f4dd3255c`
+- **Local changes:** TypeScript imports in `extensions/*.ts` use `@mariozechner/*`; relative imports end in `.js` for NodeNext; `package.json` peerDependencies list `@mariozechner/*`.
+
+**Refresh upstream:** run `npm run vendor:sync-router` from ultimate-pi root (updates this file with the latest commit SHA).

package/vendor/pi-model-router/docs/ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# Architecture: Pi Model Router Extension
+
+The `pi-model-router` is an extension-first model router for the `pi` coding agent. It registers a custom logical provider (`router`) that exposes "profiles" as models (e.g., `router/auto`). For every turn, the router intelligently selects an underlying concrete model based on task complexity, conversation phase, and user-defined rules.
+
+## Core Concepts
+
+### 1. Profiles & Tiers
+
+The router is organized into **Profiles** (e.g., `auto`, `cheap`, `deep`). Each profile defines three **Tiers**:
+
+- **High**: Reserved for architecture, design, complex debugging, and planning. Uses high-reasoning models.
+- **Medium**: The default for standard implementation, multi-file edits, and focused fixes.
+- **Low**: Used for summaries, changelogs, formatting, and simple read-only lookups.
+
+### 2. Custom Provider Implementation
+
+The extension uses `pi.registerProvider` to hook into the `pi` model lifecycle. This ensures that the selected model in the `pi` footer remains stable (e.g., `router/auto`) while the underlying model changes transparently turn-by-turn via the `streamSimple` interception.
+
+## Routing Decision Flow
+
+For every request sent to a `router/*` model, the following logic is executed:
+
+1. **Budget Check**: If a `maxSessionBudget` is configured and the session spend exceeds it, the router automatically downgrades `high` tier requests to `medium`.
+2. **Context Trigger**: If `largeContextThreshold` is exceeded (measured in tokens), the router forces the `high` tier to ensure the model can handle the large context.
+3. **Manual Pin**: If the user has pinned a tier via `/router pin` or `/router fix`, that tier is used.
+4. **Custom Rules**: Keyword-based rules defined in the config are checked against the user prompt.
+5. **LLM Classifier (Optional)**: If `classifierModel` is configured, a fast LLM is called to categorize the user's intent.
+6. **Heuristics (Fallback)**: If the classifier is off or fails, a fast local heuristic (keyword/length/tool-use analysis) is used.
+7. **Biased Stickiness**: The `phaseBias` setting modulates thresholds to keep the router in a consistent phase (e.g., staying in `high` tier during a multi-turn planning session).
+
+## Module Architecture
+
+The extension is modularized for maintainability:
+
+- `extensions/index.ts`: Orchestrator. Manages state, hooks into `pi` events, and wires modules together.
+- `extensions/provider.ts`: Implements the `router` provider and the delegation/retry loop.
+- `extensions/routing.ts`: Core decision logic, heuristics, and the LLM classifier.
+- `extensions/config.ts`: Loads, merges, and normalizes the JSON configuration.
+- `extensions/commands.ts`: Registers all `/router` subcommands and their autocompletions.
+- `extensions/ui.ts`: Manages the status line and the optional state widget.
+- `extensions/state.ts`: Handles session-persisted state and snapshots.
+- `extensions/types.ts`: Centralized interface and type definitions.
+
+## State & Persistence
+
+The router state is persisted using `pi.appendEntry` with a custom type `router-state`. This allows the router to:
+
+- Restore the active profile and pins across agent relaunches.
+- Maintain independent pins and state for different conversation branches.
+- Track accumulated session costs safely.
+
+## Reliability: Fallback Chains
+
+Each tier in a profile can define an optional `fallbacks` list. If the primary model fails (e.g., due to rate limits or provider downtime), the router automatically retries the next model in the chain before surfacing an error to the user.