@event4u/agent-switch 1.0.0

package/dist/tmux.js

@@ -0,0 +1,98 @@
+/**
+ * Opt-in tmux integration for in-place session handoff (POSIX only).
+ *
+ * `run --tmux` wraps a provider session in an agent-switch-MANAGED tmux session
+ * (a recorded name). `takeover --in-place` then hands the account over *inside
+ * that same pane*: send a clean exit to the running CLI, wait for it to exit,
+ * and respawn the pane with the target profile's env — no new terminal.
+ *
+ * Only agent-switch-managed panes are ever touched (the recorded-name check);
+ * a session running in a user's own tmux/terminal is never send-keys'd.
+ *
+ * The argv builders here are pure (unit-tested); the thin exec + the recorded
+ * managed-session file are the only side effects.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ROOT } from "./profiles.js";
+/** `<ROOT>/tmux-sessions.json`: tmux session name → the profile it manages. */
+export const TMUX_STATE = path.join(ROOT, "tmux-sessions.json");
+/** Deterministic, collision-resistant managed session name for a profile. */
+export function tmuxSessionName(provider, profile) {
+    return `asw-${provider}-${profile}`;
+}
+export function readTmuxRegistry(file = TMUX_STATE) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return raw && typeof raw === "object" ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function recordManagedSession(name, session, file = TMUX_STATE) {
+    const reg = readTmuxRegistry(file);
+    reg[name] = session;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(reg, null, 2) + "\n", { mode: 0o600 });
+}
+export function forgetManagedSession(name, file = TMUX_STATE) {
+    const reg = readTmuxRegistry(file);
+    if (name in reg) {
+        delete reg[name];
+        fs.writeFileSync(file, JSON.stringify(reg, null, 2) + "\n", { mode: 0o600 });
+    }
+}
+// ---------- pure argv builders ----------------------------------------------
+/** `tmux new-session -A -s <name> -e VAR=dir -- <cmd...>` — attach-or-create a
+ *  named session with the profile env exported into it. */
+export function newSessionArgs(name, envVar, dir, cmd) {
+    return ["new-session", "-A", "-s", name, "-e", `${envVar}=${dir}`, "--", ...cmd];
+}
+/** `tmux respawn-pane -k -t <target> -e VAR=dir -- <cmd...>` — replace the
+ *  pane's process with the target profile's env + the resume command. `-k`
+ *  reliably kills-and-replaces (the pane persists), which is why the in-place
+ *  handoff uses this rather than a send-keys/close dance that would tear the
+ *  pane down when the CLI is the pane's own command. */
+export function respawnPaneArgs(target, envVar, dir, cmd) {
+    return ["respawn-pane", "-k", "-t", target, "-e", `${envVar}=${dir}`, "--", ...cmd];
+}
+/** `tmux send-keys -t <target> <literal> Enter` — type a command into a pane.
+ *  Used by `compact` to type `/compact` into an agent-switch-MANAGED pane (the
+ *  CLI is the pane's own process and stays running, so send-keys is right here,
+ *  unlike takeover's respawn-pane). NEVER used on a non-managed pane. */
+export function sendKeysArgs(target, literal) {
+    return ["send-keys", "-t", target, literal, "Enter"];
+}
+// ---------- environment detection --------------------------------------------
+export function tmuxAvailable() {
+    if (process.platform === "win32")
+        return false;
+    return spawnSync("tmux", ["-V"], { stdio: "ignore" }).status === 0;
+}
+/** Inside a tmux pane? (`$TMUX` is set by tmux for every pane.) */
+export function insideTmux(env = process.env) {
+    return typeof env.TMUX === "string" && env.TMUX.length > 0;
+}
+/**
+ * The managed session for the current pane, or null. Pure given the current
+ * session name + the registry — so `insideTmux` + a `tmux display-message`
+ * lookup feed it, and it is unit-testable without tmux.
+ */
+export function currentManagedSession(currentName, registry) {
+    if (!currentName)
+        return null;
+    return registry[currentName] ?? null;
+}
+/** The current pane's tmux session name (via `tmux display-message -p '#S'`),
+ *  or null when not inside tmux / tmux missing. */
+export function currentTmuxSessionName() {
+    if (!insideTmux())
+        return null;
+    const r = spawnSync("tmux", ["display-message", "-p", "#S"], { encoding: "utf8" });
+    if (r.status !== 0)
+        return null;
+    const s = r.stdout.trim();
+    return s.length ? s : null;
+}

package/dist/tokens.js

@@ -0,0 +1,88 @@
+/**
+ * Token + cost reporting (roadmap: road-to-agent-switch-session-telemetry,
+ * Phase 5), DELEGATED to ccusage (council D2 — verified viable in spikes/t7).
+ * agent-switch does NOT re-implement transcript aggregation, dedup, or a
+ * pricing engine. It contributes two things ccusage cannot: (1) pointing
+ * ccusage at a specific profile's config dir, and (2) the cost-honesty label —
+ * agent-switch knows a profile is a subscription/OAuth login, so its cost is
+ * "notional" (API-equivalent), not real spend.
+ *
+ * ccusage is an OPTIONAL external tool (the tmux/playwright pattern): detected
+ * on PATH, never bundled. Absent → the caller prints an install pointer.
+ */
+import { spawnSync } from "node:child_process";
+/** The command `tokens install` runs (in the GUI's embedded terminal or a
+ *  user's shell) to install ccusage globally. Fixed literal — never bundled as
+ *  a dependency (zero-dep invariant + council D2). */
+export const CCUSAGE_INSTALL = ["npm", "install", "-g", "ccusage"];
+/** Resolve the ccusage runner. A PATH binary is preferred; the
+ *  `AGENT_SWITCH_CCUSAGE` env var overrides with an explicit argv prefix
+ *  (e.g. "npx -y ccusage@latest") for a zero-install run or tests. Null when
+ *  neither is available. */
+export function resolveCcusageRunner(env = process.env) {
+    const override = env.AGENT_SWITCH_CCUSAGE?.trim();
+    if (override)
+        return override.split(/\s+/);
+    const probe = process.platform === "win32" ? "where" : "which";
+    const r = spawnSync(probe, ["ccusage"], { encoding: "utf8" });
+    if (r.status === 0 && (r.stdout || "").trim())
+        return ["ccusage"];
+    return null;
+}
+/** Parse ccusage `daily --json` output ({ daily: [...], totals: {...} }) into
+ *  our shape. Pure + defensive: unknown/short shapes degrade to empty, never
+ *  throw. `costBasis` is stamped by the caller (ccusage cannot know it). */
+export function parseCcusageDaily(json, costBasis) {
+    const rows = Array.isArray(json?.daily) ? json.daily : Array.isArray(json) ? json : [];
+    const num = (v) => (Number.isFinite(v) ? v : 0);
+    const days = rows.map((r) => ({
+        date: typeof r?.period === "string" ? r.period : typeof r?.date === "string" ? r.date : "?",
+        inputTokens: num(r?.inputTokens),
+        outputTokens: num(r?.outputTokens),
+        cacheCreationTokens: num(r?.cacheCreationTokens),
+        cacheReadTokens: num(r?.cacheReadTokens),
+        totalTokens: num(r?.totalTokens),
+        cost: num(r?.totalCost),
+        models: Array.isArray(r?.modelsUsed) ? r.modelsUsed : [],
+    }));
+    const t = json?.totals ?? {};
+    const totals = {
+        inputTokens: num(t.inputTokens) || days.reduce((s, d) => s + d.inputTokens, 0),
+        outputTokens: num(t.outputTokens) || days.reduce((s, d) => s + d.outputTokens, 0),
+        cacheCreationTokens: num(t.cacheCreationTokens) || days.reduce((s, d) => s + d.cacheCreationTokens, 0),
+        cacheReadTokens: num(t.cacheReadTokens) || days.reduce((s, d) => s + d.cacheReadTokens, 0),
+        totalTokens: num(t.totalTokens) || days.reduce((s, d) => s + d.totalTokens, 0),
+        cost: num(t.totalCost) || days.reduce((s, d) => s + d.cost, 0),
+    };
+    return { days, totals, costBasis };
+}
+/** The cost basis for a profile. agent-switch profiles are OAuth/subscription
+ *  logins → their token cost is NOTIONAL (API-equivalent, not real spend). A
+ *  raw API key credential (sk-ant-…) would be `computed`. */
+export function costBasisFor(rawCredential) {
+    // A raw API key → real, computed spend. Anything else (OAuth login blob, or
+    // unknown) → notional, the safe label that never overstates real spend.
+    if (rawCredential && /^sk-(ant|proj)-/.test(rawCredential.trim()))
+        return "computed";
+    return "notional";
+}
+/** Run ccusage for one profile's config dir and return the parsed report, or
+ *  null when ccusage failed / produced no JSON (caller degrades gracefully). */
+export function runCcusage(runner, provider, configDir, costBasis) {
+    const envKey = provider === "codex" ? "CODEX_HOME" : "CLAUDE_CONFIG_DIR";
+    const [cmd, ...prefix] = runner;
+    const r = spawnSync(cmd, [...prefix, "daily", "--json"], {
+        encoding: "utf8",
+        timeout: 180_000,
+        env: { ...process.env, [envKey]: configDir },
+    });
+    const out = (r.stdout || "").trim();
+    if (!out)
+        return null;
+    try {
+        return parseCcusageDaily(JSON.parse(out), costBasis);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/usage.js

@@ -0,0 +1,208 @@
+/**
+ * Usage engine — policy-scoped, own-profile only.
+ *
+ * Parses Claude's OAuth `/usage` response into a defensive snapshot, formats it
+ * for `status`, tracks 30-day history, and detects active-profile threshold
+ * crossings. It NEVER compares or ranks accounts — that is the anti-rotation
+ * boundary the whole roadmap is locked around. Codex/Antigravity have no usage
+ * readout (verified), so they surface "usage unavailable" and never reach here.
+ */
+// The windows Claude's /usage exposes, richest first. seven_day_opus/sonnet are
+// the per-model 7-day windows (extension-verified); absent shapes are skipped.
+const WINDOW_DEFS = [
+    ["five_hour", "5h"],
+    ["seven_day", "7d"],
+    ["seven_day_opus", "7d Opus"],
+    ["seven_day_sonnet", "7d Sonnet"],
+];
+/** One entry of the current `limits[]` shape → a window, or null to skip. This
+ *  array is the ONLY place the per-model weekly limit (e.g. Fable) is exposed;
+ *  `weekly_all` is the all-models weekly window, `session` the 5h window. */
+function windowFromLimit(l) {
+    if (!l || typeof l !== "object")
+        return null;
+    const utilization = typeof l.percent === "number" ? Math.round(l.percent) : null;
+    const resetsAt = typeof l.resets_at === "string" ? l.resets_at : null;
+    if (utilization === null && resetsAt === null)
+        return null;
+    const kind = typeof l.kind === "string" ? l.kind : "";
+    if (kind === "session")
+        return { key: "five_hour", label: "5h", utilization, resetsAt };
+    if (kind === "weekly_all")
+        return { key: "seven_day", label: "All", utilization, resetsAt };
+    if (kind === "weekly_scoped") {
+        const model = l.scope?.model?.display_name;
+        const surface = l.scope?.surface;
+        const name = (typeof model === "string" && model) || (typeof surface === "string" && surface) || "scoped";
+        const key = `weekly_${name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+        return { key, label: name, utilization, resetsAt };
+    }
+    return { key: kind || "unknown", label: kind ? kind.replace(/_/g, " ") : "?", utilization, resetsAt };
+}
+/** Defensive parse — unknown shapes degrade to fewer windows, never throw.
+ *  Prefers the current `limits[]` array (carries the per-model Fable window);
+ *  falls back to the legacy top-level `five_hour`/`seven_day` keys. */
+export function parseUsage(raw, capturedAt = new Date().toISOString()) {
+    const windows = [];
+    if (Array.isArray(raw?.limits) && raw.limits.length > 0) {
+        const seen = new Set();
+        for (const l of raw.limits) {
+            const w = windowFromLimit(l);
+            if (w && !seen.has(w.key)) {
+                seen.add(w.key);
+                windows.push(w);
+            }
+        }
+    }
+    if (windows.length === 0) {
+        for (const [key, label] of WINDOW_DEFS) {
+            const w = raw?.[key];
+            if (!w || typeof w !== "object")
+                continue;
+            const utilization = typeof w.utilization === "number" ? Math.round(w.utilization) : null;
+            const resetsAt = typeof w.resets_at === "string" ? w.resets_at : null;
+            if (utilization === null && resetsAt === null)
+                continue;
+            windows.push({ key, label, utilization, resetsAt });
+        }
+    }
+    let routines = null;
+    const r = raw?.routines;
+    if (r && typeof r.used === "number" && typeof r.limit === "number") {
+        routines = { used: r.used, limit: r.limit };
+    }
+    return { windows, routines, capturedAt };
+}
+function resetHint(iso) {
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return "";
+    return `  resets ${d.toLocaleString(undefined, { weekday: "short", hour: "2-digit", minute: "2-digit" })}`;
+}
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Default minimum gap (fraction of the window) before pace is called either
+ *  way — guards against noise around the on-track line. */
+export const PACE_MIN_GAP = 0.05;
+/** Window length for pace, derived from the key. The 5h window is deliberately
+ *  excluded (too short/bursty to pace meaningfully); only weekly windows pace. */
+function paceWindowMs(key) {
+    if (key === "five_hour")
+        return null;
+    if (key.startsWith("seven_day") || key.startsWith("weekly"))
+        return WEEK_MS;
+    return null;
+}
+/**
+ * "Ahead of pace" = more of the window's quota consumed than of its cycle
+ * elapsed. PURE and stale-safe: time is measured against the snapshot's
+ * `capturedAt` (its real measurement instant), never the wall clock, so a
+ * re-served stale snapshot is judged against when it was actually taken. This
+ * is purely informational — it is NEVER an input to a switch decision (the
+ * anti-rotation boundary this file is locked around).
+ *
+ * Returns null when it cannot be judged: no utilization/reset, the 5h window,
+ * within 24h of a reset (suppressed — early-cycle noise), or a captured time
+ * outside the window's own cycle.
+ */
+export function windowPace(w, capturedAtIso, minGap = PACE_MIN_GAP) {
+    if (w.utilization === null || w.resetsAt === null)
+        return null;
+    const durMs = paceWindowMs(w.key);
+    if (durMs === null)
+        return null;
+    const reset = Date.parse(w.resetsAt);
+    const captured = Date.parse(capturedAtIso);
+    if (Number.isNaN(reset) || Number.isNaN(captured))
+        return null;
+    const cycleStart = reset - durMs;
+    const elapsedMs = captured - cycleStart;
+    if (elapsedMs < DAY_MS)
+        return null; // 24h post-reset suppression
+    if (elapsedMs <= 0 || elapsedMs > durMs)
+        return null; // outside this cycle
+    const aheadBy = w.utilization / 100 - elapsedMs / durMs;
+    if (aheadBy > minGap)
+        return "ahead";
+    if (aheadBy < -minGap)
+        return "behind";
+    return "on-track";
+}
+/** Human-readable lines for `status`; empty when nothing is known. */
+export function formatSnapshot(s) {
+    const lines = [];
+    for (const w of s.windows) {
+        if (w.utilization === null)
+            continue;
+        // Surface only "ahead of pace" — the one informative signal; on-track /
+        // behind are the quiet default and add no line noise.
+        const pace = windowPace(w, s.capturedAt) === "ahead" ? "  · ahead of pace" : "";
+        lines.push(`  ${w.label}: ${String(w.utilization).padStart(3)}%${w.resetsAt ? resetHint(w.resetsAt) : ""}${pace}`);
+    }
+    if (s.routines)
+        lines.push(`  routines: ${s.routines.used}/${s.routines.limit}`);
+    return lines;
+}
+// ---------- headroom + auto-switch decision (pure) --------------------------
+/** Highest utilization across a snapshot's windows (0-100), or null when no
+ *  window reports a number. This is a profile's OWN headroom, never a ranking. */
+export function maxUtilization(s) {
+    const vals = s.windows.map((w) => w.utilization).filter((u) => typeof u === "number");
+    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.
+ */
+export function pickSwitchTarget(active, candidates, threshold, isEligible = () => true) {
+    const activeSnap = candidates.find((c) => c.name === active)?.snapshot;
+    const activeMax = activeSnap ? maxUtilization(activeSnap) : null;
+    if (activeMax === null || activeMax < threshold)
+        return null; // active still has headroom
+    let best = null;
+    for (const c of candidates) {
+        if (c.name === active)
+            continue;
+        if (!isEligible(c.name))
+            continue; // tag filter: only eligible accounts are switch targets
+        const m = maxUtilization(c.snapshot);
+        if (m === null || m >= threshold)
+            continue; // unknown or also maxed → not a target
+        if (!best || m < best.max)
+            best = { name: c.name, max: m };
+    }
+    return best?.name ?? null;
+}
+export const DEFAULT_THRESHOLDS = [75, 90];
+/**
+ * Edge-triggered threshold detection: a threshold fires once when utilization
+ * first reaches it, and the fired-set resets when the window rolls over
+ * (`resetsAt` changes). Returns the crossings for THIS poll plus the new state
+ * to persist. Pure — no I/O, no cross-account view.
+ */
+export function detectCrossings(snapshot, prev, thresholds = DEFAULT_THRESHOLDS) {
+    const state = {};
+    const crossings = [];
+    for (const w of snapshot.windows) {
+        const prevW = prev[w.key];
+        if (w.utilization === null) {
+            state[w.key] = prevW ?? { resetsAt: w.resetsAt, fired: [] };
+            continue;
+        }
+        // Same cycle → keep the fired set; rolled over → reset it.
+        const fired = prevW && prevW.resetsAt === w.resetsAt ? [...prevW.fired] : [];
+        for (const t of thresholds) {
+            if (w.utilization >= t && !fired.includes(t)) {
+                crossings.push({ window: w.key, threshold: t, utilization: w.utilization });
+                fired.push(t);
+            }
+        }
+        state[w.key] = { resetsAt: w.resetsAt, fired };
+    }
+    return { crossings, state };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@event4u/agent-switch",
+  "version": "1.0.0",
+  "description": "Switch between multiple Claude Code accounts on macOS, Linux, and Windows via isolated CLAUDE_CONFIG_DIR profiles",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/event4u-app/agent-switch.git"
+  },
+  "type": "module",
+  "bin": {
+    "agent-switch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "tsc -p tsconfig.test.json && cd dist-test && node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.49.0",
+    "@event4u/agent-switch-darwin": "1.0.0",
+    "@event4u/agent-switch-linux-x64": "1.0.0",
+    "@event4u/agent-switch-win32-x64": "1.0.0"
+  }
+}