@event4u/agent-switch 1.6.1 → 2.0.0

package/dist/token-freshen.js

@@ -0,0 +1,154 @@
+/**
+ * Keep a Claude profile's OAuth access token usable for the read-only usage /
+ * profile endpoints — WITHOUT agent-switch ever touching the credential store.
+ *
+ * The problem: a stored access token lives ~8h, the refresh token ~3 weeks.
+ * agent-switch reads the credential and calls the OAuth endpoints with whatever
+ * access token is in the store. Once that token expires the endpoints 401 and
+ * usage silently freezes on the last cached numbers — for exactly the profiles
+ * the operator is NOT actively using, which is the whole point of the readout.
+ * Starting Claude Code on the profile "fixes" it, because Claude Code refreshes.
+ *
+ * The mechanism: let Claude Code do the refresh. `claude doctor` is a LOCAL
+ * health check — it runs no completion and consumes no quota — but it goes
+ * through Claude Code's auth path, so an expired token is refreshed first,
+ * under Claude Code's own lock, into Claude Code's own store. Verified against
+ * CC 2.1.x (2026-07-25): with `expiresAt` in the past, `claude doctor` rotates
+ * BOTH the access and the refresh token and moves `expiresAt` ~8h out.
+ *
+ * Why not the refresh grant ourselves: that rotation is precisely the hazard the
+ * Phase-4 lock recorded — an out-of-band grant invalidates the refresh token a
+ * live session still holds. Delegating honours that lock instead of reopening
+ * it: agent-switch stays read-only outside `rebind` (ADR-003), and the one
+ * process allowed to rotate the token family is the one that owns it. Full
+ * rationale, evidence, and the rejected alternatives: ADR-004.
+ */
+import { spawnSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { accessTokenOf, readProfileCredential } from "./api.js";
+import { ROOT } from "./profiles.js";
+import { resolveBinary } from "./providers.js";
+/** Treat a token as spent this close to `expiresAt` — mirrors Claude Code's own
+ *  5-minute refresh buffer, so we never race it into a just-expired window. */
+export const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+/** Minimum gap between two freshen attempts for one profile. A truly dead login
+ *  (refresh token expired / revoked) cannot be healed by retrying, and the GUI
+ *  re-reads usage every few seconds — without this floor a dead profile would
+ *  spawn `claude doctor` on every cycle. */
+export const FRESHEN_COOLDOWN_MS = 10 * 60 * 1000;
+/** How long to let Claude Code's health check run before giving up on it. The
+ *  observed run is a few seconds; this is a stuck-process guard, and it bounds
+ *  how long a daemon poll cycle can stall on one profile. */
+const FRESHEN_TIMEOUT_MS = 30_000;
+/** `expiresAt` (epoch ms) out of a credential blob; null when absent/unparseable. */
+export function tokenExpiresAt(credentials) {
+    if (!credentials)
+        return null;
+    try {
+        const v = JSON.parse(credentials)?.claudeAiOauth?.expiresAt;
+        return typeof v === "number" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is this credential's access token spent (or about to be)? Pure — the testable
+ * core. A credential we cannot read or whose `expiresAt` we cannot parse is NOT
+ * reported as expired: we have no evidence it is, and spawning Claude Code on a
+ * guess is worse than one failed read.
+ */
+export function needsFreshen(credentials, now, bufferMs = EXPIRY_BUFFER_MS) {
+    const exp = tokenExpiresAt(credentials);
+    if (exp === null)
+        return false;
+    return exp - now <= bufferMs;
+}
+/** The attempt-stamp file for a config dir. Keyed by hash so the path stays
+ *  flat and filesystem-safe, and lives in agent-switch's own root — never
+ *  inside Claude Code's config dir. */
+function attemptStampFile(configDir) {
+    const digest = crypto.createHash("sha256").update(configDir.normalize("NFC"), "utf8").digest("hex").slice(0, 12);
+    return path.join(ROOT, "freshen", `${digest}`);
+}
+/** Cooldown state is a FILE, not a module variable: the GUI reads usage by
+ *  spawning a fresh `agent-switch status --json` per profile, so an in-process
+ *  map would reset on every read and defeat the floor entirely. */
+function readLastAttemptFile(configDir) {
+    try {
+        const n = Number(fs.readFileSync(attemptStampFile(configDir), "utf8").trim());
+        return Number.isFinite(n) ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function recordAttemptFile(configDir, at) {
+    const file = attemptStampFile(configDir);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, String(at));
+    }
+    catch {
+        /* best-effort: a missing stamp only costs an extra attempt */
+    }
+}
+/**
+ * `claude doctor` against one profile's config dir. stdout/stderr are dropped —
+ * this is a side-effect call, not a readout. Any completed run returns true;
+ * whether the token actually got refreshed is decided by re-reading the store.
+ */
+function runClaudeDoctor(configDir, linkedBinary) {
+    const res = spawnSync(resolveBinary("claude", linkedBinary), ["doctor"], {
+        env: { ...process.env, CLAUDE_CONFIG_DIR: configDir },
+        // Claude Code reads settings from the CWD; run it somewhere neutral so a
+        // project's config can never influence a background health check.
+        cwd: os.tmpdir(),
+        stdio: "ignore",
+        timeout: FRESHEN_TIMEOUT_MS,
+    });
+    if (res.error)
+        return false;
+    return true;
+}
+export function defaultFreshenDeps(linkedBinary = null) {
+    return {
+        now: () => Date.now(),
+        readCredential: readProfileCredential,
+        readLastAttempt: readLastAttemptFile,
+        recordAttempt: recordAttemptFile,
+        runHealthCheck: (configDir) => runClaudeDoctor(configDir, linkedBinary),
+        cooldownMs: FRESHEN_COOLDOWN_MS,
+        bufferMs: EXPIRY_BUFFER_MS,
+    };
+}
+/**
+ * Make sure the store behind `configDir` holds a usable access token, letting
+ * Claude Code refresh it when it does not. Idempotent, cooldown-guarded, and a
+ * no-op when the token is still good.
+ */
+export function freshenToken(configDir, deps = defaultFreshenDeps()) {
+    const creds = deps.readCredential(configDir);
+    if (!needsFreshen(creds, deps.now(), deps.bufferMs))
+        return "not-needed";
+    if (deps.now() - deps.readLastAttempt(configDir) < deps.cooldownMs)
+        return "cooling-down";
+    deps.recordAttempt(configDir, deps.now());
+    if (!deps.runHealthCheck(configDir))
+        return "unavailable";
+    return needsFreshen(deps.readCredential(configDir), deps.now(), deps.bufferMs) ? "still-expired" : "refreshed";
+}
+/**
+ * The access token to call the OAuth endpoints with — freshened first when it
+ * has expired. Returns whatever the store holds afterwards (null when there is
+ * no readable credential at all); a freshen that could not heal the login just
+ * means the caller's read fails as it did before.
+ */
+export function freshAccessToken(configDir, deps = defaultFreshenDeps()) {
+    freshenToken(configDir, deps);
+    const creds = deps.readCredential(configDir);
+    return creds ? accessTokenOf(creds) : null;
+}

package/dist/tooling.js

@@ -0,0 +1,324 @@
+/**
+ * Ecosystem tooling detection — the single source behind `agent-switch tooling`
+ * and the agent-config/rtk rows in `agent-switch doctor` (one implementation,
+ * two renderers; the GUI consumes `tooling --json` and never shells out).
+ *
+ * Covers agent-config, rtk, and the provider CLIs (claude, codex, agy).
+ * Detection is read-only: it runs local binaries with a short timeout and
+ * discards their output after classification; no network calls.
+ *
+ * rtk is special — upstream documents a hard name collision with an unrelated
+ * `rtk` (Rust Type Kit) and names `rtk gain` as the discriminator. Identity is
+ * judged on the probe's OUTPUT SIGNATURE, not its exit code (upstream defines
+ * no exit-code contract for `rtk gain`): a broken right tool is not the wrong
+ * tool, so a timed-out/crashed/ambiguous probe is `unverified`, never
+ * `unknown-rtk`.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readBinaryPath } from "./profiles.js";
+import { npmSearchPath } from "./updates.js";
+export const TOOL_IDS = ["agent-config", "rtk", "claude", "codex", "agy"];
+/** Which provider a probed binary belongs to (for `providers link` hints and
+ *  the user-linked path lookup). */
+const BINARY_PROVIDER = {
+    claude: "claude",
+    codex: "codex",
+    agy: "antigravity",
+};
+/** Probe timeouts: `rtk gain` is the identity discriminator and measured at
+ *  ~666 ms warm (S0.2), so 1500 ms is headroom, not hope; `--version` probes
+ *  get a little more because a cold Node CLI start can exceed 1.5 s. */
+export const RTK_PROBE_TIMEOUT_MS = 1500;
+const VERSION_PROBE_TIMEOUT_MS = 3000;
+/** spawnSync wrapper. Runs with {@link toolingSearchPath} so probes work when
+ *  this CLI was spawned from the GUI with a stripped PATH (Finder/menu-bar
+ *  launches); `shell` on Windows for `.cmd` shims (same as selfUpdate). */
+export function defaultRunner(cmd, args, timeoutMs) {
+    const r = spawnSync(cmd, args, {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        env: { ...process.env, PATH: toolingSearchPath() },
+        shell: process.platform === "win32",
+        windowsHide: true,
+    });
+    const err = r.error;
+    const timedOut = err?.code === "ETIMEDOUT" || r.signal === "SIGTERM";
+    return {
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+        status: r.status,
+        failedToStart: !!err && !timedOut,
+        timedOut,
+    };
+}
+// ---------- PATH resolution ---------------------------------------------------
+/** The PATH the tooling sweep searches: {@link npmSearchPath} already covers
+ *  the stripped-GUI-PATH case (node's own bin dir first, then the inherited
+ *  PATH, homebrew, /usr/local/bin, ~/.npm-global/bin, and ~/.local/bin — where
+ *  rtk's upstream install.sh and agy's installer land). */
+export function toolingSearchPath() {
+    return npmSearchPath();
+}
+/** Locate a binary on a search PATH without spawning it. Pure fs, injectable
+ *  platform — on Windows, tries the executable extensions; on POSIX, requires
+ *  the executable bit so a stray data file named `rtk` doesn't count. */
+export function findOnPath(binary, searchPath = toolingSearchPath(), platform = process.platform) {
+    const exts = platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+    for (const dir of searchPath.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, binary + ext);
+            try {
+                if (!fs.statSync(candidate).isFile())
+                    continue;
+                if (platform !== "win32")
+                    fs.accessSync(candidate, fs.constants.X_OK);
+                return candidate;
+            }
+            catch {
+                /* keep looking */
+            }
+        }
+    }
+    return null;
+}
+/** First version-looking token in a probe's output (`rtk 1.4.2` → `1.4.2`,
+ *  `v2.0.1-beta.3` → `2.0.1-beta.3`); null when there is none. */
+export function parseVersionToken(s) {
+    return /\bv?(\d+\.\d+\.\d+[-+.\w]*)/.exec(s)?.[1] ?? null;
+}
+// ---------- rtk identity probe ------------------------------------------------
+/** `rtk gain` output header of the real Token Killer (S0.2 measured signature). */
+const RTK_SIGNATURE = /RTK Token Savings|Token Savings/;
+/**
+ * The rtk identity probe — THE seam for the planned delegation: when
+ * agent-config ships its rtk detection contract (AC-side
+ * road-to-rtk-onboarding-correctness Phase 3), delegation replaces this
+ * function's body with a mapping over that readout; everything else in this
+ * module stays. Today's implementation is the documented fallback probe.
+ *
+ * Semantics (output signature, never exit code):
+ *   - stdout carries the Token Savings header → `token-killer` (+ version via
+ *     `rtk --version`, which is not identity-bearing);
+ *   - the probe ran and produced other output (unknown-subcommand error etc.)
+ *     → `unknown-rtk` (the name-collision case);
+ *   - timeout, crash-on-start, or a silent run → `unverified` (a broken right
+ *     tool is not the wrong tool).
+ */
+export function probeRtkIdentity(rtkCmd, run = defaultRunner) {
+    const gain = run(rtkCmd, ["gain"], RTK_PROBE_TIMEOUT_MS);
+    if (gain.timedOut || gain.failedToStart)
+        return { identity: "unverified", version: null };
+    if (RTK_SIGNATURE.test(gain.stdout)) {
+        const v = run(rtkCmd, ["--version"], VERSION_PROBE_TIMEOUT_MS);
+        return { identity: "token-killer", version: parseVersionToken(v.stdout) };
+    }
+    if (`${gain.stdout}${gain.stderr}`.trim().length > 0)
+        return { identity: "unknown-rtk", version: null };
+    return { identity: "unverified", version: null }; // ran silent — ambiguous
+}
+// ---------- hints ---------------------------------------------------------------
+function installHint(id, platform) {
+    switch (id) {
+        case "agent-config":
+            return "not installed — install: `npm install -g @event4u/agent-config`";
+        case "rtk":
+            if (platform === "darwin")
+                return "not installed — install: `brew install rtk`";
+            if (platform === "win32")
+                return "not installed — install: `winget install rtk-ai.rtk`";
+            return "not installed — install: `curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh`";
+        default:
+            return `not installed — install the ${id} CLI, or link it: \`agent-switch providers link --provider ${BINARY_PROVIDER[id]} --path <path-to-binary>\``;
+    }
+}
+function rtkUnhealthyHint(identity, platform) {
+    if (identity === "unknown-rtk") {
+        // installHint's tail carries the right per-OS install command.
+        return `the \`rtk\` on PATH is not Token Killer (name collision) — ${installHint("rtk", platform).replace("not installed — ", "")}`;
+    }
+    return "could not verify `rtk` (probe timed out or crashed) — run `rtk gain` manually to check";
+}
+/** One status entry for a tool that is not on the search PATH. Absence carries
+ *  no `identity` — there was no binary to probe, so there is nothing to judge. */
+function absent(id, platform) {
+    return { id, present: false, version: null, path: null, healthy: false, hint: installHint(id, platform) };
+}
+/**
+ * Detect every requested tool. Absence is encoded as `present: false`;
+ * `identity` appears only for rtk; `healthy` for rtk is true only for
+ * identity `token-killer`, for everything else when its `--version` probe ran.
+ */
+export function checkTooling(opts = {}) {
+    const ids = opts.ids ?? TOOL_IDS;
+    const run = opts.run ?? defaultRunner;
+    const searchPath = opts.searchPath ?? toolingSearchPath();
+    const platform = opts.platform ?? process.platform;
+    const linked = opts.linked ?? readBinaryPath;
+    return ids.map((id) => {
+        // Provider binaries honor a user-linked path first (same precedence as
+        // resolveBinary: linked > PATH, with ~/.local/bin inside the search PATH).
+        const providerId = BINARY_PROVIDER[id];
+        const linkedPath = providerId ? linked(providerId) : null;
+        const binPath = linkedPath && fs.existsSync(linkedPath) ? linkedPath : findOnPath(id, searchPath, platform);
+        if (!binPath)
+            return absent(id, platform);
+        if (id === "rtk") {
+            const { identity, version } = probeRtkIdentity(binPath, run);
+            return {
+                id,
+                present: true,
+                version,
+                path: binPath,
+                healthy: identity === "token-killer",
+                identity,
+                hint: identity === "token-killer" ? "" : rtkUnhealthyHint(identity, platform),
+            };
+        }
+        const probe = run(binPath, ["--version"], VERSION_PROBE_TIMEOUT_MS);
+        const healthy = !probe.failedToStart && !probe.timedOut;
+        return {
+            id,
+            present: true,
+            version: healthy ? parseVersionToken(probe.stdout) : null,
+            path: binPath,
+            healthy,
+            hint: healthy ? "" : `\`${id} --version\` ${probe.timedOut ? "timed out" : "failed to run"} — reinstall it (${installHint(id, platform).replace("not installed — ", "")})`,
+        };
+    });
+}
+/** npm packages behind the npm-installed tools (same commands the hints cite). */
+const NPM_PACKAGES = {
+    "agent-config": "@event4u/agent-config",
+    claude: "@anthropic-ai/claude-code",
+    codex: "@openai/codex",
+};
+/** rtk's upstream installer (linux — used for install AND upgrade there).
+ *  NEVER `cargo install rtk`: that builds the unrelated Rust Type Kit. */
+const RTK_INSTALL_SH = "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh";
+function npmCommand(pkg, latest) {
+    const spec = latest ? `${pkg}@latest` : pkg;
+    return { cmd: "npm", args: ["install", "-g", spec], display: `npm install -g ${spec}` };
+}
+/**
+ * The exact command for `tooling install|upgrade <id>` — pure, per-platform.
+ * A `refusal` result means there is no honest command to run (today: agy —
+ * the binary ships with the Antigravity app; this repo documents no standalone
+ * installer, and inventing one would be worse than saying so).
+ *
+ * `claudePath` (resolved linked-or-PATH binary) selects the claude upgrade
+ * shape: the CLI's own `claude update` when the binary is present, else the
+ * npm `@latest` reinstall.
+ */
+export function planToolAction(id, action, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    switch (id) {
+        case "agent-config":
+            return { command: npmCommand(NPM_PACKAGES["agent-config"], action === "upgrade") };
+        case "codex":
+            return { command: npmCommand(NPM_PACKAGES.codex, action === "upgrade") };
+        case "claude":
+            if (action === "upgrade" && opts.claudePath) {
+                return { command: { cmd: opts.claudePath, args: ["update"], display: "claude update" } };
+            }
+            return { command: npmCommand(NPM_PACKAGES.claude, action === "upgrade") };
+        case "rtk": {
+            if (platform === "darwin") {
+                const verb = action === "upgrade" ? "upgrade" : "install";
+                return { command: { cmd: "brew", args: [verb, "rtk"], display: `brew ${verb} rtk` } };
+            }
+            if (platform === "win32") {
+                return { command: { cmd: "winget", args: [action, "rtk-ai.rtk"], display: `winget ${action} rtk-ai.rtk` } };
+            }
+            // linux (and anything else POSIX): the upstream installer covers both actions.
+            return { command: { cmd: "sh", args: ["-c", RTK_INSTALL_SH], display: RTK_INSTALL_SH } };
+        }
+        case "agy":
+            return {
+                refusal: "`agy` has no standalone installer — the Antigravity CLI ships with the Antigravity app.\n" +
+                    "Install the app, then (if `agy` is not on PATH) link the binary:\n" +
+                    "  agent-switch providers link --provider antigravity --path <path-to-agy>",
+            };
+    }
+}
+/** The real runner: inherits stdio (the GUI runs this CLI inside its embedded
+ *  terminal, so the user watches npm/brew output live), searches
+ *  {@link toolingSearchPath} so a GUI-spawned run finds npm/brew on a stripped
+ *  PATH, and uses `shell` on Windows for `.cmd` shims (same as selfUpdate). */
+export function defaultInstallRunner(cmd, args) {
+    const r = spawnSync(cmd, args, {
+        stdio: "inherit",
+        env: { ...process.env, PATH: toolingSearchPath() },
+        shell: process.platform === "win32",
+    });
+    if (r.error?.code === "ENOENT") {
+        console.error(`❌ \`${cmd}\` not found on PATH — install it first, then retry.`);
+        return 1;
+    }
+    return r.status ?? 1;
+}
+/** The claude binary `tooling upgrade claude` prefers: linked path first (same
+ *  precedence as resolveBinary), else PATH. Null → npm fallback. */
+function resolveClaudeForUpdate() {
+    const linked = readBinaryPath("claude");
+    if (linked && fs.existsSync(linked))
+        return linked;
+    return findOnPath("claude");
+}
+/**
+ * `agent-switch tooling install|upgrade <id>` — plan the per-platform command,
+ * print it (transparency: the user sees exactly what runs), run it with
+ * inherited stdio, and return the child's exit code. A refusal (agy) prints
+ * the explanation and returns 1 without running anything.
+ */
+export function runToolAction(id, action, opts = {}) {
+    const log = opts.log ?? console.log;
+    const error = opts.error ?? console.error;
+    const claudePath = opts.claudePath !== undefined
+        ? opts.claudePath
+        : id === "claude" && action === "upgrade"
+            ? resolveClaudeForUpdate()
+            : null;
+    const plan = planToolAction(id, action, { platform: opts.platform, claudePath });
+    if ("refusal" in plan) {
+        error(plan.refusal);
+        return 1;
+    }
+    log(`→ ${plan.command.display}`);
+    const status = (opts.run ?? defaultInstallRunner)(plan.command.cmd, plan.command.args);
+    if (status === 0) {
+        log(`✅ ${id} ${action === "upgrade" ? "upgraded" : "installed"} — verify with \`agent-switch tooling\`.`);
+    }
+    else {
+        error(`❌ \`${plan.command.display}\` exited with ${status} (its output is above).`);
+    }
+    return status;
+}
+// ---------- renderers -----------------------------------------------------------
+export function statusGlyph(t) {
+    if (t.healthy)
+        return "✅";
+    return t.present ? "⚠️" : "❌";
+}
+/** Aligned human rows for `agent-switch tooling` (glyph, id, version, detail). */
+export function formatToolingLines(tools) {
+    const idW = Math.max(...tools.map((t) => t.id.length));
+    const verW = Math.max(...tools.map((t) => (t.version ?? "—").length));
+    return tools.map((t) => {
+        const detail = t.healthy
+            ? `${t.path}${t.identity === "token-killer" ? " (Token Killer verified)" : ""}`
+            : t.hint;
+        return `${statusGlyph(t)}  ${t.id.padEnd(idW)}  ${(t.version ?? "—").padEnd(verW)}  ${detail}`.trimEnd();
+    });
+}
+/** One doctor-style message per tool (doctor prefixes its own OK/WARN mark).
+ *  Never a hard error — agent-config and rtk are optional ecosystem tools. */
+export function doctorToolingLine(t) {
+    if (t.healthy) {
+        return `\`${t.id}\`${t.version ? ` ${t.version}` : ""} is installed${t.identity === "token-killer" ? " (Token Killer verified)" : ""}.`;
+    }
+    return `\`${t.id}\`: ${t.hint}`;
+}

package/dist/usage.js

@@ -151,13 +151,14 @@ export function maxUtilization(s) {
     return vals.length ? Math.max(...vals) : null;
 }
 /**
- * Opt-in auto-switch decision (pure, no I/O). Given the active profile and the
- * same-provider candidates with their usage, return the profile to switch to,
- * or null. Switches only when the active profile has hit `threshold`% on some
- * window AND another candidate has strictly more headroom (lower max
- * utilization) while itself staying below `threshold`. Ties keep the first
- * candidate. This is a single switch decision gated behind config — never a
- * display ranking.
+ * Opt-in switch SUGGESTION (pure, no I/O). Given the active profile and the
+ * same-provider candidates with their usage, return the profile to suggest
+ * switching to, or null. Suggests only when the active profile has hit
+ * `threshold`% on some window AND another candidate has strictly more headroom
+ * (lower max utilization) while itself staying below `threshold`. Ties keep the
+ * first candidate. This computes the suggestion the daemon notifies with and the
+ * user-clicked switch modal pre-selects — it never performs the switch itself,
+ * and is never a display ranking.
  */
 export function pickSwitchTarget(active, candidates, threshold, isEligible = () => true) {
     const activeSnap = candidates.find((c) => c.name === active)?.snapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@event4u/agent-switch",
-  "version": "1.6.1",
+  "version": "2.0.0",
   "description": "Switch between multiple Claude Code accounts on macOS, Linux, and Windows via isolated CLAUDE_CONFIG_DIR profiles",
   "repository": {
     "type": "git",