ultimate-pi 0.18.0 → 0.19.0

package/.pi/scripts/harness-model-router-routing.test.mjs

@@ -1,97 +0,0 @@
-#!/usr/bin/env node
-/**
- * Unit tests for session-locked pi-model-router routing (no LLM).
- * Run: npx tsx .pi/scripts/harness-model-router-routing.test.mjs
- */
-
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-	decideSessionLock,
-	applyThinkingToDecision,
-	buildRoutingDecision,
-	decideRouting,
-} from "../../vendor/pi-model-router/extensions/routing.js";
-
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-
-const sampleProfile = {
-	high: { model: "openai/gpt-5.5", thinking: "high" },
-	medium: { model: "openai/gpt-5.5", thinking: "medium" },
-	low: { model: "openai/gpt-5.5", thinking: "low" },
-};
-
-const planningContext = {
-	systemPrompt: "You are a harness architect. Design tradeoffs and migration strategy.",
-	messages: [
-		{
-			role: "user",
-			content:
-				"Plan a multi-phase refactor across modules with architecture review.",
-			timestamp: 1,
-		},
-	],
-};
-
-const shortContext = {
-	systemPrompt: "Summarize briefly.",
-	messages: [{ role: "user", content: "changelog", timestamp: 1 }],
-};
-
-const lockHigh = decideSessionLock(
-	planningContext,
-	"auto",
-	sampleProfile,
-	undefined,
-	undefined,
-	0.5,
-	[{ matches: "changelog", tier: "low" }],
-);
-assert.equal(lockHigh.tier, "high", "planning prompt locks high tier");
-
-const lockLow = decideSessionLock(shortContext, "auto", sampleProfile);
-assert.equal(lockLow.tier, "low", "short summary locks low tier");
-
-const locked = buildRoutingDecision(
-	"auto",
-	sampleProfile,
-	lockHigh.tier,
-	"planning",
-	lockHigh.reasoning,
-);
-const thinkingTurn = decideRouting(
-	{
-		...planningContext,
-		messages: [
-			...planningContext.messages,
-			{ role: "user", content: "changelog only", timestamp: 2 },
-		],
-	},
-	"auto",
-	sampleProfile,
-	locked,
-);
-const merged = applyThinkingToDecision(locked, thinkingTurn, sampleProfile);
-assert.equal(merged.targetLabel, locked.targetLabel, "model stays locked");
-assert.equal(merged.tier, thinkingTurn.tier, "thinking tier follows turn");
-assert.equal(merged.thinking, "low", "low thinking from turn tier config");
-
-const examplePath = join(ROOT, ".pi", "model-router.example.json");
-const example = JSON.parse(readFileSync(examplePath, "utf8"));
-for (const [name, profile] of Object.entries(example.profiles ?? {})) {
-	const { high, medium, low } = profile;
-	assert.equal(
-		high.model,
-		medium.model,
-		`example profile ${name}: medium/high same model`,
-	);
-	assert.equal(
-		medium.model,
-		low.model,
-		`example profile ${name}: low/medium same model`,
-	);
-}
-
-console.log("harness-model-router-routing.test: PASS");

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

@@ -1,97 +0,0 @@
-#!/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 readDefaultRouterProfile(configPath) {
-	if (!existsSync(configPath)) return "auto";
-	try {
-		const data = JSON.parse(readFileSync(configPath, "utf8"));
-		const profile =
-			typeof data.defaultProfile === "string" ? data.defaultProfile.trim() : "";
-		return profile || "auto";
-	} catch {
-		return "auto";
-	}
-}
-
-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 defaultRouterProfile = readDefaultRouterProfile(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 = defaultRouterProfile;
-		changed = true;
-	}
-
-	if (changed) {
-		saveSettings(settingsPath, settings);
-		console.log(
-			`✓ Router defaults set (\`router\` / \`${defaultRouterProfile}\`) — run /reload in pi when ready`,
-		);
-	} else {
-		console.log("[harness-model-router] Defaults unchanged (user set defaultProvider)");
-	}
-}
-
-main();

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

@@ -1,47 +0,0 @@
-#!/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'|'@earendil-works/pi-agent-core'|g" \
-		-e "s|'@earendil-works/pi-ai'|'@earendil-works/pi-ai'|g" \
-		-e "s|'@earendil-works/pi-coding-agent'|'@earendil-works/pi-coding-agent'|g" \
-		-e "s|'@earendil-works/pi-tui'|'@earendil-works/pi-tui'|g" \
-		"$f"
-done
-
-# Align package.json peers with @earendil-works (upstream lists @earendil-works)
-sed -i \
-	-e 's|"@earendil-works/pi-agent-core"|"@earendil-works/pi-agent-core"|g' \
-	-e 's|"@earendil-works/pi-ai"|"@earendil-works/pi-ai"|g' \
-	-e 's|"@earendil-works/pi-coding-agent"|"@earendil-works/pi-coding-agent"|g' \
-	-e 's|"@earendil-works/pi-tui"|"@earendil-works/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 \`@earendil-works/*\` and relative paths end in \`.js\` for TypeScript nodenext.
-EOF
-
-rm -f "$VEND/package-lock.json"
-echo "✓ Vendor refreshed at $VEND (commit $COMMIT)"

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

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

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

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

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

@@ -1,39 +0,0 @@
-# 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

@@ -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.

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

@@ -1,99 +0,0 @@
-# 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

@@ -1,10 +0,0 @@
-# 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 `@earendil-works/*`; relative imports end in `.js` for NodeNext; `package.json` peerDependencies list `@earendil-works/*`.
-  - **Session-locked routing (ultimate-pi harness):** one concrete model per session/profile, chosen from initial prompt + system prompt complexity; per-turn routing adjusts **thinking tier only** (`sessionLock` persisted in `router-state`). Harness generator emits the same `model` on high/medium/low tiers.
-
-**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

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