@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/browser/domain-skills.js

@@ -0,0 +1,157 @@
+/**
+ * Domain-skill discovery for `agents browser start`.
+ *
+ * When a browser task opens a URL, look up a site-specific SKILL.md from
+ * `~/.agents/skills/browser/domain-skills/<dir>/SKILL.md` and surface its
+ * contents so the calling agent gets per-site operating instructions
+ * (selectors, gotchas, sign-in quirks) before it starts driving the page.
+ *
+ * Matching is intentionally simple: derive the hostname's second-level
+ * label (e.g. `perplexity` from `perplexity.ai`, `slack` from `app.slack.com`)
+ * and look for a directory of the same name. If the user wants a different
+ * mapping (e.g. `mail.google.com` -> `gmail/`), they can pin it via a
+ * `domains: [...]` array in the SKILL.md frontmatter; that override beats
+ * the directory-name match.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** Where domain-skills live. Override via $AGENTS_BROWSER_DOMAIN_SKILLS_DIR for tests. */
+export function domainSkillsRoot() {
+    const override = process.env.AGENTS_BROWSER_DOMAIN_SKILLS_DIR;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.agents', 'skills', 'browser', 'domain-skills');
+}
+/**
+ * Derive match candidates from a hostname. Order matters — earlier candidates
+ * are tried first.
+ *
+ * Examples:
+ *   perplexity.ai      -> ['perplexity.ai', 'perplexity']
+ *   app.slack.com      -> ['app.slack.com', 'slack.com', 'slack']
+ *   mail.google.com    -> ['mail.google.com', 'google.com', 'google', 'mail']
+ *   higgsfield.ai      -> ['higgsfield.ai', 'higgsfield']
+ */
+export function hostnameMatchCandidates(hostname) {
+    const cleaned = hostname.toLowerCase().replace(/^www\./, '');
+    if (!cleaned)
+        return [];
+    const parts = cleaned.split('.').filter(Boolean);
+    const out = new Set();
+    out.add(cleaned);
+    // Progressive label-stripping from the left: app.slack.com -> slack.com.
+    for (let i = 1; i < parts.length; i++) {
+        out.add(parts.slice(i).join('.'));
+    }
+    // Second-level label without TLD: app.slack.com -> slack, perplexity.ai -> perplexity.
+    if (parts.length >= 2) {
+        out.add(parts[parts.length - 2]);
+    }
+    // First label too, so mail.google.com can resolve a `mail` dir if that's how
+    // the user organized their skills. Last so explicit second-level wins.
+    if (parts.length >= 2) {
+        out.add(parts[0]);
+    }
+    return Array.from(out);
+}
+/** Parse a SKILL.md's frontmatter `domains:` list, if any. Best-effort, no schema. */
+function parseDomainsFrontmatter(content) {
+    // Frontmatter must be at file start: ---\n...\n---\n
+    if (!content.startsWith('---'))
+        return [];
+    const end = content.indexOf('\n---', 3);
+    if (end < 0)
+        return [];
+    const fm = content.slice(3, end);
+    // Inline array form: domains: [a, b, c]
+    const inline = fm.match(/^domains:\s*\[([^\]]*)\]/m);
+    if (inline) {
+        return inline[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^["']|["']$/g, '').toLowerCase())
+            .filter(Boolean);
+    }
+    // Block list form:
+    //   domains:
+    //     - a
+    //     - b
+    const block = fm.match(/^domains:\s*\n((?:\s+-\s+\S+\n?)+)/m);
+    if (block) {
+        return block[1]
+            .split('\n')
+            .map((line) => line.replace(/^\s*-\s*/, '').trim().replace(/^["']|["']$/g, '').toLowerCase())
+            .filter(Boolean);
+    }
+    return [];
+}
+/**
+ * Resolve a URL to its matching domain-skill, or null if none.
+ *
+ * Two-pass strategy:
+ *   1. Index every SKILL.md in the root and read its `domains:` frontmatter.
+ *      If any pinned domain matches a candidate, return that skill.
+ *   2. Fall back to directory-name match against the candidate list.
+ *
+ * Errors (missing root, unreadable file, invalid URL) are swallowed and
+ * yield null — domain-skill discovery must never break browser start.
+ */
+export function resolveDomainSkill(url) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (!hostname)
+        return null;
+    const root = domainSkillsRoot();
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const candidates = hostnameMatchCandidates(hostname);
+    if (candidates.length === 0)
+        return null;
+    const candidateSet = new Set(candidates);
+    const indexed = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const skillPath = path.join(root, e.name, 'SKILL.md');
+        let content;
+        try {
+            content = fs.readFileSync(skillPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        indexed.push({
+            name: e.name,
+            skillPath,
+            content,
+            pinned: parseDomainsFrontmatter(content),
+        });
+    }
+    // Pass 1: explicit `domains:` overrides.
+    for (const s of indexed) {
+        for (const d of s.pinned) {
+            if (candidateSet.has(d)) {
+                return { name: s.name, path: s.skillPath, content: s.content, hostname };
+            }
+        }
+    }
+    // Pass 2: directory-name match, walking candidates in priority order.
+    const byName = new Map(indexed.map((s) => [s.name.toLowerCase(), s]));
+    for (const c of candidates) {
+        const hit = byName.get(c);
+        if (hit) {
+            return { name: hit.name, path: hit.skillPath, content: hit.content, hostname };
+        }
+    }
+    return null;
+}

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

@@ -1,6 +1,27 @@
+import * as net from 'net';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { launchBrowser, getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } 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`
@@ -34,7 +55,7 @@ export async function connectLocal(endpoint, profile) {
             `ssh:// endpoint to drive the remote browser explicitly.`);
     }
     try {
-        const { wsUrl, browser } = await discoverBrowserWsUrl(port);
+        const { wsUrl, browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
         verifyBrowserIdentity(browser, profile.browser, port);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
@@ -55,11 +76,31 @@ export async function connectLocal(endpoint, profile) {
                 `(\`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\`).`);
+        }
         const newPort = port;
         const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary, profile.electron === true);
+        let launched;
+        try {
+            launched = await launchBrowser(profile.name, 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(wsUrl);
-        return { cdp, port: newPort, pid };
+        await cdp.connect(launched.wsUrl);
+        return { cdp, port: newPort, pid: launched.pid };
     }
 }

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

@@ -63,7 +63,7 @@ export async function connectSSH(endpoint, profile) {
         tunnel.kill();
         throw new Error(`SSH tunnel failed to establish to ${host}`);
     }
-    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort);
+    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort, 'localhost', profile.name);
     try {
         verifyBrowserIdentity(browser, profile.browser, remotePort, host);
     }
@@ -180,7 +180,7 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
     const remoteCmd = [
         shellQuote(browserPath),
         `--remote-debugging-port=${port}`,
-        shellQuote('--remote-allow-origins=*'),
+        shellQuote(`--remote-allow-origins=http://127.0.0.1:${port}`),
         '--disable-background-timer-throttling',
         `--user-data-dir=/tmp/agents-browser-${port}`,
         '</dev/null >/dev/null 2>&1 &',

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

@@ -1,5 +1,12 @@
 import { BrowserService } from './service.js';
 import type { IPCRequest, IPCResponse } from './types.js';
+export interface IPCRequestOptions {
+    autoStartDaemon?: boolean;
+}
+export declare class BrowserDaemonNotRunningError extends Error {
+    constructor();
+}
+export declare function formatBrowserDaemonNotRunningError(): string;
 export declare function getSocketPath(): string;
 export declare class BrowserIPCServer {
     private server;
@@ -9,4 +16,4 @@ export declare class BrowserIPCServer {
     stop(): Promise<void>;
     private handleRequest;
 }
-export declare function sendIPCRequest(request: IPCRequest): Promise<IPCResponse>;
+export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;

package/dist/lib/browser/ipc.js

@@ -5,9 +5,32 @@ import { getHelpersDir } from '../state.js';
 import { startDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
+export class BrowserDaemonNotRunningError extends Error {
+    constructor() {
+        super(formatBrowserDaemonNotRunningError());
+        this.name = 'BrowserDaemonNotRunningError';
+    }
+}
+export function formatBrowserDaemonNotRunningError() {
+    return [
+        'Browser daemon not running.',
+        'Start it with: agents browser start (auto-picks an installed browser)',
+        'Or pin a profile: agents browser start --profile <name>',
+        'List profiles: agents browser profiles list',
+    ].join('\n');
+}
 export function getSocketPath() {
     return path.join(getHelpersDir(), 'browser', SOCKET_NAME);
 }
+async function waitForSocket(socketPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (fs.existsSync(socketPath))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error('Timeout waiting for browser daemon socket');
+}
 export class BrowserIPCServer {
     server = null;
     service;
@@ -107,12 +130,14 @@ export class BrowserIPCServer {
                     taskName: request.taskName,
                     url: request.url,
                     endpointName: request.endpoint,
+                    skipDomainSkill: request.skipDomainSkill,
                 });
                 return {
                     ok: true,
                     task: result.name,
                     tabId: result.tabId,
                     windowTargetId: result.windowId,
+                    skill: result.skill,
                 };
             }
             case 'done': {
@@ -411,8 +436,8 @@ async function maybeWarnVersionMismatch() {
         // itself a hint, but a noisy one. Stay silent on this path.
     }
 }
-export async function sendIPCRequest(request) {
-    const result = await sendRawIPCRequest(request);
+export async function sendIPCRequest(request, opts = {}) {
+    const result = await sendRawIPCRequest(request, opts);
     // Run the version check after the user's request returns — keeps the
     // critical path zero-overhead and ensures `start` doesn't get blocked
     // on a daemon-restart warning that the user hasn't read yet.
@@ -421,38 +446,18 @@ export async function sendIPCRequest(request) {
     }
     return result;
 }
-async function sendRawIPCRequest(request) {
+async function sendRawIPCRequest(request, opts = {}) {
     const socketPath = getSocketPath();
+    const autoStartDaemon = opts.autoStartDaemon ?? true;
     if (!fs.existsSync(socketPath)) {
+        if (!autoStartDaemon) {
+            throw new BrowserDaemonNotRunningError();
+        }
         await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
         await fs.promises.chmod(path.dirname(socketPath), 0o700);
         startDaemon();
         if (!fs.existsSync(socketPath)) {
-            await new Promise((resolve, reject) => {
-                const socketDir = path.dirname(socketPath);
-                const socketName = path.basename(socketPath);
-                const watcher = fs.watch(socketDir, (_event, file) => {
-                    if (file === socketName) {
-                        clearTimeout(timeout);
-                        watcher.close();
-                        resolve();
-                    }
-                });
-                watcher.on('error', (error) => {
-                    clearTimeout(timeout);
-                    watcher.close();
-                    reject(error);
-                });
-                const timeout = setTimeout(() => {
-                    watcher.close();
-                    reject(new Error('Timeout waiting for browser daemon socket'));
-                }, 6000);
-                if (fs.existsSync(socketPath)) {
-                    clearTimeout(timeout);
-                    watcher.close();
-                    resolve();
-                }
-            });
+            await waitForSocket(socketPath, 6000);
         }
         if (!fs.existsSync(socketPath)) {
             throw new Error('Failed to start browser daemon');
@@ -475,6 +480,10 @@ async function sendRawIPCRequest(request) {
             }
         });
         socket.on('error', (err) => {
+            if (!autoStartDaemon && (err.code === 'ENOENT' || err.code === 'ECONNREFUSED')) {
+                reject(new BrowserDaemonNotRunningError());
+                return;
+            }
             reject(new Error(`IPC error: ${err.message}`));
         });
         socket.on('close', () => {

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

@@ -1,9 +1,22 @@
 import type { BrowserProfile } from './types.js';
 export type { BrowserProfile } from './types.js';
+export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
 export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
+/**
+ * Ensure a `default` profile exists, auto-picking the first installed
+ * Chromium-family browser per the platform priority list in chrome.ts.
+ *
+ * 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
+ * first match. Throws an actionable error if none of those binaries are
+ * installed so the user knows exactly which browsers we'd accept.
+ */
+export declare function ensureDefaultBrowserProfile(): Promise<BrowserProfile>;
 /**
  * Compute the LOCAL port a profile will occupy at runtime:
  *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
@@ -52,12 +65,12 @@ export declare function resolveEndpoint(profile: BrowserProfile, endpointName?:
  * 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.
+ * this machine) and an `ssh://remote-host:9222` profile (Comet on a remote
+ * host) 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
+ * `ssh://remote-host?port=18805` would silently fall back to 9222 and every
  * `?port=`-style SSH profile would collide on creation.
  */
 export declare function extractConfiguredEndpoint(profile: BrowserProfile): {

package/dist/lib/browser/profiles.js

@@ -1,7 +1,9 @@
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
-import { findBrowserPath } from './chrome.js';
+import { findBrowserPath, findFirstInstalledBrowser } from './chrome.js';
+import { DEFAULT_VIEWPORT } from './devices.js';
+export const DEFAULT_BROWSER_PROFILE_NAME = 'default';
 export function getBrowserRuntimeDir() {
     return getBrowserRuntimeDirRoot();
 }
@@ -67,6 +69,44 @@ export async function getProfile(name) {
         return null;
     return configToProfile(name, config);
 }
+/**
+ * Ensure a `default` profile exists, auto-picking the first installed
+ * Chromium-family browser per the platform priority list in chrome.ts.
+ *
+ * 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
+ * first match. Throws an actionable error if none of those binaries are
+ * installed so the user knows exactly which browsers we'd accept.
+ */
+export async function ensureDefaultBrowserProfile() {
+    const existing = await getProfile(DEFAULT_BROWSER_PROFILE_NAME);
+    if (existing)
+        return existing;
+    const detected = findFirstInstalledBrowser();
+    if (!detected) {
+        throw new Error('No supported browser found. Install one of: Chrome, Brave, Edge, Chromium, or Comet, ' +
+            'then re-run `agents browser start`. Or create a profile explicitly with ' +
+            '`agents browser profiles create <name> --browser <chrome|comet|chromium|brave|edge|custom>`. ' +
+            'Note: Safari and Firefox are not supported — agents browser drives over the ' +
+            'Chrome DevTools Protocol, which they don\'t implement.');
+    }
+    const freePort = await findFreeProfilePort();
+    const profile = {
+        name: DEFAULT_BROWSER_PROFILE_NAME,
+        description: `Auto-detected ${detected.browserType} profile`,
+        browser: detected.browserType,
+        binary: detected.binary,
+        endpoints: [`cdp://127.0.0.1:${freePort}`],
+        viewport: {
+            width: DEFAULT_VIEWPORT.width,
+            height: DEFAULT_VIEWPORT.height,
+        },
+    };
+    await createProfile(profile);
+    return profile;
+}
 /**
  * Compute the LOCAL port a profile will occupy at runtime:
  *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
@@ -259,12 +299,12 @@ export function resolveEndpoint(profile, endpointName) {
  * 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.
+ * this machine) and an `ssh://remote-host:9222` profile (Comet on a remote
+ * host) 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
+ * `ssh://remote-host?port=18805` would silently fall back to 9222 and every
  * `?port=`-style SSH profile would collide on creation.
  */
 export function extractConfiguredEndpoint(profile) {

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

@@ -1,3 +1,4 @@
+import { type ResolvedDomainSkill } from './domain-skills.js';
 import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
@@ -55,12 +56,14 @@ export declare class BrowserService {
         taskName?: string;
         url?: string;
         endpointName?: string;
+        skipDomainSkill?: boolean;
     }): Promise<{
         task: string;
         name: string;
         tabId?: string;
         windowId?: string;
         profile: string;
+        skill?: ResolvedDomainSkill;
     }>;
     stop(taskName: string): Promise<{
         ok: boolean;

package/dist/lib/browser/service.js

@@ -3,12 +3,13 @@ import * as os from 'os';
 import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from './cdp.js';
+import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
 import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime } from './runtime-state.js';
+import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
@@ -347,7 +348,16 @@ export class BrowserService {
             const result = await this.navigate(taskName, opts.url, effectiveProfileName);
             tabId = result.tabId;
         }
-        return { task: taskId, name: taskName, tabId, profile: effectiveProfileName };
+        // Domain-skill discovery: when a URL is supplied, look up site-specific
+        // operating instructions and pass them back so the calling agent can pick
+        // them up alongside the task id. Failures swallowed by resolveDomainSkill.
+        let skill;
+        if (opts.url && !opts.skipDomainSkill) {
+            const resolved = resolveDomainSkill(opts.url);
+            if (resolved)
+                skill = resolved;
+        }
+        return { task: taskId, name: taskName, tabId, profile: effectiveProfileName, skill };
     }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
@@ -1425,7 +1435,7 @@ export class BrowserService {
         const existingInfo = getRunningChromeInfo(effectiveProfile.name);
         if (existingInfo) {
             try {
-                const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port);
+                const { wsUrl, browser } = await discoverBrowserWsUrl(existingInfo.port, 'localhost', effectiveProfile.name);
                 verifyBrowserIdentity(browser, effectiveProfile.browser, existingInfo.port);
                 const cdp = new CDPClient();
                 await cdp.connect(wsUrl);
@@ -1487,8 +1497,14 @@ export class BrowserService {
             };
         }
         if (url.protocol === 'wss:' || url.protocol === 'ws:') {
+            const port = parseInt(url.port || (url.protocol === 'wss:' ? '443' : '80'), 10);
             const cdp = new CDPClient();
-            await cdp.connect(endpoint);
+            try {
+                await cdp.connect(endpoint);
+            }
+            catch {
+                throw new BrowserCdpConnectionError(port, profile.name, url.hostname || 'localhost');
+            }
             await this.enableDomains(cdp);
             return {
                 cdp,
@@ -1502,7 +1518,7 @@ export class BrowserService {
         }
         if (url.protocol === 'http:' || url.protocol === 'https:') {
             const port = parseInt(url.port || (url.protocol === 'https:' ? '443' : '80'), 10);
-            const { wsUrl, browser } = await discoverBrowserWsUrl(port, url.hostname);
+            const { wsUrl, browser } = await discoverBrowserWsUrl(port, url.hostname, profile.name);
             verifyBrowserIdentity(browser, profile.browser, port, url.hostname);
             const cdp = new CDPClient();
             await cdp.connect(wsUrl);
@@ -1685,6 +1701,25 @@ export class BrowserService {
             targetId: tabId,
             flatten: true,
         }));
+        // Inject a one-shot stealth shim before any page script runs. Chromium
+        // unconditionally exposes navigator.webdriver = true when a remote-debug
+        // transport is attached; Cloudflare Turnstile, hCaptcha, and similar bot
+        // checks read that property first. For browsers agents-cli spawns the
+        // --disable-blink-features=AutomationControlled launch flag already
+        // covers this, but for attach-to-running profiles (the Comet / Arc /
+        // Brave case where the user launched the browser themselves) the flag
+        // is unavailable — Page.addScriptToEvaluateOnNewDocument is the only
+        // lever. Non-page targets (workers, service workers) will reject these
+        // calls; we swallow the error and keep going.
+        try {
+            await conn.cdp.send('Page.enable', {}, sessionId);
+            await conn.cdp.send('Page.addScriptToEvaluateOnNewDocument', {
+                source: "Object.defineProperty(navigator,'webdriver',{get:()=>undefined});",
+            }, sessionId);
+        }
+        catch {
+            // Target doesn't support Page domain — nothing to inject.
+        }
         conn.sessionCache.set(tabId, sessionId);
         return sessionId;
     }

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

@@ -1,15 +1,15 @@
 export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
 /**
  * A single named endpoint preset within a profile. Lets one profile cover
- * the local + remote variants of the same app (e.g. Rush on this Mac vs.
- * Rush on mac-mini) instead of forcing two parallel profiles.
+ * the local + remote variants of the same app (e.g. an Electron app on this
+ * Mac vs. on a remote host) instead of forcing two parallel profiles.
  *
  * Per-endpoint overrides take precedence over profile-level fields.
  */
 export interface EndpointPreset {
     /** CDP URL — `cdp://host:port` or `ssh://host?port=N` */
     target: string;
-    /** Override the profile-level binary (e.g. mac-mini has no local binary). */
+    /** Override the profile-level binary (e.g. a remote host has no local binary). */
     binary?: string;
     /** Override the profile-level targetFilter (Electron app builds may diverge). */
     targetFilter?: string;
@@ -43,7 +43,7 @@ export interface BrowserProfile {
     };
     /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
     logDir?: string;
-    /** Optional SSH host where logDir lives, e.g. "user@mac-mini". */
+    /** Optional SSH host where logDir lives, e.g. "user@remote-host". */
     logHost?: string;
 }
 /** Parsed form of `BrowserProfile.targetFilter`. */
@@ -156,6 +156,7 @@ export interface IPCRequest {
     since?: string;
     until?: string;
     appLevel?: string;
+    skipDomainSkill?: boolean;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {
@@ -200,6 +201,12 @@ export interface IPCResponse {
     uploadMode?: 'input' | 'drop' | 'chooser';
     appLogs?: any[];
     version?: string;
+    skill?: {
+        name: string;
+        path: string;
+        content: string;
+        hostname: string;
+    };
 }
 export interface ConsoleEntry {
     level: 'log' | 'info' | 'warn' | 'error';