@phnx-labs/agents-cli 1.22.25 → 1.22.26

package/dist/lib/analytics/dashboard.d.ts

@@ -1,11 +1,15 @@
-import { RECIPE_IDS, runRecipe, trendsWindow, type RecipeId, type RecipeSection, type TrendsWindow } from './recipes.js';
-export interface TrendsDashboard {
-    window: TrendsWindow;
+import { RECIPE_IDS, runRecipe, analyticsWindow, type RecipeId, type RecipeSection, type AnalyticsWindow } from './recipes.js';
+export interface MixDashboard {
+    window: AnalyticsWindow;
     durationMs: number;
     sections: RecipeSection[];
 }
-export declare function buildTrendsDashboard(opts?: {
+/** @deprecated Use MixDashboard. */
+export type TrendsDashboard = MixDashboard;
+export declare function buildMixDashboard(opts?: {
     days?: number;
     ids?: RecipeId[];
-}): TrendsDashboard;
-export { trendsWindow, runRecipe, RECIPE_IDS, type RecipeId, type RecipeSection };
+}): MixDashboard;
+/** @deprecated Use buildMixDashboard. */
+export declare const buildTrendsDashboard: typeof buildMixDashboard;
+export { analyticsWindow, analyticsWindow as trendsWindow, runRecipe, RECIPE_IDS, type RecipeId, type RecipeSection, type AnalyticsWindow, };

package/dist/lib/analytics/dashboard.js

@@ -1,4 +1,4 @@
-import { RECIPE_IDS, runRecipe, trendsWindow, } from './recipes.js';
+import { RECIPE_IDS, runRecipe, analyticsWindow, } from './recipes.js';
 const DEFAULT_ORDER = [
     'harness-mix',
     'model-mix',
@@ -9,9 +9,9 @@ const DEFAULT_ORDER = [
     'browser-activity',
     'resource-mix',
 ];
-export function buildTrendsDashboard(opts = {}) {
+export function buildMixDashboard(opts = {}) {
     const t0 = Date.now();
-    const win = trendsWindow(opts.days ?? 7);
+    const win = analyticsWindow(opts.days ?? 7);
     const ids = opts.ids ?? DEFAULT_ORDER;
     const sections = [];
     for (const id of ids) {
@@ -28,4 +28,6 @@ export function buildTrendsDashboard(opts = {}) {
         sections,
     };
 }
-export { trendsWindow, runRecipe, RECIPE_IDS };
+/** @deprecated Use buildMixDashboard. */
+export const buildTrendsDashboard = buildMixDashboard;
+export { analyticsWindow, analyticsWindow as trendsWindow, runRecipe, RECIPE_IDS, };

package/dist/lib/analytics/mix-commands.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Counter / warehouse mix recipes under `agents insights`.
+ *
+ * These used to live as the top-level `agents trends` tree. That name was a
+ * peer of `agents insights` with overlapping "analytics" meaning, so agents and
+ * humans kept picking the wrong verb. The cheap counter path (sessions index +
+ * usage.db) still exists — it is now `agents insights mix` and the recipe
+ * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ *
+ * `agents trends` remains a thin deprecated alias registered from
+ * `commands/trends.ts` that shares this same registration — no second copy of
+ * the recipe tree.
+ */
+import type { Command } from 'commander';
+export declare function parseMixDays(raw: string | undefined): number;
+export declare function printMixSection(section: {
+    id: string;
+    title: string;
+    rows: Array<Record<string, string | number | null>>;
+}): void;
+export declare function renderMixDashboard(days: number, asJson: boolean, bannerLabel?: string): void;
+/** One-line deprecation for the retired top-level `agents trends` spelling. */
+export declare function printTrendsDeprecation(): void;
+export interface RegisterMixCommandsOptions {
+    /**
+     * When true, every action prints the trends deprecation line first. Used only
+     * by the thin top-level `agents trends` alias — the real tree under insights
+     * never sets this.
+     */
+    deprecated?: boolean;
+    /**
+     * Banner label for the multi-recipe dashboard (default: agents insights mix).
+     * The deprecated alias passes `agents insights mix` still, so callers learn
+     * the new name even when they typed trends.
+     */
+    dashboardBanner?: string;
+}
+/**
+ * Attach counter-mix subcommands to a parent (typically `insights` or the
+ * deprecated `trends` alias).
+ *
+ * Layout:
+ *   <parent> mix                 multi-recipe board (default for trends alias)
+ *   <parent> recipes             list recipe ids
+ *   <parent> query               raw usage.db rows
+ *   <parent> harness-mix|…       one baked recipe
+ */
+export declare function registerMixCommands(parent: Command, opts?: RegisterMixCommandsOptions): void;
+/**
+ * Thin top-level `agents trends` alias: same mix tree, deprecation on every path,
+ * default action = mix board (old `agents trends` with no subcommand).
+ */
+export declare function registerDeprecatedTrendsAlias(program: Command): void;

package/dist/lib/analytics/mix-commands.js

@@ -0,0 +1,229 @@
+/**
+ * Counter / warehouse mix recipes under `agents insights`.
+ *
+ * These used to live as the top-level `agents trends` tree. That name was a
+ * peer of `agents insights` with overlapping "analytics" meaning, so agents and
+ * humans kept picking the wrong verb. The cheap counter path (sessions index +
+ * usage.db) still exists — it is now `agents insights mix` and the recipe
+ * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ *
+ * `agents trends` remains a thin deprecated alias registered from
+ * `commands/trends.ts` that shares this same registration — no second copy of
+ * the recipe tree.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../help.js';
+import { buildMixDashboard, analyticsWindow, runRecipe, RECIPE_IDS, } from './dashboard.js';
+import { listRecipes } from './recipes.js';
+import { queryUsage, usageDbPath, USAGE_KINDS } from './usage-db.js';
+export function parseMixDays(raw) {
+    const n = parseInt(raw ?? '7', 10);
+    return Number.isFinite(n) && n > 0 ? n : 7;
+}
+function parseLimit(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+export function printMixSection(section) {
+    console.log(chalk.bold(section.title));
+    if (section.rows.length === 0) {
+        console.log(chalk.gray('  (no data)'));
+        console.log();
+        return;
+    }
+    const keys = Object.keys(section.rows[0]);
+    const widths = keys.map((k) => Math.max(k.length, ...section.rows.map((r) => String(r[k] ?? '').length), 4));
+    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+    console.log(chalk.gray(keys.map((k, i) => pad(k.toUpperCase(), widths[i])).join('  ')));
+    for (const row of section.rows) {
+        console.log(keys.map((k, i) => pad(String(row[k] ?? ''), widths[i])).join('  '));
+    }
+    console.log();
+}
+export function renderMixDashboard(days, asJson, bannerLabel = 'agents insights mix') {
+    const dash = buildMixDashboard({ days });
+    if (asJson) {
+        console.log(JSON.stringify(dash, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`${bannerLabel} — last ${dash.window.days} days`));
+    console.log(chalk.gray(`compute ${dash.durationMs}ms · usage ${usageDbPath()}`));
+    console.log();
+    if (dash.sections.length === 0) {
+        console.log(chalk.gray('No session or usage data in this window yet.'));
+        return;
+    }
+    for (const section of dash.sections)
+        printMixSection(section);
+}
+/** One-line deprecation for the retired top-level `agents trends` spelling. */
+export function printTrendsDeprecation() {
+    console.error(chalk.yellow('agents trends is deprecated — use `agents insights mix` (or `agents insights <recipe>`).'));
+}
+/**
+ * Attach counter-mix subcommands to a parent (typically `insights` or the
+ * deprecated `trends` alias).
+ *
+ * Layout:
+ *   <parent> mix                 multi-recipe board (default for trends alias)
+ *   <parent> recipes             list recipe ids
+ *   <parent> query               raw usage.db rows
+ *   <parent> harness-mix|…       one baked recipe
+ */
+export function registerMixCommands(parent, opts = {}) {
+    const before = () => {
+        if (opts.deprecated)
+            printTrendsDeprecation();
+    };
+    const banner = opts.dashboardBanner ?? 'agents insights mix';
+    const mix = parent
+        .command('mix')
+        .description('Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db)')
+        .option('--days <n>', 'Days of history to include', '7')
+        .option('--json', 'Emit JSON instead of tables')
+        .action(function summary() {
+        before();
+        const o = this.opts();
+        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
+    });
+    setHelpSections(mix, {
+        examples: `
+      # Auto recipe board (7d)
+      agents insights mix
+
+      # Last 30 days
+      agents insights mix --days 30
+
+      # One recipe as JSON
+      agents insights harness-mix --json
+
+      # Raw usage events
+      agents insights query --kind secret --days 7
+
+      # List baked recipe ids
+      agents insights recipes
+    `,
+        notes: `
+      Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
+      Empty recipes are skipped on the default mix board.
+      This is the cheap counter path. Behavioural report (transcript content, account split)
+      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents usage\`.
+      Skill/slash-command popularity is \`agents sessions stats\`.
+    `,
+    });
+    parent.command('recipes')
+        .description('List baked mix-recipe ids')
+        .option('--json', 'Emit JSON')
+        .action((o) => {
+        before();
+        const list = listRecipes();
+        if (o.json) {
+            console.log(JSON.stringify(list, null, 2));
+            return;
+        }
+        for (const r of list) {
+            console.log(`${r.id.padEnd(22)} ${r.store.padEnd(10)} ${r.title}`);
+        }
+    });
+    parent.command('query')
+        .description('Raw usage-event query (usage.db)')
+        .option('--kind <kind>', `One of: ${USAGE_KINDS.join(', ')}`)
+        .option('--name <name>', 'Resource name filter')
+        .option('--event <event>', 'Event name filter')
+        .option('--days <n>', 'Days of history', '7')
+        .option('--limit <n>', 'Max rows', '40')
+        .option('--json', 'Emit JSON')
+        .action((o) => {
+        before();
+        const win = analyticsWindow(parseMixDays(o.days));
+        const kind = o.kind && USAGE_KINDS.includes(o.kind)
+            ? o.kind
+            : undefined;
+        if (o.kind && !kind) {
+            console.error(`Unknown kind '${o.kind}'. Expected: ${USAGE_KINDS.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        const rows = queryUsage({
+            kind,
+            name: o.name,
+            event: o.event,
+            sinceIso: win.sinceIso,
+            limit: parseLimit(o.limit, 40),
+        });
+        if (o.json) {
+            console.log(JSON.stringify({ window: win, rows }, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(chalk.gray('No usage events.'));
+            return;
+        }
+        printMixSection({
+            id: 'query',
+            title: 'Usage events',
+            rows: rows.map((r) => ({
+                ts: r.ts,
+                kind: r.kind,
+                name: r.name,
+                event: r.event,
+                agent: r.agent,
+            })),
+        });
+    });
+    for (const id of RECIPE_IDS) {
+        parent.command(id)
+            .description(`Mix recipe: ${id}`)
+            .option('--days <n>', 'Days of history', '7')
+            .option('--json', 'Emit JSON')
+            .action(function recipeAction() {
+            before();
+            const parentOpts = this.parent?.opts?.();
+            const o = { ...parentOpts, ...this.opts() };
+            const win = analyticsWindow(parseMixDays(o.days));
+            const section = runRecipe(id, win);
+            if (o.json) {
+                console.log(JSON.stringify({ window: win, section }, null, 2));
+                return;
+            }
+            if (section.empty) {
+                console.log(chalk.gray(`No data for recipe '${id}' in the last ${win.days} days.`));
+                return;
+            }
+            printMixSection(section);
+        });
+    }
+}
+/**
+ * Thin top-level `agents trends` alias: same mix tree, deprecation on every path,
+ * default action = mix board (old `agents trends` with no subcommand).
+ */
+export function registerDeprecatedTrendsAlias(program) {
+    const trends = program
+        .command('trends')
+        .description('Deprecated alias of `agents insights mix` — counter recipes over sessions + usage.db')
+        .option('--days <n>', 'Days of history to include', '7')
+        .option('--json', 'Emit JSON instead of tables')
+        .action(function summary() {
+        printTrendsDeprecation();
+        const o = this.opts();
+        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), 'agents insights mix');
+    });
+    setHelpSections(trends, {
+        examples: `
+      # Prefer the canonical spelling
+      agents insights mix
+
+      # Still works (prints a deprecation line)
+      agents trends
+      agents trends harness-mix --json
+    `,
+        notes: `
+      \`agents trends\` is a compatibility alias. New code and agent briefs should use
+      \`agents insights mix\` / \`agents insights <recipe>\`. Behavioural report remains
+      bare \`agents insights\`. Latency remains \`agents perf\`.
+    `,
+    });
+    // Same subcommands as insights, with deprecation on every fire.
+    registerMixCommands(trends, { deprecated: true, dashboardBanner: 'agents insights mix' });
+}

package/dist/lib/analytics/recipes.d.ts

@@ -1,8 +1,11 @@
 import { type UsageKind } from './usage-db.js';
-export interface TrendsWindow {
+/** Time window for mix recipes under `agents insights mix`. */
+export interface AnalyticsWindow {
     days: number;
     sinceIso: string;
 }
+/** @deprecated Use AnalyticsWindow — kept as a type alias for external callers. */
+export type TrendsWindow = AnalyticsWindow;
 export interface RecipeSection {
     id: string;
     title: string;
@@ -10,23 +13,25 @@ export interface RecipeSection {
     rows: Array<Record<string, string | number | null>>;
     empty?: boolean;
 }
-export declare function trendsWindow(days: number): TrendsWindow;
-export declare function recipeHarnessMix(win: TrendsWindow): RecipeSection;
-export declare function recipeModelMix(win: TrendsWindow): RecipeSection;
-export declare function recipeToolsPerSession(win: TrendsWindow): RecipeSection;
-export declare function recipeTokenRatio(win: TrendsWindow): RecipeSection;
-export declare function recipeSessionVolume(win: TrendsWindow): RecipeSection;
-export declare function recipeSecretsHot(win: TrendsWindow): RecipeSection;
-export declare function recipeBrowserActivity(win: TrendsWindow): RecipeSection;
-export declare function recipeResourceMix(win: TrendsWindow): RecipeSection;
+export declare function analyticsWindow(days: number): AnalyticsWindow;
+/** @deprecated Use analyticsWindow. */
+export declare const trendsWindow: typeof analyticsWindow;
+export declare function recipeHarnessMix(win: AnalyticsWindow): RecipeSection;
+export declare function recipeModelMix(win: AnalyticsWindow): RecipeSection;
+export declare function recipeToolsPerSession(win: AnalyticsWindow): RecipeSection;
+export declare function recipeTokenRatio(win: AnalyticsWindow): RecipeSection;
+export declare function recipeSessionVolume(win: AnalyticsWindow): RecipeSection;
+export declare function recipeSecretsHot(win: AnalyticsWindow): RecipeSection;
+export declare function recipeBrowserActivity(win: AnalyticsWindow): RecipeSection;
+export declare function recipeResourceMix(win: AnalyticsWindow): RecipeSection;
 export type RecipeId = 'harness-mix' | 'model-mix' | 'tools-per-session' | 'token-ratio' | 'session-volume' | 'secrets-hot' | 'browser-activity' | 'resource-mix';
 export declare const RECIPE_IDS: readonly RecipeId[];
-export declare function runRecipe(id: RecipeId, win: TrendsWindow): RecipeSection;
+export declare function runRecipe(id: RecipeId, win: AnalyticsWindow): RecipeSection;
 export declare function listRecipes(): Array<{
     id: RecipeId;
     title: string;
     store: 'sessions' | 'usage';
 }>;
-export declare function hasSessionsInWindow(win: TrendsWindow): boolean;
-export declare function usageKindsPresent(win: TrendsWindow): UsageKind[];
-export declare function usageEventCount(kind: UsageKind, win: TrendsWindow): number;
+export declare function hasSessionsInWindow(win: AnalyticsWindow): boolean;
+export declare function usageKindsPresent(win: AnalyticsWindow): UsageKind[];
+export declare function usageEventCount(kind: UsageKind, win: AnalyticsWindow): number;

package/dist/lib/analytics/recipes.js

@@ -1,11 +1,13 @@
 import Database from '../sqlite.js';
 import { getSessionsDbPath } from '../state.js';
 import { topNamesByKind, kindMix, countUsage, listUsageKindsWithData, } from './usage-db.js';
-export function trendsWindow(days) {
+export function analyticsWindow(days) {
     const d = Number.isFinite(days) && days > 0 ? days : 7;
     const since = new Date(Date.now() - d * 24 * 60 * 60 * 1000);
     return { days: d, sinceIso: since.toISOString() };
 }
+/** @deprecated Use analyticsWindow. */
+export const trendsWindow = analyticsWindow;
 function openSessions() {
     try {
         const db = new Database(getSessionsDbPath());
@@ -290,7 +292,7 @@ export function runRecipe(id, win) {
     return RUNNERS[id](win);
 }
 export function listRecipes() {
-    const win = trendsWindow(7);
+    const win = analyticsWindow(7);
     return RECIPE_IDS.map((id) => {
         const s = RUNNERS[id](win);
         return { id, title: s.title, store: s.store };

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

@@ -1,3 +1,4 @@
+import * as net from 'net';
 import { BrowserService } from './service.js';
 import type { IPCRequest, IPCResponse } from './types.js';
 export interface IPCRequestOptions {
@@ -11,6 +12,25 @@ export declare function getSocketPath(): string;
 /** Is the daemon reachable? A real connect probe on every platform — a socket
  * file existing on disk is not proof a daemon is listening on it. */
 export declare function isDaemonReachable(): Promise<boolean>;
+/**
+ * One long-lived connection to the existing browser daemon. Requests are
+ * serialized so the daemon's newline-delimited responses always map to the
+ * caller that produced them, while the process and socket stay warm between
+ * actions.
+ */
+export declare class BrowserIPCConnection {
+    private readonly socket;
+    private buffer;
+    private pending;
+    private tail;
+    private closed;
+    constructor(socket: net.Socket);
+    request(request: IPCRequest): Promise<IPCResponse>;
+    close(): Promise<void>;
+    private requestOnce;
+    private handleData;
+    private fail;
+}
 export declare class BrowserIPCServer {
     private server;
     private service;
@@ -27,3 +47,9 @@ export declare class BrowserIPCServer {
  */
 export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
+/**
+ * Open one connection that can serve many browser operations. This uses the
+ * same daemon readiness and version-reconciliation path as sendIPCRequest;
+ * only the client process and IPC socket lifetime differ.
+ */
+export declare function connectBrowserIPC(opts?: IPCRequestOptions): Promise<BrowserIPCConnection>;

package/dist/lib/browser/ipc.js

@@ -64,6 +64,92 @@ async function waitForSocket(_socketPath, timeoutMs) {
     }
     throw new Error('Timeout waiting for browser daemon socket');
 }
+/**
+ * One long-lived connection to the existing browser daemon. Requests are
+ * serialized so the daemon's newline-delimited responses always map to the
+ * caller that produced them, while the process and socket stay warm between
+ * actions.
+ */
+export class BrowserIPCConnection {
+    socket;
+    buffer = '';
+    pending;
+    tail = Promise.resolve();
+    closed = false;
+    constructor(socket) {
+        this.socket = socket;
+        socket.on('data', (data) => this.handleData(data));
+        socket.on('error', (error) => this.fail(error));
+        socket.on('close', () => {
+            this.fail(new Error('Browser daemon connection closed'));
+        });
+    }
+    request(request) {
+        const result = this.tail.then(() => this.requestOnce(request));
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async close() {
+        await this.tail;
+        if (this.closed || this.socket.destroyed)
+            return;
+        await new Promise((resolve) => {
+            this.socket.once('close', resolve);
+            this.socket.end();
+        });
+    }
+    requestOnce(request) {
+        if (this.closed || this.socket.destroyed) {
+            return Promise.reject(new Error('Browser daemon connection is closed'));
+        }
+        return new Promise((resolve, reject) => {
+            this.pending = { resolve, reject };
+            this.socket.write(`${JSON.stringify(request)}\n`, (error) => {
+                if (!error)
+                    return;
+                if (this.pending?.reject === reject)
+                    this.pending = undefined;
+                reject(error);
+            });
+        });
+    }
+    handleData(data) {
+        this.buffer += data.toString();
+        while (true) {
+            const index = this.buffer.indexOf('\n');
+            if (index === -1)
+                return;
+            const line = this.buffer.slice(0, index);
+            this.buffer = this.buffer.slice(index + 1);
+            if (!line.trim())
+                continue;
+            const pending = this.pending;
+            if (!pending) {
+                this.socket.destroy();
+                this.fail(new Error('Browser daemon sent an unexpected response'));
+                return;
+            }
+            this.pending = undefined;
+            try {
+                pending.resolve(JSON.parse(line));
+            }
+            catch {
+                const error = new Error('Browser daemon returned invalid JSON');
+                pending.reject(error);
+                this.socket.destroy();
+                this.fail(error);
+            }
+        }
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const pending = this.pending;
+        this.pending = undefined;
+        pending?.reject(error);
+    }
+}
 export class BrowserIPCServer {
     server = null;
     service;
@@ -527,33 +613,35 @@ async function reconcileDaemonVersion(socketPath) {
 export async function sendIPCRequest(request, opts = {}) {
     return sendRawIPCRequest(request, opts);
 }
+/**
+ * Open one connection that can serve many browser operations. This uses the
+ * same daemon readiness and version-reconciliation path as sendIPCRequest;
+ * only the client process and IPC socket lifetime differ.
+ */
+export async function connectBrowserIPC(opts = {}) {
+    const autoStartDaemon = opts.autoStartDaemon ?? true;
+    await prepareIPC('status', opts);
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(getIpcEndpoint());
+        const onError = (error) => {
+            socket.destroy();
+            if (!autoStartDaemon && (error.code === 'ENOENT' || error.code === 'ECONNREFUSED')) {
+                reject(new BrowserDaemonNotRunningError());
+                return;
+            }
+            reject(new Error(`IPC error: ${error.message}`));
+        };
+        socket.once('error', onError);
+        socket.once('connect', () => {
+            socket.off('error', onError);
+            resolve(new BrowserIPCConnection(socket));
+        });
+    });
+}
 async function sendRawIPCRequest(request, opts = {}) {
-    const socketPath = getSocketPath();
     const endpoint = getIpcEndpoint();
     const autoStartDaemon = opts.autoStartDaemon ?? true;
-    if (!(await isDaemonReachable())) {
-        if (!autoStartDaemon) {
-            throw new BrowserDaemonNotRunningError();
-        }
-        if (!IS_WINDOWS) {
-            await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
-            await fs.promises.chmod(path.dirname(socketPath), 0o700);
-        }
-        startDaemon();
-        if (!(await isDaemonReachable())) {
-            await waitForSocket(socketPath, 6000);
-        }
-        if (!(await isDaemonReachable())) {
-            throw new Error('Failed to start browser daemon');
-        }
-        await new Promise((r) => setTimeout(r, 300));
-    }
-    // Before serving a real request, make sure the daemon isn't running stale
-    // code. Skips the internal `version` probe (avoids recursion) and callers
-    // that opt out of auto-start. No-ops once reconciled or when versions match.
-    if (request.action !== 'version' && autoStartDaemon) {
-        await reconcileDaemonVersion(socketPath);
-    }
+    await prepareIPC(request.action, opts);
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(endpoint);
         let buffer = '';
@@ -583,3 +671,30 @@ async function sendRawIPCRequest(request, opts = {}) {
         });
     });
 }
+async function prepareIPC(action, opts) {
+    const socketPath = getSocketPath();
+    const autoStartDaemon = opts.autoStartDaemon ?? true;
+    if (!(await isDaemonReachable())) {
+        if (!autoStartDaemon) {
+            throw new BrowserDaemonNotRunningError();
+        }
+        if (!IS_WINDOWS) {
+            await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+            await fs.promises.chmod(path.dirname(socketPath), 0o700);
+        }
+        startDaemon();
+        if (!(await isDaemonReachable())) {
+            await waitForSocket(socketPath, 6000);
+        }
+        if (!(await isDaemonReachable())) {
+            throw new Error('Failed to start browser daemon');
+        }
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    // Before serving a real request, make sure the daemon isn't running stale
+    // code. Skips the internal `version` probe (avoids recursion) and callers
+    // that opt out of auto-start. No-ops once reconciled or when versions match.
+    if (action !== 'version' && autoStartDaemon) {
+        await reconcileDaemonVersion(socketPath);
+    }
+}

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

@@ -26,6 +26,17 @@ export declare function getProfileDownloadsDir(name: string): string;
 export declare function getProfileSessionsDir(name: string, task: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
+/**
+ * True when `profile` can actually launch or attach on THIS machine.
+ *
+ * A remote (`ssh://`) profile runs its browser on the far host, so a local
+ * binary check doesn't apply — assume launchable. A local profile must have its
+ * configured browser/binary present on disk here; a `default` profile
+ * auto-created on a different OS (e.g. a macOS Chrome path reused on Linux — the
+ * "Custom binary not found" failure) fails this check so the caller re-detects
+ * for the current machine.
+ */
+export declare function isProfileLaunchableHere(profile: BrowserProfile): boolean;
 /**
  * Resolve the profile `agents browser start` uses when no `--profile` is given.
  *

package/dist/lib/browser/profiles.js

@@ -105,7 +105,7 @@ export async function getProfile(name) {
  * "Custom binary not found" failure) fails this check so the caller re-detects
  * for the current machine.
  */
-function isProfileLaunchableHere(profile) {
+export function isProfileLaunchableHere(profile) {
     const remote = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('ssh://'));
     if (remote)
         return true;

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

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from 'stream';
+export interface BrowserIPCStreamOptions {
+    input: Readable;
+    output: Writable;
+    task?: string;
+    actor: string;
+    launchId?: string;
+    autoStartDaemon?: boolean;
+}
+/**
+ * Read browser IPC requests as NDJSON and write one NDJSON response per line.
+ * The Node process and daemon connection stay alive until input closes.
+ */
+export declare function runBrowserIPCStream(options: BrowserIPCStreamOptions): Promise<void>;