@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/browser/ipc.js

@@ -1,11 +1,11 @@
 import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
-import { getAgentsDir } from '../state.js';
+import { getHelpersDir } from '../state.js';
 import { startDaemon } from '../daemon.js';
 const SOCKET_NAME = 'browser.sock';
 export function getSocketPath() {
-    return path.join(getAgentsDir(), SOCKET_NAME);
+    return path.join(getHelpersDir(), SOCKET_NAME);
 }
 export class BrowserIPCServer {
     server = null;
@@ -67,8 +67,30 @@ export class BrowserIPCServer {
                 if (!request.profile) {
                     return { ok: false, error: 'Profile required' };
                 }
-                const result = await this.service.start(request.profile, request.task);
-                return { ok: true, task: result.task, windowTargetId: result.windowTargetId };
+                const result = await this.service.start(request.profile, {
+                    taskName: request.taskName,
+                    url: request.url,
+                });
+                return {
+                    ok: true,
+                    task: result.name,
+                    tabId: result.tabId,
+                    windowTargetId: result.windowId,
+                };
+            }
+            case 'launch-profile': {
+                if (!request.profile) {
+                    return { ok: false, error: 'Profile required' };
+                }
+                const result = await this.service.launchProfile(request.profile);
+                return { ok: true, port: result.port, pid: result.pid };
+            }
+            case 'done': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const result = await this.service.done(request.task);
+                return { ok: result.ok, error: result.ok ? undefined : 'Task not found' };
             }
             case 'stop': {
                 if (request.task) {
@@ -85,6 +107,10 @@ export class BrowserIPCServer {
                 const profiles = await this.service.status(request.profile);
                 return { ok: true, profiles };
             }
+            case 'history': {
+                const history = await this.service.getHistory(request.limit ?? 10);
+                return { ok: true, history };
+            }
             case 'navigate': {
                 if (!request.task || !request.url) {
                     return { ok: false, error: 'Task and URL required' };
@@ -92,20 +118,37 @@ export class BrowserIPCServer {
                 const result = await this.service.navigate(request.task, request.url, request.profile);
                 return { ok: true, tabId: result.tabId };
             }
-            case 'tabs': {
-                const tabs = await this.service.tabs(request.task, request.profile);
-                return { ok: true, tabs };
+            case 'tab-add': {
+                if (!request.task || !request.url) {
+                    return { ok: false, error: 'Task and URL required' };
+                }
+                const result = await this.service.tabAdd(request.task, request.url, request.profile);
+                return { ok: true, tabId: result.tabId };
             }
-            case 'close': {
+            case 'tab-focus': {
+                if (!request.task || !request.tabId) {
+                    return { ok: false, error: 'Task and tabId required' };
+                }
+                const result = await this.service.tabFocus(request.task, request.tabId);
+                return { ok: true, tabId: result.tabId };
+            }
+            case 'tab-close': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
                 }
-                await this.service.close(request.task, request.tabId);
+                await this.service.tabClose(request.task, request.tabId);
                 return { ok: true };
             }
+            case 'tab-list': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const tabs = await this.service.tabList(request.task);
+                return { ok: true, tabs: tabs.map(t => ({ id: t.id, url: t.url, title: t.title, task: request.task })) };
+            }
             case 'evaluate': {
-                if (!request.task || request.tabId === undefined || !request.expr) {
-                    return { ok: false, error: 'Task, tabId, and expression required' };
+                if (!request.task || !request.expr) {
+                    return { ok: false, error: 'Task and expression required' };
                 }
                 const result = await this.service.evaluate(request.task, request.tabId, request.expr);
                 return { ok: true, result };
@@ -128,33 +171,125 @@ export class BrowserIPCServer {
                 return { ok: true, refs };
             }
             case 'click': {
-                if (!request.task || !request.tabId || request.ref === undefined) {
-                    return { ok: false, error: 'Task, tabId, and ref required' };
+                if (!request.task || request.ref === undefined) {
+                    return { ok: false, error: 'Task and ref required' };
                 }
-                await this.service.click(request.task, request.tabId, request.ref);
+                await this.service.click(request.task, request.ref, request.tabId);
                 return { ok: true };
             }
             case 'type': {
-                if (!request.task || !request.tabId || request.ref === undefined || !request.text) {
-                    return { ok: false, error: 'Task, tabId, ref, and text required' };
+                if (!request.task || request.ref === undefined || !request.text) {
+                    return { ok: false, error: 'Task, ref, and text required' };
                 }
-                await this.service.type(request.task, request.tabId, request.ref, request.text);
+                await this.service.type(request.task, request.ref, request.text, request.tabId);
                 return { ok: true };
             }
             case 'press': {
-                if (!request.task || !request.tabId || !request.key) {
-                    return { ok: false, error: 'Task, tabId, and key required' };
+                if (!request.task || !request.key) {
+                    return { ok: false, error: 'Task and key required' };
                 }
-                await this.service.press(request.task, request.tabId, request.key);
+                await this.service.press(request.task, request.key, request.tabId);
                 return { ok: true };
             }
             case 'hover': {
-                if (!request.task || !request.tabId || request.ref === undefined) {
-                    return { ok: false, error: 'Task, tabId, and ref required' };
+                if (!request.task || request.ref === undefined) {
+                    return { ok: false, error: 'Task and ref required' };
+                }
+                await this.service.hover(request.task, request.ref, request.tabId);
+                return { ok: true };
+            }
+            case 'scroll': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                await this.service.scroll(request.task, request.scrollX ?? 0, request.scrollY ?? 0, request.scrollAtX, request.scrollAtY, request.tabId);
+                return { ok: true };
+            }
+            case 'set-viewport': {
+                if (!request.task || !request.width || !request.height) {
+                    return { ok: false, error: 'Task, width, and height required' };
+                }
+                await this.service.setViewport(request.task, request.width, request.height, {
+                    mobile: request.mobile,
+                    deviceScaleFactor: request.deviceScaleFactor,
+                    tabHint: request.tabId,
+                });
+                return { ok: true };
+            }
+            case 'set-device': {
+                if (!request.task || !request.deviceName) {
+                    return { ok: false, error: 'Task and device name required' };
                 }
-                await this.service.hover(request.task, request.tabId, request.ref);
+                await this.service.setDevice(request.task, request.deviceName, request.tabId);
                 return { ok: true };
             }
+            case 'console': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const logs = await this.service.getConsoleLogs(request.task, {
+                    level: request.level,
+                    clear: request.clear,
+                    tabHint: request.tabId,
+                });
+                return { ok: true, logs };
+            }
+            case 'errors': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const errors = await this.service.getErrors(request.task, {
+                    clear: request.clear,
+                    tabHint: request.tabId,
+                });
+                return { ok: true, errors };
+            }
+            case 'requests': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const requests = await this.service.getNetworkRequests(request.task, {
+                    filter: request.filter,
+                    clear: request.clear,
+                    tabHint: request.tabId,
+                });
+                return { ok: true, requests };
+            }
+            case 'response-body': {
+                if (!request.task || !request.urlPattern) {
+                    return { ok: false, error: 'Task and URL pattern required' };
+                }
+                const body = await this.service.getResponseBody(request.task, request.urlPattern, {
+                    timeout: request.timeout,
+                    maxChars: request.maxChars,
+                    tabHint: request.tabId,
+                });
+                return { ok: true, body };
+            }
+            case 'wait': {
+                if (!request.task || !request.waitType || request.waitValue === undefined) {
+                    return { ok: false, error: 'Task, wait type, and wait value required' };
+                }
+                await this.service.wait(request.task, request.waitType, request.waitValue, {
+                    timeout: request.timeout,
+                    tabHint: request.tabId,
+                });
+                return { ok: true };
+            }
+            case 'set-download-path': {
+                if (!request.task || !request.downloadPath) {
+                    return { ok: false, error: 'Task and download path required' };
+                }
+                await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
+                return { ok: true };
+            }
+            case 'wait-download': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const downloadPath = await this.service.waitForDownload(request.task, request.timeout);
+                return { ok: true, downloadPath };
+            }
             default:
                 return { ok: false, error: `Unknown action: ${request.action}` };
         }

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

@@ -1,11 +1,19 @@
 import type { BrowserProfile } from './types.js';
 export type { BrowserProfile } from './types.js';
-export declare function getBrowserProfilesDir(): string;
 export declare function getBrowserRuntimeDir(): string;
-export declare function getProfilePath(name: string): string;
 export declare function getProfileRuntimeDir(name: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
+/**
+ * Find a port in 9222–9399 that is not already claimed by another profile
+ * and is not currently in use by any OS process.
+ */
+export declare function findFreeProfilePort(): Promise<number>;
 export declare function createProfile(profile: BrowserProfile): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
 export declare function deleteProfile(name: string): Promise<void>;
+/**
+ * Extract the port intended by the profile's first endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ */
+export declare function extractConfiguredPort(profile: BrowserProfile): number | undefined;

package/dist/lib/browser/profiles.js

@@ -1,61 +1,146 @@
-import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
-import * as yaml from 'yaml';
-import { getUserAgentsDir } from '../state.js';
-export function getBrowserProfilesDir() {
-    return path.join(getUserAgentsDir(), 'browser', 'profiles');
-}
+import { execSync } from 'child_process';
+import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
+import { findBrowserPath } from './chrome.js';
 export function getBrowserRuntimeDir() {
-    const agentsDir = path.join(os.homedir(), '.agents');
-    return path.join(agentsDir, 'browser');
-}
-export function getProfilePath(name) {
-    return path.join(getBrowserProfilesDir(), `${name}.yaml`);
+    return getBrowserRuntimeDirRoot();
 }
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
+function configToProfile(name, config) {
+    return {
+        name,
+        description: config.description,
+        browser: config.browser,
+        binary: config.binary,
+        electron: config.electron,
+        endpoints: config.endpoints,
+        chrome: config.chrome,
+        secrets: config.secrets,
+        viewport: config.viewport,
+    };
+}
+function profileToConfig(profile) {
+    const config = {
+        browser: profile.browser,
+        endpoints: profile.endpoints,
+    };
+    if (profile.description)
+        config.description = profile.description;
+    if (profile.binary)
+        config.binary = profile.binary;
+    if (profile.electron)
+        config.electron = profile.electron;
+    if (profile.chrome)
+        config.chrome = profile.chrome;
+    if (profile.secrets)
+        config.secrets = profile.secrets;
+    if (profile.viewport)
+        config.viewport = profile.viewport;
+    return config;
+}
 export async function listProfiles() {
-    const dir = getBrowserProfilesDir();
-    if (!fs.existsSync(dir))
+    const meta = readMeta();
+    if (!meta.browser)
         return [];
-    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml'));
-    const profiles = [];
-    for (const file of files) {
-        const content = fs.readFileSync(path.join(dir, file), 'utf-8');
-        const profile = yaml.parse(content);
-        profiles.push(profile);
-    }
-    return profiles;
+    return Object.entries(meta.browser).map(([name, config]) => configToProfile(name, config));
 }
 export async function getProfile(name) {
-    const filePath = getProfilePath(name);
-    if (!fs.existsSync(filePath))
+    const meta = readMeta();
+    const config = meta.browser?.[name];
+    if (!config)
         return null;
-    const content = fs.readFileSync(filePath, 'utf-8');
-    return yaml.parse(content);
+    return configToProfile(name, config);
+}
+/**
+ * Find a port in 9222–9399 that is not already claimed by another profile
+ * and is not currently in use by any OS process.
+ */
+export async function findFreeProfilePort() {
+    const profiles = await listProfiles();
+    const usedByProfile = new Set();
+    for (const p of profiles) {
+        const port = extractConfiguredPort(p);
+        if (port !== undefined)
+            usedByProfile.add(port);
+    }
+    for (let port = 9222; port <= 9399; port++) {
+        if (usedByProfile.has(port))
+            continue;
+        try {
+            execSync(`lsof -i :${port}`, { stdio: 'ignore' });
+            // lsof succeeded → something is listening → port is in use
+        }
+        catch {
+            // lsof threw → nothing on this port → it's free
+            return port;
+        }
+    }
+    throw new Error('No available ports in range 9222-9399');
 }
 export async function createProfile(profile) {
-    const dir = getBrowserProfilesDir();
-    fs.mkdirSync(dir, { recursive: true });
-    const filePath = getProfilePath(profile.name);
-    if (fs.existsSync(filePath)) {
+    const meta = readMeta();
+    if (meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
-    fs.writeFileSync(filePath, yaml.stringify(profile), 'utf-8');
+    // Check for port collision with existing profiles
+    const newPort = extractConfiguredPort(profile);
+    if (newPort !== undefined && meta.browser) {
+        for (const [existingName, existingConfig] of Object.entries(meta.browser)) {
+            const existingProfile = configToProfile(existingName, existingConfig);
+            const existingPort = extractConfiguredPort(existingProfile);
+            if (existingPort === newPort) {
+                throw new Error(`Port ${newPort} is already used by profile "${existingName}". ` +
+                    `Each profile must own a unique port. Use a different port or omit --endpoint to auto-assign.`);
+            }
+        }
+    }
+    // Resolve the browser binary at create time. Fails fast with an actionable
+    // error ("Comet not installed at /Applications/Comet.app") rather than
+    // deferring the failure to the first task. `findBrowserPath` short-circuits
+    // for browser=custom without a binary by throwing — same outcome.
+    findBrowserPath(profile.browser, profile.binary);
+    meta.browser = meta.browser ?? {};
+    meta.browser[profile.name] = profileToConfig(profile);
+    writeMeta(meta);
 }
 export async function updateProfile(profile) {
-    const filePath = getProfilePath(profile.name);
-    if (!fs.existsSync(filePath)) {
+    const meta = readMeta();
+    if (!meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" does not exist`);
     }
-    fs.writeFileSync(filePath, yaml.stringify(profile), 'utf-8');
+    meta.browser[profile.name] = profileToConfig(profile);
+    writeMeta(meta);
 }
 export async function deleteProfile(name) {
-    const filePath = getProfilePath(name);
-    if (!fs.existsSync(filePath)) {
+    const meta = readMeta();
+    if (!meta.browser?.[name]) {
         throw new Error(`Profile "${name}" does not exist`);
     }
-    fs.unlinkSync(filePath);
+    delete meta.browser[name];
+    writeMeta(meta);
+}
+/**
+ * Extract the port intended by the profile's first endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ */
+export function extractConfiguredPort(profile) {
+    const endpoint = profile.endpoints[0];
+    if (!endpoint)
+        return undefined;
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.port)
+        return parseInt(url.port, 10);
+    if (url.protocol === 'cdp:')
+        return 9222;
+    if (url.protocol === 'ssh:')
+        return 9222;
+    return undefined;
 }

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

@@ -1,13 +1,36 @@
-import { type TabInfo, type ProfileStatus } from './types.js';
+import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.js';
 import { type RefOpts, type RefNode } from './refs.js';
 export declare class BrowserService {
     private connections;
     private forkingProfiles;
-    start(profileName: string, taskId?: string): Promise<{
+    private consoleLogs;
+    private pageErrors;
+    private networkRequests;
+    private pendingDownloads;
+    private enabledSessions;
+    start(profileName: string, opts?: {
+        taskName?: string;
+        url?: string;
+    }): Promise<{
         task: string;
-        windowTargetId?: string;
+        name: string;
+        tabId?: string;
+        windowId?: string;
     }>;
-    stop(taskId: string): Promise<{
+    /**
+     * Launch (or attach to) the profile's browser without creating a task. Used by
+     * `agents browser profiles launch <name>` so users can warm up the browser —
+     * including the first-run onboarding flow — before any automation starts.
+     */
+    launchProfile(profileName: string): Promise<{
+        port: number;
+        pid: number;
+    }>;
+    stop(taskName: string): Promise<{
+        ok: boolean;
+        profile?: string;
+    }>;
+    done(taskName: string): Promise<{
         ok: boolean;
         profile?: string;
     }>;
@@ -15,28 +38,81 @@ export declare class BrowserService {
     navigate(taskId: string, url: string, profileName?: string): Promise<{
         tabId: string;
         url: string;
+        created: boolean;
+    }>;
+    tabAdd(taskId: string, url: string, profileName?: string): Promise<{
+        tabId: string;
+        url: string;
     }>;
+    tabFocus(taskId: string, tabHint: string): Promise<{
+        tabId: string;
+    }>;
+    tabList(taskId: string): Promise<Array<{
+        id: string;
+        url: string;
+        title: string;
+        current: boolean;
+    }>>;
+    private resolveTabHint;
+    private resolveCurrentTab;
+    private getCdpTargetId;
     tabs(taskId?: string, profileName?: string): Promise<TabInfo[]>;
-    close(taskId: string, tabId?: string): Promise<void>;
-    evaluate(taskId: string, tabId: string, expression: string): Promise<unknown>;
-    screenshot(taskId: string, tabId?: string, outputPath?: string): Promise<string>;
+    tabClose(taskId: string, tabHint?: string): Promise<void>;
+    evaluate(taskId: string, tabHint: string | undefined, expression: string): Promise<unknown>;
+    screenshot(taskId: string, tabHint?: string, outputPath?: string): Promise<string>;
     private refsCache;
-    refs(taskId: string, tabId?: string, opts?: RefOpts): Promise<{
+    refs(taskId: string, tabHint?: string, opts?: RefOpts): Promise<{
         refs: string;
         nodeMap: Map<number, RefNode>;
     }>;
-    click(taskId: string, tabId: string, ref: number): Promise<void>;
-    type(taskId: string, tabId: string, ref: number, text: string): Promise<void>;
-    press(taskId: string, tabId: string, key: string): Promise<void>;
-    hover(taskId: string, tabId: string, ref: number): Promise<void>;
+    click(taskId: string, ref: number, tabHint?: string): Promise<void>;
+    type(taskId: string, ref: number, text: string, tabHint?: string): Promise<void>;
+    press(taskId: string, key: string, tabHint?: string): Promise<void>;
+    hover(taskId: string, ref: number, tabHint?: string): Promise<void>;
+    scroll(taskId: string, deltaX: number, deltaY: number, atX?: number, atY?: number, tabHint?: string): Promise<void>;
     status(profileName?: string): Promise<ProfileStatus[]>;
+    private reconcileFromDisk;
+    setViewport(taskId: string, width: number, height: number, options?: {
+        mobile?: boolean;
+        deviceScaleFactor?: number;
+        tabHint?: string;
+    }): Promise<void>;
+    setDevice(taskId: string, deviceName: string, tabHint?: string): Promise<void>;
+    private enableRuntimeForSession;
+    getConsoleLogs(taskId: string, options?: {
+        level?: string;
+        clear?: boolean;
+        tabHint?: string;
+    }): Promise<import('./types.js').ConsoleEntry[]>;
+    getErrors(taskId: string, options?: {
+        clear?: boolean;
+        tabHint?: string;
+    }): Promise<import('./types.js').ErrorEntry[]>;
+    private enableNetworkForSession;
+    getNetworkRequests(taskId: string, options?: {
+        filter?: string;
+        clear?: boolean;
+        tabHint?: string;
+    }): Promise<import('./types.js').NetworkRequest[]>;
+    getResponseBody(taskId: string, urlPattern: string, options?: {
+        timeout?: number;
+        maxChars?: number;
+        tabHint?: string;
+    }): Promise<string>;
+    wait(taskId: string, type: 'time' | 'selector' | 'url' | 'function' | 'load', value: string | number, options?: {
+        timeout?: number;
+        tabHint?: string;
+    }): Promise<void>;
+    setDownloadPath(taskId: string, downloadPath: string, tabHint?: string): Promise<void>;
+    waitForDownload(taskId: string, timeout?: number): Promise<string>;
+    private findTaskBySession;
     shutdown(): Promise<void>;
     private findAvailableFork;
     private forkElectronProfile;
     private connectProfile;
     private connectEndpoint;
     private enableDomains;
-    private createTaskWindow;
+    private getOrCreateWindow;
     private findTask;
     private getTabsForTask;
     private getProfileStatus;
@@ -45,4 +121,6 @@ export declare class BrowserService {
     private invalidateTargetCache;
     private saveTaskState;
     private loadTaskState;
+    private saveToHistory;
+    getHistory(limit?: number): Promise<HistoricalTask[]>;
 }