@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,25 +1,4 @@
-/**
- * paths.ts — the on-disk browser layout the CONSUMER still reads.
- *
- * browser-cli owns the browser process, drivers and IPC, but it keeps every
- * on-disk path the in-repo subsystem used (integration contract §4). So
- * `agents browser sessions` (`sessions-list.ts`) and the feed's browser tool
- * rows (`feed/tool-activity.ts`) read a profile's captures straight off disk —
- * no daemon, no engine — and need just these path helpers. They were the pure
- * path corner of the deleted `profiles.ts` / `runtime-state.ts` engine files.
- *
- * A profile's live tasks and captures may live under a COMPOSITE runtime dir
- * (`<profile>@<endpoint>`, `<profile>@<endpoint>.<fork>`), not the bare
- * `<profile>` dir, so `listProfileCacheDirs` matches every dir that belongs to a
- * profile — the same last-`@` rule browser-cli names them with.
- */
 export { getBrowserDurableDir } from '../state.js';
-/** Root of the browser runtime cache — `~/.agents/.cache/browser/`. */
 export declare function getBrowserRuntimeDir(): string;
-/** The runtime cache dir for one profile's bare name. */
 export declare function getProfileRuntimeDir(name: string): string;
-/**
- * Every runtime-cache dir that belongs to a profile, composite forms included.
- * Empty when the root does not exist yet.
- */
 export declare function listProfileCacheDirs(profileName: string): string[];

package/dist/lib/browser/paths.js

@@ -1,43 +1,17 @@
-/**
- * paths.ts — the on-disk browser layout the CONSUMER still reads.
- *
- * browser-cli owns the browser process, drivers and IPC, but it keeps every
- * on-disk path the in-repo subsystem used (integration contract §4). So
- * `agents browser sessions` (`sessions-list.ts`) and the feed's browser tool
- * rows (`feed/tool-activity.ts`) read a profile's captures straight off disk —
- * no daemon, no engine — and need just these path helpers. They were the pure
- * path corner of the deleted `profiles.ts` / `runtime-state.ts` engine files.
- *
- * A profile's live tasks and captures may live under a COMPOSITE runtime dir
- * (`<profile>@<endpoint>`, `<profile>@<endpoint>.<fork>`), not the bare
- * `<profile>` dir, so `listProfileCacheDirs` matches every dir that belongs to a
- * profile — the same last-`@` rule browser-cli names them with.
- */
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot } from '../state.js';
 export { getBrowserDurableDir } from '../state.js';
-/** Root of the browser runtime cache — `~/.agents/.cache/browser/`. */
 export function getBrowserRuntimeDir() {
     return getBrowserRuntimeDirRoot();
 }
-/** The runtime cache dir for one profile's bare name. */
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
-/**
- * The profile a runtime-cache dir key belongs to. browser-cli keys a dir as
- * `<profile>`, `<profile>@<endpoint>`, or `<profile>@<endpoint>.<fork>`. The
- * profile name may itself contain `@` (`me@work`), so split on the LAST one.
- */
 function profileOfCacheKey(key) {
     const at = key.lastIndexOf('@');
     return at === -1 ? key : key.slice(0, at);
 }
-/**
- * Every runtime-cache dir that belongs to a profile, composite forms included.
- * Empty when the root does not exist yet.
- */
 export function listProfileCacheDirs(profileName) {
     const root = getBrowserRuntimeDir();
     if (!fs.existsSync(root))

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

@@ -1,38 +1,4 @@
-/**
- * record.ts — turn the engine's NDJSON action events (fd 4) into the durable
- * `browser_sessions` row that `agents browser sessions` and `agents sessions
- * --browser` read to link a browser task back to the agent session that drove it.
- *
- * WHY THIS STAYS HERE. `sessions.db` is agents-cli state. Handing the standalone
- * engine a writer for it would have made it a second author of the session index
- * — precisely the "one engine, one executor" rule the repo holds elsewhere.
- * Instead the engine reports what it did on fd 4 and agents-cli, which owns the
- * store, records it.
- *
- * Before PHNX-4101 this upsert ran INSIDE the browser daemon at task start
- * (`BrowserService.start` → `recordBrowserSession`), with the identity resolved
- * in the calling CLI and forwarded over IPC. The engine now streams that identity
- * back on fd 4 instead, and this CLI process — the one the user actually ran, so
- * the actor is right — performs the upsert. The behavior is unchanged; only the
- * trigger moved from an IPC call to a line on a pipe.
- *
- * The feed's browser tool rows are projected from the on-disk captures and the
- * live `tasks.json` (`lib/feed/tool-activity.ts`), not from a per-action event
- * ledger, so — unlike `lib/computer/record.ts` — this emits no feed event: the
- * durable row is the whole job, and every consumer already reads it.
- */
 import type { BrowserActionEvent } from '../browser-client.js';
-/**
- * Record one action the engine performed. Never throws: the action already
- * happened and already reported its own success or failure on the engine's
- * stderr, so a bookkeeping failure must not turn a successful navigate into a
- * failed command.
- *
- * Only an event that names a `task` AND a `profile` can be recorded — the
- * `browser_sessions` row is keyed on `(profile, task)`. A task-less verb
- * (`profiles list`, `status`) carries neither and is skipped, exactly as the old
- * inline recorder only ran for task-scoped verbs.
- */
 export declare function recordBrowserAction(event: BrowserActionEvent, opts?: {
     device?: string;
 }): void;

package/dist/lib/browser/record.js

@@ -1,45 +1,8 @@
-/**
- * record.ts — turn the engine's NDJSON action events (fd 4) into the durable
- * `browser_sessions` row that `agents browser sessions` and `agents sessions
- * --browser` read to link a browser task back to the agent session that drove it.
- *
- * WHY THIS STAYS HERE. `sessions.db` is agents-cli state. Handing the standalone
- * engine a writer for it would have made it a second author of the session index
- * — precisely the "one engine, one executor" rule the repo holds elsewhere.
- * Instead the engine reports what it did on fd 4 and agents-cli, which owns the
- * store, records it.
- *
- * Before PHNX-4101 this upsert ran INSIDE the browser daemon at task start
- * (`BrowserService.start` → `recordBrowserSession`), with the identity resolved
- * in the calling CLI and forwarded over IPC. The engine now streams that identity
- * back on fd 4 instead, and this CLI process — the one the user actually ran, so
- * the actor is right — performs the upsert. The behavior is unchanged; only the
- * trigger moved from an IPC call to a line on a pipe.
- *
- * The feed's browser tool rows are projected from the on-disk captures and the
- * live `tasks.json` (`lib/feed/tool-activity.ts`), not from a per-action event
- * ledger, so — unlike `lib/computer/record.ts` — this emits no feed event: the
- * durable row is the whole job, and every consumer already reads it.
- */
 import { recordBrowserSession } from '../session/db.js';
 import { resolveActor } from '../actor.js';
-/**
- * Record one action the engine performed. Never throws: the action already
- * happened and already reported its own success or failure on the engine's
- * stderr, so a bookkeeping failure must not turn a successful navigate into a
- * failed command.
- *
- * Only an event that names a `task` AND a `profile` can be recorded — the
- * `browser_sessions` row is keyed on `(profile, task)`. A task-less verb
- * (`profiles list`, `status`) carries neither and is skipped, exactly as the old
- * inline recorder only ran for task-scoped verbs.
- */
 export function recordBrowserAction(event, opts = {}) {
     if (typeof event.task !== 'string' || typeof event.profile !== 'string')
         return;
-    // The driven machine. `host` is what a `--device` invocation stamps; `opts.device`
-    // is the fallback for an engine that drove the device this CLI resolved but did
-    // not echo it back. Both absent → a local run, recorded under this machine.
     const machine = event.host ?? opts.device;
     try {
         recordBrowserSession({
@@ -52,6 +15,5 @@ export function recordBrowserAction(event, opts = {}) {
         });
     }
     catch {
-        // Recording is best-effort; the action is already done.
     }
 }

package/dist/lib/browser/sessions-list.d.ts

@@ -1,10 +1,9 @@
 import { formatBytes } from '../format.js';
 export { formatBytes };
-import type { SessionMeta } from '../session/types.js';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export type ArtifactKind = 'screenshot' | 'pdf' | 'recording' | 'download';
 export interface BrowserArtifact {
     kind: ArtifactKind;
-    /** Owning task for session captures; undefined for downloads. */
     task?: string;
     name: string;
     path: string;
@@ -15,114 +14,37 @@ export interface ProfileArtifacts {
     profile: string;
     artifacts: BrowserArtifact[];
 }
-/** Human table for the CLI. Returns lines (no trailing newline). */
 export declare function renderBrowserSessions(groups: ProfileArtifacts[]): string;
-/**
- * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
- * substring match. Returns the absolute path, or null if nothing matched.
- */
 export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
-/** The identity fields this module cares about for one task. */
 export interface TaskIdentity {
     owner?: string;
     launchId?: string;
-    /**
-     * The agent session that drove the task. Primary identity: it is carried by
-     * every agent process, whereas a launch id is present on a minority of them.
-     * Sourced from the durable `browser_sessions` row, which survives task stop —
-     * `tasks.json` never records it beyond the task's own lifetime (RUSH-2549).
-     */
     sessionId?: string;
 }
-/**
- * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
- * keyed by task name. A task's entry is deleted on `agents browser stop` (see
- * service.ts `saveTaskState`), so a task whose run has already ended is absent
- * here even though its captures remain on disk — that is exactly the
- * "unlinked legacy task" case {@link groupIntoRows} reports. Same read-straight-
- * from-disk approach as the rest of this module: works whether or not the
- * browser daemon is running.
- */
 export declare function loadTaskIdentities(profile: string): Map<string, TaskIdentity>;
-/**
- * Identity for one profile's tasks, durable copy first.
- *
- * `browser_sessions` is the source of truth: it is written at task start and
- * never deleted, so it answers for tasks that have already stopped — the case
- * `tasks.json` structurally cannot, since `saveTaskState` rewrites that file
- * from the LIVE task map. The live file is still merged on top for a task that
- * is running right now, so a task started by an older CLI (no DB row yet) keeps
- * whatever identity it does have rather than regressing to nothing.
- */
 export declare function loadDurableTaskIdentities(profile: string): Map<string, TaskIdentity>;
-/** launchId -> indexed session id, built once from every source that records
- *  this join, so a task-heavy profile resolves without re-scanning per task. */
 export interface LaunchSessionIndex {
     byLaunchId: Map<string, string>;
 }
-/**
- * Build the launchId -> sessionId index from the same three sources
- * `feed-post.ts` `resolvePostIdentity` already uses for this exact problem —
- * a browser task's `launchId` IS the `AGENT_LAUNCH_ID` of the CLI run that
- * called `agents browser start` (see service.ts `resolveTaskIdentity`), so
- * resolving "which session ran this launch" is the same join, not a new one.
- * Lowest-confidence source first so a later, more specific source overwrites
- * it on a collision:
- *  1. the activity log (durable, but least specific — read last)
- *  2. the SessionStart hook's live-session index (kept for parity with
- *     `hook-sessions.ts`; empty on this fleet today, harmless when so)
- *  3. the per-pid launch registry (`ag run`, launch-scoped, most authoritative)
- * Computed once per interactive session, not per row.
- */
 export declare function buildLaunchSessionIndex(): LaunchSessionIndex;
-/** Resolve one launchId through the index to its canonical `SessionMeta`, or
- *  `null` when the join has no hit or the resolved session isn't indexed here. */
 export declare function resolveLaunchSession(index: LaunchSessionIndex, launchId: string): SessionMeta | null;
-/** Why a row carries no session digest: `linked` resolved one, `unresolved`
- *  has a launchId but no matching indexed session, `unlinked` has no launchId
- *  at all (a legacy task, or one whose owning run already stopped). */
 export type BrowserSessionLinkStatus = 'linked' | 'unresolved' | 'unlinked';
-/** One task-first row: every capture for one browser task (or, for
- *  `kind: 'downloads'`, one profile's downloads bucket), plus the agent
- *  session it links to when resolvable. */
 export interface BrowserSessionRow {
     kind: 'task' | 'downloads';
     profile: string;
-    /** Task name; undefined for the downloads row. */
     task?: string;
     owner?: string;
     launchId?: string;
-    /** The agent session that drove the task, when one was recorded. */
     sessionId?: string;
     linkStatus: BrowserSessionLinkStatus;
     linkedSession?: SessionMeta;
-    /** Newest first. */
     artifacts: BrowserArtifact[];
     counts: Record<ArtifactKind, number>;
-    /** Most recent capture's mtime — the row's sort/age key. */
     latestMtimeMs: number;
 }
-/**
- * Group flat per-profile artifacts into task-first rows, newest first. Pure:
- * identities and the launch resolver are passed in, so this has no filesystem
- * or session-index dependency and is unit-testable with synthetic data (see
- * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
- */
 export declare function groupIntoRows(groups: ProfileArtifacts[], taskIdentities: Map<string, Map<string, TaskIdentity>>, resolveLaunch?: (launchId: string) => SessionMeta | null, resolveSession?: (sessionId: string) => SessionMeta | null): BrowserSessionRow[];
-/** Build task-first rows for one profile (or every profile with captures),
- *  reading `tasks.json` and resolving launchIds against the live indexes.
- *  The interactive picker's data source. */
 export declare function buildBrowserSessionRows(profile?: string): BrowserSessionRow[];
-/**
- * Search predicate for the interactive picker: task name, profile, the linked
- * session's agent/topic/label, and any artifact filename in the row.
- */
 export declare function matchesBrowserSessionRow(row: BrowserSessionRow, query: string): boolean;
-/**
- * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
- * `open` is the Commander value for `--open [selector]`: undefined when the flag
- * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
- */
 export declare function runBrowserSessions(opts: {
     profile?: string;
     open?: string | boolean;

package/dist/lib/browser/sessions-list.js

@@ -1,23 +1,6 @@
-/**
- * Read-only listing of a browser profile's on-disk captures — screenshots, PDFs,
- * recordings (`<profile>/sessions/<task>/`) and downloads (`<profile>/downloads/`).
- * Reads straight from `.cache/browser/<profile>/`, so it works whether or not the
- * browser daemon is running. Backs both `agents browser sessions` and the
- * `agents sessions --browser` alias.
- *
- * Also owns the task-first grouping (RUSH-2407): browser captures are per-task
- * (`sessions/<task>/`), and a task persists `owner`/`launchId` in `tasks.json`
- * while it is live (see service.ts `resolveTaskIdentity`). This module groups
- * artifacts by task and, when a launchId is available, resolves it to the
- * agent session that ran it — reusing the session index (`getSessionById`) and
- * the same launchId join keys the rest of the CLI already uses for this exact
- * problem (pid registry, the SessionStart hook index, the activity log; see
- * `feed-post.ts` `resolvePostIdentity`), never a second parser.
- */
 import { showFile } from '../open-url.js';
 import * as fs from 'fs';
 import { formatBytes } from '../format.js';
-// Re-exported for the picker, which lists artifacts from this module's rows.
 export { formatBytes };
 import * as path from 'path';
 import { getBrowserRuntimeDir, getProfileRuntimeDir, listProfileCacheDirs } from './paths.js';
@@ -60,7 +43,6 @@ function walkFiles(dir) {
     }
     return out;
 }
-/** Every capture for one profile, newest first. */
 function listProfileArtifacts(profile) {
     const root = getProfileRuntimeDir(profile);
     const artifacts = [];
@@ -69,7 +51,7 @@ function listProfileArtifacts(profile) {
     try {
         taskDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true });
     }
-    catch { /* none */ }
+    catch { }
     for (const t of taskDirs) {
         if (!t.isDirectory())
             continue;
@@ -92,20 +74,9 @@ function listProfileArtifacts(profile) {
     artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
     return artifacts;
 }
-/**
- * Captures grouped by profile. With `only` set, returns just that profile (even
- * when empty); otherwise every profile dir on disk that has at least one capture.
- */
 function listBrowserSessions(only) {
     let profiles;
     if (only) {
-        // A profile's live tasks/captures may live under a composite runtime dir
-        // (`<name>@<device>`, `<name>@endpoint-N`, forks) — NOT the bare `<name>`
-        // dir. Resolve `only` to every cache dir that belongs to it, the same rule
-        // status()/findTask use (keyBelongsToProfile), so `--profile comet-local`
-        // surfaces the real `comet-local@zion` store instead of the empty legacy
-        // dir. Keep the requested name when nothing exists on disk yet so a fresh
-        // profile still returns its (empty) entry rather than vanishing.
         const dirs = listProfileCacheDirs(only).map((d) => path.basename(d));
         profiles = dirs.length > 0 ? dirs : [only];
     }
@@ -124,15 +95,12 @@ function listBrowserSessions(only) {
         .map((p) => ({ profile: p, artifacts: listProfileArtifacts(p) }))
         .filter((r) => !!only || r.artifacts.length > 0);
 }
-/** Per-kind counts over a flat artifact list — shared by the printed table and
- *  the interactive row labels. */
 function countByKind(artifacts) {
     const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
     for (const a of artifacts)
         counts[a.kind]++;
     return counts;
 }
-/** Human table for the CLI. Returns lines (no trailing newline). */
 export function renderBrowserSessions(groups) {
     if (groups.length === 0)
         return 'No browser profiles found.';
@@ -153,10 +121,6 @@ export function renderBrowserSessions(groups) {
     }
     return lines.join('\n');
 }
-/**
- * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
- * substring match. Returns the absolute path, or null if nothing matched.
- */
 export function resolveArtifact(groups, selector) {
     const all = groups.flatMap((g) => g.artifacts).sort((a, b) => b.mtimeMs - a.mtimeMs);
     if (all.length === 0)
@@ -166,15 +130,6 @@ export function resolveArtifact(groups, selector) {
     const hit = all.find((a) => a.name === selector) ?? all.find((a) => a.name.includes(selector));
     return hit ? hit.path : null;
 }
-/**
- * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
- * keyed by task name. A task's entry is deleted on `agents browser stop` (see
- * service.ts `saveTaskState`), so a task whose run has already ended is absent
- * here even though its captures remain on disk — that is exactly the
- * "unlinked legacy task" case {@link groupIntoRows} reports. Same read-straight-
- * from-disk approach as the rest of this module: works whether or not the
- * browser daemon is running.
- */
 export function loadTaskIdentities(profile) {
     const out = new Map();
     let raw;
@@ -205,16 +160,6 @@ export function loadTaskIdentities(profile) {
     }
     return out;
 }
-/**
- * Identity for one profile's tasks, durable copy first.
- *
- * `browser_sessions` is the source of truth: it is written at task start and
- * never deleted, so it answers for tasks that have already stopped — the case
- * `tasks.json` structurally cannot, since `saveTaskState` rewrites that file
- * from the LIVE task map. The live file is still merged on top for a task that
- * is running right now, so a task started by an older CLI (no DB row yet) keeps
- * whatever identity it does have rather than regressing to nothing.
- */
 export function loadDurableTaskIdentities(profile) {
     const merged = new Map();
     for (const record of listBrowserSessionRecords(profile)) {
@@ -234,20 +179,6 @@ export function loadDurableTaskIdentities(profile) {
     }
     return merged;
 }
-/**
- * Build the launchId -> sessionId index from the same three sources
- * `feed-post.ts` `resolvePostIdentity` already uses for this exact problem —
- * a browser task's `launchId` IS the `AGENT_LAUNCH_ID` of the CLI run that
- * called `agents browser start` (see service.ts `resolveTaskIdentity`), so
- * resolving "which session ran this launch" is the same join, not a new one.
- * Lowest-confidence source first so a later, more specific source overwrites
- * it on a collision:
- *  1. the activity log (durable, but least specific — read last)
- *  2. the SessionStart hook's live-session index (kept for parity with
- *     `hook-sessions.ts`; empty on this fleet today, harmless when so)
- *  3. the per-pid launch registry (`ag run`, launch-scoped, most authoritative)
- * Computed once per interactive session, not per row.
- */
 export function buildLaunchSessionIndex() {
     const byLaunchId = new Map();
     for (const ev of readRecentActivity({ maxBytesPerSession: 64 * 1024 })) {
@@ -264,18 +195,10 @@ export function buildLaunchSessionIndex() {
     }
     return { byLaunchId };
 }
-/** Resolve one launchId through the index to its canonical `SessionMeta`, or
- *  `null` when the join has no hit or the resolved session isn't indexed here. */
 export function resolveLaunchSession(index, launchId) {
     const sessionId = index.byLaunchId.get(launchId);
     return sessionId ? getSessionById(sessionId) : null;
 }
-/**
- * Group flat per-profile artifacts into task-first rows, newest first. Pure:
- * identities and the launch resolver are passed in, so this has no filesystem
- * or session-index dependency and is unit-testable with synthetic data (see
- * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
- */
 export function groupIntoRows(groups, taskIdentities, resolveLaunch, resolveSession) {
     const rows = [];
     for (const g of groups) {
@@ -294,9 +217,6 @@ export function groupIntoRows(groups, taskIdentities, resolveLaunch, resolveSess
         for (const [task, artifacts] of byTask) {
             artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
             const identity = identities.get(task);
-            // Session id first: it is the direct answer and the one agents actually
-            // carry. The launchId join stays as the fallback for a task that recorded
-            // only that (an older CLI, or a run whose session id was unset).
             let linkedSession = null;
             if (identity?.sessionId && resolveSession)
                 linkedSession = resolveSession(identity.sessionId);
@@ -333,27 +253,16 @@ export function groupIntoRows(groups, taskIdentities, resolveLaunch, resolveSess
     rows.sort((a, b) => b.latestMtimeMs - a.latestMtimeMs);
     return rows;
 }
-/** Build task-first rows for one profile (or every profile with captures),
- *  reading `tasks.json` and resolving launchIds against the live indexes.
- *  The interactive picker's data source. */
 export function buildBrowserSessionRows(profile) {
-    // Retention runs from BOTH listing paths, not just the computer one: a box
-    // that uses `agents browser` and never runs `agents sessions --computer`
-    // would otherwise never sweep either table. Best-effort — a read-only DB
-    // must not break a listing.
     try {
         pruneToolSessions();
     }
-    catch { /* listing must not fail on retention */ }
+    catch { }
     const groups = listBrowserSessions(profile);
     const taskIdentities = new Map(groups.map((g) => [g.profile, loadDurableTaskIdentities(g.profile)]));
     const index = buildLaunchSessionIndex();
     return groupIntoRows(groups, taskIdentities, (launchId) => resolveLaunchSession(index, launchId), (sessionId) => getSessionById(sessionId));
 }
-/**
- * Search predicate for the interactive picker: task name, profile, the linked
- * session's agent/topic/label, and any artifact filename in the row.
- */
 export function matchesBrowserSessionRow(row, query) {
     const q = query.trim().toLowerCase();
     if (!q)
@@ -370,11 +279,6 @@ export function matchesBrowserSessionRow(row, query) {
     }
     return row.artifacts.some((a) => a.name.toLowerCase().includes(q));
 }
-/**
- * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
- * `open` is the Commander value for `--open [selector]`: undefined when the flag
- * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
- */
 export async function runBrowserSessions(opts) {
     const groups = listBrowserSessions(opts.profile);
     if (opts.open !== undefined && opts.open !== false) {

package/dist/lib/browser-client.d.ts

@@ -1,158 +1,46 @@
-/**
- * browser-client.ts — the ONE process client through which agents-cli talks to
- * the standalone `browser` CLI (@phnx-labs/browser-cli, PHNX-4101).
- *
- * This is the agents-owned half of the browser extraction, and it is
- * deliberately small. agents-cli no longer carries the CDP/BiDi/Arc drivers, a
- * browser IPC service, a chrome-data/profile store, a network-capture pipeline,
- * or the remote SSH driving loop — the standalone engine owns all of it, exactly
- * as `secrets` took the keychain engine (PHNX-3989), `computer` took the
- * accessibility engine (PHNX-4075) and `sessions` took the transcript engine
- * (PHNX-4012). What stays here is what only the fleet CLI can know: which device
- * a `--device` name resolves to, whether this machine consents to being driven,
- * who the acting session is, and where an action must be recorded.
- *
- * THERE IS NO FALLBACK. A missing executable throws `BROWSER_BIN_MISSING` with
- * install guidance (DIST-1) rather than silently driving a bundled engine —
- * agents-cli has none to drive, and a fallback would re-couple the two release
- * trains this extraction exists to separate.
- *
- * Transport — inherited-fd passthrough, not request/response (matches
- * browser-cli's `bin/browser.cjs` launcher, which forwards fds 3-16):
- *
- *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
- *     stdout is the command's stdout, its `--json` is the command's `--json`,
- *     its prompts reach a real tty. agents-cli never re-formats engine output,
- *     which is what keeps the surface honest as the engine evolves.
- *   - fd 3 (`BROWSER_CONTEXT_FD`) carries ONE JSON object — the consumer context
- *     built by `lib/browser/context.ts` — written and closed immediately, so the
- *     engine reads to EOF and proceeds. The document is read once, before command
- *     parsing; a malformed one is a hard error, an absent one the standalone case.
- *   - fd 4 (`BROWSER_EVENTS_FD`) carries NDJSON action events back: one JSON
- *     object per line, each an action the engine actually performed. agents-cli
- *     turns those into feed events and `sessions --browser` history
- *     (`lib/browser/record.ts`). The engine may emit none; it must never block
- *     on this pipe.
- *
- * Both fds are anonymous pipes on the child's side, the same shape
- * `computer-client.ts` and `secrets-client.ts` settled on after a named FIFO
- * wedged macOS reads. The context is pushed rather than pulled so the engine
- * needs no callback into agents-cli — one direction each way, no reentrancy.
- */
-/** fd the engine reads its one-shot JSON context from. */
 export declare const BROWSER_CONTEXT_FD = 3;
-/** fd the engine writes NDJSON action events to. */
 export declare const BROWSER_EVENTS_FD = 4;
 export declare class BrowserClientError extends Error {
     code: string;
     constructor(code: string, message: string);
 }
 export declare function isBrowserClientError(err: unknown): err is BrowserClientError;
-/**
- * Accept only the real standalone `browser` executable, never agents-cli's own
- * `browser` command shim (`exec "$AGENTS_BIN" browser`, `installations/shims.ts`)
- * — resolving that would recurse into this process. `findInPath` already skips
- * `~/.agents/.cache/shims`; this guard is the second line, mirroring
- * `isStandaloneComputer` (agents-cli never shipped a `dist/browser.js` bin, but
- * the check stays symmetric and future-proof against one).
- */
 export declare function isStandaloneBrowser(bin: string): boolean;
-/**
- * Resolve the standalone executable. `BROWSER_BIN` wins so a dev build can be
- * driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — see
- * `isStandaloneBrowser` for why that skip is load-bearing.
- */
 export declare function resolveBrowserBin(): string;
-/** True when the standalone `browser` CLI is resolvable — the readiness signal
- * for `agents setup` without a spawn. Never throws. */
 export declare function browserInstalled(): boolean;
-/** A `.js`/`.cjs`/`.mjs` bin is run through this runtime; a real executable is exec'd directly. */
 export declare function invocation(bin: string): {
     command: string;
     prefix: string[];
 };
-/**
- * One action the engine performed, as it appears on the NDJSON events fd.
- *
- * This is the engine's wire shape (browser-cli integration contract §2), not a
- * translation of it: the engine emits `{event: "browser.action", ts, command,
- * invocationId, pid, task, profile, url, host, sessionId, launchId, actor}`.
- * `command` — not `verb` — is the field that names the action, and it is what
- * marks a line as an action event.
- */
 export interface BrowserActionEvent {
-    /** Always `browser.action` on this stream. */
     event?: string;
-    /** ISO timestamp the engine stamped. */
     ts?: string;
-    /** The verb the engine ran (`navigate`, `screenshot`, `click`, …). */
     command: string;
-    /** The engine's own id for this run — the grouping key for a session row. */
     invocationId?: string;
-    /** The engine process's pid. */
     pid?: number;
-    /** The browser task the action targeted. */
     task?: string;
-    /** The browser profile the task runs under. */
     profile?: string;
-    /** The page URL at the time of the action, when the engine reported one. */
     url?: string;
-    /** The driven device for a `--device` invocation; absent when local. */
     host?: string;
-    /** Identity, echoed back from the context this CLI handed the engine. */
     sessionId?: string;
     launchId?: string;
     actor?: string;
-    /** Free-form detail the engine attaches. */
     [key: string]: unknown;
 }
-/**
- * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
- * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
- * trailing partial line carried forward — are unit-testable without a spawn.
- *
- * A malformed line is dropped, not thrown: these events are telemetry riding
- * alongside a user-visible action that already happened. Failing the command
- * because its receipt was unreadable would be strictly worse than losing the
- * receipt. The action itself already failed loud on its own channel if it failed.
- */
 export declare function parseEventLines(buffer: string): {
     events: BrowserActionEvent[];
     rest: string;
 };
 interface RunBrowserOptions {
-    /** argv handed to the standalone, after the program name. */
     argv: string[];
-    /** The consumer context serialized onto fd 3. */
     context: unknown;
-    /** Called once per action event the engine reports on fd 4. */
     onEvent?: (event: BrowserActionEvent) => void;
-    /**
-     * Capture the engine's stdout instead of inheriting the terminal.
-     *
-     * Used only where agents-cli must READ an answer rather than show it (the
-     * setup readiness probe polling `status --json`). Verbs never capture:
-     * re-printing engine output would make agents-cli a formatter for a surface
-     * it no longer owns.
-     */
     capture?: boolean;
 }
 interface RunBrowserResult {
     exitCode: number;
-    /** Engine stdout, only when `capture` was set. */
     stdout: string;
 }
-/**
- * Run the standalone engine with the consumer context on fd 3 and the action
- * event stream on fd 4. Resolves with the engine's exit code; the caller
- * propagates it so `agents browser` exits exactly as the engine did.
- *
- * Throws `BROWSER_BIN_MISSING` when the standalone is not installed. Every other
- * failure is the engine's own, reported on the inherited stderr.
- */
 export declare function runBrowser(opts: RunBrowserOptions): Promise<RunBrowserResult>;
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export declare function _resetBrowserClientForTest(): void;
 export {};