@phnx-labs/agents-cli 1.14.5 → 1.14.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.14.6
+
+**Fix: OAuth token refresh now persists to Keychain**
+
+- Fixed bug where refreshed Claude OAuth tokens were used but never saved back to macOS Keychain
+- Previously, agents-cli would refresh expired tokens on each run but discard them, eventually exhausting the refresh token
+- Now refreshed `accessToken`, `refreshToken`, and `expiresAt` are written back to Keychain after successful refresh
+- Accounts will stay healthy across runs without requiring re-login
+
 ## 1.14.5
 
 **Browser: custom binary and Electron app support**

package/README.md

@@ -47,6 +47,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [Sessions across agents](#sessions-across-agents)
 - [Run open models through Claude Code](#run-open-models-through-claude-code)
 - [Teams](#teams)
+- [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
 - [PTY](#pty)
@@ -242,6 +243,85 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ---
 
+## Browser
+
+Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
+
+```bash
+# Create an isolated profile for automation
+agents browser profiles create work --browser chrome
+
+# Start a task, navigate, interact
+agents browser start login-flow --profile work
+agents browser navigate login-flow https://app.example.com
+agents browser refs login-flow              # Get interactive element refs
+agents browser click login-flow <tab> 42    # Click element ref 42
+agents browser type login-flow <tab> 15 "hello"
+agents browser screenshot login-flow        # Smart resizing, token-efficient
+```
+
+### Why this works where Playwright fails
+
+Playwright and Puppeteer spin up fresh browser instances with automation flags. Sites like LinkedIn, Google, and most finance apps detect and block them immediately.
+
+`agents browser` launches your existing residential Chrome (or Brave, Edge, Chromium) on your machine via CDP. Same browser fingerprint, same IP, same everything. Sites can't detect automation because you're using the same browser you'd use manually.
+
+### Token-efficient automation
+
+The CLI handles the mechanical work so agents don't burn tokens on low-level browser commands. Screenshots are automatically resized without excessive compression — agents process smaller images while keeping the detail they need to make decisions.
+
+### Profile isolation
+
+Multiple agents can run browser tasks simultaneously without stepping on each other. Each profile gets its own user data directory, cookies, and state. One agent logs into your work Slack, another into your personal email — no conflicts, no shared state.
+
+```bash
+agents browser profiles create work-slack --browser chrome
+agents browser profiles create personal-gmail --browser chrome
+# Two agents, two profiles, no interference
+```
+
+### Safe credential access
+
+Attach a [secrets bundle](#secrets) to a profile. The agent can log in without credentials in plaintext, and every secret access is recorded in the session log.
+
+```bash
+agents browser profiles create bank --browser chrome --secrets bank-creds
+```
+
+### Electron apps
+
+Control Electron apps (Slack, Discord, VS Code, your own app) with custom binaries:
+
+```bash
+agents browser profiles create rush \
+  --browser custom \
+  --binary "/Applications/Rush.app/Contents/MacOS/Rush" \
+  --electron
+```
+
+### Remote browsers
+
+Connect to browsers running anywhere — local, SSH tunnels, or cloud services:
+
+```bash
+# Local CDP (discovers WebSocket URL automatically)
+agents browser profiles create local-debug \
+  --browser chrome \
+  --endpoint "http://localhost:9222"
+
+# SSH tunnel to a remote machine
+agents browser profiles create staging \
+  --browser chrome \
+  --endpoint "ssh://deploy@staging.example.com?port=9222"
+
+# Cloud browser services (BrowserBase, Steel, etc.)
+agents browser profiles create cloud \
+  --browser chrome \
+  --endpoint "wss://connect.browserbase.com?apiKey=..."
+```
+
+---
+
 ## Secrets
 
 ```bash

package/dist/commands/secrets.js

@@ -285,10 +285,19 @@ Examples:
 
   # Delete the whole bundle and purge every keychain item it owned
   agents secrets delete prod
+
+  # Generate a random password (32 chars, all character classes)
+  agents secrets generate
+
+  # Generate a 16-char password, or a PIN, or hex
+  agents secrets generate 16
+  agents secrets generate 8 --pin
+  agents secrets generate 32 --hex
 `);
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
+        { title: 'Utilities', names: ['generate'] },
     ]);
     cmd
         .command('list')
@@ -702,4 +711,78 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('generate [length]')
+        .description('Generate a random password')
+        .option('-U, --uppercase', 'Include A-Z (default: on)')
+        .option('-l, --lowercase', 'Include a-z (default: on)')
+        .option('-d, --digits', 'Include 0-9 (default: on)')
+        .option('-s, --symbols', 'Include symbols (default: on)')
+        .option('--no-uppercase', 'Exclude A-Z')
+        .option('--no-lowercase', 'Exclude a-z')
+        .option('--no-digits', 'Exclude 0-9')
+        .option('--no-symbols', 'Exclude symbols')
+        .option('--strong', 'Include all character classes')
+        .option('--pin', 'Digits only (shortcut for -d --no-uppercase --no-lowercase --no-symbols)')
+        .option('--hex', 'Hex characters only (0-9, a-f)')
+        .option('-c, --copy', 'Copy to clipboard (does not print)')
+        .action(async (lengthArg, opts) => {
+        const length = lengthArg ? parseInt(lengthArg, 10) : 32;
+        if (isNaN(length) || length < 1 || length > 1024) {
+            console.error(chalk.red('Length must be a number between 1 and 1024.'));
+            process.exit(1);
+        }
+        const UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+        const LOWER = 'abcdefghijklmnopqrstuvwxyz';
+        const DIGITS = '0123456789';
+        const SYMBOLS = '!@#$%^&*()-_=+[]{}|;:,.<>?';
+        const HEX_LOWER = '0123456789abcdef';
+        let charClasses = [];
+        if (opts.hex) {
+            charClasses = [HEX_LOWER];
+        }
+        else if (opts.pin) {
+            charClasses = [DIGITS];
+        }
+        else {
+            const useUpper = opts.strong || opts.uppercase !== false;
+            const useLower = opts.strong || opts.lowercase !== false;
+            const useDigits = opts.strong || opts.digits !== false;
+            const useSymbols = opts.strong || opts.symbols !== false;
+            if (useUpper)
+                charClasses.push(UPPER);
+            if (useLower)
+                charClasses.push(LOWER);
+            if (useDigits)
+                charClasses.push(DIGITS);
+            if (useSymbols)
+                charClasses.push(SYMBOLS);
+        }
+        if (charClasses.length === 0) {
+            console.error(chalk.red('At least one character class must be enabled.'));
+            process.exit(1);
+        }
+        const randomBytes = crypto.getRandomValues(new Uint32Array(length * 2));
+        let password = '';
+        for (let i = 0; i < length; i++) {
+            const classIndex = randomBytes[i * 2] % charClasses.length;
+            const charClass = charClasses[classIndex];
+            const charIndex = randomBytes[i * 2 + 1] % charClass.length;
+            password += charClass[charIndex];
+        }
+        if (opts.copy) {
+            const { spawn } = await import('child_process');
+            const proc = spawn('pbcopy', [], { stdio: ['pipe', 'inherit', 'inherit'] });
+            proc.stdin.write(password);
+            proc.stdin.end();
+            await new Promise((resolve, reject) => {
+                proc.on('close', (code) => code === 0 ? resolve() : reject(new Error('pbcopy failed')));
+                proc.on('error', reject);
+            });
+            console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+        }
+        else {
+            console.log(password);
+        }
+    });
 }

package/dist/lib/browser/service.js

@@ -8,6 +8,7 @@ import { connectSSH } from './drivers/ssh.js';
 import { generateTaskId, isValidTaskId, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, typeText, pressKey, focusNode } from './input.js';
+import { emit } from '../events.js';
 export class BrowserService {
     connections = new Map();
     async start(profileName, taskId) {
@@ -39,6 +40,7 @@ export class BrowserService {
         };
         conn.tasks.set(finalTaskId, task);
         await this.saveTaskState(profileName, conn.tasks);
+        emit('browser.launch', { profile: profileName, task: finalTaskId, pid: conn.pid });
         return { task: finalTaskId, windowTargetId };
     }
     async stop(taskId) {
@@ -62,6 +64,7 @@ export class BrowserService {
                 }
                 conn.tasks.delete(taskId);
                 await this.saveTaskState(profileName, conn.tasks);
+                emit('browser.close', { profile: profileName, task: taskId });
                 return { ok: true, profile: profileName };
             }
         }
@@ -311,6 +314,34 @@ export class BrowserService {
                 sessionCache: new Map(),
             };
         }
+        if (url.protocol === 'wss:' || url.protocol === 'ws:') {
+            const cdp = new CDPClient();
+            await cdp.connect(endpoint);
+            await this.enableDomains(cdp);
+            return {
+                cdp,
+                port: 0,
+                pid: 0,
+                electron: profile.electron,
+                tasks: this.loadTaskState(profile.name),
+                sessionCache: new Map(),
+            };
+        }
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            const port = parseInt(url.port || (url.protocol === 'https:' ? '443' : '80'), 10);
+            const wsUrl = await discoverBrowserWsUrl(port, url.hostname);
+            const cdp = new CDPClient();
+            await cdp.connect(wsUrl);
+            await this.enableDomains(cdp);
+            return {
+                cdp,
+                port,
+                pid: 0,
+                electron: profile.electron,
+                tasks: this.loadTaskState(profile.name),
+                sessionCache: new Map(),
+            };
+        }
         return null;
     }
     async enableDomains(cdp) {

package/dist/lib/events.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Centralized event logging for agents-cli.
+ *
+ * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * with automatic daily rotation and rich metadata for debugging/auditing.
+ */
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.error' | 'resource.sync' | 'error' | 'warn' | 'info';
+export interface EventMeta {
+    ts: string;
+    tz: string;
+    tzName: string;
+    hostname: string;
+    platform: NodeJS.Platform;
+    arch: string;
+    pid: number;
+    event: EventType;
+}
+export interface EventPayload {
+    agent?: string;
+    version?: string;
+    cwd?: string;
+    durationMs?: number;
+    error?: string;
+    [key: string]: unknown;
+}
+export type EventRecord = EventMeta & EventPayload;
+/**
+ * Emit a structured event to the daily log file.
+ *
+ * @param event - The event type
+ * @param payload - Event-specific data (agent, version, cwd, etc.)
+ */
+export declare function emit(event: EventType, payload?: EventPayload): void;
+/**
+ * Convenience wrapper for timed operations.
+ * Returns a function to call when the operation completes.
+ *
+ * @example
+ * const done = emitStart('agent.run.start', { agent: 'claude' });
+ * // ... do work ...
+ * done({ exitCode: 0 }); // emits agent.run.end with durationMs
+ */
+export declare function emitStart(startEvent: EventType, payload?: EventPayload): (endPayload?: EventPayload) => void;
+/**
+ * Remove log files older than the retention period.
+ * Called lazily on emit or explicitly via CLI.
+ *
+ * @param retentionDays - Number of days to keep (default 30)
+ * @returns Number of files removed
+ */
+export declare function rotate(retentionDays?: number): number;
+export declare function maybeRotate(): void;
+/**
+ * Read events from log files within a date range.
+ *
+ * @param options - Query options
+ * @returns Array of event records
+ */
+export declare function query(options: {
+    startDate?: Date;
+    endDate?: Date;
+    eventTypes?: EventType[];
+    agent?: string;
+    limit?: number;
+}): EventRecord[];
+export declare const LOGS_PATH: string;

package/dist/lib/events.js

@@ -0,0 +1,183 @@
+/**
+ * Centralized event logging for agents-cli.
+ *
+ * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * with automatic daily rotation and rich metadata for debugging/auditing.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const USER_AGENTS_DIR = path.join(os.homedir(), '.agents');
+const LOGS_DIR = path.join(USER_AGENTS_DIR, 'logs');
+/** Default retention period in days. */
+const DEFAULT_RETENTION_DAYS = 30;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function getTimezoneOffset() {
+    const offset = new Date().getTimezoneOffset();
+    const sign = offset <= 0 ? '+' : '-';
+    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+    const mins = String(Math.abs(offset) % 60).padStart(2, '0');
+    return `${sign}${hours}:${mins}`;
+}
+function getTimezoneName() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        return 'Unknown';
+    }
+}
+function getLogFilePath(date = new Date()) {
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, '0');
+    const dd = String(date.getDate()).padStart(2, '0');
+    return path.join(LOGS_DIR, `events-${yyyy}-${mm}-${dd}.jsonl`);
+}
+function ensureLogsDir() {
+    if (!fs.existsSync(LOGS_DIR)) {
+        fs.mkdirSync(LOGS_DIR, { recursive: true });
+    }
+}
+// ─── Core API ─────────────────────────────────────────────────────────────────
+/**
+ * Emit a structured event to the daily log file.
+ *
+ * @param event - The event type
+ * @param payload - Event-specific data (agent, version, cwd, etc.)
+ */
+export function emit(event, payload = {}) {
+    try {
+        ensureLogsDir();
+        const record = {
+            ts: new Date().toISOString(),
+            tz: getTimezoneOffset(),
+            tzName: getTimezoneName(),
+            hostname: os.hostname(),
+            platform: os.platform(),
+            arch: os.arch(),
+            pid: process.pid,
+            event,
+            ...payload,
+        };
+        const line = JSON.stringify(record) + '\n';
+        fs.appendFileSync(getLogFilePath(), line);
+    }
+    catch {
+        // Silent failure - logging should never break the CLI
+    }
+}
+/**
+ * Convenience wrapper for timed operations.
+ * Returns a function to call when the operation completes.
+ *
+ * @example
+ * const done = emitStart('agent.run.start', { agent: 'claude' });
+ * // ... do work ...
+ * done({ exitCode: 0 }); // emits agent.run.end with durationMs
+ */
+export function emitStart(startEvent, payload = {}) {
+    const startTime = Date.now();
+    emit(startEvent, payload);
+    const endEvent = startEvent.replace('.start', '.end');
+    return (endPayload = {}) => {
+        emit(endEvent, {
+            ...payload,
+            ...endPayload,
+            durationMs: Date.now() - startTime,
+        });
+    };
+}
+// ─── Rotation ─────────────────────────────────────────────────────────────────
+/**
+ * Remove log files older than the retention period.
+ * Called lazily on emit or explicitly via CLI.
+ *
+ * @param retentionDays - Number of days to keep (default 30)
+ * @returns Number of files removed
+ */
+export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
+    try {
+        if (!fs.existsSync(LOGS_DIR))
+            return 0;
+        const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+        const files = fs.readdirSync(LOGS_DIR).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        let removed = 0;
+        for (const file of files) {
+            const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
+            if (!match)
+                continue;
+            const [, yyyy, mm, dd] = match;
+            const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
+            if (fileDate.getTime() < cutoff) {
+                fs.unlinkSync(path.join(LOGS_DIR, file));
+                removed++;
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Lazy rotation - runs at most once per day per process.
+ */
+let lastRotationCheck = 0;
+export function maybeRotate() {
+    const now = Date.now();
+    const oneDayMs = 24 * 60 * 60 * 1000;
+    if (now - lastRotationCheck > oneDayMs) {
+        lastRotationCheck = now;
+        rotate();
+    }
+}
+// ─── Query ────────────────────────────────────────────────────────────────────
+/**
+ * Read events from log files within a date range.
+ *
+ * @param options - Query options
+ * @returns Array of event records
+ */
+export function query(options) {
+    const { startDate, endDate = new Date(), eventTypes, agent, limit } = options;
+    const results = [];
+    if (!fs.existsSync(LOGS_DIR))
+        return results;
+    const files = fs.readdirSync(LOGS_DIR)
+        .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
+        .sort()
+        .reverse();
+    for (const file of files) {
+        const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
+        if (!match)
+            continue;
+        const [, yyyy, mm, dd] = match;
+        const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
+        if (startDate && fileDate < startDate)
+            continue;
+        if (endDate && fileDate > endDate)
+            continue;
+        const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        for (const line of lines.reverse()) {
+            try {
+                const record = JSON.parse(line);
+                if (eventTypes && !eventTypes.includes(record.event))
+                    continue;
+                if (agent && record.agent !== agent)
+                    continue;
+                results.push(record);
+                if (limit && results.length >= limit) {
+                    return results;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return results;
+}
+// ─── Exports ──────────────────────────────────────────────────────────────────
+export const LOGS_PATH = LOGS_DIR;

package/dist/lib/exec.js

@@ -10,6 +10,7 @@ import * as path from 'path';
 import { parseTimeout } from './routines.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+import { emitStart, maybeRotate } from './events.js';
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -201,6 +202,11 @@ export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
     const interactive = options.interactive === true || options.prompt === undefined;
+    // For Codex, 'exec' is the headless subcommand -- drop it for interactive mode
+    // so we run 'codex' (TUI) instead of 'codex exec' (one-shot)
+    if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
+        cmd.splice(1, 1);
+    }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98)
     if (options.version && cmd.length > 0) {
         cmd[0] = `${cmd[0]}@${options.version}`;
@@ -298,6 +304,15 @@ async function spawnAgent(options) {
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
     const interactive = options.interactive === true || options.prompt === undefined;
+    maybeRotate();
+    const done = emitStart('agent.run.start', {
+        agent: options.agent,
+        version: options.version,
+        cwd: options.cwd || process.cwd(),
+        mode: options.mode,
+        model: options.model,
+        interactive,
+    });
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
         // rendering, raw-mode keystrokes, colored output). Headless mode pipes
@@ -338,11 +353,13 @@ async function spawnAgent(options) {
         child.on('error', (err) => {
             if (timer)
                 clearTimeout(timer);
+            done({ error: err.message, exitCode: -1 });
             reject(err);
         });
         child.on('close', (code) => {
             if (timer)
                 clearTimeout(timer);
+            done({ exitCode: code ?? 0 });
             resolve({ exitCode: code ?? 0, stderr: stderrBuffer });
         });
     });

package/dist/lib/runner.js

@@ -14,6 +14,7 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './rout
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+import { emitStart, maybeRotate } from './events.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -107,6 +108,13 @@ function generateRunId() {
 }
 /** Execute a job synchronously (waits for completion or timeout before resolving). */
 export async function executeJob(config) {
+    maybeRotate();
+    const done = emitStart('agent.run.start', {
+        agent: config.agent,
+        version: config.version,
+        jobName: config.name,
+        mode: config.mode,
+    });
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
     const useSandbox = config.sandbox !== false;
@@ -160,6 +168,7 @@ export async function executeJob(config) {
             meta.status = 'timeout';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
+            done({ status: 'timeout', runId });
             const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
             resolve({ meta, reportPath });
         }, timeoutMs);
@@ -176,6 +185,7 @@ export async function executeJob(config) {
             meta.status = code === 0 ? 'completed' : 'failed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
+            done({ status: meta.status, exitCode: code, runId });
             const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
             resolve({ meta, reportPath });
         });
@@ -191,6 +201,7 @@ export async function executeJob(config) {
             meta.status = 'failed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
+            done({ status: 'failed', error: err.message, runId });
             resolve({ meta, reportPath: null });
         });
         child.unref();

package/dist/lib/secrets/bundles.js

@@ -16,6 +16,7 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { emit } from '../events.js';
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
     'api-key',
@@ -148,10 +149,15 @@ export function writeBundle(bundle) {
     };
     const json = JSON.stringify(payload);
     setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
+    emit('secrets.set', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
     validateBundleName(name);
-    return deleteKeychainToken(bundleMetaItem(name));
+    const deleted = deleteKeychainToken(bundleMetaItem(name));
+    if (deleted) {
+        emit('secrets.delete', { bundle: name });
+    }
+    return deleted;
 }
 export function listBundles() {
     let services;

package/dist/lib/skills.js

@@ -13,6 +13,7 @@ import * as yaml from 'yaml';
 import { SKILLS_CAPABLE_AGENTS, ensureSkillsDir } from './agents.js';
 import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { emit } from './events.js';
 const HOME = os.homedir();
 /** User-scoped skills dir (~/.agents/skills/). Used for installs. */
 export function getSkillsDir() {
@@ -255,6 +256,7 @@ export function installSkill(sourcePath, skillName, agents, method = 'symlink')
             };
         }
     }
+    emit('skill.install', { skill: skillName, agents });
     return { success: true };
 }
 /**
@@ -555,6 +557,7 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
             // Best-effort; failure here shouldn't unwind the install
         }
     }
+    emit('skill.install', { skill: skillName, agent, version });
     return { success: true };
 }
 /**
@@ -616,6 +619,7 @@ export function uninstallSkill(skillName) {
     catch {
         // Ignore removal errors
     }
+    emit('skill.remove', { skill: skillName });
     return { success: true };
 }
 export function listInstalledSkills() {

package/dist/lib/usage.js

@@ -211,7 +211,7 @@ async function getClaudeUsageInfo(options) {
         if (!isClaudeUsageOrgMatch(requestedOrgId, liveOrgId)) {
             return { snapshot: null, error: null };
         }
-        const accessToken = await getClaudeAccessToken(oauth);
+        const accessToken = await getClaudeAccessToken(oauth, options?.home);
         if (!accessToken) {
             return { snapshot: null, error: null };
         }
@@ -343,9 +343,14 @@ function normalizeClaudeWindow(window, key, label, shortLabel) {
         windowMinutes: inferWindowMinutes(key),
     };
 }
+let warnedNonDarwin = false;
 /** Load Claude OAuth credentials from the macOS Keychain. */
 export async function loadClaudeOauth(home) {
     if (process.platform !== 'darwin') {
+        if (!warnedNonDarwin && process.stderr.isTTY) {
+            process.stderr.write('[agents] Usage tracking requires macOS Keychain. Skipped on this platform.\n');
+            warnedNonDarwin = true;
+        }
         return null;
     }
     try {
@@ -374,6 +379,74 @@ export async function loadClaudeOauth(home) {
         return null;
     }
 }
+/**
+ * Save Claude OAuth credentials to the macOS Keychain.
+ * Reads the existing payload, merges the new OAuth fields, and writes back.
+ */
+async function saveClaudeOauth(home, credentials) {
+    if (process.platform !== 'darwin') {
+        return false;
+    }
+    try {
+        const account = os.userInfo().username;
+        const service = getClaudeKeychainService(home);
+        // Read existing payload to preserve other fields
+        let existingPayload = {};
+        try {
+            const { stdout } = await execFileAsync('security', [
+                'find-generic-password',
+                '-a',
+                account,
+                '-s',
+                service,
+                '-w',
+            ]);
+            existingPayload = JSON.parse(stdout.trim());
+        }
+        catch {
+            // No existing entry, start fresh
+        }
+        // Merge new credentials into existing payload
+        const newPayload = {
+            ...existingPayload,
+            claudeAiOauth: {
+                ...existingPayload.claudeAiOauth,
+                accessToken: credentials.accessToken,
+                refreshToken: credentials.refreshToken,
+                expiresAt: credentials.expiresAt,
+                scopes: credentials.scopes ?? existingPayload.claudeAiOauth?.scopes,
+            },
+        };
+        const payloadJson = JSON.stringify(newPayload);
+        // Delete existing entry first (security add-generic-password -U can fail)
+        try {
+            await execFileAsync('security', [
+                'delete-generic-password',
+                '-a',
+                account,
+                '-s',
+                service,
+            ]);
+        }
+        catch {
+            // Entry might not exist, ignore
+        }
+        // Add updated entry
+        await execFileAsync('security', [
+            'add-generic-password',
+            '-a',
+            account,
+            '-s',
+            service,
+            '-w',
+            payloadJson,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Derive the Keychain service name for a Claude home directory.
  * Managed (non-default) homes get a hash suffix for isolation.
@@ -493,8 +566,8 @@ function isCachedUsageWindowFresh(window, capturedAt, now) {
     }
     return true;
 }
-/** Obtain a valid access token, refreshing if expired. */
-async function getClaudeAccessToken(oauth) {
+/** Obtain a valid access token, refreshing if expired. Saves refreshed tokens to Keychain. */
+async function getClaudeAccessToken(oauth, home) {
     const accessToken = oauth.accessToken?.trim();
     if (!accessToken) {
         return null;
@@ -507,7 +580,12 @@ async function getClaudeAccessToken(oauth) {
         return null;
     }
     const refreshed = await refreshClaudeToken(oauth);
-    return refreshed?.accessToken?.trim() || null;
+    if (!refreshed?.accessToken) {
+        return null;
+    }
+    // Persist refreshed credentials to Keychain so they survive across runs
+    await saveClaudeOauth(home, refreshed);
+    return refreshed.accessToken.trim();
 }
 /** Refresh an expired Claude OAuth access token using the refresh token. */
 async function refreshClaudeToken(oauth) {
@@ -547,7 +625,7 @@ export async function isClaudeAuthValid(home) {
     const oauth = await loadClaudeOauth(home);
     if (!oauth)
         return false;
-    const token = await getClaudeAccessToken(oauth);
+    const token = await getClaudeAccessToken(oauth, home);
     return token !== null;
 }
 /** Build a User-Agent string for Claude API requests. */

package/dist/lib/versions.js

@@ -37,6 +37,7 @@ import { discoverPlugins, syncPluginToVersion, isPluginSynced, pluginSupportsAge
 import { composeRulesFromState } from './rules/compose.js';
 import { loadSyncManifest, saveSyncManifest, buildManifest, isSyncStale } from './sync-manifest.js';
 import { PLUGINS_CAPABLE_AGENTS } from './agents.js';
+import { emit } from './events.js';
 import { safeJoin } from './paths.js';
 import { installCommandSkillToVersion, listCommandSkillsInVersion, shouldInstallCommandAsSkill } from './command-skills.js';
 /** Promisified exec for running shell commands. */
@@ -909,6 +910,7 @@ export function setGlobalDefault(agent, version) {
     }
     else {
         meta.agents[agent] = version;
+        emit('version.switch', { agent, version });
     }
     writeMeta(meta);
 }
@@ -989,6 +991,7 @@ export async function installVersion(agent, version, onProgress) {
                 /* non-fatal; the install itself succeeded */
             }
         }
+        emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };
     }
     catch (err) {
@@ -997,6 +1000,7 @@ export async function installVersion(agent, version, onProgress) {
         if (fs.existsSync(versionDir)) {
             removeInstallArtifacts(versionDir);
         }
+        emit('version.install', { agent, version, error: err.message });
         return { success: false, installedVersion: version, error: err.message };
     }
 }
@@ -1086,6 +1090,7 @@ export function removeVersion(agent, version) {
             // Ignore if already gone
         }
     }
+    emit('version.remove', { agent, version });
     return true;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.14.5",
+  "version": "1.14.7",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",