@phnx-labs/agents-cli 1.18.3 → 1.18.5

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

@@ -1,4 +1,19 @@
 export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+/**
+ * A single named endpoint preset within a profile. Lets one profile cover
+ * the local + remote variants of the same app (e.g. Rush on this Mac vs.
+ * Rush on mac-mini) instead of forcing two parallel profiles.
+ *
+ * Per-endpoint overrides take precedence over profile-level fields.
+ */
+export interface EndpointPreset {
+    /** CDP URL — `cdp://host:port` or `ssh://host?port=N` */
+    target: string;
+    /** Override the profile-level binary (e.g. mac-mini has no local binary). */
+    binary?: string;
+    /** Override the profile-level targetFilter (Electron app builds may diverge). */
+    targetFilter?: string;
+}
 export interface BrowserProfile {
     name: string;
     description?: string;
@@ -10,7 +25,14 @@ export interface BrowserProfile {
      * represents the visible UI for Electron apps with multiple WebContents.
      */
     targetFilter?: string;
-    endpoints: string[];
+    /**
+     * Endpoint presets. Accepts two shapes for backward compatibility:
+     *   - Legacy: `string[]` of CDP URLs; first entry is the default.
+     *   - New:    `{ [presetName]: EndpointPreset }`, with optional `defaultEndpoint`.
+     * Normalize via `resolveEndpoint(profile, name?)` instead of reading directly.
+     */
+    endpoints: string[] | Record<string, EndpointPreset>;
+    defaultEndpoint?: string;
     chrome?: ChromeOptions;
     secrets?: string;
     viewport?: {
@@ -19,6 +41,10 @@ export interface BrowserProfile {
         x?: number;
         y?: number;
     };
+    /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
+    logDir?: string;
+    /** Optional SSH host where logDir lives, e.g. "muqsit@mac-mini". */
+    logHost?: string;
 }
 /** Parsed form of `BrowserProfile.targetFilter`. */
 export interface TargetFilter {
@@ -83,7 +109,7 @@ export interface HistoricalTask {
     domains: string[];
     tabCount: number;
 }
-export type IPCAction = 'start' | 'launch-profile' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload';
+export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -119,6 +145,28 @@ export interface IPCRequest {
     files?: string[];
     trigger?: number;
     uploadMode?: 'auto' | 'input' | 'drop' | 'chooser';
+    quality?: 'compressed' | 'raw';
+    endpoint?: string;
+    fps?: number;
+    duration?: number;
+    maxMb?: number;
+    source?: string;
+    lines?: number;
+    message?: string;
+    since?: string;
+    until?: string;
+    appLevel?: string;
+}
+/** Subset of IPCResponse describing a recording start result. */
+export interface RecordStartFields {
+    fps?: number;
+    durationCapSec?: number;
+    maxMb?: number;
+}
+/** Subset of IPCResponse describing a recording stop result. */
+export interface RecordStopFields {
+    durationMs?: number;
+    stopReason?: 'manual' | 'duration-cap' | 'size-cap';
 }
 export interface IPCResponse {
     ok: boolean;
@@ -131,10 +179,18 @@ export interface IPCResponse {
     history?: HistoricalTask[];
     result?: unknown;
     path?: string;
+    bytes?: number;
+    width?: number;
+    height?: number;
     refs?: string;
     nodes?: RefNodeJson[];
     port?: number;
     pid?: number;
+    fps?: number;
+    durationCapSec?: number;
+    maxMb?: number;
+    durationMs?: number;
+    stopReason?: 'manual' | 'duration-cap' | 'size-cap';
     logs?: ConsoleEntry[];
     errors?: ErrorEntry[];
     requests?: NetworkRequest[];
@@ -142,6 +198,8 @@ export interface IPCResponse {
     downloadPath?: string;
     devices?: string[];
     uploadMode?: 'input' | 'drop' | 'chooser';
+    appLogs?: any[];
+    version?: string;
 }
 export interface ConsoleEntry {
     level: 'log' | 'info' | 'warn' | 'error';
@@ -183,3 +241,10 @@ export declare function isValidTaskId(id: string): boolean;
 export declare function generateTaskId(): string;
 export declare function generateShortId(): string;
 export declare function generateFunName(): string;
+/**
+ * Auto-generated task name: `<adjective>-<noun>-<noun>-<hex8>`, e.g.
+ * `swift-crab-falcon-a3f92b1c`. Three English words make it memorable and
+ * easy to read; 32 bits of hex give every spawned task enough entropy that
+ * parallel agents never collide on the daemon side.
+ */
+export declare function generateTaskName(): string;

package/dist/lib/browser/types.js

@@ -11,13 +11,33 @@ export function generateShortId() {
 const ADJECTIVES = [
     'swift', 'cosmic', 'jolly', 'quiet', 'bold', 'bright', 'calm', 'eager',
     'golden', 'happy', 'keen', 'lucky', 'noble', 'proud', 'quick', 'royal',
+    'silver', 'amber', 'crimson', 'misty', 'sunny', 'gentle', 'wild', 'brave',
+    'merry', 'sleek', 'wise', 'fierce', 'curious', 'humble', 'spry', 'witty',
 ];
 const NOUNS = [
     'falcon', 'comet', 'tiger', 'nebula', 'phoenix', 'river', 'summit', 'wave',
     'aurora', 'breeze', 'crystal', 'dragon', 'ember', 'forest', 'glacier', 'harbor',
+    'crab', 'otter', 'hawk', 'fox', 'wolf', 'panda', 'lynx', 'raven',
+    'meadow', 'canyon', 'valley', 'orchid', 'cedar', 'thistle', 'lotus', 'briar',
 ];
 export function generateFunName() {
     const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
     const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
     return `${adj}-${noun}`;
 }
+/**
+ * Auto-generated task name: `<adjective>-<noun>-<noun>-<hex8>`, e.g.
+ * `swift-crab-falcon-a3f92b1c`. Three English words make it memorable and
+ * easy to read; 32 bits of hex give every spawned task enough entropy that
+ * parallel agents never collide on the daemon side.
+ */
+export function generateTaskName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const noun1 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    let noun2 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    while (noun2 === noun1) {
+        noun2 = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    }
+    const hex8 = crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+    return `${adj}-${noun1}-${noun2}-${hex8}`;
+}

package/dist/lib/daemon.js

@@ -178,6 +178,24 @@ export async function runDaemon() {
     for (const job of scheduled) {
         log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
     }
+    // Before the BrowserService comes up, reap browser + tunnel processes
+    // spawned by previous daemons that are no longer alive. Without this,
+    // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH
+    // tunnel it had open — and the next session would either hijack those
+    // (cdp:// profile silently driven via stale ssh tunnel) or fail to
+    // bind because the ports are still claimed.
+    try {
+        const { reapOrphanedProcesses } = await import('./browser/runtime-state.js');
+        const result = reapOrphanedProcesses();
+        if (result.reaped > 0) {
+            log('INFO', `Reaped ${result.reaped} orphan process(es) from prior daemon(s)`);
+            for (const d of result.details)
+                log('INFO', `  ${d}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Orphan reaper failed: ${err.message}`);
+    }
     const browserService = new BrowserService();
     const browserIPC = new BrowserIPCServer(browserService);
     try {
@@ -259,6 +277,14 @@ Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node
 WantedBy=default.target`;
 }
 function getAgentsBinPath() {
+    // Prefer the binary actively executing this code. `which agents` returns
+    // whatever happens to be first on PATH, which means a side-by-side dev
+    // build at ~/.local/bin would silently spawn the registry-installed
+    // daemon and run stale code. process.argv[1] is the absolute path of
+    // the JS entrypoint the user actually invoked.
+    const argv1 = process.argv[1];
+    if (argv1 && fs.existsSync(argv1))
+        return argv1;
     try {
         return execSync('which agents', { encoding: 'utf-8' }).trim();
     }
@@ -299,13 +325,20 @@ function startDaemonLocked() {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
             catch { /* not loaded, expected */ }
-            execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8' });
+            // launchctl prints `Load failed:` and exits 0 when the label is in a
+            // stuck state from a prior session — so a zero exit code isn't proof
+            // of success. If no pid materializes within the window, give up on
+            // launchd and fall through to a plain detached spawn.
+            execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
             const pid = waitForPid(3000);
-            return { pid, method: 'launchd' };
+            if (pid)
+                return { pid, method: 'launchd' };
+            // launchctl claimed success but nothing ran. Fall through.
         }
         catch {
-            return startDetached();
+            // load threw — fall through to detached spawn
         }
+        return startDetached();
     }
     if (platform === 'linux') {
         try {

package/dist/lib/events.d.ts

@@ -11,7 +11,7 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
 export interface EventMeta {
     ts: string;
     tz: string;

package/dist/lib/help.js

@@ -23,12 +23,36 @@ function formatHelpCommandsFirst(cmd, helper) {
     function formatList(textArray) {
         return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
     }
-    let output = [`Usage: ${helper.commandUsage(cmd)}`, ''];
+    // Drop arguments flagged as hidden (deprecation / compat slots) from both
+    // the Usage line and the Arguments section. Commander v12's Argument lacks
+    // hideHelp(), so we read a custom `hidden` field that callers set directly.
+    const isHidden = (a) => a.hidden === true;
+    const registeredArgs = cmd.registeredArguments ?? [];
+    const parentNames = [];
+    for (let p = cmd.parent; p; p = p.parent)
+        parentNames.unshift(p.name());
+    const parentPrefix = parentNames.length > 0 ? parentNames.join(' ') + ' ' : '';
+    const visibleArgTokens = registeredArgs
+        .filter((a) => !isHidden(a))
+        .map((a) => {
+        const n = a.name() + (a.variadic ? '...' : '');
+        return a.required ? `<${n}>` : `[${n}]`;
+    })
+        .join(' ');
+    // commander always exposes -h/--help, so every command effectively has options.
+    // Order matches commander's default: name [options] <args> [command].
+    const argsToken = visibleArgTokens ? ` ${visibleArgTokens}` : '';
+    const commandToken = cmd.commands.length > 0 ? ' [command]' : '';
+    const usageLine = `${parentPrefix}${cmd.name()} [options]${argsToken}${commandToken}`;
+    let output = [`Usage: ${usageLine}`, ''];
     const commandDescription = helper.commandDescription(cmd);
     if (commandDescription.length > 0) {
         output = output.concat([helper.wrap(commandDescription, helpWidth, 0), '']);
     }
-    const argumentList = helper.visibleArguments(cmd).map((argument) => {
+    const argumentList = helper
+        .visibleArguments(cmd)
+        .filter((a) => !isHidden(a))
+        .map((argument) => {
         return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument));
     });
     if (argumentList.length > 0) {
@@ -36,9 +60,12 @@ function formatHelpCommandsFirst(cmd, helper) {
     }
     const visibleCommands = helper.visibleCommands(cmd);
     const subcommandTermNoAlias = (sub) => {
-        // Mirror commander's default subcommandTerm but drop the |alias suffix.
+        // Mirror commander's default subcommandTerm but drop the |alias suffix and
+        // skip arguments marked as hidden (Argument#hideHelp()), so deprecation /
+        // compatibility slots don't pollute the usage line.
         const argList = sub.registeredArguments ?? [];
         const args = argList
+            .filter((a) => !a.hidden)
             .map((a) => {
             const n = a.name() + (a.variadic ? '...' : '');
             return a.required ? `<${n}>` : `[${n}]`;

package/dist/lib/secrets/bundles.d.ts

@@ -82,6 +82,26 @@ export interface RotateOptions {
  * unless `clearMeta` or a `meta` patch is supplied.
  */
 export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions): void;
+/** Options for renameBundle. */
+export interface RenameOptions {
+    /** When true, overwrite an existing destination bundle (purges its keychain items first). */
+    force?: boolean;
+}
+/**
+ * Rename a bundle: move metadata + every keychain-backed value to a new name.
+ *
+ * Sequence is ordered so the source stays intact if anything in the copy
+ * phase fails:
+ *   1) read source, validate dest
+ *   2) purge dest if --force, refuse otherwise
+ *   3) copy each keychain value source -> dest
+ *   4) write new bundle metadata
+ *   5) delete the old per-key keychain items + old metadata
+ *
+ * Steps 1-4 are reversible. If 5 partially fails (e.g. iCloud Keychain
+ * hiccup), running `rename` again is a safe no-op for the source items.
+ */
+export declare function renameBundle(oldName: string, newName: string, opts?: RenameOptions): void;
 export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
     key: string;
     item: string;

package/dist/lib/secrets/bundles.js

@@ -306,6 +306,62 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     writeBundle(bundle);
 }
+/**
+ * Rename a bundle: move metadata + every keychain-backed value to a new name.
+ *
+ * Sequence is ordered so the source stays intact if anything in the copy
+ * phase fails:
+ *   1) read source, validate dest
+ *   2) purge dest if --force, refuse otherwise
+ *   3) copy each keychain value source -> dest
+ *   4) write new bundle metadata
+ *   5) delete the old per-key keychain items + old metadata
+ *
+ * Steps 1-4 are reversible. If 5 partially fails (e.g. iCloud Keychain
+ * hiccup), running `rename` again is a safe no-op for the source items.
+ */
+export function renameBundle(oldName, newName, opts = {}) {
+    validateBundleName(oldName);
+    validateBundleName(newName);
+    if (oldName === newName) {
+        throw new Error(`Bundle name unchanged ('${oldName}').`);
+    }
+    if (!bundleExists(oldName)) {
+        throw new Error(`Bundle '${oldName}' not found.`);
+    }
+    const source = readBundle(oldName);
+    if (bundleExists(newName)) {
+        if (!opts.force) {
+            throw new Error(`Bundle '${newName}' already exists. Use --force to overwrite.`);
+        }
+        const dest = readBundle(newName);
+        for (const { item } of keychainItemsForBundle(dest)) {
+            deleteKeychainToken(item, dest.icloud_sync);
+        }
+        deleteBundle(newName);
+    }
+    // Copy phase: read old item, write new item. Old items stay in place
+    // until step 5 so a partial failure here leaves the source intact.
+    const sourceItems = keychainItemsForBundle(source);
+    for (const { key, item: oldItem } of sourceItems) {
+        const raw = source.vars[key];
+        if (typeof raw !== 'string' || !raw.startsWith('keychain:'))
+            continue;
+        const shortId = raw.slice('keychain:'.length);
+        const newItem = secretsKeychainItem(newName, shortId);
+        const value = getKeychainToken(oldItem, source.icloud_sync);
+        setKeychainToken(newItem, value, source.icloud_sync);
+    }
+    // writeBundle preserves source.created_at and refreshes updated_at.
+    const renamed = { ...source, name: newName };
+    writeBundle(renamed);
+    // Cleanup: delete the old per-key keychain items, then the old metadata.
+    for (const { item: oldItem } of sourceItems) {
+        deleteKeychainToken(oldItem, source.icloud_sync);
+    }
+    deleteBundle(oldName);
+    emit('secrets.rename', { from: oldName, to: newName });
+}
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {
     const items = [];

package/dist/lib/secrets/index.js

@@ -182,14 +182,14 @@ export function deleteKeychainToken(item, sync = false) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.delete(item, sync);
-    // macOS path
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        return spawnSync(bin, ['delete', item, os.userInfo().username], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).status === 0;
-    }
-    return spawnSync('security', ['delete-generic-password', '-a', os.userInfo().username, '-s', item], {
+    // macOS: Try security first (no prompts for local items), fall back to binary for synced items.
+    if (!sync && spawnSync('security', ['delete-generic-password', '-a', os.userInfo().username, '-s', item], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).status === 0)
+        return true;
+    // Fallback: binary deletes synced items via kSecAttrSynchronizableAny
+    const bin = ensureKeychainHelper();
+    return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }

package/dist/lib/types.d.ts

@@ -442,7 +442,18 @@ export interface BrowserProfileConfig {
      * Only consulted when `electron` is true.
      */
     targetFilter?: string;
-    endpoints: string[];
+    /**
+     * Endpoint presets. Accepts two shapes for backward compatibility:
+     *   - Legacy: `string[]` of CDP URLs; first entry is the default.
+     *   - New:    `{ [presetName]: { target, binary?, targetFilter? } }`.
+     */
+    endpoints: string[] | Record<string, {
+        target: string;
+        binary?: string;
+        targetFilter?: string;
+    }>;
+    /** Preset name to use when `--endpoint` is not passed to `start`. */
+    defaultEndpoint?: string;
     chrome?: {
         headless?: boolean;
         args?: string[];
@@ -452,6 +463,10 @@ export interface BrowserProfileConfig {
         width: number;
         height: number;
     };
+    /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
+    logDir?: string;
+    /** Optional SSH host where logDir lives, e.g. "muqsit@mac-mini". */
+    logHost?: string;
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */
 export interface SyncOptions {

package/dist/lib/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve the CLI version from the shipping package.json. Used by the daemon
+ * to answer `IPCAction: 'version'` and by the client to detect daemon drift —
+ * a dev-build CLI talking to a launchd-managed registry daemon would silently
+ * get stale behavior without this check.
+ */
+export declare function getCliVersion(): string;

package/dist/lib/version.js

@@ -0,0 +1,25 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+let cached = null;
+/**
+ * Resolve the CLI version from the shipping package.json. Used by the daemon
+ * to answer `IPCAction: 'version'` and by the client to detect daemon drift —
+ * a dev-build CLI talking to a launchd-managed registry daemon would silently
+ * get stale behavior without this check.
+ */
+export function getCliVersion() {
+    if (cached)
+        return cached;
+    try {
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        cached = String(pkg.version || 'unknown');
+    }
+    catch {
+        cached = 'unknown';
+    }
+    return cached;
+}

package/package.json

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