@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/browser/chrome.js

@@ -39,7 +39,11 @@ const BROWSER_PATHS = {
             `${WIN_PROGRAMFILES_X86}\\Google\\Chrome\\Application\\chrome.exe`,
             `${WIN_LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
         ],
-        comet: [],
+        comet: [
+            `${WIN_PROGRAMFILES}\\Perplexity\\Comet\\Application\\comet.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Perplexity\\Comet\\Application\\comet.exe`,
+            `${WIN_LOCALAPPDATA}\\Perplexity\\Comet\\Application\\comet.exe`,
+        ],
         chromium: [
             `${WIN_LOCALAPPDATA}\\Chromium\\Application\\chrome.exe`,
         ],
@@ -155,8 +159,8 @@ export function findBrowserPath(browserType, customBinary) {
             return resolveBrowserBinary(p);
         }
     }
-    if (browserType === 'comet' && platform !== 'darwin') {
-        throw new Error('Browser "comet" is macOS-only (Comet is a macOS Chromium fork). Use chrome, chromium, brave, or edge on this platform.');
+    if (browserType === 'comet' && platform === 'linux') {
+        throw new Error('Browser "comet" is not available on Linux (Comet ships macOS and Windows builds only). Use chrome, chromium, brave, or edge on this platform.');
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
@@ -171,7 +175,7 @@ const DEFAULT_BROWSER_PRIORITY = {
     linux: ['chrome', 'chromium', 'brave', 'edge'],
     // Windows: Edge is preinstalled on every supported build, so it's the
     // reliable always-there default.
-    win32: ['edge', 'chrome', 'brave'],
+    win32: ['edge', 'chrome', 'brave', 'comet'],
 };
 /**
  * Walk the per-platform priority list and return the first browser that's
@@ -290,11 +294,11 @@ export function killChrome(pid) {
         // stop first (no /F → posts WM_CLOSE), and only force-kill the tree if that
         // fails or the process is still around.
         try {
-            execFileSync('taskkill', ['/pid', String(pid)], { stdio: 'ignore' });
+            execFileSync('taskkill', ['/pid', String(pid)], { stdio: 'ignore', windowsHide: true });
         }
         catch {
             try {
-                execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' });
+                execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
             }
             catch {
                 // Process already dead
@@ -345,13 +349,18 @@ function sleep(ms) {
  * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
  * (lsof doesn't exist there). Returns false on any tooling error so port
  * allocation degrades to "assume free" rather than throwing.
+ *
+ * Exported as the canonical cross-platform probe — `findFreeProfilePort`
+ * (profiles.ts) must use this rather than shelling out to lsof directly,
+ * or every port scans as free on Windows.
  */
-function isPortInUse(port) {
+export function isPortInUse(port) {
     if (process.platform === 'win32') {
         try {
             const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
                 encoding: 'utf8',
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             });
             // Lines look like: "  TCP    0.0.0.0:9200    0.0.0.0:0    LISTENING    1234"
             return out.split('\n').some((line) => {
@@ -393,6 +402,7 @@ export function getPortOccupant(port) {
             const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
                 encoding: 'utf8',
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             });
             let pid = 0;
             for (const line of out.split('\n')) {
@@ -410,6 +420,7 @@ export function getPortOccupant(port) {
                 const tl = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
                     encoding: 'utf8',
                     stdio: ['ignore', 'pipe', 'ignore'],
+                    windowsHide: true,
                 });
                 const m = tl.match(/^"([^"]+)"/);
                 if (m)

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

@@ -271,7 +271,7 @@ export async function ensureRemoteBrowser(user, host, browserType, port, remoteO
             '-o',
             'BatchMode=yes',
             remoteCmd,
-        ], { stdio: ['ignore', 'ignore', 'pipe'] });
+        ], { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
         let stderr = '';
         child.stderr?.on('data', (d) => {
             stderr += d.toString();
@@ -330,6 +330,7 @@ function runSSHCommand(user, host, cmd) {
     return new Promise((resolve) => {
         const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {
             stdio: 'ignore',
+            windowsHide: true,
         });
         child.on('close', () => resolve());
         child.on('error', () => resolve());

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

@@ -0,0 +1,84 @@
+import type { NetworkRequest } from './types.js';
+/**
+ * Minimal HAR 1.2 shapes. We only produce what our request buffer can back —
+ * fields the buffer doesn't populate (headers, cookies, bodies, timings) are
+ * emitted with the spec-mandated empty defaults or `-1` sentinels so validators
+ * still accept the document.
+ *
+ * Spec: http://www.softwareishard.com/blog/har-12-spec/
+ */
+export interface HarLog {
+    version: '1.2';
+    creator: {
+        name: string;
+        version: string;
+    };
+    pages: HarPage[];
+    entries: HarEntry[];
+}
+export interface HarPage {
+    startedDateTime: string;
+    id: string;
+    title: string;
+    pageTimings: {
+        onContentLoad: number;
+        onLoad: number;
+    };
+}
+export interface HarEntry {
+    startedDateTime: string;
+    time: number;
+    request: HarRequest;
+    response: HarResponse;
+    cache: Record<string, never>;
+    timings: HarTimings;
+}
+export interface HarRequest {
+    method: string;
+    url: string;
+    httpVersion: string;
+    cookies: never[];
+    headers: never[];
+    queryString: Array<{
+        name: string;
+        value: string;
+    }>;
+    headersSize: number;
+    bodySize: number;
+}
+export interface HarResponse {
+    status: number;
+    statusText: string;
+    httpVersion: string;
+    cookies: never[];
+    headers: never[];
+    content: {
+        size: number;
+        mimeType: string;
+        text?: string;
+    };
+    redirectURL: string;
+    headersSize: number;
+    bodySize: number;
+}
+export interface HarTimings {
+    send: number;
+    wait: number;
+    receive: number;
+}
+export interface BuildHarOptions {
+    creatorName?: string;
+    creatorVersion?: string;
+}
+/**
+ * Serialize a buffered `NetworkRequest[]` into a HAR 1.2 document.
+ *
+ * The buffer only records `url`, `method`, `status`, `mimeType`, `timestamp`.
+ * Everything downstream — cookies, headers, bodies, per-phase timings — is
+ * unknown and must be emitted as the spec's "unknown" sentinels: `-1` for
+ * sizes / timings, empty arrays for cookies / headers. HAR validators accept
+ * this shape (browsers do the same for opaque cross-origin responses).
+ */
+export declare function buildHar(requests: NetworkRequest[], opts?: BuildHarOptions): {
+    log: HarLog;
+};

package/dist/lib/browser/har.js

@@ -0,0 +1,77 @@
+/**
+ * Serialize a buffered `NetworkRequest[]` into a HAR 1.2 document.
+ *
+ * The buffer only records `url`, `method`, `status`, `mimeType`, `timestamp`.
+ * Everything downstream — cookies, headers, bodies, per-phase timings — is
+ * unknown and must be emitted as the spec's "unknown" sentinels: `-1` for
+ * sizes / timings, empty arrays for cookies / headers. HAR validators accept
+ * this shape (browsers do the same for opaque cross-origin responses).
+ */
+export function buildHar(requests, opts = {}) {
+    const creator = {
+        name: opts.creatorName ?? 'agents-cli',
+        version: opts.creatorVersion ?? '',
+    };
+    const startedAt = requests.length > 0 ? Math.min(...requests.map((r) => r.timestamp)) : Date.now();
+    const page = {
+        startedDateTime: new Date(startedAt).toISOString(),
+        id: 'page_1',
+        title: 'agents browser session',
+        pageTimings: { onContentLoad: -1, onLoad: -1 },
+    };
+    const entries = requests.map((r) => {
+        const queryString = extractQueryString(r.url);
+        const mimeType = r.mimeType ?? '';
+        return {
+            startedDateTime: new Date(r.timestamp).toISOString(),
+            time: -1,
+            request: {
+                method: r.method,
+                url: r.url,
+                httpVersion: 'HTTP/1.1',
+                cookies: [],
+                headers: [],
+                queryString,
+                headersSize: -1,
+                bodySize: -1,
+            },
+            response: {
+                status: r.status ?? 0,
+                statusText: '',
+                httpVersion: 'HTTP/1.1',
+                cookies: [],
+                headers: [],
+                content: { size: -1, mimeType },
+                redirectURL: '',
+                headersSize: -1,
+                bodySize: -1,
+            },
+            cache: {},
+            timings: { send: -1, wait: -1, receive: -1 },
+        };
+    });
+    return {
+        log: {
+            version: '1.2',
+            creator,
+            pages: [page],
+            entries,
+        },
+    };
+}
+/**
+ * Pull `?a=1&b=2` off a URL into HAR's `queryString` array. Returns `[]` when
+ * the URL has no query or fails to parse (opaque URLs like `data:` shouldn't
+ * abort the whole HAR).
+ */
+function extractQueryString(url) {
+    try {
+        const u = new URL(url);
+        const out = [];
+        u.searchParams.forEach((value, name) => out.push({ name, value }));
+        return out;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/browser/ipc.js

@@ -288,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' };
@@ -305,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>;