@phnx-labs/agents-cli 1.14.4 → 1.14.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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**
+
+- Added `binary` field to browser profiles for specifying custom executable paths (e.g., Electron apps like Rush)
+- Added `electron` field to browser profiles — when true, uses existing windows instead of creating new ones (Electron doesn't support `Target.createTarget`)
+- New `custom` browser type that requires a binary path
+- Works with both local and SSH-based browser connections
+- Example profile for Rush: `agents browser profiles edit rush --browser custom --binary "/Applications/Rush.app/Contents/MacOS/Rush" --electron`
+
 ## Unreleased
 
 **System repo moved to `~/.agents-system`; `~/.agents` is now free for user-owned repos**

package/dist/lib/browser/chrome.d.ts

@@ -1,12 +1,12 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
-export declare function findBrowserPath(browserType: BrowserType): string;
+export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
 export interface LaunchResult {
     pid: number;
     port: number;
     wsUrl: string;
 }
-export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string): Promise<LaunchResult>;
+export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string): Promise<LaunchResult>;
 export declare function attachToChrome(port: number): Promise<string>;
 export declare function killChrome(pid: number): void;
 export declare function getRunningChromeInfo(profileName: string): {

package/dist/lib/browser/chrome.js

@@ -15,6 +15,7 @@ const BROWSER_PATHS = {
         chromium: ['/Applications/Chromium.app/Contents/MacOS/Chromium'],
         brave: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
         edge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        custom: [],
     },
     linux: {
         chrome: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable'],
@@ -22,6 +23,7 @@ const BROWSER_PATHS = {
         chromium: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
         brave: ['/usr/bin/brave-browser', '/usr/bin/brave'],
         edge: ['/usr/bin/microsoft-edge'],
+        custom: [],
     },
     win32: {
         chrome: [
@@ -36,9 +38,19 @@ const BROWSER_PATHS = {
         edge: [
             'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
         ],
+        custom: [],
     },
 };
-export function findBrowserPath(browserType) {
+export function findBrowserPath(browserType, customBinary) {
+    if (customBinary) {
+        if (!fs.existsSync(customBinary)) {
+            throw new Error(`Custom binary not found: ${customBinary}`);
+        }
+        return customBinary;
+    }
+    if (browserType === 'custom') {
+        throw new Error('browser: custom requires a binary path in the profile');
+    }
     const platform = os.platform();
     const platformPaths = BROWSER_PATHS[platform];
     if (!platformPaths) {
@@ -52,8 +64,8 @@ export function findBrowserPath(browserType) {
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
-export async function launchBrowser(profileName, browserType, port, options = {}, secrets) {
-    const browserPath = findBrowserPath(browserType);
+export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary) {
+    const browserPath = findBrowserPath(browserType, customBinary);
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });

package/dist/lib/browser/drivers/local.js

@@ -14,7 +14,7 @@ export async function connectLocal(endpoint, profile) {
     }
     catch {
         const newPort = allocatePort();
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets);
+        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets, profile.binary);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port: newPort, pid };

package/dist/lib/browser/drivers/ssh.js

@@ -12,7 +12,7 @@ export async function connectSSH(endpoint, profile) {
     const remotePort = parseInt(url.searchParams.get('port') || '9222', 10);
     const localPort = allocatePort();
     try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort);
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
     }
     catch {
         // Browser may already be running, continue
@@ -96,7 +96,7 @@ function tryConnect(port) {
         socket.on('error', reject);
     });
 }
-async function ensureRemoteBrowser(user, host, browserType, port) {
+async function ensureRemoteBrowser(user, host, browserType, port, customBinary) {
     const browserPaths = {
         chrome: '/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome',
         comet: '/Applications/Comet.app/Contents/MacOS/Comet',
@@ -104,9 +104,18 @@ async function ensureRemoteBrowser(user, host, browserType, port) {
         brave: '/Applications/Brave\\ Browser.app/Contents/MacOS/Brave\\ Browser',
         edge: '/Applications/Microsoft\\ Edge.app/Contents/MacOS/Microsoft\\ Edge',
     };
-    const browserPath = browserPaths[browserType];
-    if (!browserPath) {
-        throw new Error(`Unknown browser type: ${browserType}`);
+    let browserPath;
+    if (customBinary) {
+        browserPath = customBinary.replace(/ /g, '\\ ');
+    }
+    else if (browserType === 'custom') {
+        throw new Error('browser: custom requires a binary path in the profile');
+    }
+    else {
+        browserPath = browserPaths[browserType];
+        if (!browserPath) {
+            throw new Error(`Unknown browser type: ${browserType}`);
+        }
     }
     const remoteCmd = `${browserPath} --remote-debugging-port=${port} '--remote-allow-origins=*' --disable-background-timer-throttling --user-data-dir=/tmp/agents-browser-${port} </dev/null >/dev/null 2>&1 &`;
     return new Promise((resolve, reject) => {

package/dist/lib/browser/service.js

@@ -28,7 +28,7 @@ export class BrowserService {
             const task = conn.tasks.get(finalTaskId);
             return { task: finalTaskId, windowTargetId: task.windowTargetId };
         }
-        const { windowTargetId } = await this.createTaskWindow(conn.cdp, finalTaskId);
+        const { windowTargetId } = await this.createTaskWindow(conn, finalTaskId);
         const task = {
             id: finalTaskId,
             profile: profileName,
@@ -88,6 +88,19 @@ export class BrowserService {
     }
     async navigate(taskId, url, profileName) {
         const { conn, task } = await this.findTask(taskId, profileName);
+        if (conn.electron) {
+            const tabId = task.windowTargetId || task.tabIds[0];
+            if (!tabId) {
+                throw new Error('No existing tab to navigate in Electron app');
+            }
+            const sessionId = await this.getSessionId(conn, tabId);
+            await conn.cdp.send('Page.navigate', { url }, sessionId);
+            if (!task.tabIds.includes(tabId)) {
+                task.tabIds.push(tabId);
+            }
+            await this.saveTaskState(task.profile, conn.tasks);
+            return { tabId, url };
+        }
         const result = (await conn.cdp.send('Target.createTarget', {
             url,
         }));
@@ -255,6 +268,7 @@ export class BrowserService {
                 cdp,
                 port: existingInfo.port,
                 pid: existingInfo.pid,
+                electron: profile.electron,
                 tasks,
                 sessionCache: new Map(),
             };
@@ -280,6 +294,7 @@ export class BrowserService {
                 cdp: conn.cdp,
                 port: conn.port,
                 pid: conn.pid,
+                electron: profile.electron,
                 tasks: conn.pid === 0 ? this.loadTaskState(profile.name) : new Map(),
                 sessionCache: new Map(),
             };
@@ -291,6 +306,7 @@ export class BrowserService {
                 cdp: conn.cdp,
                 port: conn.port,
                 pid: conn.pid,
+                electron: profile.electron,
                 tasks: new Map(),
                 sessionCache: new Map(),
             };
@@ -300,8 +316,13 @@ export class BrowserService {
     async enableDomains(cdp) {
         await cdp.send('Target.setDiscoverTargets', { discover: true });
     }
-    async createTaskWindow(cdp, _taskId) {
-        const result = (await cdp.send('Target.createTarget', {
+    async createTaskWindow(conn, _taskId) {
+        if (conn.electron) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            const pageTarget = targetInfos.find((t) => t.type === 'page');
+            return { windowTargetId: pageTarget?.targetId };
+        }
+        const result = (await conn.cdp.send('Target.createTarget', {
             url: 'about:blank',
             newWindow: true,
         }));

package/dist/lib/browser/types.d.ts

@@ -1,8 +1,10 @@
-export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge';
+export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
 export interface BrowserProfile {
     name: string;
     description?: string;
     browser: BrowserType;
+    binary?: string;
+    electron?: boolean;
     endpoints: string[];
     chrome?: ChromeOptions;
     secrets?: string;

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

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