auto-model-router 0.1.0

package/omp-extension/router-toast.ts

@@ -0,0 +1,130 @@
+/**
+ * omp extension: toast the routed model on every turn.
+ *
+ * auto-model-router itself is a headless HTTP server — it cannot render anything in
+ * omp's TUI. This extension bridges that gap: it polls the router's decision
+ * ledger (`GET /v1/router/decisions`) and raises a TUI toast via
+ * `ctx.ui.notify(...)` whenever a new model is chosen for a turn.
+ *
+ * Install by adding this file's absolute path to omp's `extensions:` list:
+ *
+ *   # ~/.omp/agent/config.yml
+ *   extensions:
+ *     - /path/to/auto-model-router/omp-extension/router-embed.ts
+ *     - /path/to/auto-model-router/omp-extension/router-toast.ts
+ *
+ * Because the embedded router binds a random OS-assigned port and writes it to
+ * the port file, the toast resolves the base URL fresh on EVERY poll: the port
+ * file first, then `AUTO_MODEL_ROUTER_URL`, then `AUTO_MODEL_ROUTER_PORT`, then the router's
+ * own config.yml. Reading the port file each tick means the toast always polls
+ * the port the router actually bound, even though it changes every session.
+ *
+ * When the router is configured with `server.apiKey`, set AUTO_MODEL_ROUTER_API_KEY so
+ * the poll authenticates.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+import { embedPortPath, readEmbedPort } from "./embed-logic.ts";
+import { newestId, resolveRouterUrl, selectToasts, type ToastDecision } from "./toast-logic.ts";
+
+/** Raw router config.yml, or null when there is none to read. */
+function readRouterConfig(): string | null {
+	const raw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
+	const home =
+		raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(homedir(), raw.slice(1)) : raw;
+	const path = join(home, "config.yml");
+	if (!existsSync(path)) return null;
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+/** Absolute path of the shared embed port file (main session writes it). */
+function embedPortFile(): string {
+	const raw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
+	const home =
+		raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(homedir(), raw.slice(1)) : raw;
+	return embedPortPath(home);
+}
+
+const ROUTER_API_KEY = process.env.AUTO_MODEL_ROUTER_API_KEY;
+// This harness's id, matching the X-Omp-Harness header the router records.
+// Empty ⇒ toast every harness (single-harness default).
+const HARNESS_ID = process.env.OMP_HARNESS_ID ?? "";
+const POLL_MS = 2_000;
+
+export default function (pi: ExtensionAPI): void {
+	pi.setLabel("auto-model-router toast");
+
+	// The newest ledger entry already toasted. Ledger is `created_at_ms DESC`.
+	let lastSeenId: string | null = null;
+
+	pi.on("session_start", (_event, ctx) => {
+		// Headless/print/subagent sessions have no UI to toast into; skip the
+		// poll loop entirely rather than waking every 2s to do nothing.
+		if (!ctx.hasUI) return;
+
+		// The poll request's own deadline (3s) exceeds the poll period (2s), so
+		// a slow router could let a second tick start while the first is still in
+		// flight — both read the same lastSeenId and raise duplicate toasts. An
+		// in-flight flag makes each tick a no-op while the previous is outstanding.
+		let polling = false;
+
+		const timer = ctx.setInterval(async () => {
+			if (polling) return;
+			polling = true;
+			try {
+				// The embedded router binds a free OS-assigned port, so the URL
+				// is resolved fresh each tick from the port file the embed
+				// extension writes at session_start.
+				const embedPort = readEmbedPort(embedPortFile());
+				const routerUrl = resolveRouterUrl(
+					process.env.AUTO_MODEL_ROUTER_URL,
+					readRouterConfig(),
+					parseYaml,
+					process.env.AUTO_MODEL_ROUTER_PORT,
+					embedPort,
+				);
+
+				let res: Response;
+				try {
+					res = await fetch(`${routerUrl}/v1/router/decisions?limit=20`, {
+						headers: ROUTER_API_KEY === undefined ? {} : { authorization: `Bearer ${ROUTER_API_KEY}` },
+						signal: AbortSignal.timeout(3_000),
+					});
+				} catch {
+					return; // router down; nothing to toast, retry next tick
+				}
+				if (!res.ok) return;
+
+				let body: { entries?: ToastDecision[] };
+				try {
+					body = (await res.json()) as { entries?: ToastDecision[] };
+				} catch {
+					return;
+				}
+				const entries = body.entries;
+				if (!Array.isArray(entries) || entries.length === 0) return;
+
+				for (const t of selectToasts(entries, lastSeenId, HARNESS_ID)) {
+					ctx.ui.notify(t.text, "info");
+				}
+				lastSeenId = newestId(entries) ?? lastSeenId;
+			} catch {
+				// isolated by ctx.setInterval; nothing to escalate
+			} finally {
+				polling = false;
+			}
+		}, POLL_MS);
+		pi.on("session_shutdown", () => ctx.clearTimer(timer));
+	});
+}

package/omp-extension/toast-logic.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure toast selection logic, extracted from the omp extension so it can be
+ * unit-tested without omp's runtime.
+ *
+ * The router ledger is ordered `created_at_ms DESC` (newest first). The toast
+ * must:
+ *   - only toast entries newer than the last one already seen;
+ *   - skip `wasted` entries (escalation book-keeping — the abandoned probe
+ *     attempt that was superseded and never served the client);
+ *   - surface the attempt that actually served, oldest→newest.
+ */
+
+/**
+ * The router's default listen port. Only used when nothing else identifies the
+ * router, and deliberately NOT the last word: hardcoding it means polling
+ * whatever else owns that port once the router has been moved, in which case
+ * toasts simply never appear and nothing explains why.
+ */
+export const DEFAULT_ROUTER_URL = "http://127.0.0.1:8788";
+
+/**
+ * Resolves the router base URL from, in precedence order:
+ *   1. an explicit `AUTO_MODEL_ROUTER_URL` override;
+ *   2. the embedded router's port file (`embedPort`, when it holds a valid
+ *      port) — the embed extension binds a free OS-assigned port and writes it
+ *      to the port file, so the toast must poll that actual address;
+ *   3. an explicit `AUTO_MODEL_ROUTER_PORT` (`envPort`);
+ *   4. the `server` block of the router's own config;
+ *   5. `DEFAULT_ROUTER_URL`.
+ *
+ * `configText` is the raw config.yml contents, or null when absent/unreadable.
+ * `parseYaml` is injected so this stays dependency-free and testable.
+ */
+export function resolveRouterUrl(
+	envUrl: string | undefined,
+	configText: string | null,
+	parseYaml: (text: string) => unknown,
+	envPort?: string,
+	embedPort?: number | null,
+): string {
+	if (envUrl !== undefined && envUrl !== "") return envUrl;
+
+	let port: number | undefined;
+	if (embedPort !== undefined && embedPort !== null) {
+		port = embedPort;
+	} else if (envPort !== undefined && envPort !== "") {
+		const parsedPort = Number.parseInt(envPort, 10);
+		if (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65_535) port = parsedPort;
+	}
+	const envWins = port !== undefined;
+
+	if (configText === null) return envWins ? `http://127.0.0.1:${port}` : DEFAULT_ROUTER_URL;
+
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(configText);
+	} catch {
+		return envWins ? `http://127.0.0.1:${port}` : DEFAULT_ROUTER_URL;
+	}
+	if (typeof parsed !== "object" || parsed === null) return envWins ? `http://127.0.0.1:${port}` : DEFAULT_ROUTER_URL;
+	const server: unknown = (parsed as Record<string, unknown>).server;
+	if (typeof server !== "object" || server === null) return envWins ? `http://127.0.0.1:${port}` : DEFAULT_ROUTER_URL;
+
+	const rec = server as Record<string, unknown>;
+	const resolvedPort = envWins
+		? port!
+		: typeof rec.port === "number" && Number.isInteger(rec.port) && rec.port > 0
+			? rec.port
+			: 8788;
+	const rawHost = typeof rec.host === "string" && rec.host !== "" ? rec.host : "127.0.0.1";
+	// A wildcard listen address is not a connectable target.
+	const host = rawHost === "0.0.0.0" || rawHost === "::" ? "127.0.0.1" : rawHost;
+	return `http://${host}:${resolvedPort}`;
+}
+
+/** Subset of a ledger entry (see src/cost/types.ts LedgerEntry). */
+export interface ToastDecision {
+	id: string;
+	slug: string;
+	servedSlug: string | null;
+	tier: string;
+	reportedUsd: number | null;
+	wasted: boolean;
+	/** Harness id from the request header; empty for the default harness. */
+	harnessId: string;
+}
+
+export interface ToastMessage {
+	model: string;
+	tier: string;
+	costUsd: number | null;
+	/** Human-readable line for `ctx.ui.notify`. */
+	text: string;
+}
+
+export function toToastText(d: ToastDecision): string {
+	const model = d.servedSlug ?? d.slug;
+	const cost = d.reportedUsd === null ? "" : ` \u00b7 $${d.reportedUsd.toFixed(5)}`;
+	return `${model} [${d.tier}]${cost}`;
+}
+
+/**
+ * Given the newest-first ledger window and the last-toasted entry id, return
+ * the new toasts to raise, oldest→newest. Pass `lastSeenId === null` on the
+ * first tick to toast nothing (avoids a burst on startup).
+ *
+ * When `harnessId` is non-empty, only entries from that harness are toasted,
+ * so multiple harnesses sharing one router don't spam each other's toasts.
+ */
+export function selectToasts(
+	entries: ToastDecision[],
+	lastSeenId: string | null,
+	harnessId = "",
+): ToastMessage[] {
+	if (lastSeenId === null) return [];
+	// `entries` is newest-first. Entries strictly newer than lastSeenId are the
+	// contiguous prefix before it. `-1` (id rolled out of the window) → treat
+	// every entry as new.
+	const idx = entries.findIndex((e) => e.id === lastSeenId);
+	const newer = idx === -1 ? entries : entries.slice(0, idx);
+	const out: ToastMessage[] = [];
+	for (let i = newer.length - 1; i >= 0; i--) {
+		const d = newer[i];
+		if (d === undefined) continue;
+		if (d.wasted) continue;
+		if (harnessId !== "" && d.harnessId !== harnessId) continue;
+		out.push({ model: d.servedSlug ?? d.slug, tier: d.tier, costUsd: d.reportedUsd, text: toToastText(d) });
+	}
+	return out;
+}
+
+/** The newest entry id in a newest-first list, for advancing `lastSeenId`. */
+export function newestId(entries: ToastDecision[]): string | null {
+	const first = entries[0];
+	return first === undefined ? null : first.id;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "auto-model-router",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
+  "type": "module",
+  "bin": {
+    "auto-model-router": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "smoke": "bun run tools/smoke.ts"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drewappling/auto-model-router.git"
+  },
+  "homepage": "https://github.com/drewappling/auto-model-router",
+  "bugs": {
+    "url": "https://github.com/drewappling/auto-model-router/issues"
+  },
+  "omp": {
+    "extensions": [
+      "./omp-extension/router-embed.ts",
+      "./omp-extension/router-toast.ts",
+      "./omp-extension/router-configure.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./omp-extension/router-embed.ts",
+      "./omp-extension/router-toast.ts",
+      "./omp-extension/router-configure.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}