@phnx-labs/agents-cli 1.19.1 → 1.20.0

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);
     }

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)

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)

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);

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

@@ -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';

package/dist/lib/cli-resources.d.ts

@@ -0,0 +1,109 @@
+/** A single install method. Exactly one of the keys (npm/brew/script/binary) is set. */
+export type InstallMethod = {
+    npm: string;
+} | {
+    brew: string;
+} | {
+    script: string;
+} | {
+    binary: BinarySpec;
+};
+/** Per-platform binary download spec. Keys are `<os>-<arch>` (e.g. darwin-arm64). */
+export interface BinarySpec {
+    [platform: string]: {
+        url: string;
+        /** Path inside the archive (relative). Required when url is a .tar.gz/.zip. */
+        extract?: string;
+    };
+}
+/** Parsed CLI manifest. */
+export interface CliManifest {
+    /** Name as it appears on the command line (e.g. "higgsfield"). */
+    name: string;
+    /** One-line summary shown in `agents cli list`. */
+    description?: string;
+    /** Project homepage; used in detail view + post-install messaging. */
+    homepage?: string;
+    /** Command run to verify the binary is installed (default: "<name> --version"). */
+    check: string;
+    /** Install methods tried in order; first one whose tool is available is used. */
+    install: InstallMethod[];
+    /** Message printed after successful install — typically auth instructions. */
+    postInstall?: string;
+    /** Origin layer this manifest was resolved from. */
+    source: string;
+    /** Absolute path to the yaml file. */
+    path: string;
+}
+/** A validation problem in a CLI manifest. */
+export interface CliManifestError {
+    /** Filename that failed to parse. */
+    file: string;
+    /** Human-readable reason. */
+    reason: string;
+}
+/**
+ * Parse a single CLI manifest from its YAML contents.
+ * Returns a manifest on success; throws on schema violations so callers can
+ * decide whether to surface or swallow the error per file.
+ */
+export declare function parseCliManifest(contents: string, opts: {
+    name: string;
+    source: string;
+    path: string;
+}): CliManifest;
+/**
+ * Discover all CLI manifests resolvable from the current cwd. Returns valid
+ * manifests and any parse errors separately so the CLI can show both.
+ */
+export declare function listCliManifests(cwd?: string): {
+    manifests: CliManifest[];
+    errors: CliManifestError[];
+};
+/** Resolve a single CLI manifest by name. Returns null when not declared. */
+export declare function resolveCliManifest(name: string, cwd?: string): CliManifest | null;
+export declare function hasCommand(cmd: string): boolean;
+/** Run the manifest's `check` command. Returns true when it exits 0. */
+export declare function isCliInstalled(manifest: CliManifest): boolean;
+/**
+ * Pick the first install method whose required host tool is available.
+ * Returns null when none of the declared methods can run on this host.
+ */
+export declare function selectInstallMethod(manifest: CliManifest): InstallMethod | null;
+/** Short description of a method for display. */
+export declare function describeMethod(method: InstallMethod): string;
+export interface InstallResult {
+    manifest: CliManifest;
+    /** Method that was attempted (null if no compatible method existed). */
+    method: InstallMethod | null;
+    /** True when the post-install `check` passed. */
+    installed: boolean;
+    /** stdout/stderr captured from the install command, for surfacing on failure. */
+    output?: string;
+    /** Set when the install runner threw or exited non-zero. */
+    error?: string;
+}
+/**
+ * Install a single CLI by running its first compatible method. Streams the
+ * underlying command's output to the parent terminal so users see brew/npm
+ * progress live. Verifies success by re-running `check`.
+ */
+export declare function installCli(manifest: CliManifest, opts?: {
+    dryRun?: boolean;
+}): InstallResult;
+/**
+ * Map a declarative method to a shell command. Centralized so tests and dry-run
+ * surface the exact string that would execute.
+ */
+export declare function buildInstallCommand(method: InstallMethod): string;
+export interface CliStatus {
+    manifest: CliManifest;
+    installed: boolean;
+}
+/** Convenience: list all manifests + their installed-on-host status. */
+export declare function listCliStatus(cwd?: string): {
+    statuses: CliStatus[];
+    errors: CliManifestError[];
+};
+/** Names of CLIs that are declared but not currently installed on the host. */
+export declare function getMissingClis(cwd?: string): CliManifest[];