@phnx-labs/agents-cli 1.22.25 → 1.22.27

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/auth-health.d.ts

@@ -156,10 +156,54 @@ export interface AuthProbeRow {
     account?: string;
     health: AuthHealth;
 }
+/** One installed (agent, version) home, tagged with its resolved account label. */
+export interface FleetAuthInstall {
+    agent: AgentId;
+    version: string;
+    /** Human account label from {@link authAccountLabel}, or undefined when none resolves. */
+    account: string | undefined;
+}
+/**
+ * A set of installs that share one provider account and MUST be probed once.
+ * The live probe runs against `probe` (the representative home); every entry in
+ * `members` — the representative included — then receives that one verdict.
+ */
+export interface FleetAuthProbeGroup<T extends FleetAuthInstall> {
+    probe: T;
+    members: T[];
+}
 /**
- * Enumerate every installed (agent, version) on THIS host, probe each in
- * parallel, and return the rows (installs with no credential at all are
- * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ * Collapse installs so a live auth probe fires ONCE per (agent, account) rather
+ * than once per version home.
+ *
+ * Several version homes signed into the same provider account share one OAuth
+ * rate limit, so probing each of them concurrently — which the daemon did every
+ * three minutes across every installed home (RUSH-2111) — raced that limit into
+ * a 429 storm that then parked the whole box behind a `Retry-After` penalty (the
+ * incident {@link file:./usage-backoff.ts} was written to survive; this removes
+ * its cause). Grouping by account means N homes on one account issue ONE request.
+ *
+ * `isMergeable` scopes the dedup to the installs it actually helps: only agents
+ * that make a network probe ({@link LIVE_PROBE_AGENTS}) can 429, so only they are
+ * merged. A best-effort agent (its verdict is a cheap local file read, no rate
+ * limit) is left per-install — collapsing it would gain nothing and could
+ * silently override one home's local `signedIn` verdict with another's. Installs
+ * with no resolvable account label, or that `isMergeable` rejects, are never
+ * merged: each becomes its own group keyed by version, preserving the old
+ * per-install probe (also the `unconfigured` case dropped downstream). Pure: no
+ * fs, no network, so the dedup decision is unit-tested directly.
+ */
+export declare function groupFleetAuthInstalls<T extends FleetAuthInstall>(installs: readonly T[], isMergeable?: (install: T) => boolean): FleetAuthProbeGroup<T>[];
+/**
+ * Enumerate every installed (agent, version) on THIS host and return one row per
+ * install (installs with no credential at all are dropped). Shared by
+ * `agents fleet ping --local` and the daemon refresh.
+ *
+ * The live network probe is deduped by account: homes sharing one provider
+ * account are probed ONCE and the verdict is fanned out to each home's row, so
+ * the daemon's every-3-minute refresh can no longer fire concurrent same-account
+ * requests and self-inflict a 429 (RUSH-2111). Each home still gets its own cache
+ * row (the cache key is per-version by design — see {@link authCacheKey}).
  */
 export declare function probeLocalFleetAuth(opts?: {
     cliVersion?: string | null;

package/dist/lib/auth-health.js

@@ -283,28 +283,87 @@ export async function probeAuthHealth(agent, home, opts) {
     return { verdict: info?.signedIn ? 'unverified' : 'unconfigured', checkedAt };
 }
 /**
- * Enumerate every installed (agent, version) on THIS host, probe each in
- * parallel, and return the rows (installs with no credential at all are
- * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ * Collapse installs so a live auth probe fires ONCE per (agent, account) rather
+ * than once per version home.
+ *
+ * Several version homes signed into the same provider account share one OAuth
+ * rate limit, so probing each of them concurrently — which the daemon did every
+ * three minutes across every installed home (RUSH-2111) — raced that limit into
+ * a 429 storm that then parked the whole box behind a `Retry-After` penalty (the
+ * incident {@link file:./usage-backoff.ts} was written to survive; this removes
+ * its cause). Grouping by account means N homes on one account issue ONE request.
+ *
+ * `isMergeable` scopes the dedup to the installs it actually helps: only agents
+ * that make a network probe ({@link LIVE_PROBE_AGENTS}) can 429, so only they are
+ * merged. A best-effort agent (its verdict is a cheap local file read, no rate
+ * limit) is left per-install — collapsing it would gain nothing and could
+ * silently override one home's local `signedIn` verdict with another's. Installs
+ * with no resolvable account label, or that `isMergeable` rejects, are never
+ * merged: each becomes its own group keyed by version, preserving the old
+ * per-install probe (also the `unconfigured` case dropped downstream). Pure: no
+ * fs, no network, so the dedup decision is unit-tested directly.
+ */
+export function groupFleetAuthInstalls(installs, isMergeable = () => true) {
+    const groups = new Map();
+    for (const inst of installs) {
+        // The `acct:` / `ver:` tokens make the two branches disjoint, so an account
+        // label can never collide with a version fallback key no matter its content.
+        const key = inst.account && isMergeable(inst)
+            ? `${inst.agent} acct:${inst.account}`
+            : `${inst.agent} ver:${inst.version}`;
+        const existing = groups.get(key);
+        if (existing)
+            existing.members.push(inst);
+        else
+            groups.set(key, { probe: inst, members: [inst] });
+    }
+    return [...groups.values()];
+}
+/**
+ * Enumerate every installed (agent, version) on THIS host and return one row per
+ * install (installs with no credential at all are dropped). Shared by
+ * `agents fleet ping --local` and the daemon refresh.
+ *
+ * The live network probe is deduped by account: homes sharing one provider
+ * account are probed ONCE and the verdict is fanned out to each home's row, so
+ * the daemon's every-3-minute refresh can no longer fire concurrent same-account
+ * requests and self-inflict a 429 (RUSH-2111). Each home still gets its own cache
+ * row (the cache key is per-version by design — see {@link authCacheKey}).
  */
 export async function probeLocalFleetAuth(opts) {
     const agentIds = opts?.agents ?? ALL_AGENT_IDS;
-    const tasks = [];
+    // Enumerate every install, then resolve its account label. getAccountInfo is a
+    // local credential-file read (no network), so this fan-out is cheap and cannot
+    // contribute to the rate limit the probe grouping below exists to avoid.
+    const installs = [];
     for (const agent of agentIds) {
         for (const version of listInstalledVersions(agent)) {
-            const home = getVersionHomePath(agent, version);
-            tasks.push((async () => {
-                const info = await getAccountInfo(agent, home).catch(() => null);
-                const health = await probeAuthHealth(agent, home, { cliVersion: opts?.cliVersion, info });
-                health.account = authAccountLabel(info);
-                if (health.verdict === 'unconfigured')
-                    return null;
-                return { agent, version, account: health.account, health };
-            })());
+            installs.push({ agent, version, home: getVersionHomePath(agent, version), info: null, account: undefined });
         }
     }
-    const settled = await Promise.all(tasks);
-    return settled.filter((r) => r !== null);
+    await Promise.all(installs.map(async (inst) => {
+        inst.info = await getAccountInfo(inst.agent, inst.home).catch(() => null);
+        inst.account = authAccountLabel(inst.info);
+    }));
+    // Probe once per (agent, account) — but only for the network-probing agents
+    // that can actually 429; best-effort agents stay per-install (see
+    // groupFleetAuthInstalls). Groups run in parallel: they target distinct
+    // accounts, so no same-account concurrency is left to trip the throttle.
+    const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
+        const rep = group.probe;
+        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info });
+        health.account = authAccountLabel(rep.info);
+        if (health.verdict === 'unconfigured')
+            return [];
+        return group.members.map((inst) => ({
+            agent: inst.agent,
+            version: inst.version,
+            account: health.account,
+            // A distinct object per row so a later mutation of one can't bleed across.
+            health: { ...health },
+        }));
+    }));
+    return perGroup.flat();
 }
 /** Persist a host's probed rows into the cache (keyed by host+agent+version). */
 export function writeFleetAuthRows(host, rows) {

package/dist/lib/bench/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema.js";
+export * from "./storage.js";
+export * from "./runner.js";

package/dist/lib/bench/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema.js";
+export * from "./storage.js";
+export * from "./runner.js";

package/dist/lib/bench/runner.d.ts

@@ -0,0 +1,16 @@
+import type { BenchCell, BenchCellResult, BenchRunResult, BenchTask } from "./types.js";
+export interface CellExecutionRequest extends BenchCell {
+    prompt: string;
+    cwd: string;
+}
+export type CellExecutor = (request: CellExecutionRequest) => Promise<Omit<BenchCellResult, keyof BenchCell | "wall_ms" | "status">>;
+export declare function extractTokenCount(stdout: string, stderr: string): number | undefined;
+export declare function executeCellViaAgentsRun(request: CellExecutionRequest): ReturnType<CellExecutor>;
+export declare function runCells(options: {
+    task?: BenchTask;
+    prompt: string;
+    cells: BenchCell[];
+    concurrency: number;
+    execute?: CellExecutor;
+    tempRoot?: string;
+}): Promise<BenchRunResult>;

package/dist/lib/bench/runner.js

@@ -0,0 +1,111 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { getCliLaunch } from "../cli-entry.js";
+export function extractTokenCount(stdout, stderr) {
+    const matches = [
+        ...`${stdout}\n${stderr}`.matchAll(/(?:tokens used|total tokens|token usage)\s*[:=]?\s*([\d,]+)/gi),
+    ];
+    const raw = matches.at(-1)?.[1];
+    if (!raw)
+        return undefined;
+    const tokens = Number(raw.replaceAll(",", ""));
+    return Number.isSafeInteger(tokens) && tokens >= 0 ? tokens : undefined;
+}
+export async function executeCellViaAgentsRun(request) {
+    const args = [
+        "run",
+        request.agent,
+        request.prompt,
+        "--cwd",
+        request.cwd,
+        "--headless",
+        "--no-tmux",
+    ];
+    if (request.model)
+        args.push("--model", request.model);
+    const launch = getCliLaunch(args);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(launch.command, launch.args, {
+            cwd: request.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({
+            exit: code,
+            stdout,
+            stderr,
+            tokens: extractTokenCount(stdout, stderr),
+        }));
+    });
+}
+function copyFixture(task, cellIndex, runRoot) {
+    const cwd = path.join(runRoot, `cell-${cellIndex}`);
+    fs.mkdirSync(cwd, { recursive: true });
+    if (fs.existsSync(task.fixtureDir))
+        fs.cpSync(task.fixtureDir, cwd, { recursive: true });
+    return cwd;
+}
+export async function runCells(options) {
+    if (!Number.isInteger(options.concurrency) || options.concurrency < 1)
+        throw new Error("concurrency must be a positive integer");
+    if (options.cells.length === 0)
+        throw new Error("at least one bench cell is required");
+    const runId = `${new Date().toISOString().replace(/[-:.TZ]/g, "")}-${process.pid}`;
+    const startedAt = new Date();
+    const runRoot = fs.mkdtempSync(path.join(options.tempRoot ?? os.tmpdir(), `agents-bench-${runId}-`));
+    const results = new Array(options.cells.length);
+    const execute = options.execute ?? executeCellViaAgentsRun;
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= options.cells.length)
+                return;
+            const cell = options.cells[index];
+            const cwd = options.task
+                ? copyFixture(options.task, index, runRoot)
+                : path.join(runRoot, `cell-${index}`);
+            fs.mkdirSync(cwd, { recursive: true });
+            const started = performance.now();
+            try {
+                const output = await execute({ ...cell, prompt: options.prompt, cwd });
+                results[index] = {
+                    ...cell,
+                    ...output,
+                    wall_ms: Math.round(performance.now() - started),
+                    status: output.exit === 0 ? "passed" : "failed",
+                };
+            }
+            catch (error) {
+                results[index] = {
+                    ...cell,
+                    exit: null,
+                    stdout: "",
+                    stderr: error instanceof Error ? error.message : String(error),
+                    wall_ms: Math.round(performance.now() - started),
+                    status: "failed",
+                };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(options.concurrency, options.cells.length) }, worker));
+    return {
+        schema_version: 1,
+        run_id: runId,
+        ...(options.task ? { task_id: options.task.id } : {}),
+        prompt: options.prompt,
+        started_at: startedAt.toISOString(),
+        finished_at: new Date().toISOString(),
+        cells: results,
+    };
+}

package/dist/lib/bench/schema.d.ts

@@ -0,0 +1,5 @@
+import type { BenchRunResult, BenchTask } from "./types.js";
+export declare function parseTask(raw: unknown, sourcePath: string): BenchTask;
+export declare function parseRunResult(raw: unknown): BenchRunResult;
+export declare function validateRunId(runId: string): string;
+export declare function loadTask(taskId: string, tasksRoot: string): BenchTask;

package/dist/lib/bench/schema.js

@@ -0,0 +1,91 @@
+import * as fs from "fs";
+import * as path from "path";
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function string(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} must be a non-empty string`);
+    return value;
+}
+export function parseTask(raw, sourcePath) {
+    const value = object(raw, "task.json");
+    const id = string(value.id, "task.id");
+    const prompt = string(value.prompt, "task.prompt");
+    if (!Array.isArray(value.pass) || value.pass.length === 0)
+        throw new Error("task.pass must be a non-empty array");
+    const pass = value.pass.map((item, index) => {
+        const criterion = object(item, `task.pass[${index}]`);
+        const type = string(criterion.type, `task.pass[${index}].type`);
+        if (type === "exit_zero")
+            return { type };
+        if (type === "file_exists")
+            return { type, path: string(criterion.path, `task.pass[${index}].path`) };
+        if (type === "stdout_contains")
+            return {
+                type,
+                value: string(criterion.value, `task.pass[${index}].value`),
+            };
+        if (type === "command_succeeds")
+            return {
+                type,
+                command: string(criterion.command, `task.pass[${index}].command`),
+            };
+        throw new Error(`task.pass[${index}].type is unsupported: ${type}`);
+    });
+    const taskDir = path.dirname(sourcePath);
+    return {
+        id,
+        prompt,
+        pass,
+        fixtureDir: path.join(taskDir, "fixture"),
+        sourcePath,
+    };
+}
+export function parseRunResult(raw) {
+    const value = object(raw, "bench result");
+    if (value.schema_version !== 1)
+        throw new Error("bench result schema_version must be 1");
+    string(value.run_id, "bench result run_id");
+    string(value.prompt, "bench result prompt");
+    string(value.started_at, "bench result started_at");
+    string(value.finished_at, "bench result finished_at");
+    if (value.task_id !== undefined)
+        string(value.task_id, "bench result task_id");
+    if (!Array.isArray(value.cells))
+        throw new Error("bench result cells must be an array");
+    value.cells.forEach((rawCell, index) => {
+        const cell = object(rawCell, `bench result cells[${index}]`);
+        string(cell.agent, `bench result cells[${index}].agent`);
+        if (cell.model !== undefined)
+            string(cell.model, `bench result cells[${index}].model`);
+        if (cell.status !== "passed" && cell.status !== "failed")
+            throw new Error(`bench result cells[${index}].status must be passed or failed`);
+        if (cell.exit !== null &&
+            (!Number.isInteger(cell.exit) || cell.exit < 0))
+            throw new Error(`bench result cells[${index}].exit must be a non-negative integer or null`);
+        if (typeof cell.wall_ms !== "number" ||
+            !Number.isFinite(cell.wall_ms) ||
+            cell.wall_ms < 0)
+            throw new Error(`bench result cells[${index}].wall_ms must be a non-negative number`);
+        if (cell.tokens !== undefined &&
+            (!Number.isSafeInteger(cell.tokens) || cell.tokens < 0))
+            throw new Error(`bench result cells[${index}].tokens must be a non-negative integer`);
+        if (typeof cell.stdout !== "string" || typeof cell.stderr !== "string")
+            throw new Error(`bench result cells[${index}] stdout and stderr must be strings`);
+    });
+    return value;
+}
+export function validateRunId(runId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(runId))
+        throw new Error(`Invalid run id: ${runId}`);
+    return runId;
+}
+export function loadTask(taskId, tasksRoot) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(taskId))
+        throw new Error(`Invalid task id: ${taskId}`);
+    const sourcePath = path.join(tasksRoot, taskId, "task.json");
+    return parseTask(JSON.parse(fs.readFileSync(sourcePath, "utf8")), sourcePath);
+}

package/dist/lib/bench/storage.d.ts

@@ -0,0 +1,5 @@
+import type { BenchRunResult } from "./types.js";
+export declare function benchHistoryDir(): string;
+export declare function saveRun(result: BenchRunResult, root?: string): string;
+export declare function loadRun(runId: string, root?: string): BenchRunResult;
+export declare function listRuns(root?: string): BenchRunResult[];

package/dist/lib/bench/storage.js

@@ -0,0 +1,32 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getUserAgentsDir } from "../state.js";
+import { parseRunResult, validateRunId } from "./schema.js";
+export function benchHistoryDir() {
+    return path.join(getUserAgentsDir(), ".history", "bench");
+}
+export function saveRun(result, root = benchHistoryDir()) {
+    parseRunResult(result);
+    validateRunId(result.run_id);
+    fs.mkdirSync(root, { recursive: true });
+    const target = path.join(root, `${result.run_id}.json`);
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(result, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    fs.renameSync(temporary, target);
+    return target;
+}
+export function loadRun(runId, root = benchHistoryDir()) {
+    validateRunId(runId);
+    return parseRunResult(JSON.parse(fs.readFileSync(path.join(root, `${runId}.json`), "utf8")));
+}
+export function listRuns(root = benchHistoryDir()) {
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => parseRunResult(JSON.parse(fs.readFileSync(path.join(root, name), "utf8"))))
+        .sort((a, b) => b.started_at.localeCompare(a.started_at));
+}

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

@@ -0,0 +1,40 @@
+export type BenchPassCriterion = {
+    type: "file_exists";
+    path: string;
+} | {
+    type: "exit_zero";
+} | {
+    type: "stdout_contains";
+    value: string;
+} | {
+    type: "command_succeeds";
+    command: string;
+};
+export interface BenchTask {
+    id: string;
+    prompt: string;
+    pass: BenchPassCriterion[];
+    fixtureDir: string;
+    sourcePath: string;
+}
+export interface BenchCell {
+    agent: string;
+    model?: string;
+}
+export interface BenchCellResult extends BenchCell {
+    status: "passed" | "failed";
+    exit: number | null;
+    wall_ms: number;
+    tokens?: number;
+    stdout: string;
+    stderr: string;
+}
+export interface BenchRunResult {
+    schema_version: 1;
+    run_id: string;
+    task_id?: string;
+    prompt: string;
+    started_at: string;
+    finished_at: string;
+    cells: BenchCellResult[];
+}

package/dist/lib/bench/types.js

@@ -0,0 +1 @@
+export {};

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