auto-model-router 0.7.2 → 0.7.3

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.7.2",
+    "version": "0.7.3",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.7.2",
+      "version": "0.7.3",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -235,7 +235,7 @@ bun tools/install.ts --no-toast --no-configure   # only the required embed exten
 The installer adds:
 
 - `router-embed.ts` — **required**; runs the router in-process.
-- `router-toast.ts` — optional; chosen-model toasts.
+- `router-toast.ts` — optional; per-turn toasts naming the model and why it was chosen.
 - `router-configure.ts` — optional; the `/router` command (configure, usage reports, status).
 - `router-digest.ts` — optional; condenses large tool results with a cheap model before an expensive one reads them (needs `digest.enabled`).
 
@@ -814,6 +814,7 @@ disk and back up the previous file to a timestamped `.bak`.
 | `AUTO_MODEL_ROUTER_URL` | Toast/base URL override (the toast reads the shared port file first). | — |
 | `AUTO_MODEL_ROUTER_API_KEY` | Client bearer for the toast poll when `server.apiKey` is set. | — |
 | `OMP_HARNESS_ID` | Per-harness toast scoping. | — |
+| `AUTO_MODEL_ROUTER_TOAST` | `compact` for the one-line toast; anything else keeps the decision trail. | verbose |
 
 ---
 
@@ -1469,11 +1470,27 @@ come from a small omp extension that polls the router's in-process ledger:
 // omp-extension/router-toast.ts  (shipped in this repo)
 ```
 
-It raises a TUI toast (`ctx.ui.notify`) like
-`openrouter · meta/muse-glimmer-30b [trivial] · $0.00001` or
-`ollama · glm-5.3-flash [moderate] · $0.00070` whenever a new model is chosen —
-provider first, so a mixed catalog is legible at a glance. Install it by adding
-the file's absolute path to omp's `extensions:` list.
+It raises a TUI toast (`ctx.ui.notify`) whenever a model is chosen, explaining
+the decision rather than just naming it — provider first, so a mixed catalog is
+legible at a glance:
+
+```
+openrouter · openai/gpt-5.2 [hard] · $0.01820
+why: failover: z-ai/glm-5.3-flash empty_completion (hit the length cap having…
+     escalated from moderate
+48.2k prompt · 12.8k compacted · 11 tools · attempt 2 · 2.1s to first token
+```
+
+The **why** lines come from the router's own decision trail, picked by how much
+they change what you would do: a failover or a policy pin explains a surprising
+model outright, a hold or a tier rescue explains why the obvious cheaper pick was
+skipped, and when nothing surprising happened the ranking rationale itself is
+shown. The last line is what the model was actually handed. An unreported cost
+falls back to the forecast (`~$…`).
+
+`AUTO_MODEL_ROUTER_TOAST=compact` restores the old one-liner
+(`openrouter · meta/muse-glimmer-30b [trivial] · $0.00001`). Install the
+extension by adding the file's absolute path to omp's `extensions:` list.
 
 Because the embedded router binds a random port, the toast resolves the router
 base URL on every poll in this order: the embedded router's port file

package/omp-extension/router-toast.ts

@@ -38,6 +38,9 @@ import { newestId, selectToasts, type ToastDecision } from "./toast-logic.ts";
 // Empty ⇒ toast every harness (single-harness default).
 const HARNESS_ID = process.env.OMP_HARNESS_ID ?? "";
 const POLL_MS = 2_000;
+// The toast explains the choice by default: model, tier, cost, why it was picked
+// and what it was handed. `AUTO_MODEL_ROUTER_TOAST=compact` restores the one-liner.
+const VERBOSE = (process.env.AUTO_MODEL_ROUTER_TOAST ?? "").toLowerCase() !== "compact";
 
 export default function (pi: ExtensionAPI): void {
 	pi.setLabel("auto-model-router toast");
@@ -91,7 +94,7 @@ export default function (pi: ExtensionAPI): void {
 				const entries = body.entries;
 				if (!Array.isArray(entries) || entries.length === 0) return;
 
-				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId)) {
+				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID, sessionId, VERBOSE)) {
 					ctx.ui.notify(t.text, "info");
 				}
 				lastSeenId = newestId(entries) ?? lastSeenId;

package/omp-extension/toast-logic.ts

@@ -88,6 +88,20 @@ export interface ToastDecision {
 	 * default. Lets the toast scope to a single interactive session.
 	 */
 	ompSessionId?: string;
+	/** The router's own decision trail, already written for people. */
+	reasons?: string[];
+	/** Classifier inputs; only a few are worth surfacing. */
+	features?: { promptTokens?: number; toolCount?: number; turnDepth?: number; isToolResultContinuation?: boolean } | null;
+	/** Attempt index within the turn; >0 means this served after an escalation. */
+	attempt?: number;
+	/** Prompt tokens compaction removed before dispatch. */
+	promptTokensSaved?: number;
+	/** What the router expected this to cost, before the upstream reported. */
+	predictedUsd?: number;
+	latencyMs?: number;
+	ttftMs?: number | null;
+	task?: string | null;
+	classificationSource?: string;
 }
 
 export interface ToastMessage {
@@ -110,10 +124,89 @@ export function providerOf(slug: string): { provider: string; model: string } {
 	return { provider: "openrouter", model: slug };
 }
 
-export function toToastText(d: ToastDecision): string {
+/**
+ * Which parts of the decision trail earn a line in a toast.
+ *
+ * The router writes many reasons per turn; a toast has room for two. These
+ * patterns are ordered by how much they change what the reader would do:
+ * a failover or a policy pin explains a surprising model outright, a hold or a
+ * rescue explains why the obvious cheaper pick was skipped, and the rest is
+ * ordinary ranking that the tier already conveys.
+ */
+const REASON_PRIORITY: readonly RegExp[] = [
+	/failover|escalat/i,
+	/policy|pin(ned)?|allow|deny/i,
+	/held|sticky|hysteresis|switch margin/i,
+	/budget raised|reasons before it answers/i,
+	// The RESCUE wording only: "cheapest above the quality floor" is ordinary
+	// ranking, and matching a bare "floor" would push it above real surprises.
+	/tier rescue|relaxed|adaptive (floor|ceiling)/i,
+	/cache|warm/i,
+	/compact/i,
+	/explor/i,
+];
+
+const clip = (text: string, max: number): string => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+
+/** Up to `limit` reasons, most explanatory first, each trimmed for one line. */
+export function whyReasons(reasons: readonly string[] | undefined, limit = 2): string[] {
+	if (reasons === undefined || reasons.length === 0) return [];
+	const picked: string[] = [];
+	const seen = new Set<number>();
+	for (const re of REASON_PRIORITY) {
+		for (let i = 0; i < reasons.length && picked.length < limit; i++) {
+			const r = reasons[i];
+			if (r === undefined || seen.has(i) || !re.test(r)) continue;
+			seen.add(i);
+			picked.push(clip(r.replace(/\s+/g, " ").trim(), 90));
+		}
+		if (picked.length >= limit) break;
+	}
+	// Nothing matched a pattern: the first reason is the ranking rationale itself.
+	if (picked.length === 0 && reasons[0] !== undefined) picked.push(clip(reasons[0].replace(/\s+/g, " ").trim(), 90));
+	return picked;
+}
+
+const tokens = (n: number): string => (n >= 1000 ? `${Math.round(n / 100) / 10}k` : String(n));
+
+/** The turn's shape in a few words: what the model was actually handed. */
+export function factsOf(d: ToastDecision): string[] {
+	const out: string[] = [];
+	const f = d.features ?? undefined;
+	if (f?.promptTokens !== undefined && f.promptTokens > 0) out.push(`${tokens(f.promptTokens)} prompt`);
+	if (d.promptTokensSaved !== undefined && d.promptTokensSaved > 0) out.push(`${tokens(d.promptTokensSaved)} compacted`);
+	if (f?.toolCount !== undefined && f.toolCount > 0) out.push(`${f.toolCount} tools`);
+	if (f?.isToolResultContinuation === true) out.push("tool continuation");
+	if (d.attempt !== undefined && d.attempt > 0) out.push(`attempt ${d.attempt + 1}`);
+	if (d.task !== undefined && d.task !== null && d.task !== "" && d.task !== "coding") out.push(d.task);
+	if (d.ttftMs !== undefined && d.ttftMs !== null && d.ttftMs > 0) out.push(`${(d.ttftMs / 1000).toFixed(1)}s to first token`);
+	else if (d.latencyMs !== undefined && d.latencyMs > 0) out.push(`${(d.latencyMs / 1000).toFixed(1)}s`);
+	return out;
+}
+
+/** `$0.00042`, or the prediction when the upstream reported nothing. */
+function costOf(d: ToastDecision): string {
+	if (d.reportedUsd !== null && d.reportedUsd !== undefined) return `$${d.reportedUsd.toFixed(5)}`;
+	if (d.predictedUsd !== undefined && d.predictedUsd > 0) return `~$${d.predictedUsd.toFixed(5)}`;
+	return "";
+}
+
+/**
+ * The toast body. `verbose` (the default) adds the decision trail and the
+ * turn's shape under the headline; `compact` is the original single line, for
+ * anyone who wants the model name and nothing else.
+ */
+export function toToastText(d: ToastDecision, verbose = true): string {
 	const { provider, model } = providerOf(d.servedSlug ?? d.slug);
-	const cost = d.reportedUsd === null ? "" : ` \u00b7 $${d.reportedUsd.toFixed(5)}`;
-	return `${provider} \u00b7 ${model} [${d.tier}]${cost}`;
+	const cost = costOf(d);
+	const head = `${provider} \u00b7 ${model} [${d.tier}]${cost === "" ? "" : ` \u00b7 ${cost}`}`;
+	if (!verbose) return head;
+	const lines = [head];
+	const why = whyReasons(d.reasons);
+	for (const [i, r] of why.entries()) lines.push(`${i === 0 ? "why: " : "     "}${r}`);
+	const facts = factsOf(d);
+	if (facts.length > 0) lines.push(facts.join(" \u00b7 "));
+	return lines.join("\n");
 }
 
 /**
@@ -129,6 +222,7 @@ export function selectToasts(
 	lastSeenId: string | null,
 	harnessId = "",
 	ompSessionId = "",
+	verbose = true,
 ): ToastMessage[] {
 	if (lastSeenId === null) return [];
 	// `entries` is newest-first. Entries strictly newer than lastSeenId are the
@@ -143,7 +237,7 @@ export function selectToasts(
 		if (d.wasted) continue;
 		if (harnessId !== "" && d.harnessId !== harnessId) continue;
 		if (ompSessionId !== "" && d.ompSessionId !== ompSessionId) continue;
-		out.push({ model: d.servedSlug ?? d.slug, tier: d.tier, costUsd: d.reportedUsd, text: toToastText(d) });
+		out.push({ model: d.servedSlug ?? d.slug, tier: d.tier, costUsd: d.reportedUsd, text: toToastText(d, verbose) });
 	}
 	return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/test/toast-logic.test.ts

@@ -7,8 +7,10 @@ import {
 	newestId,
 	providerOf,
 	resolveRouterUrl,
+	factsOf,
 	selectToasts,
 	toToastText,
+	whyReasons,
 	type ToastDecision,
 } from "../omp-extension/toast-logic.ts";
 
@@ -199,3 +201,62 @@ describe("toToastText", () => {
 		expect(providerOf("z-ai/glm-5.3-flash")).toEqual({ provider: "openrouter", model: "z-ai/glm-5.3-flash" });
 	});
 });
+
+describe("verbose toast", () => {
+	const FULL = dec({
+		slug: "ollama/gpt-oss:20b",
+		servedSlug: "ollama/gpt-oss:20b",
+		tier: "trivial",
+		reportedUsd: 0.000308,
+		reasons: [
+			"policy: pinned to ollama/gpt-oss:20b",
+			"completion budget raised 12 to 512: ollama/gpt-oss:20b reasons before it answers",
+			"cheapest above the quality floor",
+		],
+		features: { promptTokens: 22899, toolCount: 11, isToolResultContinuation: true },
+		attempt: 1,
+		promptTokensSaved: 12800,
+		ttftMs: 2100,
+	});
+
+	test("the headline keeps its shape and the body explains the choice", () => {
+		const lines = toToastText(FULL).split(String.fromCharCode(10));
+		expect(lines[0]).toBe("ollama · gpt-oss:20b [trivial] · $0.00031");
+		expect(lines[1]).toBe("why: policy: pinned to ollama/gpt-oss:20b");
+		expect(lines[2]).toContain("completion budget raised");
+		expect(lines[3]).toBe("22.9k prompt · 12.8k compacted · 11 tools · tool continuation · attempt 2 · 2.1s to first token");
+	});
+
+	test("compact is the old single line", () => {
+		expect(toToastText(FULL, false)).toBe("ollama · gpt-oss:20b [trivial] · $0.00031");
+		expect(toToastText(FULL, false).includes(String.fromCharCode(10))).toBe(false);
+	});
+
+	test("a surprise outranks ordinary ranking, and ranking shows when nothing surprised", () => {
+		// "cheapest above the quality floor" is ordinary: a failover and a hold win.
+		expect(whyReasons(["cheapest above the quality floor", "failover: x/y empty_completion; retrying a/b"])[0]).toContain("failover");
+		expect(whyReasons(["cheapest above the quality floor", "held from the previous turn: switch margin not cleared"])[0]).toContain("held");
+		// Nothing notable: the ranking rationale itself is the answer.
+		expect(whyReasons(["cheapest above the quality floor"])).toEqual(["cheapest above the quality floor"]);
+		expect(whyReasons([])).toEqual([]);
+		expect(whyReasons(undefined)).toEqual([]);
+		// At most two lines, however many reasons the router recorded.
+		expect(whyReasons(["failover: a", "policy: b", "held: c", "cache warm"]).length).toBe(2);
+	});
+
+	test("an unreported cost falls back to the prediction, and thin decisions stay short", () => {
+		expect(toToastText(dec({ reportedUsd: null, predictedUsd: 0.00042, reasons: [], features: null }))).toBe("openrouter · meta/muse-glimmer-30b [trivial] · ~$0.00042");
+		expect(toToastText(dec({ reportedUsd: null, features: null }))).toBe("openrouter · meta/muse-glimmer-30b [trivial]");
+	});
+
+	test("facts skip what a reader does not need", () => {
+		expect(factsOf(dec({ features: { promptTokens: 0, toolCount: 0 }, attempt: 0, task: "coding" }))).toEqual([]);
+		expect(factsOf(dec({ features: { promptTokens: 900 }, task: "vision" }))).toEqual(["900 prompt", "vision"]);
+	});
+
+	test("selectToasts renders compact when asked", () => {
+		const entries = [dec({ id: "d2", slug: "x/b", reasons: ["failover: nope"] }), dec({ id: "d1" })];
+		expect(selectToasts(entries, "d1", "", "", false)[0]?.text.includes(String.fromCharCode(10))).toBe(false);
+		expect(selectToasts(entries, "d1")[0]?.text.includes(String.fromCharCode(10))).toBe(true);
+	});
+});