@phnx-labs/agents-cli 1.18.4 → 1.18.5

package/dist/lib/browser/profiles.js

@@ -21,6 +21,8 @@ function configToProfile(name, config) {
         chrome: config.chrome,
         secrets: config.secrets,
         viewport: config.viewport,
+        logDir: config.logDir,
+        logHost: config.logHost,
     };
 }
 function profileToConfig(profile) {
@@ -44,6 +46,10 @@ function profileToConfig(profile) {
         config.secrets = profile.secrets;
     if (profile.viewport)
         config.viewport = profile.viewport;
+    if (profile.logDir)
+        config.logDir = profile.logDir;
+    if (profile.logHost)
+        config.logHost = profile.logHost;
     return config;
 }
 export async function listProfiles() {
@@ -60,14 +66,45 @@ export async function getProfile(name) {
     return configToProfile(name, config);
 }
 /**
- * Find a port in 9222–9399 that is not already claimed by another profile
- * and is not currently in use by any OS process.
+ * Compute the LOCAL port a profile will occupy at runtime:
+ *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
+ *   - `ssh://host?port=N` → N (the SSH tunnel binds local N → remote N now)
+ *   - `ws[s]://`, `http[s]://` → undefined (we don't claim a local port)
+ *
+ * This is what callers should compare to detect collisions; the (host,
+ * port) tuple is no longer enough because SSH profiles do compete with
+ * cdp:// profiles for local ports under the new tunnel scheme.
+ */
+export function effectiveLocalPort(profile) {
+    const presets = getEndpointPresets(profile);
+    const firstName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
+        ? profile.defaultEndpoint
+        : Object.keys(presets)[0];
+    if (!firstName)
+        return undefined;
+    const target = presets[firstName].target;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'cdp:' && url.protocol !== 'ssh:')
+        return undefined;
+    return parseEndpointUrl(target)?.port;
+}
+/**
+ * Find a port in 9222–9399 that is not already claimed by ANY existing
+ * profile (cdp:// or ssh://) and is not in use by any OS process. The
+ * SSH change to bind locally on `?port=N` means we no longer get to
+ * skip remote profiles in this scan.
  */
 export async function findFreeProfilePort() {
     const profiles = await listProfiles();
     const usedByProfile = new Set();
     for (const p of profiles) {
-        const port = extractConfiguredPort(p);
+        const port = effectiveLocalPort(p);
         if (port !== undefined)
             usedByProfile.add(port);
     }
@@ -90,15 +127,20 @@ export async function createProfile(profile) {
     if (meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
-    // Check for port collision with existing profiles
-    const newPort = extractConfiguredPort(profile);
-    if (newPort !== undefined && meta.browser) {
+    // Collision check. Every CDP/SSH profile ends up listening on (or
+    // tunneling to) the same LOCAL port number as the one configured in the
+    // endpoint URL — SSH profiles now reuse `?port=N` locally so we no
+    // longer need to scope by host. Two profiles that would need the same
+    // local port can't both run at the same time.
+    const newLocal = effectiveLocalPort(profile);
+    if (newLocal !== undefined && meta.browser) {
         for (const [existingName, existingConfig] of Object.entries(meta.browser)) {
             const existingProfile = configToProfile(existingName, existingConfig);
-            const existingPort = extractConfiguredPort(existingProfile);
-            if (existingPort === newPort) {
-                throw new Error(`Port ${newPort} is already used by profile "${existingName}". ` +
-                    `Each profile must own a unique port. Use a different port or omit --endpoint to auto-assign.`);
+            const existingLocal = effectiveLocalPort(existingProfile);
+            if (existingLocal === newLocal) {
+                throw new Error(`Local port ${newLocal} is already used by profile "${existingName}". ` +
+                    `Each profile must own a unique local port (SSH tunnels now bind ` +
+                    `to their configured port locally too). Pick a different port.`);
             }
         }
     }
@@ -181,17 +223,34 @@ export function resolveEndpoint(profile, endpointName) {
     };
 }
 /**
- * Extract the port intended by the profile's default endpoint.
+ * Extract the (host, port) pair intended by the profile's default endpoint.
  * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Ports are scoped by host: a `cdp://127.0.0.1:9222` profile (local Chrome on
+ * this machine) and an `ssh://mac-mini:9222` profile (Comet on mac-mini)
+ * point at different physical ports — the host disambiguates them.
+ *
+ * Accepts both `scheme://host:port` and `scheme://host?port=N` shapes (the
+ * latter is the documented form in `types.ts` for `ssh://`). Without this,
+ * `ssh://mac-mini?port=18805` would silently fall back to 9222 and every
+ * `?port=`-style SSH profile would collide on creation.
  */
-export function extractConfiguredPort(profile) {
+export function extractConfiguredEndpoint(profile) {
     const presets = getEndpointPresets(profile);
     const firstName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
         ? profile.defaultEndpoint
         : Object.keys(presets)[0];
     if (!firstName)
         return undefined;
-    const endpoint = presets[firstName].target;
+    return parseEndpointUrl(presets[firstName].target);
+}
+/**
+ * Shared endpoint parser used by both the collision-detection code path and
+ * the connection drivers. Returning a single normalized `(host, port)` here
+ * keeps `extractConfiguredEndpoint` and the SSH driver from drifting on URL
+ * conventions (which is how `?port=N` ended up being silently ignored).
+ */
+export function parseEndpointUrl(endpoint) {
     let url;
     try {
         url = new URL(endpoint);
@@ -199,11 +258,56 @@ export function extractConfiguredPort(profile) {
     catch {
         return undefined;
     }
-    if (url.port)
-        return parseInt(url.port, 10);
-    if (url.protocol === 'cdp:')
-        return 9222;
-    if (url.protocol === 'ssh:')
-        return 9222;
+    const host = normalizeHost(url.hostname, url.protocol);
+    if (!host)
+        return undefined;
+    const port = extractPortFromUrl(url);
+    if (port !== undefined)
+        return { host, port };
+    // SSH endpoints tunnel to a remote port AND bind that same port locally,
+    // so they do "own" a local port — the host-scoped collision check used
+    // to disagree, but we want the local-port-scoped semantics now.
+    if (url.protocol === 'cdp:' || url.protocol === 'ssh:')
+        return { host, port: 9222 };
+    return undefined;
+}
+function extractPortFromUrl(url) {
+    if (url.port) {
+        const n = parseInt(url.port, 10);
+        if (Number.isFinite(n))
+            return n;
+    }
+    // `scheme://host?port=N` — the form documented for SSH endpoints in
+    // `types.ts`. WHATWG URL parsing surfaces it via searchParams only.
+    const qp = url.searchParams.get('port');
+    if (qp) {
+        const n = parseInt(qp, 10);
+        if (Number.isFinite(n))
+            return n;
+    }
     return undefined;
 }
+/**
+ * Extract the port intended by the profile's default endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Note: this loses the host dimension — for collision detection use
+ * `extractConfiguredEndpoint` instead, which returns the (host, port) pair.
+ */
+export function extractConfiguredPort(profile) {
+    return extractConfiguredEndpoint(profile)?.port;
+}
+function normalizeHost(hostname, protocol) {
+    if (!hostname) {
+        // cdp:// and ssh:// without an explicit host imply localhost.
+        if (protocol === 'cdp:' || protocol === 'ssh:')
+            return '127.0.0.1';
+        return undefined;
+    }
+    if (hostname === 'localhost')
+        return '127.0.0.1';
+    return hostname;
+}
+export function isLocalHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}

package/dist/lib/browser/runtime-state.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Per-profile runtime files we persist under
+ * `~/.agents/.cache/browser/<composite>/`:
+ *
+ *  - `pid`     — child process ID we spawned (or 0 if attached to an
+ *                already-running browser)
+ *  - `port`    — CDP port we ended up speaking on
+ *  - `command` — basename of the executable so we can defend against pid
+ *                reuse (`process.kill(pid, 0)` only proves *some* process
+ *                with that id exists; if the OS recycled it for an
+ *                unrelated daemon, we'd happily attach to garbage)
+ *  - `meta.json` — richer record: which daemon spawned us, when, the
+ *                user-data-dir we wrote into, optional tunnel PID. This
+ *                is the file the orphan reaper reads on daemon startup.
+ *  - `tasks.json` — open task state (managed elsewhere by service.ts)
+ *
+ * The one-value-per-file fields are kept for backward compat with older
+ * builds; `meta.json` is additive and consulted preferentially.
+ */
+export interface ProfileRuntime {
+    pid: number;
+    port: number;
+    command?: string;
+    /** Full path of the user-data-dir we passed to --user-data-dir, used by the reaper to confirm. */
+    userDataDir?: string;
+    /** PID of the daemon that spawned this. When the daemon dies, the next one reaps. */
+    daemonPid?: number;
+    /** Wall-clock time of spawn — useful for diagnostics and TTL-based cleanup. */
+    spawnedAt?: number;
+    /** What kind of process: 'browser' (Chrome-family), 'electron' (Notion etc.), or 'tunnel' (ssh -L). */
+    kind?: 'browser' | 'electron' | 'tunnel';
+    /** Local ssh -L PID, if this profile is SSH-backed. Distinct from `pid` (which is the remote browser, normally 0). */
+    tunnelPid?: number;
+}
+/**
+ * Save the runtime record atomically. We write the legacy one-value-per-
+ * file fields plus a JSON meta blob so future code can read either.
+ * The cache directory may not exist yet (first launch); we create it.
+ */
+export declare function writeProfileRuntime(profileName: string, runtime: ProfileRuntime): void;
+/** Read just the JSON meta record. Returns null when absent or malformed. */
+export declare function readProfileRuntimeMeta(profileName: string): ProfileRuntime | null;
+/**
+ * Read the runtime triple. Returns null when the files are missing OR when
+ * the recorded pid no longer points at the same process we launched —
+ * stale data is auto-cleaned to keep the next caller from acting on it.
+ */
+export declare function readProfileRuntime(profileName: string): ProfileRuntime | null;
+/** Remove the pid/port/command/meta files. Leaves chrome-data + tasks.json intact. */
+export declare function clearProfileRuntime(profileName: string): void;
+/**
+ * Recursively remove the whole profile cache (chrome-data, tasks.json,
+ * everything). Used by `profiles delete` so an old profile name doesn't
+ * leak its history into a freshly-recreated one.
+ */
+export declare function removeProfileCache(profileName: string): void;
+/**
+ * Find every cache directory belonging to a given profile. The composite
+ * naming (`<name>@<endpoint>`) means a single agents-cli profile can have
+ * multiple runtime dirs side by side; this finds them all plus the legacy
+ * non-composite dir from older builds.
+ */
+export declare function listProfileCacheDirs(profileName: string): string[];
+/**
+ * `process.kill(pid, 0)` answers "is a process with this id alive?" — but
+ * pid reuse is real on long-uptime machines, and a stale cache pointing
+ * at a since-reassigned pid would happily call the imposter ours.
+ *
+ * Strategy: if we recorded the executable basename when we launched, ask
+ * `ps` what command the live pid is running and compare. No command on
+ * record means we fall back to the existence check (older cache entries
+ * or `pid:0` for "attached to an externally-launched browser").
+ */
+export declare function isProcessAlive(pid: number, expectedCommand?: string): boolean;
+/**
+ * Snapshot of one tracked profile, suitable for `agents browser ps` output.
+ * Combines the on-disk meta record with live-process probes so callers can
+ * tell at a glance which entries are alive, stale, or have outright leaked.
+ */
+export interface ProfileSnapshot {
+    /** Composite name as the cache dir is keyed: `<profile>` or `<profile>@<endpoint>`. */
+    name: string;
+    /** Absolute path of the cache dir. */
+    dir: string;
+    meta: ProfileRuntime | null;
+    /** Live-process probe: does the recorded pid still exist + match command? */
+    pidAlive: boolean;
+    /** Live-process probe for the tunnel pid (SSH profiles). */
+    tunnelAlive: boolean;
+    /** True iff the daemon that started this is still alive. False == orphaned. */
+    daemonAlive: boolean;
+    /** Number of tasks recorded in tasks.json (open browser tabs). */
+    taskCount: number;
+}
+/**
+ * Read every profile cache directory and produce a structured snapshot.
+ * Works without the daemon — `agents browser ps` uses this to render a
+ * complete state view even when the IPC server is down. The caller can
+ * post-process to detect conflicts (e.g. two profiles with the same port,
+ * or a port someone else is listening on).
+ */
+export declare function listAllProfileSnapshots(): ProfileSnapshot[];
+/**
+ * Reap browser + tunnel processes spawned by daemons that no longer exist.
+ * Call once on daemon startup. The idea: every process we spawn records
+ * its daemonPid in meta.json. If that daemon is dead (crashed, SIGKILL),
+ * its children were left rootless — kill them now so they don't hijack
+ * the next session's local ports.
+ *
+ * We're conservative: a record with no daemonPid (older builds) is left
+ * alone — we'd rather leak than wrongly kill a user-owned process that
+ * happens to share metadata.
+ */
+export declare function reapOrphanedProcesses(): {
+    reaped: number;
+    details: string[];
+};

package/dist/lib/browser/runtime-state.js

@@ -0,0 +1,259 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { getProfileRuntimeDir, getBrowserRuntimeDir } from './profiles.js';
+const PID_FILE = 'pid';
+const PORT_FILE = 'port';
+const COMMAND_FILE = 'command';
+const META_FILE = 'meta.json';
+function readNumberFile(p) {
+    try {
+        const n = parseInt(fs.readFileSync(p, 'utf-8').trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readStringFile(p) {
+    try {
+        return fs.readFileSync(p, 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save the runtime record atomically. We write the legacy one-value-per-
+ * file fields plus a JSON meta blob so future code can read either.
+ * The cache directory may not exist yet (first launch); we create it.
+ */
+export function writeProfileRuntime(profileName, runtime) {
+    const dir = getProfileRuntimeDir(profileName);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, PID_FILE), String(runtime.pid));
+    fs.writeFileSync(path.join(dir, PORT_FILE), String(runtime.port));
+    if (runtime.command) {
+        fs.writeFileSync(path.join(dir, COMMAND_FILE), runtime.command);
+    }
+    const meta = {
+        ...runtime,
+        daemonPid: runtime.daemonPid ?? process.pid,
+        spawnedAt: runtime.spawnedAt ?? Date.now(),
+    };
+    fs.writeFileSync(path.join(dir, META_FILE), JSON.stringify(meta));
+}
+/** Read just the JSON meta record. Returns null when absent or malformed. */
+export function readProfileRuntimeMeta(profileName) {
+    const dir = getProfileRuntimeDir(profileName);
+    try {
+        const raw = fs.readFileSync(path.join(dir, META_FILE), 'utf-8');
+        const obj = JSON.parse(raw);
+        if (typeof obj !== 'object' || obj === null)
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the runtime triple. Returns null when the files are missing OR when
+ * the recorded pid no longer points at the same process we launched —
+ * stale data is auto-cleaned to keep the next caller from acting on it.
+ */
+export function readProfileRuntime(profileName) {
+    const dir = getProfileRuntimeDir(profileName);
+    const pid = readNumberFile(path.join(dir, PID_FILE));
+    const port = readNumberFile(path.join(dir, PORT_FILE));
+    const command = readStringFile(path.join(dir, COMMAND_FILE)) ?? undefined;
+    if (pid === null || port === null)
+        return null;
+    if (!isProcessAlive(pid, command)) {
+        clearProfileRuntime(profileName);
+        return null;
+    }
+    return { pid, port, command };
+}
+/** Remove the pid/port/command/meta files. Leaves chrome-data + tasks.json intact. */
+export function clearProfileRuntime(profileName) {
+    const dir = getProfileRuntimeDir(profileName);
+    for (const f of [PID_FILE, PORT_FILE, COMMAND_FILE, META_FILE]) {
+        try {
+            fs.unlinkSync(path.join(dir, f));
+        }
+        catch { /* not present */ }
+    }
+}
+/**
+ * Recursively remove the whole profile cache (chrome-data, tasks.json,
+ * everything). Used by `profiles delete` so an old profile name doesn't
+ * leak its history into a freshly-recreated one.
+ */
+export function removeProfileCache(profileName) {
+    const dir = getProfileRuntimeDir(profileName);
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* gone */ }
+}
+/**
+ * Find every cache directory belonging to a given profile. The composite
+ * naming (`<name>@<endpoint>`) means a single agents-cli profile can have
+ * multiple runtime dirs side by side; this finds them all plus the legacy
+ * non-composite dir from older builds.
+ */
+export function listProfileCacheDirs(profileName) {
+    const root = getBrowserRuntimeDir();
+    if (!fs.existsSync(root))
+        return [];
+    const matches = [];
+    for (const entry of fs.readdirSync(root)) {
+        if (entry === profileName)
+            matches.push(path.join(root, entry));
+        else if (entry.startsWith(`${profileName}@`))
+            matches.push(path.join(root, entry));
+    }
+    return matches;
+}
+/**
+ * `process.kill(pid, 0)` answers "is a process with this id alive?" — but
+ * pid reuse is real on long-uptime machines, and a stale cache pointing
+ * at a since-reassigned pid would happily call the imposter ours.
+ *
+ * Strategy: if we recorded the executable basename when we launched, ask
+ * `ps` what command the live pid is running and compare. No command on
+ * record means we fall back to the existence check (older cache entries
+ * or `pid:0` for "attached to an externally-launched browser").
+ */
+export function isProcessAlive(pid, expectedCommand) {
+    if (pid === 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        if (err && err.code === 'EPERM') {
+            // exists but we can't signal it — count it as alive
+            return !expectedCommand || matchesCommand(pid, expectedCommand);
+        }
+        return false;
+    }
+    if (!expectedCommand)
+        return true;
+    return matchesCommand(pid, expectedCommand);
+}
+/**
+ * Read every profile cache directory and produce a structured snapshot.
+ * Works without the daemon — `agents browser ps` uses this to render a
+ * complete state view even when the IPC server is down. The caller can
+ * post-process to detect conflicts (e.g. two profiles with the same port,
+ * or a port someone else is listening on).
+ */
+export function listAllProfileSnapshots() {
+    const root = getBrowserRuntimeDir();
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(root).sort()) {
+        const dir = path.join(root, name);
+        let stat;
+        try {
+            stat = fs.statSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const meta = readProfileRuntimeMeta(name);
+        const taskCount = readTaskCount(dir);
+        const pidAlive = meta ? isProcessAlive(meta.pid, meta.command) : false;
+        const tunnelAlive = meta?.tunnelPid ? isProcessAlive(meta.tunnelPid, 'ssh') : false;
+        const daemonAlive = meta?.daemonPid ? isProcessAlive(meta.daemonPid) : false;
+        out.push({ name, dir, meta, pidAlive, tunnelAlive, daemonAlive, taskCount });
+    }
+    return out;
+}
+function readTaskCount(dir) {
+    try {
+        const raw = fs.readFileSync(path.join(dir, 'tasks.json'), 'utf-8');
+        const obj = JSON.parse(raw);
+        if (Array.isArray(obj))
+            return obj.length;
+        if (obj && typeof obj === 'object')
+            return Object.keys(obj).length;
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Reap browser + tunnel processes spawned by daemons that no longer exist.
+ * Call once on daemon startup. The idea: every process we spawn records
+ * its daemonPid in meta.json. If that daemon is dead (crashed, SIGKILL),
+ * its children were left rootless — kill them now so they don't hijack
+ * the next session's local ports.
+ *
+ * We're conservative: a record with no daemonPid (older builds) is left
+ * alone — we'd rather leak than wrongly kill a user-owned process that
+ * happens to share metadata.
+ */
+export function reapOrphanedProcesses() {
+    const root = getBrowserRuntimeDir();
+    if (!fs.existsSync(root))
+        return { reaped: 0, details: [] };
+    let reaped = 0;
+    const details = [];
+    for (const profileName of fs.readdirSync(root)) {
+        const meta = readProfileRuntimeMeta(profileName);
+        if (!meta)
+            continue;
+        if (!meta.daemonPid)
+            continue;
+        if (meta.daemonPid === process.pid)
+            continue;
+        // Owning daemon still alive — leave its kids alone.
+        if (isProcessAlive(meta.daemonPid))
+            continue;
+        // Kill what the dead daemon left behind. Best-effort.
+        const kill = (pid, label) => {
+            if (!pid || pid === 0)
+                return;
+            // Only kill if it matches the recorded command — guards against
+            // pid reuse handing us an unrelated process to murder.
+            if (meta.command && !matchesCommand(pid, meta.command) &&
+                !matchesCommand(pid, 'ssh'))
+                return;
+            try {
+                process.kill(pid, 'SIGTERM');
+                reaped++;
+                details.push(`reaped ${label ?? 'pid'} ${pid} (profile ${profileName})`);
+            }
+            catch { /* already gone */ }
+        };
+        kill(meta.pid, 'browser');
+        kill(meta.tunnelPid, 'tunnel');
+        clearProfileRuntime(profileName);
+    }
+    return { reaped, details };
+}
+function matchesCommand(pid, expectedCommand) {
+    try {
+        const out = execSync(`ps -p ${pid} -o comm=`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (!out)
+            return false;
+        // Match on the basename only — `/Applications/Comet.app/Contents/MacOS/Comet`
+        // vs the recorded `Comet`, vs `Google\ Chrome`. Case-insensitive.
+        const live = path.basename(out).toLowerCase();
+        const want = path.basename(expectedCommand).toLowerCase();
+        return live === want || live.startsWith(want) || want.startsWith(live);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -34,7 +34,14 @@ export declare function pickWindowTarget<T extends {
     url?: string;
     title?: string;
 }>(targets: T[], filter: string | undefined): T | undefined;
+/**
+ * Parse a `--since`/`--until` value. Accepts ISO-8601 absolute timestamps
+ * or relative offsets like `30s`, `5m`, `2h`, `1d`.
+ */
+export declare function parseSinceUntil(s: string): Date;
+export declare function readNewestMatchingFile(dir: string, prefix: string, tailLines: number): string;
 export declare class BrowserService {
+    private static readonly SOURCE_PREFIX;
     private connections;
     private forkingProfiles;
     private consoleLogs;
@@ -162,6 +169,15 @@ export declare class BrowserService {
         maxChars?: number;
         tabHint?: string;
     }): Promise<string>;
+    getAppLogs(taskId: string, opts: {
+        lines?: number;
+        level?: string;
+        filter?: string;
+        message?: string;
+        source?: string;
+        since?: string;
+        until?: string;
+    }): Promise<any[]>;
     wait(taskId: string, type: 'time' | 'selector' | 'url' | 'function' | 'load', value: string | number, options?: {
         timeout?: number;
         tabHint?: string;