auto-model-router 0.7.2 → 0.8.0

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.8.0",
     "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.8.0",
       "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 |
 
 ---
 
@@ -1305,6 +1306,17 @@ whatever else is authenticated. A local router deliberately gets no such entry
 is ephemeral, so a persisted one names a dead socket next launch — but a remote's URL and
 key are stable. **The file then holds the member key: treat it as a secret.**
 
+**Short-lived keys.** A remote that issues them (the team edition does) hands `connect` a
+refresh token beside the key (`--refresh-token`, `--key-expires`, `--refresh-expires`,
+`--device`), all kept in `remote.json`. The omp extension trades the refresh token for a
+new key a day before expiry, at session start, and re-writes every config `connect`
+wrote; `auto-model-router refresh` does the same by hand (`--force` to do it early), and
+`auto-model-router token` prints a key that is good right now, refreshing first if needed —
+the shape a harness key-helper wants (Claude Code's `apiKeyHelper`). The remote keeps the
+old key valid until its own expiry, so a session still holding it is never cut. A refresh
+token presented twice means the credential was copied: the remote revokes that device, and
+the machine onboards again.
+
 In remote mode omp sends `X-Agentdox-Scope` derived from the workspace folder, so one
 remote router serves every repo on the machine with that repo's shared context. The remote
 decides what to do with it: a team edition that pins a scope on the member's group
@@ -1469,11 +1481,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/remote-logic.ts

@@ -22,6 +22,12 @@ export interface RemoteRouter {
 	userId: string;
 	name: string;
 	joinedAtMs: number;
+	/** Present when the remote issues short-lived keys: trades for the next key (see src/cli/refresh.ts). */
+	refreshToken?: string;
+	keyExpiresAtMs?: number;
+	refreshExpiresAtMs?: number;
+	/** What the remote calls this machine. */
+	device?: string;
 }
 
 export function remoteFilePath(routerHome: string): string {
@@ -33,7 +39,17 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 	try {
 		const raw = JSON.parse(text) as Record<string, unknown>;
 		if (typeof raw.url !== "string" || typeof raw.key !== "string" || raw.url === "" || raw.key === "") return null;
-		return { url: raw.url.replace(/\/+$/, ""), key: raw.key, userId: typeof raw.userId === "string" ? raw.userId : "", name: typeof raw.name === "string" ? raw.name : "", joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0 };
+		return {
+			url: raw.url.replace(/\/+$/, ""),
+			key: raw.key,
+			userId: typeof raw.userId === "string" ? raw.userId : "",
+			name: typeof raw.name === "string" ? raw.name : "",
+			joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0,
+			...(typeof raw.refreshToken === "string" && raw.refreshToken !== "" ? { refreshToken: raw.refreshToken } : {}),
+			...(typeof raw.keyExpiresAtMs === "number" ? { keyExpiresAtMs: raw.keyExpiresAtMs } : {}),
+			...(typeof raw.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: raw.refreshExpiresAtMs } : {}),
+			...(typeof raw.device === "string" && raw.device !== "" ? { device: raw.device } : {}),
+		};
 	} catch {
 		return null;
 	}

package/omp-extension/router-embed.ts

@@ -27,6 +27,7 @@ import { ompModelsPath } from "../src/cli/config-cmd.ts";
 import { loadConfig } from "../src/config/load.ts";
 import { startServer } from "../src/server/http.ts";
 import { readRemoteRouter, remoteProviderRegistration } from "./remote-logic.ts";
+import { refreshAndRewrite, shouldRefresh } from "../src/cli/refresh.ts";
 import type { StartedServer } from "../src/server/http.ts";
 import type { RouterConfig } from "../src/config/types.ts";
 
@@ -161,8 +162,21 @@ export default function (pi: ExtensionAPI): void {
 		// Remote mode (`auto-model-router connect`): a router elsewhere is the
 		// router. Register it as the provider with its key and bind nothing
 		// locally; the other extensions find it through remote.json.
-		const remote = readRemoteRouter(routerHome());
+		let remote = readRemoteRouter(routerHome());
 		if (remote !== null) {
+			// A short-lived key is traded a day ahead of its expiry, and every config
+			// re-written, so no session ever starts on a dead key. The remote keeps the
+			// old key valid until its own expiry, so this session's main handle (which
+			// omp resolved from models.yml before we loaded) is not cut either way.
+			if (shouldRefresh(remote)) {
+				try {
+					const fresh = await refreshAndRewrite({ remote });
+					remote = { ...remote, key: fresh.key, refreshToken: fresh.refreshToken, keyExpiresAtMs: fresh.keyExpiresAtMs, refreshExpiresAtMs: fresh.refreshExpiresAtMs };
+					writeEmbedLog(`remote credential refreshed; key valid until ${new Date(fresh.keyExpiresAtMs).toISOString()}`);
+				} catch (err) {
+					writeEmbedLog(`remote credential refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
 			pi.registerProvider(EMBED_PROVIDER_ID, remoteProviderRegistration(remote, sessionId, !ctx.hasUI, cfg.ledger.fallbackBlend, deriveAgentdoxScope(process.cwd())));
 			pi.setLabel(`auto-model-router remote (${remote.url.replace(/^https?:\/\//, "")})`);
 			writeEmbedLog(`remote mode url=${remote.url} user=${remote.userId} session=${sessionId}`);

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,88 @@ 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[] = [];
+	// One line per category: the router often records the same fact twice from
+	// different angles ("policy: pinned to x" beside "pinned to x by session
+	// override"), and a toast that says it twice has wasted half its room.
+	for (const re of REASON_PRIORITY) {
+		const hit = reasons.find((r) => re.test(r));
+		if (hit === undefined) continue;
+		picked.push(clip(hit.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 +221,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 +236,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.8.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/connect.ts

@@ -44,8 +44,13 @@ export interface ConnectOptions {
 	packageDir: string;
 	/** Cost figures omp shows for the remote's virtual models, USD per million tokens. */
 	blend?: { inputPerMtok: number; outputPerMtok: number };
-	/** Adds `X-Agentdox-Scope` to omp's models.yml entry. Machine-wide: only for a single-project machine. */
+	/** Adds `X-Agentdox-Scope` to omp's models.yml entry. Machine-wide: only for a single-project machine. Undefined keeps what the managed block already has. */
 	agentdoxScope?: string;
+	/** Short-lived credential fields from a remote that issues them; absent for a permanent key. */
+	refreshToken?: string;
+	keyExpiresAtMs?: number;
+	refreshExpiresAtMs?: number;
+	device?: string;
 	platform: string;
 	pathHas: (bin: string) => boolean;
 }
@@ -190,6 +195,16 @@ export function mergeModelsYml(before: string, blockText: string): string {
 	return `${body.replace(/\s*$/, "")}${eol}providers:${eol}${block}${eol}`;
 }
 
+/** The `X-Agentdox-Scope` the managed block carries, or "" when none. */
+export function existingBlockScope(text: string): string {
+	const begin = text.indexOf(MODELS_YML_BEGIN);
+	if (begin < 0) return "";
+	const end = text.indexOf(MODELS_YML_END, begin);
+	const block = text.slice(begin, end < 0 ? text.length : end);
+	const m = /X-Agentdox-Scope:\s*(\S+)/.exec(block);
+	return m?.[1] ?? "";
+}
+
 /** True when the file already defines our provider outside a block we manage. */
 export function hasForeignRouterProvider(text: string): boolean {
 	if (text.includes(MODELS_YML_BEGIN)) return false;
@@ -207,7 +222,25 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	// 1. remote.json: what puts the omp extensions into remote mode.
 	const rh = routerHomeOf(o);
 	report.remoteFile = remoteFilePath(rh);
-	write(report.remoteFile, `${JSON.stringify({ url: o.url, key: o.key, userId: o.userId, name: o.name, joinedAtMs: Date.now() }, null, 2)}\n`);
+	const previous = existsSync(report.remoteFile) ? (JSON.parse(readFileSync(report.remoteFile, "utf8")) as Record<string, unknown>) : {};
+	write(
+		report.remoteFile,
+		`${JSON.stringify(
+			{
+				url: o.url,
+				key: o.key,
+				userId: o.userId,
+				name: o.name,
+				joinedAtMs: typeof previous.joinedAtMs === "number" ? previous.joinedAtMs : Date.now(),
+				...(o.refreshToken !== undefined && o.refreshToken !== "" ? { refreshToken: o.refreshToken } : {}),
+				...(o.keyExpiresAtMs !== undefined ? { keyExpiresAtMs: o.keyExpiresAtMs } : {}),
+				...(o.refreshExpiresAtMs !== undefined ? { refreshExpiresAtMs: o.refreshExpiresAtMs } : {}),
+				...(o.device !== undefined && o.device !== "" ? { device: o.device } : {}),
+			},
+			null,
+			2,
+		)}\n`,
+	);
 
 	// 2. omp
 	const agentDir = ompAgentDir(o);
@@ -225,7 +258,9 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 			report.notes.push(`${modelsPath} already defines an auto-model-router provider by hand; left alone — remove it to let connect manage the remote entry`);
 			report.configured.push(`omp (${cfgPath}; extensions only)`);
 		} else {
-			const modelsAfter = mergeModelsYml(modelsBefore, renderRemoteModelsYml(o.url, o.key, o.blend ?? { inputPerMtok: 1.1, outputPerMtok: 4.4 }, o.agentdoxScope ?? ""));
+			// A refresh re-writes the block without knowing the scope: keep the one already there.
+			const scope = o.agentdoxScope ?? existingBlockScope(modelsBefore);
+			const modelsAfter = mergeModelsYml(modelsBefore, renderRemoteModelsYml(o.url, o.key, o.blend ?? { inputPerMtok: 1.1, outputPerMtok: 4.4 }, scope));
 			if (modelsAfter !== modelsBefore) {
 				// Never overwrite another provider's work without a way back.
 				if (modelsBefore !== "" && !o.dryRun) writeFileSync(`${modelsPath}.${new Date().toISOString().replaceAll(":", "-")}.bak`, modelsBefore, "utf8");
@@ -292,6 +327,7 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		}
 	} else report.notes.push("add the environment lines to your shell profile, or re-run with --profile");
 	report.notes.push("omp's models.yml now carries the member key; treat that file as a secret");
+	if (o.refreshToken !== undefined && o.refreshToken !== "") report.notes.push("the key is short-lived: omp refreshes it at session start; `auto-model-router refresh` does it by hand, and `auto-model-router token` prints a current key for a harness key-helper");
 	return report;
 }
 
@@ -316,8 +352,31 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	const home = process.env.HOME !== undefined && process.env.HOME !== "" ? process.env.HOME : homedir();
 	// A single-project machine can label every request; a machine with several
 	// repos should leave it off and let the extensions send the workspace's own.
-	const agentdoxScope = flagString(args, "scope") ?? "";
-	const report = connectRemote({ url, key, userId, name, profile: args.flags.has("profile"), dryRun: args.flags.has("dry-run"), only, env: process.env, home, packageDir, platform: process.platform, pathHas, agentdoxScope });
+	const scopeFlag = flagString(args, "scope");
+	// A remote that issues short-lived keys hands these over beside the key.
+	const refreshToken = flagString(args, "refresh-token") ?? "";
+	const keyExpires = Number.parseInt(flagString(args, "key-expires") ?? "", 10);
+	const refreshExpires = Number.parseInt(flagString(args, "refresh-expires") ?? "", 10);
+	const device = flagString(args, "device") ?? "";
+	const report = connectRemote({
+		url,
+		key,
+		userId,
+		name,
+		profile: args.flags.has("profile"),
+		dryRun: args.flags.has("dry-run"),
+		only,
+		env: process.env,
+		home,
+		packageDir,
+		platform: process.platform,
+		pathHas,
+		...(scopeFlag === undefined ? {} : { agentdoxScope: scopeFlag }),
+		...(refreshToken === "" ? {} : { refreshToken }),
+		...(Number.isFinite(keyExpires) ? { keyExpiresAtMs: keyExpires } : {}),
+		...(Number.isFinite(refreshExpires) ? { refreshExpiresAtMs: refreshExpires } : {}),
+		...(device === "" ? {} : { device }),
+	});
 	console.log(`${args.flags.has("dry-run") ? "would write" : "wrote"} ${report.remoteFile}${name === "" ? "" : ` for ${name}`}`);
 	for (const c of report.configured) console.log(`  configured ${c}`);
 	for (const s of report.skipped) console.log(`  skipped    ${s}`);

package/src/cli/refresh.ts

@@ -0,0 +1,139 @@
+/**
+ * Short-lived remote credentials.
+ *
+ * A remote router (the team edition) may hand a machine an access key that
+ * expires plus a refresh token that trades for the next one. `remote.json`
+ * carries all of it; `auto-model-router refresh` trades early and re-writes
+ * every harness config `connect` wrote, and `auto-model-router token` prints a
+ * key that is good right now (refreshing first when needed), which is what a
+ * harness that can run a command for its key — Claude Code's `apiKeyHelper` —
+ * wants. The omp extension refreshes on its own at session start.
+ *
+ * A refresh a day early costs nothing: the remote keeps the old key valid until
+ * its own expiry, so a session still holding it is never cut.
+ */
+
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readRemoteRouter, type RemoteRouter } from "../../omp-extension/remote-logic.ts";
+import { routerHome } from "../../omp-extension/router-url.ts";
+import type { CliArgs } from "./args.ts";
+import { connectRemote } from "./connect.ts";
+
+/** How close to expiry a key is refreshed. Wide, so a machine used once a day never sees a dead key. */
+export const REFRESH_AHEAD_MS = 24 * 3_600_000;
+
+export interface RefreshedCredential {
+	key: string;
+	keyExpiresAtMs: number;
+	refreshToken: string;
+	refreshExpiresAtMs: number;
+	device?: string;
+}
+
+/** True when the credential can and should be traded now: it has a refresh token and its key is near or past expiry. */
+export function shouldRefresh(remote: RemoteRouter, nowMs = Date.now()): boolean {
+	if (remote.refreshToken === undefined || remote.refreshToken === "") return false;
+	if (remote.keyExpiresAtMs === undefined) return false;
+	return remote.keyExpiresAtMs - nowMs <= REFRESH_AHEAD_MS;
+}
+
+export class RefreshError extends Error {
+	constructor(
+		public readonly code: string,
+		message: string,
+	) {
+		super(message);
+		this.name = "RefreshError";
+	}
+}
+
+/** Trades the refresh token at the remote for the next credential. */
+export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof fetch = fetch): Promise<RefreshedCredential> {
+	if (remote.refreshToken === undefined || remote.refreshToken === "") throw new RefreshError("no_refresh_token", "this machine holds no refresh token; onboard it again with a setup token");
+	const res = await fetchImpl(`${remote.url}/auth/refresh`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ refreshToken: remote.refreshToken }),
+		signal: AbortSignal.timeout(15_000),
+	});
+	const body = (await res.json().catch(() => null)) as { key?: unknown; keyExpiresAtMs?: unknown; refreshToken?: unknown; refreshExpiresAtMs?: unknown; device?: unknown; error?: { code?: string; message?: string } } | null;
+	if (!res.ok || body === null || typeof body.key !== "string" || typeof body.refreshToken !== "string") {
+		throw new RefreshError(body?.error?.code ?? `http_${res.status}`, body?.error?.message ?? `the remote answered ${res.status} to the refresh`);
+	}
+	return {
+		key: body.key,
+		keyExpiresAtMs: typeof body.keyExpiresAtMs === "number" ? body.keyExpiresAtMs : Date.now(),
+		refreshToken: body.refreshToken,
+		refreshExpiresAtMs: typeof body.refreshExpiresAtMs === "number" ? body.refreshExpiresAtMs : Date.now(),
+		...(typeof body.device === "string" ? { device: body.device } : {}),
+	};
+}
+
+/**
+ * Refreshes and re-writes every place the key lives: remote.json and the
+ * harness configs `connect` manages. Returns the fresh credential. `home` and
+ * `packageDir` are injectable for tests.
+ */
+export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?: typeof fetch; home?: string; packageDir?: string; env?: Record<string, string | undefined>; platform?: string; pathHas?: (bin: string) => boolean }): Promise<RefreshedCredential> {
+	const fresh = await refreshCredential(opts.remote, opts.fetchImpl ?? fetch);
+	const home = opts.home ?? (process.env.HOME !== undefined && process.env.HOME !== "" ? process.env.HOME : homedir());
+	const packageDir = opts.packageDir ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+	connectRemote({
+		url: opts.remote.url,
+		key: fresh.key,
+		userId: opts.remote.userId,
+		name: opts.remote.name,
+		refreshToken: fresh.refreshToken,
+		keyExpiresAtMs: fresh.keyExpiresAtMs,
+		refreshExpiresAtMs: fresh.refreshExpiresAtMs,
+		device: fresh.device ?? opts.remote.device ?? "",
+		profile: false,
+		dryRun: false,
+		only: [],
+		env: opts.env ?? process.env,
+		home,
+		packageDir,
+		platform: opts.platform ?? process.platform,
+		pathHas: opts.pathHas ?? ((bin) => Bun.which(bin) !== null),
+		// undefined keeps whatever scope the managed models.yml block already carries.
+	});
+	return fresh;
+}
+
+/** `auto-model-router refresh [--force]` */
+export async function refreshCommand(args: CliArgs): Promise<void> {
+	const remote = readRemoteRouter(routerHome());
+	if (remote === null) throw new Error(`no remote router configured (${routerHome()}/remote.json); run connect first`);
+	if (!args.flags.has("force") && !shouldRefresh(remote)) {
+		const left = remote.keyExpiresAtMs === undefined ? "no expiry" : `${Math.max(0, Math.round((remote.keyExpiresAtMs - Date.now()) / 3_600_000))}h left`;
+		console.log(`the access key does not need refreshing yet (${left}); --force refreshes anyway`);
+		return;
+	}
+	const fresh = await refreshAndRewrite({ remote });
+	console.log(`refreshed: the new access key lasts until ${new Date(fresh.keyExpiresAtMs).toISOString()}; every harness config was re-written`);
+}
+
+/**
+ * `auto-model-router token`: a key that is good right now, on stdout and
+ * nothing else — the shape a harness's key-helper command expects. Refreshes
+ * first when the key is near expiry.
+ */
+export async function tokenCommand(args: CliArgs): Promise<void> {
+	const remote = readRemoteRouter(routerHome());
+	if (remote === null) throw new Error(`no remote router configured (${routerHome()}/remote.json); run connect first`);
+	if (!args.flags.has("no-refresh") && shouldRefresh(remote)) {
+		try {
+			const fresh = await refreshAndRewrite({ remote });
+			process.stdout.write(`${fresh.key}\n`);
+			return;
+		} catch (err) {
+			// A key that is still valid beats no key: fall through and print what we hold.
+			if (remote.keyExpiresAtMs !== undefined && remote.keyExpiresAtMs <= Date.now()) throw err;
+			console.error(`warning: refresh failed (${err instanceof Error ? err.message : String(err)}); printing the current key`);
+		}
+	}
+	process.stdout.write(`${remote.key}\n`);
+}
+

package/src/index.ts

@@ -13,6 +13,7 @@ import { configCommand } from "./cli/config-cmd.ts";
 import { explainCommand } from "./cli/explain.ts";
 import { exportCommand } from "./cli/export.ts";
 import { connectCommand } from "./cli/connect.ts";
+import { refreshCommand, tokenCommand } from "./cli/refresh.ts";
 import { modelsCommand } from "./cli/models.ts";
 import { reportCommand } from "./cli/report.ts";
 import { serveCommand } from "./cli/serve.ts";
@@ -26,7 +27,9 @@ Usage: auto-model-router <command> [options]
   stats      Show routed spend, per-model share, and escalation rates
   report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   export     One row per day, harness and model as CSV (--json for rows)
-  connect    Point this machine at a remote router (--url, --key; --scope labels a single-project machine; --profile persists the environment)
+  connect    Point this machine at a remote router (--url, --key[, --refresh-token]; --scope labels a single-project machine; --profile persists the environment)
+  refresh    Trade the refresh token for a new access key and re-write every harness config (--force: even when not near expiry)
+  token      Print an access key that is good right now, refreshing first if needed (for a harness key-helper)
   models     Show what each complexity tier would consider, and why
   explain    Route a saved request without dispatching it, and explain the decision
   config     Interactive wizard over the router's own config.yml
@@ -84,6 +87,12 @@ async function main(): Promise<number> {
 		case "join": // the first release's name
 			await connectCommand(args);
 			return 0;
+		case "refresh":
+			await refreshCommand(args);
+			return 0;
+		case "token":
+			await tokenCommand(args);
+			return 0;
 		case "models":
 			await modelsCommand(args);
 			return 0;

package/test/remote.test.ts

@@ -5,7 +5,8 @@ import { join } from "node:path";
 
 import { addExtensions, codexBlock, connectRemote, setDotenv, type ConnectOptions } from "../src/cli/connect.ts";
 import { parseRemoteRouter, readRemoteRouter, remoteProviderRegistration } from "../omp-extension/remote-logic.ts";
-import { hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
+import { existingBlockScope, hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
+import { refreshAndRewrite, refreshCredential, RefreshError, shouldRefresh } from "../src/cli/refresh.ts";
 
 /**
  * Remote mode: remote.json puts the omp extensions on a router elsewhere,
@@ -147,3 +148,77 @@ describe("omp models.yml for a remote router", () => {
 		expect(hasForeignRouterProvider(yaml("providers:", "  openai: {}"))).toBe(false);
 	});
 });
+
+describe("short-lived remote credentials", () => {
+	const NL = String.fromCharCode(10);
+	const remote = { url: "https://team.example", key: "amrt_old", userId: "u_ada", name: "Ada", joinedAtMs: 1, refreshToken: "amrr_r1", keyExpiresAtMs: 0, refreshExpiresAtMs: 0, device: "laptop" };
+
+	test("remote.json round-trips the credential fields, and a permanent key has none", () => {
+		const parsed = parseRemoteRouter(JSON.stringify(remote))!;
+		expect(parsed).toMatchObject({ refreshToken: "amrr_r1", keyExpiresAtMs: 0, refreshExpiresAtMs: 0, device: "laptop" });
+		const permanent = parseRemoteRouter(JSON.stringify({ url: "https://t", key: "k" }))!;
+		expect(permanent.refreshToken).toBeUndefined();
+		expect(shouldRefresh(permanent)).toBe(false);
+	});
+
+	test("a key is refreshed a day ahead of expiry, never without a refresh token", () => {
+		const now = 1_000_000_000_000;
+		const day = 24 * 3_600_000;
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now + 3 * day }, now)).toBe(false);
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now + day - 1 }, now)).toBe(true);
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now - 1 }, now)).toBe(true); // already dead: still worth a try
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now - 1, refreshToken: "" }, now)).toBe(false);
+	});
+
+	test("refreshCredential trades at /auth/refresh and surfaces the remote's refusal code", async () => {
+		const calls: { url: string; body: string }[] = [];
+		const ok = (async (url: string | URL | Request, init?: RequestInit) => {
+			calls.push({ url: String(url), body: String(init?.body) });
+			return Response.json({ key: "amrt_new", keyExpiresAtMs: 5, refreshToken: "amrr_r2", refreshExpiresAtMs: 9, device: "laptop" });
+		}) as unknown as typeof fetch;
+		const fresh = await refreshCredential(remote, ok);
+		expect(fresh).toEqual({ key: "amrt_new", keyExpiresAtMs: 5, refreshToken: "amrr_r2", refreshExpiresAtMs: 9, device: "laptop" });
+		expect(calls[0]).toEqual({ url: "https://team.example/auth/refresh", body: JSON.stringify({ refreshToken: "amrr_r1" }) });
+		const refused = (async () => Response.json({ error: { code: "refresh_reused", message: "already used" } }, { status: 401 })) as unknown as typeof fetch;
+		let err: RefreshError | null = null;
+		try {
+			await refreshCredential(remote, refused);
+		} catch (e) {
+			err = e as RefreshError;
+		}
+		expect(err?.code).toBe("refresh_reused");
+		expect(err?.message).toBe("already used");
+		await expect(refreshCredential({ ...remote, refreshToken: "" }, ok)).rejects.toBeInstanceOf(RefreshError);
+	});
+
+	test("refreshAndRewrite re-writes remote.json and the managed models.yml block, keeping its scope and join time", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-refresh-"));
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), "extensions: []" + NL);
+		const routerHome = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: routerHome, HERMES_HOME: join(home, "no-hermes") };
+		try {
+			// First: a connect with a scope and a credential.
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			connectRemote({ url: "https://team.example", key: "amrt_old", userId: "u_ada", name: "Ada", refreshToken: "amrr_r1", keyExpiresAtMs: 1, refreshExpiresAtMs: 2, device: "laptop", agentdoxScope: "omp-router", profile: false, dryRun: false, only: ["omp"], env, home, packageDir: process.cwd(), platform: "linux", pathHas: () => false });
+			const before = JSON.parse(readFileSync(join(routerHome, "remote.json"), "utf8")) as Record<string, unknown>;
+			expect(before).toMatchObject({ key: "amrt_old", refreshToken: "amrr_r1", keyExpiresAtMs: 1, device: "laptop" });
+			const models0 = readFileSync(join(agent, "models.yml"), "utf8");
+			expect(models0).toContain("apiKey: amrt_old");
+			expect(existingBlockScope(models0)).toBe("omp-router");
+			// Then a refresh, which knows nothing about the scope.
+			const fetchImpl = (async () => Response.json({ key: "amrt_new", keyExpiresAtMs: 50, refreshToken: "amrr_r2", refreshExpiresAtMs: 90 })) as unknown as typeof fetch;
+			const fresh = await refreshAndRewrite({ remote: parseRemoteRouter(readFileSync(join(routerHome, "remote.json"), "utf8"))!, fetchImpl, home, packageDir: process.cwd(), env, platform: "linux", pathHas: () => false });
+			expect(fresh.key).toBe("amrt_new");
+			const after = JSON.parse(readFileSync(join(routerHome, "remote.json"), "utf8")) as Record<string, unknown>;
+			expect(after).toMatchObject({ key: "amrt_new", refreshToken: "amrr_r2", keyExpiresAtMs: 50, refreshExpiresAtMs: 90, device: "laptop", joinedAtMs: before.joinedAtMs });
+			const models1 = readFileSync(join(agent, "models.yml"), "utf8");
+			expect(models1).toContain("apiKey: amrt_new");
+			expect(models1).not.toContain("amrt_old");
+			expect(existingBlockScope(models1)).toBe("omp-router"); // kept, not lost
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});

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,64 @@ 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);
+		// The same fact recorded twice from different angles takes one line, not both.
+		expect(whyReasons(["policy: pinned to ollama/gpt-oss:20b", "pinned to ollama/gpt-oss:20b by session override"])).toEqual(["policy: pinned to ollama/gpt-oss:20b"]);
+	});
+
+	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);
+	});
+});