@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/browser/ipc.js

@@ -32,8 +32,12 @@ export function getSocketPath() {
 function getIpcEndpoint() {
     return ipcEndpoint(getSocketPath());
 }
-/** Can we open a connection to the daemon right now? Used on Windows where a
- * named pipe can't be probed with fs.existsSync. Resolves false on any error. */
+/** Can we open a connection to the daemon right now? Resolves false on any
+ * error. This is the authoritative liveness check on every platform: a live
+ * daemon accepts the connection, while a stale POSIX socket file left behind by
+ * a crashed daemon (or one that "appears and is immediately destroyed", #556)
+ * rejects with ECONNREFUSED and is correctly reported as not reachable —
+ * something fs.existsSync can't distinguish. */
 function probeDaemon(endpoint, timeoutMs = 500) {
     return new Promise((resolve) => {
         const sock = net.createConnection(endpoint);
@@ -45,16 +49,16 @@ function probeDaemon(endpoint, timeoutMs = 500) {
         sock.on('error', () => { clearTimeout(timer); finish(false); });
     });
 }
-/** Is the daemon reachable? existsSync probe on POSIX, connect probe on Windows. */
-async function isDaemonReachable() {
-    if (IS_WINDOWS)
-        return probeDaemon(getIpcEndpoint());
-    return fs.existsSync(getSocketPath());
+/** Is the daemon reachable? A real connect probe on every platform — a socket
+ * file existing on disk is not proof a daemon is listening on it. */
+export async function isDaemonReachable() {
+    return probeDaemon(getIpcEndpoint());
 }
-async function waitForSocket(socketPath, timeoutMs) {
+async function waitForSocket(_socketPath, timeoutMs) {
+    const endpoint = getIpcEndpoint();
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (IS_WINDOWS ? await probeDaemon(getIpcEndpoint()) : fs.existsSync(socketPath))
+        if (await probeDaemon(endpoint))
             return;
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
@@ -284,6 +288,13 @@ export class BrowserIPCServer {
                 const shot = await this.service.screenshot(request.task, request.tabId, request.path, request.quality);
                 return { ok: true, path: shot.path, bytes: shot.bytes, width: shot.width, height: shot.height };
             }
+            case 'pdf': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const doc = await this.service.printToPdf(request.task, request.tabId, request.path);
+                return { ok: true, path: doc.path, bytes: doc.bytes };
+            }
             case 'refs': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
@@ -301,10 +312,24 @@ export class BrowserIPCServer {
                 return { ok: true, refs, nodes };
             }
             case 'click': {
-                if (!request.task || request.ref === undefined) {
-                    return { ok: false, error: 'Task and ref required' };
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                // Coordinate click (`--at X,Y`) bypasses ref resolution entirely.
+                if (request.atX !== undefined && request.atY !== undefined) {
+                    await this.service.clickAt(request.task, request.atX, request.atY, request.tabId);
+                    return { ok: true };
+                }
+                if (request.ref === undefined) {
+                    return { ok: false, error: 'Task and ref (or --at X,Y) required' };
+                }
+                const { healed } = await this.service.click(request.task, request.ref, request.tabId);
+                if (healed) {
+                    return {
+                        ok: true,
+                        message: `self-healed ref ${healed.from} -> ${healed.to} (${healed.role} "${healed.name}")`,
+                    };
                 }
-                await this.service.click(request.task, request.ref, request.tabId);
                 return { ok: true };
             }
             case 'type': {

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

@@ -12,7 +12,7 @@ export declare function getProfile(name: string): Promise<BrowserProfile | null>
  * Re-uses an existing `default` profile as-is (we don't second-guess the user
  * if they've already customized it). On first run we walk the priority list
  * (macOS: chrome > brave > edge > chromium > comet; Linux: chrome > chromium >
- * brave > edge; Windows: edge > chrome > brave) and pin the profile to the
+ * brave > edge; Windows: edge > chrome > brave > comet) and pin the profile to the
  * first match. Throws an actionable error if none of those binaries are
  * installed so the user knows exactly which browsers we'd accept.
  */

package/dist/lib/browser/profiles.js

@@ -1,7 +1,6 @@
 import * as path from 'path';
-import { execFileSync } from 'child_process';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
-import { findBrowserPath, findFirstInstalledBrowser } from './chrome.js';
+import { findBrowserPath, findFirstInstalledBrowser, isPortInUse } from './chrome.js';
 import { DEFAULT_VIEWPORT } from './devices.js';
 export const DEFAULT_BROWSER_PROFILE_NAME = 'default';
 export function getBrowserRuntimeDir() {
@@ -76,7 +75,7 @@ export async function getProfile(name) {
  * Re-uses an existing `default` profile as-is (we don't second-guess the user
  * if they've already customized it). On first run we walk the priority list
  * (macOS: chrome > brave > edge > chromium > comet; Linux: chrome > chromium >
- * brave > edge; Windows: edge > chrome > brave) and pin the profile to the
+ * brave > edge; Windows: edge > chrome > brave > comet) and pin the profile to the
  * first match. Throws an actionable error if none of those binaries are
  * installed so the user knows exactly which browsers we'd accept.
  */
@@ -153,14 +152,13 @@ export async function findFreeProfilePort() {
     for (let port = 9222; port <= 9399; port++) {
         if (usedByProfile.has(port))
             continue;
-        try {
-            execFileSync('lsof', ['-i', `:${port}`], { stdio: 'ignore' });
-            // lsof succeeded → something is listening → port is in use
-        }
-        catch {
-            // lsof threw → nothing on this port → it's free
+        // Platform-aware bound-port probe (lsof on POSIX, netstat on Windows).
+        // The old inline lsof call threw ENOENT on Windows — where lsof doesn't
+        // exist — so EVERY port scanned as "free", including one an already-
+        // running browser was listening on (typically 9222), and the new profile
+        // would silently attach to that browser instead of launching its own.
+        if (!isPortInUse(port))
             return port;
-        }
     }
     throw new Error('No available ports in range 9222-9399');
 }

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

@@ -12,9 +12,74 @@ export interface RefNode {
     backendNodeId?: number;
     editor?: string;
 }
+/**
+ * Stable, navigation-surviving identity for a ref. Unlike {@link RefNode}, this
+ * carries no `backendNodeId` (which goes stale the moment the DOM re-renders) —
+ * only the accessible descriptor a fresh `getRefs` can be re-matched against.
+ * Cached in per-task state so a later `click <ref>` can self-heal when the
+ * integer ref has drifted (see {@link healRef}).
+ */
+export interface RefDescriptor {
+    ref: number;
+    role: string;
+    name: string;
+    attrs: string[];
+    /**
+     * Best-effort CSS selector captured via DOM. Reserved for future
+     * selector-based healing; matching today is role+name+attrs+position.
+     */
+    selector?: string;
+}
+/**
+ * A cached ref listing for one tab: the stable descriptors plus the resolved
+ * {@link RefOpts} the listing was built with. A later `click`/`type` MUST
+ * rebuild its node map with these same opts, or the integer refs it looks up
+ * are numbered against a *different* accessibility filter than the one the
+ * user saw in `browser refs` — the drift that makes self-heal silently click
+ * the wrong element on the second click.
+ */
+export interface RefSnapshot {
+    descriptors: RefDescriptor[];
+    opts: {
+        interactive: boolean;
+        limit: number;
+    };
+}
+/** Snapshot the stable descriptor for every ref in a freshly-built node map. */
+export declare function describeRefs(nodeMap: Map<number, RefNode>): RefDescriptor[];
+/**
+ * Re-resolve a stale ref against a freshly-built node map by matching the
+ * cached descriptor. Pure — no CDP, no DOM.
+ *
+ * The integer ref assigned by {@link getRefs} is positional: it shifts whenever
+ * the accessibility tree changes (navigation, re-render, or even a different
+ * `interactive` filter). The descriptor's (role, name) pair is the coarse
+ * identity, but a page can carry duplicate (role, name) elements — two "Submit"
+ * buttons, one action button per repeated list row. Matching on (role, name)
+ * alone would heal to whichever duplicate the fresh scan happens to hit first,
+ * which can be the wrong one. So among (role, name) matches we tie-break, in
+ * priority order:
+ *
+ *   1. **DOM-backed** — a candidate with a `backendNodeId` is resolvable to
+ *      coordinates; one without is unclickable, so healing to it is useless.
+ *   2. **Attribute similarity** — the cached `attrs` (disabled / checked /
+ *      selected / …) disambiguate otherwise-identical twins (the *disabled*
+ *      Submit vs the enabled one).
+ *   3. **Positional proximity** — the fresh ref closest to the original cached
+ *      ref index wins, so a repeated list-row action heals to its nearest
+ *      positional twin rather than jumping across the page.
+ *
+ * Returns the new integer ref, or `null` when no node with the same role+name
+ * exists in the fresh map (unhealable — the element is genuinely gone).
+ */
+export declare function healRef(descriptor: Pick<RefDescriptor, 'ref' | 'role' | 'name' | 'attrs'>, freshNodeMap: Map<number, RefNode>): number | null;
 export declare function getRefs(cdp: CDPClient, sessionId: string, opts?: RefOpts): Promise<{
     refs: string;
     nodeMap: Map<number, RefNode>;
+    opts: {
+        interactive: boolean;
+        limit: number;
+    };
 }>;
 export declare function resolveRefToCoords(cdp: CDPClient, sessionId: string, nodeMap: Map<number, RefNode>, ref: number): Promise<{
     x: number;

package/dist/lib/browser/refs.js

@@ -1,3 +1,75 @@
+/** Snapshot the stable descriptor for every ref in a freshly-built node map. */
+export function describeRefs(nodeMap) {
+    return Array.from(nodeMap.values()).map((n) => ({
+        ref: n.ref,
+        role: n.role,
+        name: n.name,
+        attrs: n.attrs.slice(),
+    }));
+}
+/**
+ * Re-resolve a stale ref against a freshly-built node map by matching the
+ * cached descriptor. Pure — no CDP, no DOM.
+ *
+ * The integer ref assigned by {@link getRefs} is positional: it shifts whenever
+ * the accessibility tree changes (navigation, re-render, or even a different
+ * `interactive` filter). The descriptor's (role, name) pair is the coarse
+ * identity, but a page can carry duplicate (role, name) elements — two "Submit"
+ * buttons, one action button per repeated list row. Matching on (role, name)
+ * alone would heal to whichever duplicate the fresh scan happens to hit first,
+ * which can be the wrong one. So among (role, name) matches we tie-break, in
+ * priority order:
+ *
+ *   1. **DOM-backed** — a candidate with a `backendNodeId` is resolvable to
+ *      coordinates; one without is unclickable, so healing to it is useless.
+ *   2. **Attribute similarity** — the cached `attrs` (disabled / checked /
+ *      selected / …) disambiguate otherwise-identical twins (the *disabled*
+ *      Submit vs the enabled one).
+ *   3. **Positional proximity** — the fresh ref closest to the original cached
+ *      ref index wins, so a repeated list-row action heals to its nearest
+ *      positional twin rather than jumping across the page.
+ *
+ * Returns the new integer ref, or `null` when no node with the same role+name
+ * exists in the fresh map (unhealable — the element is genuinely gone).
+ */
+export function healRef(descriptor, freshNodeMap) {
+    const { ref, role, name, attrs } = descriptor;
+    const cachedAttrs = new Set(attrs);
+    // How well a candidate's attribute set matches the cached one: reward shared
+    // attrs, penalize both extras the candidate carries and cached attrs it is
+    // missing. Exact set equality scores highest; an all-attrs-empty comparison
+    // scores 0 for every candidate (so the tie-break falls through to proximity).
+    const attrScore = (node) => {
+        let shared = 0;
+        for (const a of node.attrs)
+            if (cachedAttrs.has(a))
+                shared += 1;
+        const extra = node.attrs.length - shared;
+        const missing = cachedAttrs.size - shared;
+        return shared * 2 - extra - missing;
+    };
+    let best = null;
+    let bestKey = null;
+    for (const node of freshNodeMap.values()) {
+        if (node.role !== role || node.name !== name)
+            continue;
+        // Lexicographic key, all "higher is better":
+        //   [ DOM-backed, attribute similarity, -distance-to-original-ref ].
+        const key = [
+            node.backendNodeId !== undefined ? 1 : 0,
+            attrScore(node),
+            -Math.abs(node.ref - ref),
+        ];
+        if (bestKey === null ||
+            key[0] > bestKey[0] ||
+            (key[0] === bestKey[0] && key[1] > bestKey[1]) ||
+            (key[0] === bestKey[0] && key[1] === bestKey[1] && key[2] > bestKey[2])) {
+            best = node;
+            bestKey = key;
+        }
+    }
+    return best ? best.ref : null;
+}
 const EDITOR_DETECT_FN = `(function() {
   let el = this;
   for (let i = 0; i < 5; i++) {
@@ -101,7 +173,7 @@ export async function getRefs(cdp, sessionId, opts = {}) {
             : `- ${role}${nameStr} [ref=${ref}]${attrStr}${editorStr}`;
         lines.push(line);
     }
-    return { refs: lines.join('\n'), nodeMap };
+    return { refs: lines.join('\n'), nodeMap, opts: { interactive, limit } };
 }
 function truncate(s, max) {
     if (s.length <= max)

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

@@ -269,6 +269,7 @@ function liveProcessCommand(pid) {
             const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'], {
                 encoding: 'utf-8',
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             }).trim();
             // Rows look like: "node.exe","1234","Console","1","12,345 K"
             // A no-match prints an "INFO: No tasks..." line that won't match the regex.

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

@@ -43,6 +43,13 @@ export declare function pickWindowTarget<T extends {
 export declare function parseSinceUntil(s: string): Date;
 export declare function readNewestMatchingRemoteFileCommand(dir: string, prefix: string, tailLines: number): string;
 export declare function readNewestMatchingFile(dir: string, prefix: string, tailLines: number): string;
+/** Describes a ref that was re-resolved from a drifted integer via its cached descriptor. */
+export interface HealInfo {
+    from: number;
+    to: number;
+    role: string;
+    name: string;
+}
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
     private connections;
@@ -104,6 +111,17 @@ export declare class BrowserService {
         width: number;
         height: number;
     }>;
+    /**
+     * Export the current tab as a PDF via CDP `Page.printToPDF`. Reuses the
+     * screenshot session + tab resolution so `--tab`, path sandboxing, and the
+     * auto-path (`sessions/<task>/<ts>.pdf`) all behave identically to
+     * `screenshot`. `printBackground: true` matches Chrome's default print flow
+     * — without it, dark-mode pages render on a blank sheet.
+     */
+    printToPdf(taskId: string, tabHint?: string, outputPath?: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
     private recordings;
     recordStart(taskId: string, tabHint?: string, opts?: {
         fps?: number;
@@ -126,12 +144,30 @@ export declare class BrowserService {
         path?: string;
         elapsedMs?: number;
     }>;
-    private refsCache;
     refs(taskId: string, tabHint?: string, opts?: RefOpts): Promise<{
         refs: string;
         nodeMap: Map<number, RefNode>;
     }>;
-    click(taskId: string, ref: number, tabHint?: string): Promise<void>;
+    /** Record the last ref listing (descriptors + opts) for a tab into state. */
+    private cacheRefDescriptors;
+    /**
+     * Re-resolve a caller-supplied ref against a freshly-built node map, healing
+     * it back to the right element when the integer ref has drifted since the
+     * cached `refs` listing. Shared by `click` and `type` so both self-heal
+     * identically. Returns the ref to act on plus, when a heal occurred, the
+     * {@link HealInfo} to surface. Throws when the cached element is gone.
+     */
+    private resolveHealedRef;
+    click(taskId: string, ref: number, tabHint?: string): Promise<{
+        healed?: HealInfo;
+    }>;
+    /**
+     * Click raw viewport coordinates, bypassing ref resolution entirely. Backs
+     * `browser click --at X,Y` — the escape hatch when the accessibility tree
+     * exposes no usable ref (canvas apps, custom-drawn UI) and the caller has
+     * located the target from a screenshot.
+     */
+    clickAt(taskId: string, x: number, y: number, tabHint?: string): Promise<void>;
     type(taskId: string, ref: number, text: string, tabHint?: string, clear?: boolean): Promise<void>;
     press(taskId: string, key: string, tabHint?: string): Promise<void>;
     hover(taskId: string, ref: number, tabHint?: string): Promise<void>;