@event4u/agent-switch 1.0.0

package/dist/keychain.js

@@ -0,0 +1,54 @@
+/**
+ * macOS Keychain access for Claude Code credentials.
+ *
+ * Contract knowledge adopted from claude-swap (session.py, macos_keychain.py),
+ * which references claude-code's own envUtils.ts / macOsKeychainHelpers.ts:
+ *
+ * - Default install: service "Claude Code-credentials", account = username.
+ * - With CLAUDE_CONFIG_DIR set, Claude Code hashes the *raw, unresolved* env
+ *   var value, NFC-normalized: service = "Claude Code-credentials-" +
+ *   sha256(NFC(dir)).hex[:8]. Hash exactly the string that gets exported.
+ * - Claude Code reads the keychain BEFORE the plaintext .credentials.json
+ *   fallback — a stale hashed entry shadows a fresh file seed, so delete the
+ *   hashed entry before seeding a profile.
+ * - This is an internal contract of Claude Code, not a public API. Everything
+ *   here is best-effort and must degrade gracefully if the naming changes.
+ */
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
+export const DEFAULT_SERVICE = "Claude Code-credentials";
+export function isMac() {
+    return process.platform === "darwin";
+}
+/** Keychain service name Claude Code derives for a CLAUDE_CONFIG_DIR. */
+export function serviceNameFor(configDir) {
+    const normalized = configDir.normalize("NFC");
+    const digest = crypto.createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 8);
+    return `${DEFAULT_SERVICE}-${digest}`;
+}
+function security(args) {
+    try {
+        return execFileSync("security", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch {
+        return null;
+    }
+}
+/** Read a generic password; null if missing/off-macOS/denied. */
+export function getPassword(service) {
+    if (!isMac())
+        return null;
+    const out = security(["find-generic-password", "-a", os.userInfo().username, "-w", "-s", service]);
+    return out === null ? null : out.replace(/\n$/, "");
+}
+/** Best-effort delete of a generic password entry. */
+export function deletePassword(service) {
+    if (!isMac())
+        return false;
+    return (security(["delete-generic-password", "-a", os.userInfo().username, "-s", service]) !== null);
+}
+/** The live credential of the default ~/.claude install (keychain, macOS). */
+export function readDefaultCredential() {
+    return getPassword(DEFAULT_SERVICE);
+}

package/dist/locks.js

@@ -0,0 +1,89 @@
+/**
+ * Cooperate with Claude Code's own advisory locks while reading its files.
+ *
+ * Protocol adopted from claude-swap's claude_locks.py (which documents
+ * claude-code's utils/auth.ts, utils/config.ts, utils/lockfile.ts):
+ *
+ * - Claude Code guards its OAuth token refresh with npm `proper-lockfile` on
+ *   the config home dir, and its ~/.claude.json writes on the config file.
+ * - The lock artifact is a DIRECTORY at "<target>.lock"; mkdir atomicity is
+ *   the mutex. A lock is stale when its mtime is older than 10s; live holders
+ *   touch every 5s. Claude Code retries a held credentials lock 5x with 1-2s
+ *   jittered sleeps, so briefly holding it is fully cooperative.
+ *
+ * Why we need it: `agent-switch import` snapshots the live default credential. A
+ * read landing inside Claude Code's refresh window (read → network → save,
+ * all under ~/.claude.lock) could capture a pre-rotation refresh token that
+ * is dead the moment the refresh saves. Holding the lock during the read
+ * closes that race.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const STALENESS_MS = 10_000;
+const TOUCH_INTERVAL_MS = 3_000; // faster than claude-code's 5s, for margin
+const DEFAULT_TIMEOUT_MS = 9_000;
+const RETRY_SLEEP_MS = 250;
+function lockDirFor(target) {
+    return path.join(path.dirname(target), path.basename(target) + ".lock");
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Acquire a proper-lockfile-compatible directory lock; run fn; release. */
+export async function withProperLock(target, fn, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const lockDir = lockDirFor(target);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            fs.mkdirSync(lockDir); // atomic acquire
+            break;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            // Held — take over if stale, else wait.
+            let stale = false;
+            try {
+                stale = Date.now() - fs.statSync(lockDir).mtimeMs > STALENESS_MS;
+            }
+            catch {
+                continue; // vanished between mkdir and stat — retry immediately
+            }
+            if (stale) {
+                try {
+                    fs.rmdirSync(lockDir);
+                }
+                catch {
+                    /* raced with another taker — loop */
+                }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`timed out waiting for Claude Code's lock at ${lockDir} — ` +
+                    `a running session may be mid-refresh; retry in a moment`);
+            }
+            await sleep(RETRY_SLEEP_MS);
+        }
+    }
+    const toucher = setInterval(() => {
+        try {
+            const now = new Date();
+            fs.utimesSync(lockDir, now, now);
+        }
+        catch {
+            /* released early / removed — nothing to do */
+        }
+    }, TOUCH_INTERVAL_MS);
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(toucher);
+        try {
+            fs.rmdirSync(lockDir);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}

package/dist/mappings.js

@@ -0,0 +1,132 @@
+/**
+ * Directory → (provider, profile) mappings for automatic per-repo account
+ * selection across all three CLI assistants.
+ *
+ * `agent-switch dir --provider <id>` resolves the current working directory to
+ * the nearest mapped ancestor for that provider, so each shell wrapper
+ * (`claude`/`codex`/`agy`) picks the right account per repository without
+ * switching. Precedence in the wrapper: directory mapping > active-for-provider
+ * > default.
+ *
+ * Keys are normalized (expanded, absolute, symlink-resolved; win32 drive-letter
+ * canonicalized) paths; values are `{ provider, name }`. A path may map a
+ * different profile per provider, so the stored value is keyed by provider:
+ * `{ "<path>": { claude: "<name>", codex: "<name>", ... } }`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ROOT, ensureRoot } from "./profiles.js";
+const MAPPINGS_FILE = path.join(ROOT, "mappings.json");
+/**
+ * Windows path canonicalization for mapping keys. NTFS is case-insensitive and
+ * drive letters appear in both cases (`C:\` vs `c:\`), so a mapping keyed under
+ * one case must match a lookup in the other. Uppercase the drive letter (the
+ * Windows convention). Pure — no FS access — so it is unit-tested cross-platform.
+ * No-op off win32.
+ */
+export function canonicalizeWin32(resolved, platform = process.platform) {
+    if (platform !== "win32")
+        return resolved;
+    return resolved.replace(/^([a-z]):/, (_m, d) => d.toUpperCase() + ":");
+}
+export function normalizePath(p) {
+    let resolved = path.resolve(p);
+    try {
+        resolved = fs.realpathSync(resolved);
+    }
+    catch {
+        /* keep unresolved if the path doesn't exist */
+    }
+    return canonicalizeWin32(resolved);
+}
+export function loadMappings() {
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(MAPPINGS_FILE, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const raw = data && typeof data.mappings === "object" ? data.mappings : {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        // v1: value was a bare profile name (Claude). v2: value is a provider map.
+        if (typeof value === "string")
+            out[key] = { claude: value };
+        else if (value && typeof value === "object")
+            out[key] = value;
+    }
+    return out;
+}
+function save(mappings) {
+    ensureRoot();
+    fs.writeFileSync(MAPPINGS_FILE, JSON.stringify({ schema: 2, mappings }, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
+export function setMapping(dir, providerId, name) {
+    const key = normalizePath(dir);
+    const mappings = loadMappings();
+    mappings[key] = { ...mappings[key], [providerId]: name };
+    save(mappings);
+    return key;
+}
+/** Remove a directory's mapping — one provider, or the whole entry. */
+export function removeMapping(dir, providerId) {
+    const key = normalizePath(dir);
+    const mappings = loadMappings();
+    if (!(key in mappings))
+        return false;
+    if (providerId) {
+        if (!(providerId in mappings[key]))
+            return false;
+        delete mappings[key][providerId];
+        if (Object.keys(mappings[key]).length === 0)
+            delete mappings[key];
+    }
+    else {
+        delete mappings[key];
+    }
+    save(mappings);
+    return true;
+}
+/** Nearest mapped ancestor of `dir` (inclusive) for a provider; null if none. */
+export function resolveMapping(dir, providerId) {
+    const mappings = loadMappings();
+    let current = normalizePath(dir);
+    for (;;) {
+        const entry = mappings[current];
+        if (entry && entry[providerId])
+            return { path: current, name: entry[providerId] };
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/** Drop mappings pointing at a removed (provider, name). Returns removed keys. */
+export function pruneMappings(providerId, name) {
+    const mappings = loadMappings();
+    const removed = [];
+    for (const [key, entry] of Object.entries(mappings)) {
+        if (entry[providerId] === name) {
+            delete entry[providerId];
+            if (Object.keys(entry).length === 0)
+                delete mappings[key];
+            removed.push(key);
+        }
+    }
+    if (removed.length > 0)
+        save(mappings);
+    return removed;
+}
+/** All mappings as flat rows for display. */
+export function mappingRows() {
+    const rows = [];
+    for (const [key, entry] of Object.entries(loadMappings())) {
+        for (const [provider, name] of Object.entries(entry)) {
+            rows.push({ path: key, provider: provider, name: name });
+        }
+    }
+    return rows.sort((a, b) => a.path.localeCompare(b.path) || a.provider.localeCompare(b.provider));
+}

package/dist/notifications.js

@@ -0,0 +1,70 @@
+/**
+ * Notification event log — a small persistent ring buffer shared by the daemon
+ * (auto-switch results, poll failures) and the GUI (its own limit-fetch
+ * failures). It is the single source of truth for the app's bell/flyout and the
+ * "internal system" fallback when desktop notifications are unavailable.
+ *
+ * Stored at `~/.agent-switch/notifications.json` as a plain JSON array, oldest
+ * first, capped at MAX_NOTIFICATIONS. Appends deduplicate an identical event
+ * within DEDUP_WINDOW_MS so a persistent failure polled every few minutes does
+ * not spam the list (and does not re-fire a desktop notification each cycle).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ROOT } from "./profiles.js";
+export const NOTIFICATIONS_FILE = path.join(ROOT, "notifications.json");
+export const MAX_NOTIFICATIONS = 25;
+/** An identical event within this window is dropped instead of re-appended. */
+export const DEDUP_WINDOW_MS = 30 * 60_000;
+export function readNotifications(file = NOTIFICATIONS_FILE) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(raw) ? raw : [];
+    }
+    catch {
+        return []; // missing / unreadable / malformed → empty, never throws
+    }
+}
+function writeNotifications(list, file) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(list.slice(-MAX_NOTIFICATIONS)));
+}
+/**
+ * Append an event (kept newest-last). Deduplicates a byte-identical
+ * kind+title+message against the most recent entry within DEDUP_WINDOW_MS.
+ * Returns the created notification, or `null` when it was deduplicated.
+ */
+export function appendNotification(event, now = Date.now(), file = NOTIFICATIONS_FILE) {
+    const list = readNotifications(file);
+    const last = list[list.length - 1];
+    if (last &&
+        last.kind === event.kind &&
+        last.title === event.title &&
+        last.message === event.message &&
+        now - last.ts < DEDUP_WINDOW_MS) {
+        return null;
+    }
+    const created = {
+        id: `${now}-${Math.random().toString(36).slice(2, 8)}`,
+        ts: now,
+        kind: event.kind,
+        title: event.title,
+        message: event.message,
+    };
+    writeNotifications([...list, created], file);
+    return created;
+}
+export function clearNotifications(file = NOTIFICATIONS_FILE) {
+    writeNotifications([], file);
+}
+/** Mark a stored notification as already-OS-notified (set by the daemon after it
+ *  fires a desktop notification, so the GUI does not re-notify). No-op if the id
+ *  is gone (trimmed out of the ring). */
+export function markOsNotified(id, file = NOTIFICATIONS_FILE) {
+    const list = readNotifications(file);
+    const n = list.find((x) => x.id === id);
+    if (!n)
+        return;
+    n.osNotified = true;
+    writeNotifications(list, file);
+}

package/dist/notify.js

@@ -0,0 +1,84 @@
+/**
+ * Per-session context-threshold detection + alert config (roadmap:
+ * road-to-agent-switch-session-telemetry, Phase 3). Own-session only: a
+ * crossing names a project dir + percentage + suggested action, NEVER another
+ * profile (council #5 — furthest from the rotation line).
+ *
+ * Delivery is via the shared notification log (`src/notifications.ts` →
+ * `appendNotification`): the daemon records the coalesced crossing there and
+ * the GUI bell/flyout reads it + fires a best-effort desktop notification (the
+ * app's single notifier). This module only DETECTS + COALESCES; it does not
+ * fire an OS toast itself.
+ *
+ * Config lives in `<ROOT>/telemetry-config.json` (its own file rather than
+ * state.json, whose readState rebuilds from known fields and would drop new
+ * ones): { notify: boolean (default OFF), contextThresholds: number[] }.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DEFAULT_CONTEXT_THRESHOLDS = [80, 95];
+export function configFile(root) {
+    return path.join(root, "telemetry-config.json");
+}
+export function readTelemetryConfig(root) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(configFile(root), "utf8"));
+        const thresholds = Array.isArray(raw?.contextThresholds) && raw.contextThresholds.every((n) => typeof n === "number")
+            ? [...raw.contextThresholds].sort((a, b) => a - b)
+            : DEFAULT_CONTEXT_THRESHOLDS;
+        return { notify: raw?.notify === true, contextThresholds: thresholds };
+    }
+    catch {
+        return { notify: false, contextThresholds: DEFAULT_CONTEXT_THRESHOLDS };
+    }
+}
+export function writeTelemetryConfig(root, cfg) {
+    fs.mkdirSync(root, { recursive: true });
+    fs.writeFileSync(configFile(root), JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * Edge-triggered per-session context crossings. A threshold fires once when a
+ * session first reaches it. Re-arm (clear the fired set) happens when:
+ *   - the session id is in `compacted` (a real PreCompact/PostCompact/
+ *     SessionStart(compact) event was seen — the ground-truth signal), OR
+ *   - pct fell below the lowest threshold (conservative fallback when hooks
+ *     are not installed).
+ * Pure — no I/O, own-session only (caller passes one profile's live sessions).
+ */
+export function detectContextCrossings(samples, prev, thresholds = DEFAULT_CONTEXT_THRESHOLDS, compacted = new Set()) {
+    const sorted = [...thresholds].sort((a, b) => a - b);
+    const minT = sorted[0] ?? Infinity;
+    const state = {};
+    const crossings = [];
+    for (const s of samples) {
+        if (s.pct === null)
+            continue; // window unknown → cannot threshold
+        const prevS = prev[s.sessionId];
+        let fired = prevS ? [...prevS.fired] : [];
+        // re-arm on real compaction or a drop below the lowest threshold
+        if (compacted.has(s.sessionId) || s.pct < minT)
+            fired = [];
+        for (const t of sorted) {
+            if (s.pct >= t && !fired.includes(t)) {
+                crossings.push({ sessionId: s.sessionId, where: s.where, threshold: t, pct: s.pct });
+                fired.push(t);
+            }
+        }
+        state[s.sessionId] = { fired, lastPct: s.pct };
+    }
+    return { crossings, state };
+}
+/** Coalesce same-cycle crossings into ONE notification body (council #11 — no
+ *  toast storm). Reports the count + the single worst session. Project +
+ *  percentage only; never a profile name. */
+export function coalesce(crossings) {
+    if (crossings.length === 0)
+        return null;
+    const worst = crossings.reduce((a, b) => (b.pct > a.pct ? b : a));
+    const n = new Set(crossings.map((c) => c.sessionId)).size;
+    const title = n === 1 ? `Context ${worst.threshold}%+` : `${n} sessions high on context`;
+    const body = n === 1
+        ? `${worst.where} at ${worst.pct}% context — consider /compact`
+        : `worst: ${worst.where} at ${worst.pct}% — consider /compact`;
+    return { title, body };
+}

package/dist/os-notify.js

@@ -0,0 +1,66 @@
+/**
+ * Best-effort OS desktop notifications for the background daemon, so an
+ * auto-switch is visible even when the GUI is closed. Per-platform native
+ * command, no external dependency:
+ *   - macOS   → `osascript -e 'display notification …'`
+ *   - Linux   → `notify-send <title> <body>`
+ *   - Windows → PowerShell balloon tip via System.Windows.Forms.NotifyIcon
+ *
+ * `buildOsNotifyCommand` is pure (command construction only) so it is unit
+ * testable; `osNotify` wraps it with a fire-and-forget spawn that never throws.
+ */
+import { spawnSync } from "node:child_process";
+/** AppleScript string literal escaping: backslash and double-quote only. */
+function escAppleScript(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** PowerShell single-quoted string literal escaping: double the single quote. */
+function escPowerShellSingle(s) {
+    return s.replace(/'/g, "''");
+}
+/**
+ * Build the native notify command for a platform, or null when unsupported.
+ * `platform` matches `process.platform` values (`darwin` / `linux` / `win32`).
+ */
+export function buildOsNotifyCommand(platform, title, body) {
+    if (platform === "darwin") {
+        const script = `display notification "${escAppleScript(body)}" with title "${escAppleScript(title)}"`;
+        return { program: "osascript", args: ["-e", script] };
+    }
+    if (platform === "linux") {
+        // notify-send treats the first arg as summary, the second as body.
+        return { program: "notify-send", args: [title, body] };
+    }
+    if (platform === "win32") {
+        const t = escPowerShellSingle(title);
+        const b = escPowerShellSingle(body);
+        const script = [
+            "Add-Type -AssemblyName System.Windows.Forms;",
+            "$n = New-Object System.Windows.Forms.NotifyIcon;",
+            "$n.Icon = [System.Drawing.SystemIcons]::Information;",
+            "$n.Visible = $true;",
+            `$n.ShowBalloonTip(5000, '${t}', '${b}', [System.Windows.Forms.ToolTipIcon]::Info);`,
+            "Start-Sleep -Milliseconds 6000; $n.Dispose();",
+        ].join(" ");
+        return { program: "powershell", args: ["-NoProfile", "-Command", script] };
+    }
+    return null;
+}
+/**
+ * Fire a desktop notification via the OS. Returns true when the command was
+ * dispatched successfully, false on an unsupported platform or any failure
+ * (the caller treats a false as "not shown" and leaves the in-app log as the
+ * record). Never throws.
+ */
+export function osNotify(title, body, platform = process.platform) {
+    const cmd = buildOsNotifyCommand(platform, title, body);
+    if (!cmd)
+        return false;
+    try {
+        const r = spawnSync(cmd.program, cmd.args, { stdio: "ignore", timeout: 10_000 });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}