@phnx-labs/agents-cli 1.14.7 → 1.16.0

package/dist/index.js

@@ -3,7 +3,7 @@
  * CLI entry point for agents-cli.
  *
  * Registers all commands, handles update checks, auto-corrects typos,
- * and launches the first-run interactive init when appropriate.
+ * and launches the first-run interactive setup when appropriate.
  */
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -26,7 +26,7 @@ const VERSION = packageJson.version;
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
 import { registerRepoCommands } from './commands/repo.js';
-import { registerInitCommand, runInit } from './commands/init.js';
+import { registerSetupCommand, runSetup } from './commands/setup.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerViewCommand } from './commands/view.js';
 import { registerCommandsCommands } from './commands/commands.js';
@@ -59,7 +59,6 @@ import { registerAliasCommand } from './commands/alias.js';
 import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { isPromptCancelled } from './commands/utils.js';
-import { getAgentsDir } from './lib/state.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault } from './lib/versions.js';
 import { addShimsToPath, ensureShimCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
@@ -80,7 +79,7 @@ Install, configure, run, and dispatch AI coding agents from one place.
 Works with Claude, Codex, Gemini, Cursor, OpenCode, OpenClaw, and Droid.
 
 Quick start:
-  agents init                     First-time setup (interactive)
+  agents setup                    First-time setup (interactive)
   agents view                     See what's installed
   agents run <agent> ["prompt"]   Run an agent (interactive without prompt, headless with)
   agents sessions                 Browse past sessions across all agents
@@ -199,7 +198,8 @@ async function showWhatsNew(fromVersion, toVersion) {
     }
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const UPDATE_CHECK_FILE = path.join(getAgentsDir(), '.update-check');
+import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir } from './lib/state.js';
+const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
 function readUpdateCache() {
     try {
@@ -526,7 +526,7 @@ program
 });
 registerPullCommand(program);
 registerRepoCommands(program);
-registerInitCommand(program);
+registerSetupCommand(program);
 applyGlobalHelpConventions(program);
 /** Calculate the Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
@@ -582,7 +582,7 @@ await checkForUpdates();
 // status marker that we'll print on the *next* invocation.
 const { spawnDetachedSync } = await import('./lib/auto-pull.js');
 spawnDetachedSync();
-// First-run experience: no args + no config yet + TTY -> launch interactive init.
+// First-run experience: no args + no config yet + TTY -> launch interactive setup.
 // Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
 const passedArgs = process.argv.slice(2);
 const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
@@ -613,14 +613,14 @@ async function registerLazyCommands() {
     }
 }
 await registerLazyCommands();
-const metaFilePath = path.join(getAgentsDir(), 'agents.yaml');
+const metaFilePath = path.join(getUserAgentsDir(), 'agents.yaml');
 const firstRun = passedArgs.length === 0 &&
     !fs.existsSync(metaFilePath) &&
     process.stdin.isTTY &&
     process.stdout.isTTY;
 if (firstRun) {
     try {
-        await runInit(program);
+        await runSetup(program);
     }
     catch (err) {
         if (!(err instanceof Error && err.name === 'ExitPromptError')) {
@@ -629,14 +629,11 @@ if (firstRun) {
     }
     process.exit(0);
 }
-// Commands that require the system repo to be cloned first.
-const SYSTEM_REPO_COMMANDS = new Set([
-    'view', 'status', 'skills', 'rules', 'commands', 'hooks',
-    'mcp', 'permissions', 'versions', 'packages', 'sync',
-    'subagents', 'repo', 'plugins', 'doctor',
-]);
-if (!firstRun && requestedCommand && SYSTEM_REPO_COMMANDS.has(requestedCommand)) {
-    const { ensureInitialized } = await import('./commands/init.js');
+// Every command requires the system repo to be cloned first. `setup` is the
+// only exemption — it's the command that does the cloning.
+const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
+if (!firstRun && requestedCommand && !SETUP_EXEMPT_COMMANDS.has(requestedCommand)) {
+    const { ensureInitialized } = await import('./commands/setup.js');
     await ensureInitialized(program);
 }
 // One-shot idempotent migrations (split-layout, legacy file moves).
@@ -648,8 +645,8 @@ if (!firstRun && requestedCommand && SYSTEM_REPO_COMMANDS.has(requestedCommand))
 if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     try {
         const { runMigration } = await import('./lib/migrate.js');
-        const sentinel = path.join(getAgentsDir(), '.migrated');
-        const sentinelValue = `${VERSION}-v2`;
+        const sentinel = getMigratedSentinelPath();
+        const sentinelValue = `${VERSION}-v8`;
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {
@@ -658,7 +655,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         }
         catch { /* best-effort — fall through to run */ }
         if (needRun) {
-            runMigration();
+            await runMigration();
             try {
                 fs.mkdirSync(path.dirname(sentinel), { recursive: true });
                 fs.writeFileSync(sentinel, sentinelValue);

package/dist/lib/agents.js

@@ -16,7 +16,7 @@ import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
-import { getVersionsDir, getShimsDir, getAgentsDir } from './state.js';
+import { getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
 import { loadClaudeOauth } from './usage.js';
 const execFileAsync = promisify(execFile);
@@ -29,7 +29,7 @@ const HOME = os.homedir();
 export const CODEX_HOOKS_MIN_VERSION = '0.116.0';
 /** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
 export const GEMINI_HOOKS_MIN_VERSION = '0.26.0';
-const CLI_VERSION_CACHE_PATH = path.join(getAgentsDir(), '.cli-version-cache.json');
+const CLI_VERSION_CACHE_PATH = getCliVersionCachePath();
 let cliVersionCache = null;
 function loadCliVersionCache() {
     if (cliVersionCache)

package/dist/lib/auto-pull-worker.js

@@ -9,14 +9,13 @@
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import { simpleGit } from 'simple-git';
 import { tryAutoPull, isGitRepo } from './git.js';
-import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, } from './state.js';
+import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath } from './auto-pull.js';
 const LOCK_TTL_MS = 5 * 60 * 1000;
 function ensureFetchDir() {
-    const dir = path.join(getSystemAgentsDir(), '.fetch');
+    const dir = getFetchCacheDir();
     if (!fs.existsSync(dir)) {
         try {
             fs.mkdirSync(dir, { recursive: true });

package/dist/lib/auto-pull.js

@@ -13,10 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
-import { getSystemAgentsDir } from './state.js';
+import { getFetchCacheDir } from './state.js';
 /** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
-    return path.join(getSystemAgentsDir(), '.fetch');
+    return getFetchCacheDir();
 }
 /** Per-repo lock file path. mtime acts as a recency check. */
 export function lockFilePath(alias) {

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

@@ -14,7 +14,13 @@ export declare class CDPClient {
     private handleMessage;
     private handleClose;
 }
-export declare function discoverBrowserWsUrl(port: number, host?: string): Promise<string>;
+export interface BrowserDiscovery {
+    wsUrl: string;
+    browser: string;
+}
+export declare function discoverBrowserWsUrl(port: number, host?: string): Promise<BrowserDiscovery>;
+export declare function normalizeBrowserName(s: string): string;
+export declare function verifyBrowserIdentity(reported: string, expected: string, port: number, host?: string): void;
 export declare function listTargets(port: number, host?: string): Promise<Array<{
     id: string;
     type: string;

package/dist/lib/browser/cdp.js

@@ -83,7 +83,35 @@ export async function discoverBrowserWsUrl(port, host = 'localhost') {
         throw new Error(`Failed to discover browser: ${response.status}`);
     }
     const data = (await response.json());
-    return data.webSocketDebuggerUrl;
+    const browserField = data.Browser || data.Product || '';
+    return {
+        wsUrl: data.webSocketDebuggerUrl,
+        browser: normalizeBrowserName(browserField),
+    };
+}
+export function normalizeBrowserName(s) {
+    if (!s)
+        return 'unknown';
+    return s.split('/')[0].trim().toLowerCase().replace(/\s+/g, '-');
+}
+export function verifyBrowserIdentity(reported, expected, port, host = 'localhost') {
+    if (expected === 'custom')
+        return;
+    if (reported === 'unknown')
+        return;
+    const matches = {
+        chrome: ['chrome', 'google-chrome', 'headlesschrome'],
+        chromium: ['chromium', 'headlesschrome'],
+        comet: ['comet'],
+        brave: ['brave', 'brave-browser'],
+        edge: ['edge', 'microsoft-edge', 'msedge'],
+    };
+    const accepted = matches[expected] || [expected];
+    if (accepted.includes(reported))
+        return;
+    const target = host === 'localhost' || host === '127.0.0.1' ? `port ${port}` : `${host}:${port}`;
+    throw new Error(`Browser identity mismatch: profile expects "${expected}" but ${target} is serving "${reported}". ` +
+        `Stop the running browser (e.g. \`pkill -f ${reported}\`) or update the profile to browser=${reported}, then retry.`);
 }
 export async function listTargets(port, host = 'localhost') {
     const response = await fetch(`http://${host}:${port}/json`);

package/dist/lib/browser/chrome.js

@@ -77,6 +77,7 @@ export async function launchBrowser(profileName, browserType, port, options = {}
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
         ...(options.headless ? ['--headless=new'] : []),
+        ...(options.viewport ? [`--window-size=${options.viewport.width},${options.viewport.height}`] : []),
         ...(options.args || []),
     ];
     let env = { ...process.env };
@@ -103,7 +104,8 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     for (let i = 0; i < 30; i++) {
         await sleep(200);
         try {
-            wsUrl = await discoverBrowserWsUrl(port);
+            const result = await discoverBrowserWsUrl(port);
+            wsUrl = result.wsUrl;
             break;
         }
         catch {
@@ -116,11 +118,12 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     return { pid, port, wsUrl };
 }
 export async function attachToChrome(port) {
-    return discoverBrowserWsUrl(port);
+    const { wsUrl } = await discoverBrowserWsUrl(port);
+    return wsUrl;
 }
 export function killChrome(pid) {
     try {
-        process.kill(pid, 'SIGTERM');
+        process.kill(pid, 'SIGINT');
     }
     catch {
         // Process already dead

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

@@ -0,0 +1,4 @@
+import type { DeviceDescriptor } from './types.js';
+export declare const DEVICES: Record<string, DeviceDescriptor>;
+export declare function getDevice(name: string): DeviceDescriptor | undefined;
+export declare function listDevices(): string[];

package/dist/lib/browser/devices.js

@@ -0,0 +1,27 @@
+export const DEVICES = {
+    'iPhone 14': {
+        width: 390,
+        height: 844,
+        deviceScaleFactor: 3,
+        mobile: true,
+    },
+    'iPad': {
+        width: 768,
+        height: 1024,
+        deviceScaleFactor: 2,
+        mobile: true,
+    },
+    'MacBook Pro': {
+        width: 1440,
+        height: 900,
+        deviceScaleFactor: 2,
+        mobile: false,
+    },
+};
+export function getDevice(name) {
+    const key = Object.keys(DEVICES).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? DEVICES[key] : undefined;
+}
+export function listDevices() {
+    return Object.keys(DEVICES);
+}

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

@@ -1,4 +1,4 @@
-import { CDPClient, discoverBrowserWsUrl } from '../cdp.js';
+import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { launchBrowser, allocatePort } from '../chrome.js';
 export async function connectLocal(endpoint, profile) {
     const url = new URL(endpoint);
@@ -7,14 +7,19 @@ export async function connectLocal(endpoint, profile) {
     }
     const port = parseInt(url.port, 10) || 9222;
     try {
-        const wsUrl = await discoverBrowserWsUrl(port);
+        const { wsUrl, browser } = await discoverBrowserWsUrl(port);
+        verifyBrowserIdentity(browser, profile.browser, port);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port, pid: 0 };
     }
-    catch {
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
+            throw err;
+        }
         const newPort = allocatePort();
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets, profile.binary);
+        const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
+        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port: newPort, pid };

package/dist/lib/browser/drivers/ssh.d.ts

@@ -7,3 +7,4 @@ export interface SSHConnection {
     cleanup: () => void;
 }
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
+export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;

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

@@ -1,6 +1,6 @@
 import { spawn } from 'child_process';
 import * as net from 'net';
-import { CDPClient, discoverBrowserWsUrl } from '../cdp.js';
+import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { allocatePort } from '../chrome.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
@@ -9,7 +9,7 @@ export async function connectSSH(endpoint, profile) {
     }
     const user = url.username || process.env.USER || 'root';
     const host = url.hostname;
-    const remotePort = parseInt(url.searchParams.get('port') || '9222', 10);
+    const remotePort = url.port ? parseInt(url.port, 10) : 9222;
     const localPort = allocatePort();
     try {
         await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
@@ -17,7 +17,7 @@ export async function connectSSH(endpoint, profile) {
     catch {
         // Browser may already be running, continue
     }
-    const tunnel = await startSSHTunnel(user, host, localPort, remotePort);
+    let tunnel = await startSSHTunnel(user, host, localPort, remotePort);
     try {
         await waitForPort(localPort, 8000);
     }
@@ -25,7 +25,14 @@ export async function connectSSH(endpoint, profile) {
         tunnel.kill();
         throw new Error(`SSH tunnel failed to establish to ${host}`);
     }
-    const wsUrl = await discoverBrowserWsUrl(localPort);
+    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort);
+    try {
+        verifyBrowserIdentity(browser, profile.browser, remotePort, host);
+    }
+    catch (err) {
+        tunnel.kill();
+        throw err;
+    }
     const cdp = new CDPClient();
     await cdp.connect(wsUrl);
     return {
@@ -133,6 +140,27 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         }, 2000);
     });
 }
+export async function restartRemoteBrowser(user, host, browserType, port, customBinary) {
+    // Kill any process using the remote debugging port
+    const killCmd = `lsof -ti :${port} | xargs kill -9 2>/dev/null || true`;
+    await runSSHCommand(user, host, killCmd);
+    await sleep(500);
+    await ensureRemoteBrowser(user, host, browserType, port, customBinary);
+    await sleep(1500);
+}
+function runSSHCommand(user, host, cmd) {
+    return new Promise((resolve) => {
+        const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {
+            stdio: 'ignore',
+        });
+        child.on('close', () => resolve());
+        child.on('error', () => resolve());
+        setTimeout(() => {
+            child.kill();
+            resolve();
+        }, 3000);
+    });
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

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,23 @@ 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 '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 +100,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 +111,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 '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 'close': {
+            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 +164,118 @@ 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.tabId, request.ref);
+                await this.service.hover(request.task, request.ref, 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.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}` };
         }
@@ -195,6 +316,7 @@ export async function sendIPCRequest(request) {
         if (!fs.existsSync(socketPath)) {
             throw new Error('Failed to start browser daemon');
         }
+        await new Promise((r) => setTimeout(r, 300));
     }
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(socketPath);

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

@@ -1,11 +1,14 @@
 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>;
 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;