@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/browser/service.js

@@ -4,11 +4,13 @@ import * as path from 'path';
 import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
 import { getProfile, getProfileRuntimeDir, getProfileDownloadsDir, getProfileSessionsDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, parseEndpointUrl, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
+import { assertRemoteControlAllowedForRequest } from './remote-control.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
+import { adoptLegacyRuntimeIfLocal, isLegacyEndpointKey, resolveBrowserTarget, shouldForkProfile, } from './resolve-target.js';
 import { clearProfileRuntime, listProfileCacheDirs, readProfileRuntimeMeta, isProcessAlive } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
-import { generateTaskId, generateShortId, connectionKey, asConnectionKey, parseConnectionKey, keyBelongsToProfile, } from './types.js';
+import { generateTaskId, generateShortId, asConnectionKey, parseConnectionKey, keyBelongsToProfile, } from './types.js';
 import { reapAbandonedTasks, resolveLiveIdentities, taskOwnerIsGone, } from './hygiene.js';
 import { taskMatchesCaller } from './caller-identity.js';
 import { getRefs, resolveRefToCoords, describeRefs, healRef } from './refs.js';
@@ -297,7 +299,8 @@ export class BrowserService {
      * Live browsers, keyed by {@link ConnectionKey} — NOT by profile name. The
      * branded key type is what makes `connections.get(someProfileName)` (the
      * RUSH-2709 miss that made `status --profile <name>` return empty for a
-     * running `<name>@endpoint-0`) fail to compile.
+     * running `<name>@<device>`) fail to compile. Keys are `<profile>@<device>`
+     * (legacy leftover `<profile>@endpoint-N` dirs are still recognized).
      */
     connections = new Map();
     forkingProfiles = new Set();
@@ -312,26 +315,21 @@ export class BrowserService {
     /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
     static TOUCH_PERSIST_INTERVAL_MS = 60_000;
     async start(profileName, opts = {}) {
-        const profile = await getProfile(profileName);
-        if (!profile) {
-            throw new Error(`Profile "${profileName}" not found`);
-        }
-        // Pick the endpoint preset. Throws with the candidate list if the user
-        // passed an unknown name. The runtime key `<profile>@<endpoint>` is what
-        // the connection map + per-profile runtime dirs are keyed on, so a single
-        // YAML profile can run at multiple endpoints concurrently.
-        //
-        // `effectiveProfile.name` stays BARE. Overwriting it with the runtime key
-        // here (pre-RUSH-2709) is what leaked `comet-local@endpoint-0` into every
-        // listing and made `status --profile comet-local` miss its own browser.
-        // The key travels as its own argument instead.
-        const resolved = resolveEndpoint(profile, opts.endpointName);
-        const composite = connectionKey(profileName, resolved.name);
-        const effectiveProfile = {
-            ...profile,
-            binary: resolved.binary,
-            targetFilter: resolved.targetFilter,
-        };
+        // Consent gate, before anything is resolved or launched. This is the
+        // authoritative one: gating only the `browser start` COMMAND left the ~18
+        // page verbs that create a browser implicitly (navigate, click, screenshot,
+        // …) able to open a browser on a machine whose owner never opted in.
+        assertRemoteControlAllowedForRequest(opts.fleetRemote, { actor: opts.actor });
+        // Registry decides WHERE. Three outcomes, no fourth: local if this
+        // device declares the name; tunnel to a declaring device otherwise;
+        // fail loud if nobody does. Never auto-create a local browser under a
+        // name that means a logged-in browser somewhere else.
+        const routed = resolveBrowserTarget(profileName, {
+            endpointName: opts.endpointName,
+            probe: opts.probe,
+        });
+        const composite = routed.key;
+        const effectiveProfile = routed.profile;
         const taskId = generateTaskId();
         let taskName;
         if (opts.taskName) {
@@ -345,23 +343,12 @@ export class BrowserService {
             taskName = taskId;
         }
         const taskLabel = deriveTaskLabel({ title: opts.title, url: opts.url });
-        let conn = this.connections.get(composite);
-        let effectiveKey = composite;
-        // If we have a cached connection, confirm it's still usable before any
-        // caller relies on it. A browser killed externally (Cmd-Q, crash, or a
-        // user clearing the profile by hand) leaves a closed WebSocket here.
-        // Without this check the next `cdp.send` throws "CDP connection not
-        // open" and the user has no way to recover short of killing the daemon.
-        if (conn && !(await isConnHealthy(conn))) {
-            try {
-                conn.cdp.close();
-            }
-            catch { /* already closed */ }
-            conn.cleanup?.();
-            this.connections.delete(composite);
-            conn = undefined;
-        }
-        if (conn && conn.electron && conn.tasks.size > 0) {
+        const reused = await this.reuseProfileConnection(profileName, composite, routed.local);
+        let conn = reused?.conn;
+        let effectiveKey = reused?.key ?? composite;
+        // Fork is a local Electron chrome-data mint. Never fork a tunnelled
+        // connection — that would launch a logged-out browser on THIS box.
+        if (conn && routed.local && shouldForkProfile(routed.kind, conn)) {
             if (this.forkingProfiles.has(composite)) {
                 while (this.forkingProfiles.has(composite)) {
                     await new Promise((r) => setTimeout(r, 50));
@@ -388,13 +375,14 @@ export class BrowserService {
             }
         }
         else if (!conn) {
-            conn = await this.connectProfile(effectiveProfile, resolved.target, composite);
-            conn.key = composite;
-            conn.profile = profileName;
-            this.connections.set(composite, conn);
-            await this.applyDefaultDownloadBehavior(conn, composite);
+            adoptLegacyRuntimeIfLocal(routed.local, profileName, composite, getBrowserRuntimeDir());
+            conn = await this.openConnection(effectiveProfile, routed.target, composite, profileName, { persistRemote: !routed.local });
+            effectiveKey = composite;
         }
-        if (conn && !conn.profile)
+        if (!conn) {
+            throw new Error(`Could not connect to profile "${profileName}"`);
+        }
+        if (!conn.profile)
             conn.profile = profileName;
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
@@ -515,7 +503,16 @@ export class BrowserService {
             if (resolved)
                 skill = resolved;
         }
-        return { task: taskId, name: taskName, tabId, profile: profileName, key: effectiveKey, skill };
+        return {
+            task: taskId,
+            name: taskName,
+            tabId,
+            profile: profileName,
+            key: effectiveKey,
+            device: routed.device,
+            picked: routed.picked,
+            skill,
+        };
     }
     /**
      * Reclaim a live page already showing `url` from an ABANDONED task, instead
@@ -668,7 +665,7 @@ export class BrowserService {
     /**
      * Close tasks whose owning agent session is gone, or that have sat untouched
      * past the idle window. The entry point the daemon's periodic tick and
-     * `agents browser gc` both call; the policy lives in `hygiene.ts`.
+     * `agents browser prune` both call; the policy lives in `hygiene.ts`.
      */
     async reapAbandoned(opts = {}) {
         return reapAbandonedTasks(this, opts);
@@ -748,7 +745,7 @@ export class BrowserService {
         return this.stop(taskName);
     }
     async stopProfile(profileRef) {
-        // Connections are keyed by the runtime key `<profile>@<endpoint>` (see
+        // Connections are keyed by the runtime key `<profile>@<device>` (see
         // start()) while callers pass the bare profile name (or, occasionally, an
         // exact key). A plain `connections.get(profileRef)` therefore missed every
         // real remote connection, so `cleanup()` never ran — leaving the SSH tunnel
@@ -1529,8 +1526,9 @@ export class BrowserService {
      * `profileName` is a {@link ProfileName} — a BARE name, never a runtime key.
      * Every candidate is selected by the one rule ({@link keyBelongsToProfile}),
      * and a scoped query that finds no live connection falls through to disk, so
-     * `status --profile comet-local` reports the LIVE `comet-local@endpoint-0`
-     * instead of the empty list it used to return (RUSH-2709).
+     * `status --profile comet-local` reports the LIVE `comet-local@<device>`
+     * (and leftover `comet-local@endpoint-0` dirs) instead of the empty list
+     * it used to return (RUSH-2709).
      */
     async status(profileRef) {
         // Reconnect live browsers after a daemon restart so status is not empty
@@ -2064,14 +2062,24 @@ export class BrowserService {
      * already resolved the endpoint and built the `effectiveProfile` with
      * the per-endpoint binary/targetFilter overrides applied; we just use it.
      *
-     * `key` is the runtime key (`<profile>@<endpoint>`) and is what every on-disk
-     * lookup uses, so per-endpoint pid/port files don't collide when the same app
-     * runs locally and remotely at the same time. It is a SEPARATE argument
-     * because `effectiveProfile.name` stays the bare, user-facing name (RUSH-2709).
+     * `key` is the runtime key (`<profile>@<device>`) and is what every on-disk
+     * lookup uses. It is a SEPARATE argument because `effectiveProfile.name`
+     * stays the bare, user-facing name (RUSH-2709).
      */
-    async connectProfile(effectiveProfile, target, key) {
+    async connectProfile(effectiveProfile, target, key, opts = {}) {
         const existingInfo = getRunningChromeInfo(key);
-        if (existingInfo) {
+        const tunnelled = opts.persistRemote || target.startsWith('ssh:');
+        if (tunnelled) {
+            // A leftover local chrome-data / pid file under this key is the
+            // pre-T2 logged-out browser on THIS box. Attaching localhost CDP
+            // here is the original bug. Only a recorded SSH tunnel is ours to
+            // reuse, and connectSSH already does that via isOwnTunnel.
+            const meta = readProfileRuntimeMeta(key);
+            if (meta && meta.kind !== 'tunnel') {
+                clearProfileRuntime(key);
+            }
+        }
+        else if (existingInfo) {
             try {
                 const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port, 'localhost', effectiveProfile.name);
                 verifyBrowserIdentity(browser, effectiveProfile.browser, existingInfo.port);
@@ -2100,13 +2108,13 @@ export class BrowserService {
                 clearProfileRuntime(key);
             }
         }
-        const conn = await this.connectEndpoint(effectiveProfile, target, key);
+        const conn = await this.connectEndpoint(effectiveProfile, target, key, opts);
         if (!conn) {
             throw new Error(`Could not connect to endpoint ${target} for profile "${effectiveProfile.name}"`);
         }
         return conn;
     }
-    async connectEndpoint(profile, endpoint, key) {
+    async connectEndpoint(profile, endpoint, key, opts = {}) {
         const url = new URL(endpoint);
         if (url.protocol === 'cdp:') {
             const conn = await connectLocal(endpoint, profile, key);
@@ -2123,7 +2131,9 @@ export class BrowserService {
             };
         }
         if (url.protocol === 'ssh:') {
-            const conn = await connectSSH(endpoint, profile, key);
+            const conn = await connectSSH(endpoint, profile, key, {
+                persistRemote: opts.persistRemote,
+            });
             await this.enableDomains(conn.cdp);
             return {
                 cdp: conn.cdp,
@@ -2277,6 +2287,15 @@ export class BrowserService {
      *   - no handle, zero, !createIfMissing → return null (caller reports "nothing to close")
      */
     async resolveOrCreateTask(opts) {
+        // Consent gate — the one chokepoint every drive/mutate verb passes through.
+        // ipc.ts routes each PAGE_RESOLVE_VERB and CLOSE_VERB here via bindTask, so
+        // gating at the top refuses a fleet-remote ATTACH (an explicit --task, or a
+        // lone identity match) exactly as it already refused an implicit CREATE.
+        // Gating only the create branch below left tab-add/navigate/done on an
+        // already-running browser ungated, so a remote caller could drive the
+        // owner's authenticated profile with consent off (RUSH-3064). Read the
+        // per-request marker, never the daemon's env — see remote-control.ts.
+        assertRemoteControlAllowedForRequest(opts.fleetRemote, { actor: opts.actor });
         if (opts.task) {
             const found = await this.findTask(opts.task, opts.profile);
             return { ...found, created: false };
@@ -2310,6 +2329,10 @@ export class BrowserService {
         // Zero matches for this caller.
         if (!opts.createIfMissing)
             return null;
+        // The top-of-function consent gate already refused a fleet-remote create
+        // here — before ensureDefaultBrowserProfile() below can probe local browser
+        // installs and persist an `auto-chrome` profile — so a refused request never
+        // leaves state behind on the target machine.
         // Implicit start on the default / named profile.
         let profileName = opts.profile;
         if (!profileName) {
@@ -2318,13 +2341,19 @@ export class BrowserService {
             profileName = detected.name;
         }
         const started = await this.start(profileName, {
+            fleetRemote: opts.fleetRemote,
             url: opts.url,
             actor: opts.actor,
             launchId: opts.launchId,
             sessionId: opts.sessionId,
             title: opts.title,
         });
-        return { ...(await this.findTask(started.name, started.profile)), created: true };
+        return {
+            ...(await this.findTask(started.name, started.profile)),
+            created: true,
+            picked: started.picked,
+            device: started.device,
+        };
     }
     listTasksForCaller(caller) {
         const out = [];
@@ -2465,7 +2494,15 @@ export class BrowserService {
             return null;
         let resolved;
         try {
-            resolved = resolveEndpoint(profile, endpointFromKey);
+            // Legacy keys encode the preset (`endpoint-0`). New keys encode the
+            // declaring device, which is not a preset name — resolve via registry.
+            if (endpointFromKey && /^endpoint-\d+$/.test(endpointFromKey)) {
+                resolved = resolveEndpoint(profile, endpointFromKey);
+            }
+            else {
+                const routed = resolveBrowserTarget(bare);
+                resolved = { name: routed.device, target: routed.target };
+            }
         }
         catch {
             return null;
@@ -2835,6 +2872,104 @@ export class BrowserService {
         history = history.slice(0, 50);
         await fs.promises.writeFile(historyFile, JSON.stringify(history, null, 2));
     }
+    /**
+     * The cached connection for `key`, or undefined — evicting it first if the
+     * browser died underneath us.
+     *
+     * A browser killed externally (Cmd-Q, crash, a user clearing the profile by
+     * hand) leaves a closed WebSocket in the map. Without this the next
+     * `cdp.send` throws "CDP connection not open" and there is no recovery short
+     * of killing the daemon.
+     */
+    async reuseHealthyConnection(key) {
+        const conn = this.connections.get(key);
+        if (!conn)
+            return undefined;
+        if (await isConnHealthy(conn))
+            return conn;
+        try {
+            conn.cdp.close();
+        }
+        catch { /* already closed */ }
+        conn.cleanup?.();
+        this.connections.delete(key);
+        return undefined;
+    }
+    /**
+     * Reuse a live connection for this profile: the new `<name>@<device>` key
+     * first, then any leftover `<name>@endpoint-N` key still in the map so a
+     * browser started before the key collapse is not abandoned.
+     */
+    async reuseProfileConnection(profileName, preferred, local) {
+        const preferredConn = await this.reuseHealthyConnection(preferred);
+        if (preferredConn)
+            return { conn: preferredConn, key: preferred };
+        // Leftover `@endpoint-N` connections are THIS machine's pre-T2 local
+        // browser. Reusing them on a tunnelled resolve is the original bug.
+        if (!local)
+            return undefined;
+        for (const key of [...this.connections.keys()]) {
+            if (key === preferred)
+                continue;
+            if (!isLegacyEndpointKey(key, profileName))
+                continue;
+            if (parseConnectionKey(key).fork !== undefined)
+                continue;
+            const conn = await this.reuseHealthyConnection(key);
+            if (conn)
+                return { conn, key };
+        }
+        return undefined;
+    }
+    /** Connect a profile at `target`, register it under `key`, and arm downloads. */
+    async openConnection(profile, target, key, profileName, opts = {}) {
+        const conn = await this.connectProfile(profile, target, key, opts);
+        conn.key = key;
+        conn.profile = profileName;
+        this.connections.set(key, conn);
+        await this.applyDefaultDownloadBehavior(conn, key);
+        return conn;
+    }
+    /**
+     * Open a tab for a HUMAN to read, bound to no task.
+     *
+     * That is the entire difference from {@link start}, and it is the point. The
+     * abandoned-task reaper closes a task's tabs when the calling session dies or
+     * after the idle window, but it "deliberately never touches a tab that is not
+     * in `task.tabs`" (hygiene.ts) — so a viewer tab must not be in one, or the
+     * artifact the user is reading vanishes when the agent that rendered it exits.
+     *
+     * Consequently `stop`/`done` do not close it either, which is correct: it is
+     * the user's tab now.
+     */
+    async showUrl(profileName, url, opts = {}) {
+        // Same consent gate as start(): this opens a browser, so a fleet-remote
+        // caller needs the target machine's opt-in.
+        assertRemoteControlAllowedForRequest(opts.fleetRemote, { actor: opts.actor });
+        const routed = resolveBrowserTarget(profileName, {
+            endpointName: opts.endpointName,
+            probe: opts.probe,
+        });
+        const key = routed.key;
+        const effectiveProfile = routed.profile;
+        const reused = await this.reuseProfileConnection(profileName, key, routed.local);
+        let conn = reused?.conn;
+        const effectiveKey = reused?.key ?? key;
+        if (!conn) {
+            adoptLegacyRuntimeIfLocal(routed.local, profileName, key, getBrowserRuntimeDir());
+            conn = await this.openConnection(effectiveProfile, routed.target, key, profileName, { persistRemote: !routed.local });
+        }
+        // createPageTarget refuses Arc with an actionable error rather than crashing it.
+        const created = await this.createPageTarget(conn, { url });
+        this.invalidateTargetCache(conn);
+        return {
+            profile: profileName,
+            key: effectiveKey,
+            tabId: created.targetId,
+            device: routed.device,
+            picked: routed.picked,
+        };
+    }
     async getHistory(limit = 10) {
         const historyFile = path.join(getBrowserRuntimeDir(), 'history.json');
         if (!fs.existsSync(historyFile))

package/dist/lib/browser/sessions-list.d.ts

@@ -32,8 +32,6 @@ export declare function renderBrowserSessions(groups: ProfileArtifacts[]): strin
  * substring match. Returns the absolute path, or null if nothing matched.
  */
 export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
-/** Open a file in the OS default app. Returns true on success. */
-export declare function openArtifact(filePath: string): boolean;
 /** The identity fields this module cares about for one task. */
 export interface TaskIdentity {
     owner?: string;
@@ -139,4 +137,4 @@ export declare function runBrowserSessions(opts: {
     profile?: string;
     open?: string | boolean;
     json?: boolean;
-}): void;
+}): Promise<void>;

package/dist/lib/browser/sessions-list.js

@@ -14,12 +14,12 @@
  * problem (pid registry, the SessionStart hook index, the activity log; see
  * `feed-post.ts` `resolvePostIdentity`), never a second parser.
  */
+import { showFile } from '../open-url.js';
 import * as fs from 'fs';
 import { formatBytes } from '../format.js';
 // Re-exported for the picker, which lists artifacts from this module's rows.
 export { formatBytes };
 import * as path from 'path';
-import { spawnSync } from 'child_process';
 import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
 import { formatRelativeTime } from '../session/relative-time.js';
 import { getSessionById, listBrowserSessionRecords, pruneToolSessions } from '../session/db.js';
@@ -158,19 +158,6 @@ export function resolveArtifact(groups, selector) {
     const hit = all.find((a) => a.name === selector) ?? all.find((a) => a.name.includes(selector));
     return hit ? hit.path : null;
 }
-/** Open a file in the OS default app. Returns true on success. */
-export function openArtifact(filePath) {
-    const openers = process.platform === 'darwin'
-        ? [['open', [filePath]]]
-        : process.platform === 'win32'
-            ? [['cmd', ['/c', 'start', '""', filePath]]]
-            : [['xdg-open', [filePath]], ['gnome-open', [filePath]]];
-    for (const [cmd, args] of openers) {
-        if (spawnSync(cmd, args, { stdio: 'ignore' }).status === 0)
-            return true;
-    }
-    return false;
-}
 /**
  * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
  * keyed by task name. A task's entry is deleted on `agents browser stop` (see
@@ -380,7 +367,7 @@ export function matchesBrowserSessionRow(row, query) {
  * `open` is the Commander value for `--open [selector]`: undefined when the flag
  * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
  */
-export function runBrowserSessions(opts) {
+export async function runBrowserSessions(opts) {
     const groups = listBrowserSessions(opts.profile);
     if (opts.open !== undefined && opts.open !== false) {
         const selector = opts.open === true ? 'latest' : opts.open;
@@ -390,7 +377,7 @@ export function runBrowserSessions(opts) {
             process.exit(1);
         }
         console.log(target);
-        if (!openArtifact(target)) {
+        if ((await showFile(target)).via === 'none') {
             console.error(`Could not open ${target}`);
             process.exit(1);
         }

package/dist/lib/browser/task-index.d.ts

@@ -0,0 +1,70 @@
+export interface TaskBinding {
+    device: string;
+    profile?: string;
+    url?: string;
+    sessionId?: string;
+    launchId?: string;
+    createdAt: number;
+}
+export type TaskIndex = Record<string, TaskBinding>;
+export declare const REJECT_DEVICE_MESSAGE: string;
+export type TaskRoute = {
+    kind: 'proceed';
+    task?: string;
+    device: string;
+} | {
+    kind: 'unknown';
+    task: string;
+    message: string;
+} | {
+    kind: 'ambiguous';
+    message: string;
+} | {
+    kind: 'reject-device';
+    message: string;
+};
+export declare function taskIndexPath(): string;
+export declare function readTaskIndex(): TaskIndex;
+export declare function getTaskBinding(name: string): TaskBinding | undefined;
+export declare function listTaskBindings(): Array<{
+    name: string;
+} & TaskBinding>;
+export declare function bindTask(name: string, binding: TaskBinding): void;
+export declare function updateTaskBinding(name: string, patch: Partial<TaskBinding>): void;
+export declare function unbindTask(name: string): void;
+/** Drop every binding recorded under this profile (after `stop --profile` / gc). */
+export declare function unbindTasksForProfile(profile: string): void;
+export declare function tasksForCaller(sessionId?: string, launchId?: string): Array<{
+    name: string;
+} & TaskBinding>;
+export declare function formatOpenTaskList(entries: Array<{
+    name: string;
+} & TaskBinding>, now?: number): string;
+export declare function unknownTaskMessage(name: string, entries?: ({
+    name: string;
+} & TaskBinding)[]): string;
+export declare function ambiguousTasksMessage(entries: Array<{
+    name: string;
+} & TaskBinding>): string;
+/**
+ * Decide where a page verb should run.
+ *
+ * `--device` on a later verb is always rejected (bind it at start).
+ * A named task that is not in the local index fails loud with the open-task
+ * list. Two or more tasks for this caller, with no `--task`, fail the same way.
+ * Zero matches with no `--task` proceeds locally — the daemon still resolves
+ * from caller identity for the first implicit create.
+ */
+export declare function resolveTaskRoute(opts: {
+    task?: string;
+    device?: string;
+    sessionId?: string;
+    launchId?: string;
+    self?: string;
+}): TaskRoute;
+/**
+ * The daemon sandboxes screenshot writes to the browser runtime dir, so `-o`
+ * outside that dir is ignored there. The CLI process honors `-o` by copying
+ * the captured file to the requested path. Same path → no copy.
+ */
+export declare function honorScreenshotOutput(requested: string | undefined, daemonPath: string): string;