@event4u/agent-switch 1.6.1 → 1.7.0

package/README.md

@@ -27,6 +27,8 @@ Most naive switchers snapshot the macOS Keychain entry (`Claude Code-credentials
 
 `agent-switch` uses **`CLAUDE_CONFIG_DIR` isolation** instead. Each profile gets its own config directory under `~/.agent-switch/<name>/config`. Claude Code derives a *separate* keychain entry per config dir, so every account stays logged in **live and independently**. Switching only changes which directory new `claude` invocations point at — nothing is snapshotted, nothing goes stale, and each account logs in via browser exactly once.
 
+The same restraint governs the whole tool: no proxy, no traffic interception, no fingerprinting, no prompt rewriting — see [NON-GOALS.md](NON-GOALS.md) for the explicit list and the alternatives this ecosystem offers instead.
+
 ## Install
 
 **npm / npx** (any OS — needs Node ≥ 20). The package is published as

package/dist/args.js

@@ -28,6 +28,7 @@ const VALUE_FLAGS = new Set([
     "tag",
     "ack",
     "brief",
+    "profile",
 ]);
 /** Resolve a `--provider` value to a ProviderId; throws (not exits) on invalid
  *  so callers can test it. Undefined → claude. */

package/dist/doctor.js

@@ -12,6 +12,7 @@ import { allProviders } from "./providers.js";
 import { credentialStore } from "./credentials.js";
 import { sharedLinkHealth } from "./share.js";
 import { checkAuth } from "./api.js";
+import { checkTooling, doctorToolingLine } from "./tooling.js";
 const OK = "✅";
 const WARN = "⚠️";
 const ERR = "❌";
@@ -112,6 +113,12 @@ export async function runDoctor() {
             line(WARN, `claude/${n}: ${parts.join("; ")} — run \`agent-switch share sync\`.`);
         }
     }
+    // Ecosystem tooling (agent-config + rtk) — same detection module as
+    // `agent-switch tooling`, never a second implementation. Both tools are
+    // optional, so an unhealthy row is a WARN, never a blocking error.
+    for (const t of checkTooling({ ids: ["agent-config", "rtk"] })) {
+        line(t.healthy ? OK : WARN, doctorToolingLine(t));
+    }
     console.log(`\n  profile root: ${ROOT}`);
     console.log("");
     line(hardError ? ERR : OK, hardError ? "doctor found a blocking problem (see above)." : "no blocking problems.");

package/dist/index.js

@@ -23,6 +23,8 @@ import { withProperLock } from "./locks.js";
 import { applySharing, removeSharing, syncSharing, sharedLinkHealth } from "./share.js";
 import { detectShell, shellenvScript } from "./shellenv.js";
 import { runDoctor } from "./doctor.js";
+import { TOOL_IDS, checkTooling, formatToolingLines, runToolAction } from "./tooling.js";
+import { readHistory } from "./history.js";
 import { launchGui } from "./gui-launch.js";
 import { checkForUpdate, selfUpdate } from "./updates.js";
 import { mappingRows, pruneMappings, removeMapping, resolveMapping, setMapping, } from "./mappings.js";
@@ -1623,6 +1625,60 @@ function cmdOpen(appId, name) {
 function cmdShellenv(shellArg) {
     console.log(shellenvScript(detectShell(shellArg)));
 }
+/** `agent-switch tooling` — ecosystem tool readout (agent-config, rtk, provider
+ *  CLIs). `--json` is the GUI IPC contract: the GUI renders this readout and
+ *  never shells out to detect on its own. */
+function cmdTooling(json = false) {
+    const tools = checkTooling();
+    if (json) {
+        console.log(JSON.stringify(tools, null, 2));
+        return;
+    }
+    console.log(`agent-switch tooling — platform ${process.platform}\n`);
+    for (const l of formatToolingLines(tools))
+        console.log(l);
+}
+/** `agent-switch tooling install|upgrade <id>` — run the tool's per-platform
+ *  install/upgrade command as a visible child process (the GUI runs this inside
+ *  its embedded terminal). Exit code = the child's exit code. */
+function cmdToolingAction(action, id) {
+    if (!id || !TOOL_IDS.includes(id)) {
+        die(`usage: agent-switch tooling ${action} <${TOOL_IDS.join("|")}>`);
+    }
+    process.exit(runToolAction(id, action));
+}
+/**
+ * `agent-switch usage history [--provider claude] [--profile <name>] [--json]`
+ * — the daemon-recorded usage-history ring per profile (same file the daemon
+ * appends: `<profileDir>/usage-history.json`). `--json` is the GUI contract:
+ * `[{ profile, samples: [{ at, windows }] }]`. Own-profile data only.
+ */
+function cmdUsageHistory(providerId, sub, flags = {}) {
+    if (sub !== "history")
+        die("usage: agent-switch usage history [--provider P] [--profile <name>] [--json]");
+    const profiles = typeof flags.profile === "string"
+        ? [requireProfile(providerId, flags.profile, "usage history --profile")]
+        : listProfiles(providerId);
+    if (profiles.length === 0)
+        die(`no ${providerId} profiles`);
+    const rows = profiles.map((p) => ({
+        profile: p,
+        samples: readHistory(path.join(profileDir(providerId, p), "usage-history.json")),
+    }));
+    if (flags.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    for (const r of rows) {
+        if (r.samples.length === 0) {
+            console.log(`${providerId}/${r.profile}: no usage history yet (the daemon records samples — agent-switch service start)`);
+            continue;
+        }
+        const first = r.samples[0].at;
+        const last = r.samples[r.samples.length - 1].at;
+        console.log(`${providerId}/${r.profile}: ${r.samples.length} sample${r.samples.length === 1 ? "" : "s"} (${first} → ${last})`);
+    }
+}
 function usage() {
     console.log(`agent-switch — switch accounts for Claude Code, Codex, and Antigravity (macOS · Linux · Windows)
 
@@ -1665,6 +1721,9 @@ Provider defaults to claude; pass --provider codex|antigravity for the others.
   agent-switch notify --kind K --title T --message M [--json]   record a notification event
   agent-switch os-notify [on|off|status] [--json]   daemon-side OS desktop notifications (default off)
   agent-switch uninstall [--force]             remove all agent-switch data + daemon
+  agent-switch usage history [--provider P] [--profile <name>] [--json]   daemon-recorded usage samples per profile
+  agent-switch tooling [--json]                ecosystem tool readout (agent-config, rtk, provider CLIs)
+  agent-switch tooling install|upgrade <tool>  install/upgrade an ecosystem tool (agent-config, rtk, claude, codex)
   agent-switch doctor                          per-OS, per-provider self-check`);
 }
 // ---------- main -------------------------------------------------------------
@@ -1743,6 +1802,15 @@ async function main() {
         case "rm": return cmdRemove(providerId, positional[0], !!flags.force);
         case "shellenv": return cmdShellenv(flags.shell ?? positional[0]);
         case "service": return cmdService(positional[0]);
+        case "usage": return cmdUsageHistory(providerId, positional[0], flags);
+        case "tooling":
+            if (positional[0] === "install" || positional[0] === "upgrade") {
+                return cmdToolingAction(positional[0], positional[1]);
+            }
+            if (positional[0] !== undefined) {
+                die(`usage: agent-switch tooling [install|upgrade <${TOOL_IDS.join("|")}>] [--json]`);
+            }
+            return cmdTooling(!!flags.json);
         case "doctor": return process.exit(await runDoctor());
         case "help":
         case "--help":

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/package.json

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