@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/commands/browser.js

@@ -1,14 +1,14 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, listProfilesWithScope, formatProfilesTable, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, listProfilesWithScope, formatProfilesTable, editProfile, moveProfileScope, renameProfile, assertRegistrableProfileName, misfiledFleetProfile, } from '../lib/browser/profiles.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
 import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
 import { findBrowserPath, getPortOccupant, isLauncherScript, listInstalledBrowsers } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, buildProfilePrunePlan, pruneProfiles, PRUNE_REASON_TEXT, } from '../lib/browser/runtime-state.js';
-import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { DEFAULT_VIEWPORT, parseWindowSize, parseWindowPosition } from '../lib/browser/devices.js';
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
@@ -330,8 +330,11 @@ function registerProfilesCommands(browser) {
         .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
         .option('--target-filter <expr>', 'Pick the visible CDP page target when the app exposes more than one. Format: url:<substring> or title:<substring>')
         .action(async (name, opts) => {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            console.error('Profile name must be lowercase alphanumeric with hyphens');
+        try {
+            assertRegistrableProfileName(name);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
         if (!VALID_BROWSERS.includes(opts.browser)) {
@@ -370,22 +373,22 @@ function registerProfilesCommands(browser) {
             height: DEFAULT_VIEWPORT.height,
         };
         if (opts.window) {
-            const m = String(opts.window).match(/^(\d+)x(\d+)$/);
-            if (!m) {
+            const size = parseWindowSize(String(opts.window));
+            if (!size) {
                 console.error(`--window must be WxH, e.g. ${DEFAULT_VIEWPORT.width}x${DEFAULT_VIEWPORT.height}`);
                 process.exit(1);
             }
-            viewport.width = parseInt(m[1], 10);
-            viewport.height = parseInt(m[2], 10);
+            viewport.width = size.width;
+            viewport.height = size.height;
         }
         if (opts.position) {
-            const m = String(opts.position).match(/^(-?\d+),(-?\d+)$/);
-            if (!m) {
+            const pos = parseWindowPosition(String(opts.position));
+            if (!pos) {
                 console.error('--position must be X,Y, e.g. 80,80');
                 process.exit(1);
             }
-            viewport.x = parseInt(m[1], 10);
-            viewport.y = parseInt(m[2], 10);
+            viewport.x = pos.x;
+            viewport.y = pos.y;
         }
         const profile = {
             name,
@@ -407,6 +410,193 @@ function registerProfilesCommands(browser) {
             console.error(`warning: secrets bundle "${opts.secrets}" does not exist yet. Create it with: agents secrets create ${opts.secrets}`);
         }
     });
+    profiles
+        .command('edit <name>')
+        .description('Edit an existing profile in place (stays in the store it already lives in)')
+        // Declared only so the action can explain WHY the browser type is not
+        // editable. Without it commander rejects `-b` as an unknown option before
+        // the action runs, and the delete-and-recreate guidance never reaches anyone.
+        .option('-b, --browser <type>', 'Not editable — see the error for the delete-and-recreate path')
+        .option('-d, --description <text>', "Profile description (pass '' to clear)")
+        .option('-e, --endpoint <url>', 'Replace the endpoint list (repeatable)', collect, [])
+        .option('-s, --secrets <bundle>', 'Secrets bundle to inject')
+        .option('--headless', 'Run in headless mode')
+        .option('--no-headless', 'Run headed')
+        .option('--window <WxH>', 'Window size in CSS pixels')
+        .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
+        .option('--binary <path>', 'Absolute path to the browser/app binary')
+        .option('--electron', 'Treat this profile as an Electron desktop app')
+        .option('--no-electron', 'Stop treating it as an Electron app')
+        .option('--target-filter <expr>', "url:<substring> or title:<substring>; requires --electron (pass '' to clear)")
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (name, opts) => {
+        // The browser type and the name are identity, not settings: both key the
+        // on-disk runtime dir and any live `<name>@<endpoint>` connection, so
+        // changing either orphans the cached browser data (and its logins).
+        if (opts.browser) {
+            console.error('browser type is not editable — it keys the on-disk profile cache. ' +
+                `Delete and recreate instead: agents browser profiles delete ${name} && agents browser profiles create ${name} -b <type>`);
+            process.exit(1);
+        }
+        if (opts.targetFilter) {
+            const parsed = parseTargetFilter(String(opts.targetFilter));
+            if (!parsed) {
+                console.error('--target-filter must be url:<substring> or title:<substring> (non-empty value, no leading whitespace)');
+                process.exit(1);
+            }
+        }
+        const patch = {};
+        if (opts.description !== undefined)
+            patch.description = opts.description || undefined;
+        if (opts.endpoint && opts.endpoint.length > 0)
+            patch.endpoints = opts.endpoint;
+        if (opts.secrets !== undefined)
+            patch.secrets = opts.secrets;
+        if (opts.binary !== undefined)
+            patch.binary = opts.binary;
+        if (opts.targetFilter !== undefined)
+            patch.targetFilter = opts.targetFilter || undefined;
+        // commander maps --electron/--no-electron and --headless/--no-headless onto
+        // one boolean each, and leaves it undefined when neither was passed.
+        if (opts.electron !== undefined)
+            patch.electron = opts.electron || undefined;
+        if (opts.headless !== undefined || opts.window || opts.position) {
+            const current = await getProfile(name);
+            if (!current) {
+                console.error(`Profile "${name}" does not exist`);
+                process.exit(1);
+            }
+            if (opts.headless !== undefined) {
+                const chrome = { ...current.chrome };
+                if (opts.headless)
+                    chrome.headless = true;
+                else
+                    delete chrome.headless;
+                // `{ headless: undefined }` is truthy, so profileToConfig would persist
+                // a bare `chrome: {}` into the YAML and the change-detector would report
+                // a phantom edit on an already-headed profile. Drop the key entirely.
+                patch.chrome = Object.keys(chrome).length > 0 ? chrome : undefined;
+            }
+            if (opts.window || opts.position) {
+                const viewport = { ...(current.viewport ?? { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height }) };
+                if (opts.window) {
+                    const size = parseWindowSize(String(opts.window));
+                    if (!size) {
+                        console.error('--window must be WxH, e.g. 1512x982');
+                        process.exit(1);
+                    }
+                    viewport.width = size.width;
+                    viewport.height = size.height;
+                }
+                if (opts.position) {
+                    const pos = parseWindowPosition(String(opts.position));
+                    if (!pos) {
+                        console.error('--position must be X,Y, e.g. 80,80');
+                        process.exit(1);
+                    }
+                    viewport.x = pos.x;
+                    viewport.y = pos.y;
+                }
+                patch.viewport = viewport;
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            console.error('Nothing to edit. Pass at least one field, e.g. -d "<description>".');
+            process.exit(1);
+        }
+        let result;
+        try {
+            result = await editProfile(name, patch);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...result.profile, scope: result.scope, changed: result.changed }, null, 2));
+        }
+        else if (result.changed.length === 0) {
+            console.log(`No change: ${name} already had those values.`);
+        }
+        else {
+            console.log(`Updated ${name} (${result.scope}): ${result.changed.join(', ')}`);
+        }
+        if (result.fleetCopyLeftStale) {
+            console.error(`warning: "${name}" is machine-local by rule, so the edit was written to this machine only. ` +
+                `The fleet-synced copy still holds the old values on every other box.`);
+        }
+        if (patch.secrets && !bundleExists(patch.secrets)) {
+            console.error(`warning: secrets bundle "${patch.secrets}" does not exist yet. Create it with: agents secrets create ${patch.secrets}`);
+        }
+    });
+    profiles
+        .command('rename <from> <to>')
+        .description("Rename a profile, moving its browser data with it (logins survive)")
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (from, to, opts) => {
+        let res;
+        try {
+            res = await renameProfile(from, to);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ from, to, ...res }, null, 2));
+            return;
+        }
+        console.log(`Renamed ${from} -> ${to} (${res.scope})`);
+        if (res.movedDirs.length > 0) {
+            console.log(`  moved ${res.movedDirs.length} browser data dir${res.movedDirs.length === 1 ? '' : 's'} — logins preserved`);
+        }
+        if (res.repointedDefault) {
+            console.log(`  browser.profile now points at ${to}`);
+        }
+        if (res.repointedViewer) {
+            console.log(`  browser.viewer now points at ${to}`);
+        }
+        if (res.stalePins.length > 0) {
+            const devices = [...new Set(res.stalePins.map((p) => p.device))];
+            const one = devices.length === 1;
+            console.error(`warning: ${devices.join(', ')} still ${one ? 'pins' : 'pin'} "${from}" in ` +
+                `${one ? 'its' : 'their'} own device config. Fix with:`);
+            for (const pin of res.stalePins) {
+                console.error(`  agents config set ${pin.key} ${to} --device ${pin.device}`);
+            }
+        }
+    });
+    profiles
+        .command('scope <name> <scope>')
+        .description('Move a profile between the fleet-synced store and this machine (local|fleet)')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (name, scope, opts) => {
+        if (scope !== 'local' && scope !== 'fleet') {
+            console.error('scope must be `local` or `fleet`');
+            process.exit(1);
+        }
+        let moved;
+        try {
+            moved = await moveProfileScope(name, scope);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ profile: name, ...moved }, null, 2));
+            return;
+        }
+        if (moved.from === moved.to) {
+            console.log(`${name} is already ${scope}.`);
+            return;
+        }
+        console.log(`Moved ${name}: ${moved.from} -> ${moved.to}`);
+        if (scope === 'local') {
+            console.error(`note: ${name} is no longer visible on any other machine. ` +
+                `Run this ON the machine that owns the browser — the surviving copy is this one.`);
+        }
+    });
     profiles
         .command('show <name>')
         .description('Show profile details')
@@ -531,12 +721,29 @@ function registerProfilesCommands(browser) {
             console.log(JSON.stringify({ dryRun: !!opts.dryRun, ...plan }, null, 2));
             return;
         }
+        // A misfiled fleet profile is never a prune candidate (deleting a fleet
+        // entry deletes it everywhere), so without this it would only ever surface
+        // in --json. It is the one kept-reason a user has to act on.
+        const misfiled = plan.kept.filter((k) => k.misfiled);
+        const reportMisfiled = () => {
+            if (misfiled.length === 0)
+                return;
+            console.log('');
+            console.log(`${misfiled.length} fleet profile${misfiled.length === 1 ? '' : 's'} ${misfiled.length === 1 ? 'is' : 'are'} misfiled — ` +
+                `fleet-synced but bound to a local port, so the name means a different browser on every machine:`);
+            for (const k of misfiled) {
+                console.log(`  ${k.name} — agents browser profiles scope ${k.name} local`);
+            }
+            console.log('Run that on the machine that owns each browser. Nothing was moved for you.');
+            console.log('(Prune never deletes these — removing a fleet entry removes it everywhere.)');
+        };
         if (plan.candidates.length === 0) {
             console.log('Nothing to prune — every profile is in use, healthy, or protected.');
             if (plan.kept.length > 0) {
                 for (const k of plan.kept)
                     console.log(`  kept ${k.name} (${k.scope}) — ${k.why}`);
             }
+            reportMisfiled();
             return;
         }
         const verb = opts.dryRun ? 'Would remove' : 'Removed';
@@ -547,6 +754,7 @@ function registerProfilesCommands(browser) {
                 : '';
             console.log(`  ${c.name} (${c.scope}) — ${PRUNE_REASON_TEXT[c.reason]}${cache}`);
         }
+        reportMisfiled();
         if (opts.dryRun) {
             console.log('');
             console.log('Nothing was changed. Re-run without --dry-run to apply.');
@@ -594,6 +802,15 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
+        // 0. Store scope. A fleet-synced profile whose endpoint is loopback cdp://
+        //    means a DIFFERENT browser on every machine — the name lies everywhere
+        //    but here. Checked first because it invalidates the reading of every
+        //    check below on any other box.
+        const scoped = (await listProfilesWithScope()).find((p) => p.profile.name === name);
+        const misfiled = scoped ? misfiledFleetProfile(profile, scoped.scope) : { misfiled: false };
+        checks.push(misfiled.misfiled
+            ? { label: 'scope', ok: false, detail: misfiled.why }
+            : { label: 'scope', ok: true, detail: scoped ? `stored ${scoped.scope}` : 'stored local' });
         // 1. Binary exists for declared browser type, and is a real executable we
         //    can drive — not a distro launcher script. findBrowserPath already
         //    unwraps the known Chromium wrappers to their ELF; if it still hands
@@ -836,9 +1053,11 @@ function registerTaskCommands(browser) {
         .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
         .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
         .action(async (opts) => {
-        // Consent gate: a fleet-remote `browser --device <this-machine> start` may
-        // only open a browser here if the owner opted in. Refuse before we resolve
-        // or auto-create any profile. Local starts are never gated.
+        // Fast-fail copy of the consent gate, so a refused start never resolves or
+        // auto-creates a profile. The AUTHORITATIVE gate is in the daemon
+        // (BrowserService.start / resolveOrCreateTask, via
+        // assertRemoteControlAllowedForRequest) — it has to be, because the page
+        // verbs create a browser implicitly and never reach this command.
         try {
             assertRemoteControlAllowed();
         }
@@ -1053,6 +1272,38 @@ function registerTaskCommands(browser) {
             console.log(`  ${c.task}  (${c.profile}, ${c.reason})`);
         }
     });
+    browser
+        .command('show <url>')
+        .description('Open a URL for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
+        .option('--os-browser', 'Use the OS default handler instead of the configured viewer')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (url, opts) => {
+        // The entry point external tools need. `navigate` binds a task, which the
+        // abandoned-task reaper closes when the calling session ends — wrong for a
+        // page a person is reading. This does not.
+        const { showUrl, showFile } = await import('../lib/open-url.js');
+        // `+` not `*` on the scheme body: `[a-z][a-z0-9+.-]*:` matches a Windows
+        // drive letter (`C:\Users\me\plan.html`), so a real path was treated as a
+        // URL. A scheme is at least two characters.
+        const isLocalFile = !/^[a-z][a-z0-9+.-]+:/i.test(url);
+        const outcome = isLocalFile
+            ? await showFile(path.resolve(url), { osBrowser: opts.osBrowser })
+            : await showUrl(url, { osBrowser: opts.osBrowser });
+        if (opts.json) {
+            console.log(JSON.stringify(outcome, null, 2));
+        }
+        else if (outcome.via === 'none') {
+            console.error(`Could not open a browser — open this yourself:\n  ${url}`);
+        }
+        else if (outcome.via === 'profile') {
+            console.log(`Shown in ${outcome.profile}: ${url}`);
+        }
+        else {
+            console.log(`Opened in the OS default browser: ${url}`);
+        }
+        if (outcome.via === 'none')
+            process.exit(1);
+    });
     browser
         .command('navigate [url]')
         .alias('goto')

package/dist/commands/config.js

@@ -72,6 +72,7 @@ function parseValue(key, parsed, raw) {
                 case 'notes':
                     return raw.trim();
                 case 'browser.profile':
+                case 'browser.viewer':
                     return raw.trim();
             }
             // A device property with no arm above used to fall out of the switch and
@@ -121,7 +122,7 @@ function setConfig(parsed, value) {
             // (same store `agents devices config` / getConfigValue use). Bare
             // browser.profile targets this machine; devices.<name>.browser.profile
             // targets a peer.
-            setConfigValue('browser.profile', value, parsed.device ? { device: parsed.device } : undefined);
+            setConfigValue(parsed.property === 'viewer' ? 'browser.viewer' : 'browser.profile', value, parsed.device ? { device: parsed.device } : undefined);
             return;
         }
         case 'project':
@@ -167,8 +168,12 @@ function unsetConfig(parsed) {
         }
         case 'browser': {
             const target = parsed.device ? { device: parsed.device } : undefined;
-            const had = getConfigValue('browser.profile', target).value !== undefined;
-            unsetConfigValue('browser.profile', target);
+            // Must follow parsed.property. Hardcoding 'browser.profile' here meant
+            // `config unset browser.viewer` deleted the user's browser.profile while
+            // printing success, and left browserViewer in place.
+            const name = parsed.property === 'viewer' ? 'browser.viewer' : 'browser.profile';
+            const had = getConfigValue(name, target).value !== undefined;
+            unsetConfigValue(name, target);
             return had;
         }
         case 'project': {
@@ -204,7 +209,7 @@ function getConfig(parsed) {
         case 'auto':
             return getConfigValue('auto.pool').value;
         case 'browser': {
-            return getConfigValue('browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
+            return getConfigValue(parsed.property === 'viewer' ? 'browser.viewer' : 'browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
         }
         case 'project':
             return getProjectRoot();
@@ -274,6 +279,11 @@ function* listCentralConfigEntries() {
         const key = 'browser.profile';
         yield { key, value: browserProfile, hint: configKeyStorageHint(parseConfigKey(key)) };
     }
+    const browserViewer = getConfigValue('browser.viewer').value;
+    if (browserViewer !== undefined) {
+        const key = 'browser.viewer';
+        yield { key, value: browserViewer, hint: configKeyStorageHint(parseConfigKey(key)) };
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {
@@ -314,7 +324,19 @@ function* listDeviceConfigEntries(device) {
                     continue;
                 key = `${prefix}browser.profile`;
                 break;
+            case 'browser.viewer':
+                // Same duplication rule as browser.profile above.
+                if (device === machineId())
+                    continue;
+                key = `${prefix}browser.viewer`;
+                break;
             default:
+                // A `default: continue` here silently drops any device property with no
+                // arm — which is how browser.viewer was invisible to `config list` after
+                // being added everywhere else. This is the fourth switch enumerating
+                // DeviceConfigProperty; unlike parseValue's it cannot use a `never`
+                // binding (it must keep skipping properties that are deliberately not
+                // listed), so the completeness test in config.test.ts is the guard.
                 continue;
         }
         yield { key, value: entry.value, hint: configKeyStorageHint(parseConfigKey(key)) };

package/dist/commands/cost.d.ts

@@ -5,7 +5,7 @@
  * This is the read side of issue #323. Cost and duration are computed and
  * persisted at scan time (see src/lib/session/discover.ts + db.ts); this
  * command only queries and renders them — a pure SQLite/CLI win, no server,
- * no telemetry. Distinct from `agents usage`, which reports live rate-limit /
+ * no telemetry. Distinct from `agents view`, which reports live rate-limit /
  * quota status per agent and is left untouched.
  */
 import type { Command } from 'commander';

package/dist/commands/detach.d.ts

@@ -1,5 +1,18 @@
 import type { Command } from 'commander';
+import type { ActiveSession } from '../lib/session/active.js';
 export declare function registerDetachCommand(program: Command): void;
+/**
+ * Stop a live agent's interactive process and tear down its mux. tmux-hosted
+ * sessions are killed by session (closes the pane, ends the agent, reaps its
+ * helper processes); a plain process is SIGTERM'd (then SIGKILLed) by pid. Either
+ * way we wait for the process to actually exit before returning.
+ *
+ * Shared by two callers: `detach` (stop the terminal so the headless resume it
+ * spawns next doesn't fight the old process over the same transcript) and `stop`
+ * (end the session outright — no resume). `socket` defaults to the shared agents
+ * socket; it is a parameter only so a test can drive an isolated tmux server.
+ */
+export declare function stopInteractive(s: ActiveSession, socket?: string): Promise<void>;
 export declare function detachAction(id: string, opts?: {
     local?: boolean;
 }): Promise<void>;

package/dist/commands/detach.js

@@ -34,17 +34,20 @@ export function registerDetachCommand(program) {
     });
 }
 /**
- * Stop the interactive process so it can't fight the headless resume over the
- * same transcript. tmux-hosted sessions are killed by session (closes the pane
- * and ends the agent); a plain process is SIGTERM'd by pid. Either way we then
- * wait for the process to actually exit before returning, so the headless
- * continuation never starts writing the transcript while the old process is
- * still flushing it.
+ * Stop a live agent's interactive process and tear down its mux. tmux-hosted
+ * sessions are killed by session (closes the pane, ends the agent, reaps its
+ * helper processes); a plain process is SIGTERM'd (then SIGKILLed) by pid. Either
+ * way we wait for the process to actually exit before returning.
+ *
+ * Shared by two callers: `detach` (stop the terminal so the headless resume it
+ * spawns next doesn't fight the old process over the same transcript) and `stop`
+ * (end the session outright — no resume). `socket` defaults to the shared agents
+ * socket; it is a parameter only so a test can drive an isolated tmux server.
  */
-async function stopInteractive(s) {
+export async function stopInteractive(s, socket = getDefaultSocketPath()) {
     if (s.tmuxTarget) {
         const name = s.tmuxTarget.split(':')[0];
-        await killSession(name, getDefaultSocketPath());
+        await killSession(name, socket);
     }
     else if (s.pid && s.pid > 0) {
         try {