auto-model-router 0.8.1 → 0.9.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.8.1",
+    "version": "0.9.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.8.1",
+      "version": "0.9.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1312,10 +1312,20 @@ refresh token beside the key (`--refresh-token`, `--key-expires`, `--refresh-exp
 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.
+the shape a harness key-helper wants. 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.
+
+The refresh token, the long-lived secret, does not sit in a file: `connect` puts it in the
+operating system's credential store — DPAPI on Windows (ciphertext in
+`<router home>/refresh.dpapi`, decryptable only by that Windows user on that machine),
+the login keychain on macOS, the Secret Service on Linux — and `remote.json` only names
+which store holds it. `<router home>/refresh.token`, owner-readable only, is the fallback
+when no store is usable (a CI box), and the note at the end of `connect` says when that
+happened. **Claude Code** gets its settings file written instead of an environment: the
+`env` block carries `ANTHROPIC_BASE_URL`, and `apiKeyHelper` runs
+`auto-model-router token`, so no key is in its environment or on disk for it and a
+short-lived key rotates underneath a running session.
 
 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

package/omp-extension/remote-logic.ts

@@ -22,8 +22,16 @@ 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). */
+	/**
+	 * Present only in a remote.json written before the credential store existed:
+	 * the token inline. New files name the store instead (`refreshTokenStore`) and
+	 * the token is read from it when a refresh happens (src/cli/refresh.ts).
+	 */
 	refreshToken?: string;
+	/** Which OS store holds the refresh token: dpapi (Windows), keychain (macOS), secret-service (Linux) or file. */
+	refreshTokenStore?: "dpapi" | "keychain" | "secret-service" | "file";
+	/** The account the store files it under (`<userId>@<remote host>`). */
+	refreshAccount?: string;
 	keyExpiresAtMs?: number;
 	refreshExpiresAtMs?: number;
 	/** What the remote calls this machine. */
@@ -46,6 +54,8 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 			name: typeof raw.name === "string" ? raw.name : "",
 			joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0,
 			...(typeof raw.refreshToken === "string" && raw.refreshToken !== "" ? { refreshToken: raw.refreshToken } : {}),
+			...(raw.refreshTokenStore === "dpapi" || raw.refreshTokenStore === "keychain" || raw.refreshTokenStore === "secret-service" || raw.refreshTokenStore === "file" ? { refreshTokenStore: raw.refreshTokenStore } : {}),
+			...(typeof raw.refreshAccount === "string" && raw.refreshAccount !== "" ? { refreshAccount: raw.refreshAccount } : {}),
 			...(typeof raw.keyExpiresAtMs === "number" ? { keyExpiresAtMs: raw.keyExpiresAtMs } : {}),
 			...(typeof raw.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: raw.refreshExpiresAtMs } : {}),
 			...(typeof raw.device === "string" && raw.device !== "" ? { device: raw.device } : {}),
@@ -55,6 +65,22 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 	}
 }
 
+/** True when this machine can trade for a new key: a refresh token inline, or a store that holds one. */
+export function hasRefresh(remote: RemoteRouter): boolean {
+	return (remote.refreshToken !== undefined && remote.refreshToken !== "") || remote.refreshTokenStore !== undefined;
+}
+
+/** The account a remote user's refresh token is filed under in the OS store. */
+export function refreshAccountOf(url: string, userId: string): string {
+	let host = url;
+	try {
+		host = new URL(url).host;
+	} catch {
+		/* keep the raw url */
+	}
+	return `${userId === "" ? "member" : userId}@${host}`;
+}
+
 export function readRemoteRouter(routerHome: string): RemoteRouter | null {
 	for (const path of [remoteFilePath(routerHome), join(routerHome, LEGACY_FILE)]) {
 		if (!existsSync(path)) continue;

package/package.json

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

package/src/cli/connect.ts

@@ -14,7 +14,9 @@
  *               $HERMES_HOME/plugins and .env points them at the remote
  *   Codex       ~/.codex/config.toml gains the auto-model-router provider
  *   Aider       ~/.aider.conf.yml gains the base URL, key and model
- *   Claude Code ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY (printed; --profile persists)
+ *   Claude Code ~/.claude/settings.json gains the base URL (its `env` block) and
+ *               `apiKeyHelper` running `auto-model-router token`, so no key
+ *               sits in its environment or on disk for it
  *
  * Every write is idempotent and announced. `--profile` persists the
  * environment lines (shell rc on POSIX, user environment on Windows).
@@ -26,7 +28,8 @@ import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileS
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { refreshAccountOf, remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { pickStore, saveRefreshToken, type StoreDeps, type StoreKind } from "./credential-store.ts";
 import { flagString, type CliArgs } from "./args.ts";
 
 export interface ConnectOptions {
@@ -48,6 +51,9 @@ export interface ConnectOptions {
 	agentdoxScope?: string;
 	/** Short-lived credential fields from a remote that issues them; absent for a permanent key. */
 	refreshToken?: string;
+	/** Which store takes the refresh token; picked from the platform when absent. Tests inject a backend. */
+	store?: StoreKind;
+	storeDeps?: StoreDeps;
 	keyExpiresAtMs?: number;
 	refreshExpiresAtMs?: number;
 	device?: string;
@@ -223,6 +229,16 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	const rh = routerHomeOf(o);
 	report.remoteFile = remoteFilePath(rh);
 	const previous = existsSync(report.remoteFile) ? (JSON.parse(readFileSync(report.remoteFile, "utf8")) as Record<string, unknown>) : {};
+	// The refresh token is the long-lived secret: it goes to the OS credential store, and
+	// remote.json only says which one. The access key stays in the file: it is short-lived,
+	// and the extensions need it without a subprocess on every poll.
+	let refreshTokenStore: StoreKind | undefined;
+	const refreshAccount = refreshAccountOf(o.url, o.userId);
+	if (o.refreshToken !== undefined && o.refreshToken !== "" && !o.dryRun) {
+		const wanted = o.store ?? pickStore(o.platform, o.pathHas);
+		refreshTokenStore = saveRefreshToken(rh, refreshAccount, o.refreshToken, wanted, o.storeDeps ?? { pathHas: o.pathHas });
+		if (refreshTokenStore !== wanted) report.notes.push(`the ${wanted} credential store was not usable; the refresh token is in ${join(rh, "refresh.token")} (owner-readable only)`);
+	} else if (o.refreshToken !== undefined && o.refreshToken !== "") refreshTokenStore = o.store ?? pickStore(o.platform, o.pathHas);
 	write(
 		report.remoteFile,
 		`${JSON.stringify(
@@ -232,7 +248,7 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 				userId: o.userId,
 				name: o.name,
 				joinedAtMs: typeof previous.joinedAtMs === "number" ? previous.joinedAtMs : Date.now(),
-				...(o.refreshToken !== undefined && o.refreshToken !== "" ? { refreshToken: o.refreshToken } : {}),
+				...(refreshTokenStore !== undefined ? { refreshTokenStore, refreshAccount } : {}),
 				...(o.keyExpiresAtMs !== undefined ? { keyExpiresAtMs: o.keyExpiresAtMs } : {}),
 				...(o.refreshExpiresAtMs !== undefined ? { refreshExpiresAtMs: o.refreshExpiresAtMs } : {}),
 				...(o.device !== undefined && o.device !== "" ? { device: o.device } : {}),
@@ -300,11 +316,33 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		report.configured.push(`Aider (${aiderConf})`);
 	} else report.skipped.push("Aider (not found)");
 
-	// 6. Claude Code: environment only.
-	if (wants(o, "claude") && o.pathHas("claude")) {
-		report.envLines.push(`ANTHROPIC_BASE_URL=${o.url}`, `ANTHROPIC_API_KEY=${o.key}`);
-		report.configured.push("Claude Code (environment)");
-	} else report.skipped.push("Claude Code (not on PATH)");
+	// 6. Claude Code: its settings file carries the base URL (the `env` block) and a key
+	// helper, a command it runs for the key — so the key is never in its environment or
+	// on disk for it. Without a refresh token the helper still works (it prints the key it
+	// holds); the helper is what lets a short-lived key rotate underneath a running session.
+	const claudeDir = join(o.home, ".claude");
+	if (wants(o, "claude") && (o.pathHas("claude") || existsSync(claudeDir))) {
+		const settingsPath = join(claudeDir, "settings.json");
+		let settings: Record<string, unknown> = {};
+		const before = existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : "";
+		try {
+			settings = before === "" ? {} : (JSON.parse(before) as Record<string, unknown>);
+		} catch {
+			report.notes.push(`${settingsPath} is not valid JSON; left alone — set env.ANTHROPIC_BASE_URL and apiKeyHelper by hand`);
+			settings = {};
+		}
+		const env: Record<string, unknown> = { ...((settings.env as Record<string, unknown> | undefined) ?? {}), ANTHROPIC_BASE_URL: o.url };
+		// Never leave a stale key beside the helper: the helper is the source now.
+		delete env.ANTHROPIC_API_KEY;
+		const entry = resolve(o.packageDir, "src", "index.ts").replaceAll("\\", "/");
+		const next = { ...settings, env, apiKeyHelper: `bun run "${entry}" token` };
+		const after = `${JSON.stringify(next, null, 2)}\n`;
+		if (after !== before) {
+			if (before !== "" && !o.dryRun) writeFileSync(`${settingsPath}.${new Date().toISOString().replaceAll(":", "-")}.bak`, before, "utf8");
+			write(settingsPath, after);
+		}
+		report.configured.push(`Claude Code (${settingsPath}: env.ANTHROPIC_BASE_URL + apiKeyHelper; open a new session)`);
+	} else report.skipped.push("Claude Code (not on PATH and no ~/.claude)");
 	report.envLines.unshift(`AUTO_MODEL_ROUTER_URL=${o.url}`, `AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
 	report.envLines = [...new Set(report.envLines)];
 

package/src/cli/credential-store.ts

@@ -0,0 +1,157 @@
+/**
+ * Where the refresh token lives on a member's machine.
+ *
+ * The access key has to sit in harness config files (a harness needs a literal
+ * bearer), and it is short-lived. The refresh token is the long-lived secret,
+ * so it goes to the operating system's credential store instead of a file:
+ *
+ *   Windows  DPAPI (CurrentUser scope): the token is encrypted so that only
+ *            this Windows user on this machine can decrypt it, and the
+ *            ciphertext is kept in `<router home>/refresh.dpapi`. Built in;
+ *            no module to install. The plaintext passes to PowerShell through
+ *            an environment variable, never an argument.
+ *   macOS    the login keychain, through `security` (service
+ *            `auto-model-router`, one account per remote user).
+ *   Linux    the Secret Service through `secret-tool` when it is installed.
+ *   file     `<router home>/refresh.token`, owner-readable only — the fallback
+ *            when none of the above works, and the choice on CI boxes.
+ *
+ * `remote.json` records which store holds it (`refreshTokenStore`) and the
+ * account name; it never holds the token itself once a store other than
+ * `file` is in use. A remote.json written before this existed may still carry
+ * the token inline; reading honours that until the next refresh moves it.
+ */
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type StoreKind = "dpapi" | "keychain" | "secret-service" | "file";
+
+const SERVICE = "auto-model-router";
+
+/** The store this platform offers, given which tools are on PATH. */
+export function pickStore(platform: string, pathHas: (bin: string) => boolean): StoreKind {
+	if (platform === "win32") return pathHas("powershell") || pathHas("pwsh") ? "dpapi" : "file";
+	if (platform === "darwin") return pathHas("security") ? "keychain" : "file";
+	if (platform === "linux") return pathHas("secret-tool") ? "secret-service" : "file";
+	return "file";
+}
+
+const powershell = (pathHas: (bin: string) => boolean): string => (pathHas("pwsh") ? "pwsh" : "powershell");
+
+function dpapiProtect(secret: string, pathHas: (bin: string) => boolean): string {
+	const r = spawnSync(
+		powershell(pathHas),
+		["-NoProfile", "-NonInteractive", "-Command", "Add-Type -AssemblyName System.Security; [Convert]::ToBase64String([System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($env:AMR_SECRET), $null, 'CurrentUser'))"],
+		{ encoding: "utf8", env: { ...process.env, AMR_SECRET: secret } },
+	);
+	if (r.status !== 0 || r.stdout.trim() === "") throw new Error(`DPAPI protect failed: ${r.stderr.trim() || r.status}`);
+	return r.stdout.trim();
+}
+
+function dpapiUnprotect(blob: string, pathHas: (bin: string) => boolean): string {
+	const r = spawnSync(
+		powershell(pathHas),
+		["-NoProfile", "-NonInteractive", "-Command", "Add-Type -AssemblyName System.Security; [Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String($env:AMR_BLOB), $null, 'CurrentUser'))"],
+		{ encoding: "utf8", env: { ...process.env, AMR_BLOB: blob } },
+	);
+	if (r.status !== 0) throw new Error(`DPAPI unprotect failed: ${r.stderr.trim() || r.status}`);
+	return r.stdout.replace(/\r?\n$/, "");
+}
+
+const filePath = (routerHome: string): string => join(routerHome, "refresh.token");
+const dpapiPath = (routerHome: string): string => join(routerHome, "refresh.dpapi");
+
+export interface StoreDeps {
+	pathHas?: (bin: string) => boolean;
+	/** Injected in tests to stand in for the platform tools. */
+	backend?: { save(account: string, secret: string): void; load(account: string): string | null; remove(account: string): void };
+}
+
+/**
+ * Saves the refresh token and returns the store that took it. A store that
+ * fails (keychain locked, tool missing) falls back to the file, so a member is
+ * never left without a refresh token; the caller records what was used.
+ */
+export function saveRefreshToken(routerHome: string, account: string, secret: string, kind: StoreKind, deps: StoreDeps = {}): StoreKind {
+	const pathHas = deps.pathHas ?? ((bin) => Bun.which(bin) !== null);
+	mkdirSync(routerHome, { recursive: true });
+	try {
+		if (deps.backend !== undefined) {
+			deps.backend.save(account, secret);
+			return kind;
+		}
+		switch (kind) {
+			case "dpapi":
+				writeFileSync(dpapiPath(routerHome), `${dpapiProtect(secret, pathHas)}\n`, { encoding: "utf8", mode: 0o600 });
+				rmSync(filePath(routerHome), { force: true });
+				return "dpapi";
+			case "keychain": {
+				const r = spawnSync("security", ["add-generic-password", "-U", "-a", account, "-s", SERVICE, "-w", secret], { encoding: "utf8" });
+				if (r.status !== 0) throw new Error(r.stderr.trim());
+				rmSync(filePath(routerHome), { force: true });
+				return "keychain";
+			}
+			case "secret-service": {
+				const r = spawnSync("secret-tool", ["store", `--label=${SERVICE} ${account}`, "service", SERVICE, "account", account], { encoding: "utf8", input: secret });
+				if (r.status !== 0) throw new Error(r.stderr.trim());
+				rmSync(filePath(routerHome), { force: true });
+				return "secret-service";
+			}
+			case "file":
+				break;
+		}
+	} catch {
+		// fall through to the file
+	}
+	writeFileSync(filePath(routerHome), `${secret}\n`, { encoding: "utf8", mode: 0o600 });
+	try {
+		chmodSync(filePath(routerHome), 0o600);
+	} catch {
+		/* Windows */
+	}
+	return "file";
+}
+
+/** The refresh token from the store `remote.json` names, or null when it is gone. */
+export function loadRefreshToken(routerHome: string, account: string, kind: StoreKind, deps: StoreDeps = {}): string | null {
+	const pathHas = deps.pathHas ?? ((bin) => Bun.which(bin) !== null);
+	try {
+		if (deps.backend !== undefined) return deps.backend.load(account);
+		switch (kind) {
+			case "dpapi": {
+				const p = dpapiPath(routerHome);
+				if (!existsSync(p)) return null;
+				return dpapiUnprotect(readFileSync(p, "utf8").trim(), pathHas);
+			}
+			case "keychain": {
+				const r = spawnSync("security", ["find-generic-password", "-a", account, "-s", SERVICE, "-w"], { encoding: "utf8" });
+				return r.status === 0 ? r.stdout.replace(/\r?\n$/, "") : null;
+			}
+			case "secret-service": {
+				const r = spawnSync("secret-tool", ["lookup", "service", SERVICE, "account", account], { encoding: "utf8" });
+				return r.status === 0 && r.stdout !== "" ? r.stdout.replace(/\r?\n$/, "") : null;
+			}
+			case "file": {
+				const p = filePath(routerHome);
+				return existsSync(p) ? readFileSync(p, "utf8").trim() : null;
+			}
+		}
+	} catch {
+		return null;
+	}
+	return null;
+}
+
+/** Forgets the token everywhere it might be. */
+export function removeRefreshToken(routerHome: string, account: string, deps: StoreDeps = {}): void {
+	rmSync(filePath(routerHome), { force: true });
+	rmSync(dpapiPath(routerHome), { force: true });
+	if (deps.backend !== undefined) {
+		deps.backend.remove(account);
+		return;
+	}
+	if (process.platform === "darwin") spawnSync("security", ["delete-generic-password", "-a", account, "-s", SERVICE], { encoding: "utf8" });
+	if (process.platform === "linux") spawnSync("secret-tool", ["clear", "service", SERVICE, "account", account], { encoding: "utf8" });
+}

package/src/cli/refresh.ts

@@ -16,7 +16,8 @@
 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 { hasRefresh, readRemoteRouter, refreshAccountOf, type RemoteRouter } from "../../omp-extension/remote-logic.ts";
+import { loadRefreshToken, type StoreDeps } from "./credential-store.ts";
 import { routerHome } from "../../omp-extension/router-url.ts";
 import type { CliArgs } from "./args.ts";
 import { connectRemote } from "./connect.ts";
@@ -34,7 +35,7 @@ export interface RefreshedCredential {
 
 /** 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 (!hasRefresh(remote)) return false;
 	if (remote.keyExpiresAtMs === undefined) return false;
 	return remote.keyExpiresAtMs - nowMs <= REFRESH_AHEAD_MS;
 }
@@ -49,13 +50,21 @@ export class RefreshError extends Error {
 	}
 }
 
+/** The refresh token: inline from an older remote.json, else from the OS store remote.json names. */
+export function resolveRefreshToken(remote: RemoteRouter, routerHome: string, storeDeps: StoreDeps = {}): string | null {
+	if (remote.refreshToken !== undefined && remote.refreshToken !== "") return remote.refreshToken;
+	if (remote.refreshTokenStore === undefined) return null;
+	return loadRefreshToken(routerHome, remote.refreshAccount ?? refreshAccountOf(remote.url, remote.userId), remote.refreshTokenStore, storeDeps);
+}
+
 /** 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");
+export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof fetch = fetch, routerHomeDir: string = routerHome(), storeDeps: StoreDeps = {}): Promise<RefreshedCredential> {
+	const token = resolveRefreshToken(remote, routerHomeDir, storeDeps);
+	if (token === null || token === "") throw new RefreshError("no_refresh_token", "this machine holds no refresh token (or its credential store no longer has it); 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 }),
+		body: JSON.stringify({ refreshToken: token }),
 		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;
@@ -76,8 +85,9 @@ export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof
  * 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);
+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; routerHome?: string; storeDeps?: StoreDeps }): Promise<RefreshedCredential> {
+	const rh = opts.routerHome ?? routerHome();
+	const fresh = await refreshCredential(opts.remote, opts.fetchImpl ?? fetch, rh, opts.storeDeps ?? {});
 	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({
@@ -97,6 +107,9 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 		packageDir,
 		platform: opts.platform ?? process.platform,
 		pathHas: opts.pathHas ?? ((bin) => Bun.which(bin) !== null),
+		// The store that already holds it keeps it; a machine never silently changes store.
+		...(opts.remote.refreshTokenStore !== undefined ? { store: opts.remote.refreshTokenStore } : {}),
+		...(opts.storeDeps !== undefined ? { storeDeps: opts.storeDeps } : {}),
 		// undefined keeps whatever scope the managed models.yml block already carries.
 	});
 	return fresh;

package/test/remote.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 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 { existingBlockScope, hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
-import { refreshAndRewrite, refreshCredential, RefreshError, shouldRefresh } from "../src/cli/refresh.ts";
+import { refreshAndRewrite, refreshCredential, RefreshError, resolveRefreshToken, shouldRefresh } from "../src/cli/refresh.ts";
+import { loadRefreshToken, pickStore, removeRefreshToken, saveRefreshToken } from "../src/cli/credential-store.ts";
+import { hasRefresh, refreshAccountOf } from "../omp-extension/remote-logic.ts";
 
 /**
  * Remote mode: remote.json puts the omp extensions on a router elsewhere,
@@ -78,7 +80,8 @@ describe("connect", () => {
 		expect(readFileSync(join(home, ".codex", "config.toml"), "utf8")).toContain("[model_providers.auto-model-router]");
 		expect(readFileSync(join(home, ".aider.conf.yml"), "utf8")).toContain("openai-api-base: https://team.example/v1");
 		expect(r1.configured.join("\n")).toMatch(/omp[\s\S]*Hermes[\s\S]*Codex[\s\S]*Aider[\s\S]*Claude Code/);
-		expect(r1.envLines).toEqual(["AUTO_MODEL_ROUTER_URL=https://team.example", "AUTO_MODEL_ROUTER_API_KEY=amrt_key", "ANTHROPIC_BASE_URL=https://team.example", "ANTHROPIC_API_KEY=amrt_key"]);
+		// Claude Code is configured through its settings file now, so nothing ANTHROPIC_* rides in the environment.
+		expect(r1.envLines).toEqual(["AUTO_MODEL_ROUTER_URL=https://team.example", "AUTO_MODEL_ROUTER_API_KEY=amrt_key"]);
 		// Running again changes nothing.
 		const snapshot = [ompCfg, readFileSync(join(home, ".codex", "config.toml"), "utf8"), readFileSync(join(home, ".aider.conf.yml"), "utf8")];
 		connectRemote(o);
@@ -99,7 +102,8 @@ describe("connect", () => {
 		connectRemote(o2);
 		const rc = readFileSync(join(h2, ".zshrc"), "utf8");
 		expect(rc.split("# auto-model-router remote").length).toBe(2);
-		expect(rc).toContain("export ANTHROPIC_BASE_URL=https://team.example");
+		expect(rc).toContain("export AUTO_MODEL_ROUTER_URL=https://team.example");
+		expect(rc).not.toContain("ANTHROPIC_");
 		rmSync(home, { recursive: true, force: true });
 		rmSync(h2, { recursive: true, force: true });
 	});
@@ -203,16 +207,21 @@ describe("short-lived remote credentials", () => {
 			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" });
+			// The refresh token is in the store (the file here: no platform tool on PATH); remote.json only names it.
+			expect(before).toMatchObject({ key: "amrt_old", keyExpiresAtMs: 1, device: "laptop", refreshTokenStore: "file", refreshAccount: "u_ada@team.example" });
+			expect(before.refreshToken).toBeUndefined();
+			expect(readFileSync(join(routerHome, "refresh.token"), "utf8").trim()).toBe("amrr_r1");
 			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 });
+			const fresh = await refreshAndRewrite({ remote: parseRemoteRouter(readFileSync(join(routerHome, "remote.json"), "utf8"))!, fetchImpl, home, packageDir: process.cwd(), env, platform: "linux", pathHas: () => false, routerHome });
 			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 });
+			expect(after).toMatchObject({ key: "amrt_new", keyExpiresAtMs: 50, refreshExpiresAtMs: 90, device: "laptop", joinedAtMs: before.joinedAtMs, refreshTokenStore: "file" });
+			expect(after.refreshToken).toBeUndefined();
+			expect(readFileSync(join(routerHome, "refresh.token"), "utf8").trim()).toBe("amrr_r2");
 			const models1 = readFileSync(join(agent, "models.yml"), "utf8");
 			expect(models1).toContain("apiKey: amrt_new");
 			expect(models1).not.toContain("amrt_old");
@@ -222,3 +231,91 @@ describe("short-lived remote credentials", () => {
 		}
 	});
 });
+
+describe("the refresh token lives in the OS credential store", () => {
+	const NL = String.fromCharCode(10);
+	// A fake backend stands in for DPAPI / the keychain / secret-service.
+	const vault = new Map<string, string>();
+	const backend = { save: (a: string, s: string) => void vault.set(a, s), load: (a: string) => vault.get(a) ?? null, remove: (a: string) => void vault.delete(a) };
+
+	test("the store is picked from the platform and its tools; the file is the fallback everywhere", () => {
+		expect(pickStore("win32", (b) => b === "powershell")).toBe("dpapi");
+		expect(pickStore("win32", () => false)).toBe("file");
+		expect(pickStore("darwin", (b) => b === "security")).toBe("keychain");
+		expect(pickStore("linux", (b) => b === "secret-tool")).toBe("secret-service");
+		expect(pickStore("linux", () => false)).toBe("file");
+		expect(refreshAccountOf("https://team.example:8790/", "u_ada")).toBe("u_ada@team.example:8790");
+	});
+
+	test("save/load through a store, and the file fallback keeps the token owner-readable", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-store-"));
+		try {
+			expect(saveRefreshToken(home, "u@t", "amrr_x", "keychain", { backend })).toBe("keychain");
+			expect(loadRefreshToken(home, "u@t", "keychain", { backend })).toBe("amrr_x");
+			expect(existsSync(join(home, "refresh.token"))).toBe(false); // nothing on disk
+			expect(saveRefreshToken(home, "u@t", "amrr_f", "file")).toBe("file");
+			expect(loadRefreshToken(home, "u@t", "file")).toBe("amrr_f");
+			removeRefreshToken(home, "u@t", { backend });
+			expect(loadRefreshToken(home, "u@t", "keychain", { backend })).toBeNull();
+			expect(existsSync(join(home, "refresh.token"))).toBe(false);
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("connect files the token in the store and remote.json only names it; refresh reads it back; an older inline token still works", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-store2-"));
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), "extensions: []" + NL);
+		const rh = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: rh, HERMES_HOME: join(home, "no-hermes") };
+		try {
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			connectRemote({ url: "https://team.example", key: "amrt_k1", userId: "u_ada", name: "Ada", refreshToken: "amrr_r1", keyExpiresAtMs: 1, refreshExpiresAtMs: 2, device: "laptop", store: "keychain", storeDeps: { backend }, profile: false, dryRun: false, only: ["omp"], env, home, packageDir: process.cwd(), platform: "darwin", pathHas: () => false });
+			const written = readFileSync(join(rh, "remote.json"), "utf8");
+			expect(written).not.toContain("amrr_r1");
+			const remote = parseRemoteRouter(written)!;
+			expect(remote).toMatchObject({ refreshTokenStore: "keychain", refreshAccount: "u_ada@team.example" });
+			expect(remote.refreshToken).toBeUndefined();
+			expect(hasRefresh(remote)).toBe(true);
+			expect(resolveRefreshToken(remote, rh, { backend })).toBe("amrr_r1");
+			// The refresh trades the stored token and files the new one in the same store.
+			const seen: string[] = [];
+			const fetchImpl = (async (_u: string | URL | Request, init?: RequestInit) => {
+				seen.push(String(init?.body));
+				return Response.json({ key: "amrt_k2", keyExpiresAtMs: 50, refreshToken: "amrr_r2", refreshExpiresAtMs: 90 });
+			}) as unknown as typeof fetch;
+			await refreshAndRewrite({ remote, fetchImpl, home, packageDir: process.cwd(), env, platform: "darwin", pathHas: () => false, routerHome: rh, storeDeps: { backend } });
+			expect(seen[0]).toBe(JSON.stringify({ refreshToken: "amrr_r1" }));
+			expect(vault.get("u_ada@team.example")).toBe("amrr_r2");
+			expect(readFileSync(join(rh, "remote.json"), "utf8")).not.toContain("amrr_r2");
+			// An older remote.json with the token inline is honoured until its next refresh.
+			const legacy = parseRemoteRouter(JSON.stringify({ url: "https://t", key: "k", refreshToken: "amrr_inline" }))!;
+			expect(resolveRefreshToken(legacy, rh)).toBe("amrr_inline");
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("connect writes Claude Code's settings: base URL in env, a key helper instead of a key, other settings kept", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-claude-"));
+		const claude = join(home, ".claude");
+		mkdirSync(claude, { recursive: true });
+		writeFileSync(join(claude, "settings.json"), JSON.stringify({ theme: "dark", env: { ANTHROPIC_API_KEY: "sk-old", FOO: "bar" } }, null, 2) + NL);
+		const env = { HOME: home, PI_CODING_AGENT_DIR: join(home, "no-omp"), AUTO_MODEL_ROUTER_HOME: join(home, ".auto-model-router"), HERMES_HOME: join(home, "no-hermes") };
+		try {
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			const r = connectRemote({ url: "https://team.example", key: "amrt_k", userId: "u_ada", name: "Ada", profile: false, dryRun: false, only: ["claude"], env, home, packageDir: "/pkg", platform: "linux", pathHas: () => false });
+			expect(r.configured.some((c) => c.startsWith("Claude Code ("))).toBe(true);
+			const s = JSON.parse(readFileSync(join(claude, "settings.json"), "utf8")) as { theme: string; env: Record<string, string>; apiKeyHelper: string };
+			expect(s.theme).toBe("dark");
+			expect(s.env).toEqual({ FOO: "bar", ANTHROPIC_BASE_URL: "https://team.example" }); // the stale key is gone
+			expect(s.apiKeyHelper).toMatch(/^bun run ".*\/pkg\/src\/index\.ts" token$/); // an absolute path, drive letter and all on Windows
+			expect(r.envLines.some((l) => l.startsWith("ANTHROPIC_API_KEY="))).toBe(false);
+			expect(readdirSync(claude).some((f) => f.startsWith("settings.json.") && f.endsWith(".bak"))).toBe(true); // the previous file was kept
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});