@phnx-labs/agents-cli 1.22.116 → 1.22.118

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

@@ -1,266 +0,0 @@
-import * as net from 'net';
-import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
-import { launchBrowser, getPortOccupant, getProcessUserDataDir, storeOccupant, storeRelaunchCommand } from '../chrome.js';
-import { parseEndpointUrl, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir } from '../profiles.js';
-/**
- * Cheap TCP-level "is something bound here?" probe. Used as a fallback when
- * `getPortOccupant()` (lsof-based) misses the process — Comet and other
- * Electron apps sometimes hold a TCP socket that lsof's `-sTCP:LISTEN` filter
- * doesn't report. If anything ACKs the connection, we treat the port as taken
- * and surface a friendly error instead of silently auto-launching a fresh
- * browser that would then conflict.
- */
-async function probeTcpBound(port, host = '127.0.0.1', timeoutMs = 500) {
-    return new Promise((resolve) => {
-        const sock = net.createConnection({ port, host });
-        const cleanup = () => {
-            sock.removeAllListeners();
-            sock.destroy();
-        };
-        const timer = setTimeout(() => { cleanup(); resolve(false); }, timeoutMs);
-        sock.once('connect', () => { clearTimeout(timer); cleanup(); resolve(true); });
-        sock.once('error', () => { clearTimeout(timer); cleanup(); resolve(false); });
-    });
-}
-/**
- * Local-port listeners we refuse to attach through. These forward CDP traffic
- * to a remote host — silently using them would let a `cdp://127.0.0.1:N`
- * profile drive a browser on a different machine without the caller realizing.
- */
-const TUNNEL_PROCESS_NAMES = new Set(['ssh', 'autossh', 'mosh-client', 'socat']);
-function isTunnelProcess(command) {
-    return TUNNEL_PROCESS_NAMES.has(command.toLowerCase());
-}
-/**
- * Arc is single-instance: relaunching the Arc binary with a fresh
- * `--user-data-dir` does not create a second debuggable process — macOS routes
- * the launch to the running Arc, which was started with no debug port, so the
- * spawn produces a stray window and no CDP endpoint (issue #2779). agents
- * browser therefore ATTACHES to the user's running Arc and never launches its
- * own. When the running Arc exposes no CDP endpoint on the profile's port, we
- * fail loud with the one relaunch that fixes it rather than silently spawning a
- * duplicate. Exported so the contract is unit-testable without a real Arc.
- */
-export function arcAttachRequiredError(profileName, port) {
-    return new Error(`Arc is not exposing a CDP endpoint on cdp://127.0.0.1:${port} for profile ` +
-        `"${profileName}". Arc is single-instance — agents browser attaches to your ` +
-        `RUNNING Arc and never launches a second one, so it will not start an isolated ` +
-        `Arc for you. Quit Arc, then relaunch it with remote debugging on this port:\n` +
-        `  open -a Arc --args --remote-debugging-port=${port}\n` +
-        `and retry. The port must match the profile's endpoint (\`agents browser profiles list\`).`);
-}
-/**
- * The loud error an ATTACH-ONLY profile raises when nothing debuggable is on its
- * port (PHNX-3967). Same contract as {@link arcAttachRequiredError}, generalized
- * to any browser: agents attach to a browser the user already started and NEVER
- * spawn a rival window, so instead of falling through to `launchBrowser` (which
- * would produce the second, logged-out dock tile this ticket set out to end) we
- * fail loud with the exact relaunch that makes the canonical instance
- * attachable — pinned to the profile's DURABLE `--user-data-dir` so the one-time
- * sign-in persists. Exported so the contract is unit-testable without a browser.
- */
-export function attachOnlyRequiredError(profile, port) {
-    if (profile.browser === 'arc')
-        return arcAttachRequiredError(profile.name, port);
-    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
-    const dataDir = resolveProfileDataDir(profile);
-    return new Error(`Profile "${profile.name}" is attach-only and nothing is serving the Chrome ` +
-        `DevTools Protocol on cdp://127.0.0.1:${port}. agents browser attaches to the ` +
-        `${app} you already started and never launches a second one, so it will not spawn ` +
-        `a rival window (that is the duplicate, logged-out tile this profile exists to ` +
-        `prevent). Launch the canonical ${app} with remote debugging on its durable data dir:\n` +
-        `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${dataDir}\n` +
-        `and retry. Keep signing in once in that window — the data dir is durable, so the ` +
-        `login survives quit+relaunch.`);
-}
-/**
- * The loud error an attach-only profile raises when a browser IS serving CDP on
- * its port but is a FOREIGN instance — its `--user-data-dir` is not the profile's
- * durable dir (PHNX-3967). This closes the port-squat: a logged-out `/tmp/...`
- * Comet answering CDP on the canonical port passes the browser-FAMILY identity
- * check, so without an ownership check agents would drive it as if it were the
- * credentialed browser. Rather than adopt the squatter we reject it and name the
- * fix. Exported for unit testing.
- */
-export function foreignInstanceError(profile, port, runningDataDir, pid) {
-    const expected = resolveProfileDataDir(profile);
-    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
-    return new Error(`Attach-only ownership check failed for profile "${profile.name}" on ` +
-        `cdp://127.0.0.1:${port}: a ${app} is serving CDP there (pid ${pid}) but it is ` +
-        `running a FOREIGN user-data-dir\n` +
-        `  running:  ${runningDataDir}\n` +
-        `  expected: ${expected}\n` +
-        `so it is not this profile's credentialed browser. agents will not drive it. Close ` +
-        `that instance (\`kill ${pid}\`), then relaunch the canonical ${app}:\n` +
-        `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${expected}`);
-}
-/**
- * The loud error a profile pinned to the owner's own store (PHNX-4042) raises
- * when a browser already holds that store without a debug port. Launching on it
- * would not open a second browser: Chromium hands the arguments to the running
- * instance and exits, the port never binds, and the agent would wait out a
- * timeout while the owner sees a stray window. Exported for unit testing.
- */
-export function storeInUseError(profile, port, pid) {
-    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
-    const dataDir = resolveProfileDataDir(profile);
-    return new Error(`Profile "${profile.name}" is pinned to ${dataDir}, and a ${app} (pid ${pid}) already has that ` +
-        `store open without remote debugging, so nothing serves the Chrome DevTools Protocol on ` +
-        `cdp://127.0.0.1:${port}. agents browser will not launch a second ${app} on the same store. ` +
-        `Quit that ${app}, then relaunch it with remote debugging:\n` +
-        `  ${storeRelaunchCommand(profile.browser, port, dataDir, profile.profileDirectory)}\n` +
-        `and retry. Your logins stay: the store is the one you already use.`);
-}
-/**
- * Prefix every ownership-rejection message carries, so `connectLocal`'s catch can
- * re-throw it verbatim instead of misreading it as "attach failed, launch fresh".
- */
-const OWNERSHIP_REJECTION_PREFIX = 'Attach-only ownership check failed';
-/**
- * Verify the browser serving CDP on `port` belongs to this attach-only profile,
- * by comparing its live `--user-data-dir` to the profile's durable dir
- * (PHNX-3967). No-op for a `launch`-policy profile. When an occupant IS present
- * but its data dir can't be read, fail LOUD rather than open: a canonical Comet
- * this profile is meant to attach to was launched by the user with the durable
- * `--user-data-dir` and is readable via `ps`, so an unreadable occupant is the
- * suspicious case, not a legitimate one — driving it would be the exact
- * port-squat this guard exists to stop.
- */
-function verifyEndpointOwnership(profile, port) {
-    // Attach-only profiles and profiles pinned to the owner's own store
-    // (PHNX-4042) both name the exact user-data dir a running instance must have.
-    if (!isAttachOnlyProfile(profile) && !profile.userDataDir)
-        return;
-    // Arc is the user's single running instance under its own default data dir; it
-    // has no managed durable dir to compare against and no /tmp-squat vector.
-    if (profile.browser === 'arc')
-        return;
-    const occupant = getPortOccupant(port);
-    if (!occupant)
-        return;
-    const expected = resolveProfileDataDir(profile);
-    const runningDataDir = getProcessUserDataDir(occupant.pid);
-    if (!runningDataDir) {
-        throw new Error(`${OWNERSHIP_REJECTION_PREFIX} for profile "${profile.name}" on cdp://127.0.0.1:${port}: ` +
-            `a process (pid ${occupant.pid}) is serving CDP there but its --user-data-dir could not be ` +
-            `read, so ownership can't be confirmed. Refusing to attach to an unverified instance. If ` +
-            `this is your canonical browser, relaunch it with --user-data-dir=${expected} so the ` +
-            `attach-only guard can verify it.`);
-    }
-    if (normalizeDataDir(runningDataDir) !== normalizeDataDir(expected)) {
-        throw foreignInstanceError(profile, port, runningDataDir, occupant.pid);
-    }
-}
-export async function connectLocal(endpoint, profile, 
-/**
- * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,
- * pid, and port files are stored under. Separate from `profile.name`, which
- * stays the bare user-facing name and appears only in messages (RUSH-2709).
- */
-key) {
-    const url = new URL(endpoint);
-    if (url.protocol !== 'cdp:') {
-        throw new Error(`Invalid local endpoint: ${endpoint}`);
-    }
-    // Share the parser with the SSH driver and the collision-detection code
-    // path so `cdp://host:N` and `cdp://host?port=N` behave identically.
-    const parsed = parseEndpointUrl(endpoint);
-    const port = parsed?.port ?? 9222;
-    // Refuse to attach through an SSH tunnel before we even try to speak CDP.
-    // `verifyBrowserIdentity` only inspects what comes back over the wire — it
-    // can't tell whether the browser actually lives on this machine or on the
-    // far end of an `ssh -L` tunnel. A stale tunnel from a prior session
-    // (common when an SSH-driven profile is deleted before the daemon exits)
-    // will silently hijack any "local" profile bound to the same port.
-    const preOccupant = getPortOccupant(port);
-    if (preOccupant && isTunnelProcess(preOccupant.command)) {
-        throw new Error(`Port ${port} is held by ${preOccupant.command} (pid ${preOccupant.pid}), an SSH ` +
-            `tunnel forwarding to a remote host. Profile "${profile.name}" is configured as ` +
-            `local (${endpoint}) but traffic would round-trip to another machine. Either kill ` +
-            `the tunnel (\`kill ${preOccupant.pid}\`) and retry, or switch the profile to an ` +
-            `ssh:// endpoint to drive the remote browser explicitly.`);
-    }
-    try {
-        const { wsUrl, browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
-        verifyBrowserIdentity(browser, profile.browser, port);
-        // Ownership beyond browser FAMILY (PHNX-3967): a foreign /tmp Comet answers
-        // CDP on the canonical port and passes verifyBrowserIdentity, so before we
-        // adopt the endpoint confirm its --user-data-dir is this profile's durable
-        // dir. Rejects the port-squatter loudly instead of driving it.
-        verifyEndpointOwnership(profile, port);
-        const cdp = new CDPClient();
-        await cdp.connect(wsUrl);
-        return { cdp, port, pid: 0 };
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
-            throw err;
-        }
-        // An ownership rejection is a definitive answer — never fall through to a
-        // fresh launch or a generic port message. Re-throw it verbatim.
-        if (err instanceof Error && err.message.startsWith(OWNERSHIP_REJECTION_PREFIX)) {
-            throw err;
-        }
-        // An attach-only profile reached the catch, so the attach above failed:
-        // nothing debuggable is on this port. Never fall through to launchBrowser —
-        // that would spawn the duplicate/stray-window this ticket set out to end
-        // (Arc: #2779, PHNX-2399; Comet: PHNX-3967). Fail loud with the relaunch that
-        // makes the canonical instance attachable.
-        if (isAttachOnlyProfile(profile)) {
-            throw attachOnlyRequiredError(profile, port);
-        }
-        // Distinguish "nothing listening on this port" (fine to launch fresh) from
-        // "something is listening but it's not a debuggable browser" (bail loudly —
-        // silently launching on a different port leads to confusing `pid 0` and
-        // `CDP connection not open` errors downstream).
-        const occupant = getPortOccupant(port);
-        if (occupant) {
-            throw new Error(`Port ${port} is occupied by ${occupant.command} (pid ${occupant.pid}) but is ` +
-                `not serving the Chrome DevTools Protocol. Either stop that process ` +
-                `(\`kill ${occupant.pid}\`) or restart it with \`--remote-debugging-port=${port}\` ` +
-                `so profile "${profile.name}" can attach.`);
-        }
-        // lsof-based detection misses some Electron-family processes (Comet, custom
-        // chrome wrappers). Cheap TCP probe as a safety net: if something ACKs a
-        // connect, the port is bound — bail loudly with the profile name + endpoint
-        // rather than silently launching a duplicate browser.
-        if (await probeTcpBound(port)) {
-            throw new Error(`Profile "${profile.name}" is configured for cdp://127.0.0.1:${port}, ` +
-                `but something is already bound to that port without serving the Chrome ` +
-                `DevTools Protocol. If that's your browser running without remote debugging, ` +
-                `quit it and relaunch with \`--remote-debugging-port=${port}\`. Otherwise, ` +
-                `update the profile to a free port (\`agents browser profiles list\`).`);
-        }
-        // A store-pinned profile launches on the owner's store only while nothing
-        // holds it; a browser already open there without a port must be relaunched
-        // by the owner, never doubled (PHNX-4042).
-        if (profile.userDataDir) {
-            const holder = storeOccupant(profile.userDataDir);
-            if (holder)
-                throw storeInUseError(profile, port, holder.pid);
-        }
-        const newPort = port;
-        const chromeOpts = {
-            ...profile.chrome,
-            viewport: profile.viewport,
-            // A discovered native profile launches the owner's browser on its own
-            // store: one window for the owner and agents, logins intact (PHNX-4042).
-            ...(profile.userDataDir
-                ? { userDataDir: profile.userDataDir, profileDirectory: profile.profileDirectory }
-                : {}),
-        };
-        let launched;
-        try {
-            launched = await launchBrowser(key, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary, profile.electron === true);
-        }
-        catch (launchErr) {
-            const reason = launchErr instanceof Error ? launchErr.message : String(launchErr);
-            throw new Error(`Could not start ${profile.browser} for profile "${profile.name}" on port ${newPort}: ${reason}. ` +
-                `Check that the browser binary is installed (\`agents browser profiles list\`) and ` +
-                `that no other process is holding the port.`);
-        }
-        const cdp = new CDPClient();
-        await cdp.connect(launched.wsUrl);
-        return { cdp, port: newPort, pid: launched.pid };
-    }
-}

package/dist/lib/browser/drivers/ssh.d.ts

@@ -1,120 +0,0 @@
-import { CDPClient } from '../cdp.js';
-import type { BrowserProfile, ConnectionKey } from '../types.js';
-import { shellQuote } from '../../ssh-exec.js';
-export { shellQuote };
-export interface SSHConnection {
-    cdp: CDPClient;
-    port: number;
-    pid: number;
-    cleanup: () => void;
-}
-/**
- * Which shell dialect the *remote* host speaks. Selected per-endpoint via the
- * `&os=windows` query param on an `ssh://` target. POSIX is the default — the
- * historical behavior for macOS/Linux remotes. Windows remotes run OpenSSH
- * Server with cmd.exe as the default shell, so the launch/teardown command
- * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
- */
-type RemoteOs = 'windows' | 'posix';
-interface SSHConnectOptions {
-    /**
-     * Attach to a browser another device already declared (identity-bearing or
-     * a fungible name we don't declare here). Do not launch a fresh remote
-     * chrome-data, and do not kill that browser when the tunnel closes — it
-     * holds the logins the caller is trying to reach.
-     */
-    persistRemote?: boolean;
-}
-/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
-export declare function persistRemoteLifecycle(persistRemote: boolean): {
-    launchRemote: boolean;
-    killOnCleanup: boolean;
-};
-export declare function connectSSH(endpoint: string, profile: BrowserProfile, 
-/**
- * Runtime key (`<profile>@<device>`) this connection is stored under. It
- * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
- * name and appears only in messages (RUSH-2709).
- */
-key: ConnectionKey, opts?: SSHConnectOptions): Promise<SSHConnection>;
-/**
- * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
- * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn
- * → Windows sshd → cmd.exe with zero escaping hazards (hand-quoted
- * `powershell -Command "…"` is fragile the moment a path or URL is involved).
- */
-export declare function encodePowerShell(script: string): string;
-/**
- * The PowerShell that launches the browser on a Windows remote. Three hard
- * requirements shaped this:
- *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
- *      the session's job tree on disconnect, which reaps both `start /B` and
- *      `Start-Process` children (verified against a real box). A scheduled
- *      task runs under the Task Scheduler service, so the process survives
- *      after we drop the ssh connection and reconnect over the CDP tunnel.
- *   2. The browser must run in the user's INTERACTIVE session. The previous
- *      WMI `Win32_Process.Create` launch also survived disconnect, but it
- *      spawned Edge in session 0 (the services session): the CDP socket bound
- *      and accepted, yet the DevTools server never initialized — every
- *      /json/version probe hung forever and DevToolsActivePort was never
- *      written (verified against a real box, Edg/150). A scheduled task
- *      registered and started by the logged-on user runs in that user's
- *      interactive session, where DevTools comes up normally.
- *   3. A distinct `--user-data-dir` so a fresh instance bound to the debugging
- *      port comes up even when the user already has Edge open.
- * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
- * registry at runtime rather than relying on a bare `msedge` name. The task is
- * unregistered immediately after start — the browser keeps running; nothing
- * lingers in the scheduler.
- */
-export declare function buildWindowsLaunchScript(browserType: string, port: number, customBinary?: string): string;
-/**
- * The PowerShell that kills whatever holds the CDP port on a Windows remote.
- * Tree-kill (`taskkill /T`), not `Stop-Process`: Chromium is multi-process, and
- * killing only the port-owning main process orphans its children. The orphans
- * keep the profile's SingletonLock, so every later launch against the same
- * `--user-data-dir` delegates to the zombie tree, exits, and never binds the
- * CDP port — `browser start --device` then fails until someone hand-cleans the
- * box (found live on win-mini by the #561 e2e suite).
- */
-export declare function buildWindowsKillScript(port: number): string;
-/**
- * Build the remote command that launches the browser detached with a CDP port.
- * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
- * starts it via an interactive one-shot scheduled task (encoded PowerShell)
- * so it survives the ssh session AND serves CDP (session 0 never does).
- */
-export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string, port: number, customBinary?: string): string;
-/**
- * Build the remote command that kills whatever holds the CDP port.
- * POSIX uses `lsof`+`kill`; Windows uses encoded PowerShell
- * (Get-NetTCPConnection → Stop-Process).
- */
-export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
-export declare function ensureRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
-/**
- * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
- * task-launched (Windows) / detached (posix) browser process is not orphaned when
- * the ssh tunnel is torn down — killing only the tunnel left it running on
- * win-mini after every `browser stop`. Best-effort: never rejects.
- */
-export declare function killRemoteBrowser(user: string, host: string, remoteOs: RemoteOs, port: number): Promise<void>;
-/**
- * Identify whether a pid listening on our target local port is an SSH
- * tunnel WE would have spawned for `host:remotePort`. Used so that two
- * agents-browser invocations of the same SSH profile share a tunnel
- * rather than failing the second one with "port in use".
- *
- * Best-effort match against the ssh -L command line via `ps`. If we
- * can't read the cmd or the args don't look like ours, treat as not-ours.
- *
- * Windows has no `ps`, so the POSIX branch below always throws there and every
- * reuse check returned false — the second invocation to the same host:port then
- * failed "port in use". On win32 we instead reuse the netstat -ano + tasklist
- * occupant lookup (getPortOccupant): the tunnel binds `remotePort` locally
- * (localPort === remotePort in the caller), so the pid holding that port is our
- * ssh.exe. tasklist only exposes the image name, not the full command line, so
- * we can't match host/remotePort as tightly as the POSIX branch — an ssh
- * process on our exact local port is our tunnel in practice.
- */
-export declare function isOwnTunnel(pid: number, host: string, remotePort: number): boolean;