@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/feed/tool-activity.js

@@ -0,0 +1,313 @@
+/**
+ * Event-driven tool-activity collector — the thing that makes the rows in
+ * `tools.ts` reach the feed stream without a poll.
+ *
+ * THE COST THIS EXISTS TO AVOID. A status surface that wants "which browser
+ * tasks and computer runs are there right now" has, until this module, one way
+ * to ask: run `agents browser sessions --json` and `agents computer sessions
+ * --json`, per device, on a timer. Two subprocesses per tool per device per
+ * tick, each paying a full CLI boot, to answer "nothing changed" almost every
+ * time. A menu bar at a one-minute cadence over a ten-device fleet is 1,200
+ * process spawns an hour for, typically, zero new rows.
+ *
+ * WHAT REPLACES IT. The two sources are files on the machine that owns them:
+ * the browser runtime tree (task index + capture dirs) and the event ledger
+ * that `computer.action` appends to. This collector watches those roots, and
+ * re-projects ONLY when one of them reports a change. A warm idle does no work
+ * at all: no directory read, no subprocess, no emission. When something does
+ * change it re-projects and emits the DIFF — the changed rows and the vanished
+ * row keys — never a full snapshot, so a single new screenshot costs one
+ * `tool.upsert`.
+ *
+ * WHEN THE WATCHERS CANNOT ARM (an unsupported filesystem, a root that does not
+ * exist yet) the collector says so on `armed` and re-projects on the bounded
+ * sweep cadence instead. That is a stated degradation, not a silent one: a
+ * caller can surface it, and the diff shape is identical either way.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getBrowserRuntimeDir } from '../state.js';
+import { getEventsDir } from './events.js';
+import { listTaskBindings } from '../browser/task-index.js';
+import { buildBrowserSessionRows } from '../browser/sessions-list.js';
+import { buildComputerSessionRows, standaloneComputerActionsDir } from '../computer/sessions-list.js';
+import { boundBrowserRow, projectBrowserToolRow, projectComputerToolRow, sortToolRows } from './tools.js';
+/** Re-projection cadence used only while no directory watcher could arm. */
+export const TOOL_SWEEP_MS = 5_000;
+/** Computer ledger rows read per projection. Bounds the newest-first window. */
+const TOOL_COMPUTER_LIMIT = 500;
+/**
+ * Project every browser task and computer run this machine knows about into
+ * canonical tool rows, newest first. Impure by design — the three readers are
+ * injectable so a test drives real temp stores rather than a mocked service.
+ */
+export function collectToolRows(scope, sources = {}) {
+    let complete = true;
+    const read = (source, empty) => {
+        try {
+            return source();
+        }
+        catch {
+            complete = false;
+            return empty;
+        }
+    };
+    const bindings = new Map();
+    for (const binding of read(sources.bindings ?? listTaskBindings, []))
+        bindings.set(binding.name, binding);
+    const liveTasks = new Map();
+    for (const task of read(sources.liveTasks ?? (() => readLiveBrowserTasks()), []))
+        liveTasks.set(task.task, task);
+    const rows = [];
+    const browserRows = read(sources.browserRows ?? (() => buildBrowserSessionRows()), []);
+    const captured = new Set();
+    for (const row of browserRows) {
+        if (row.task)
+            captured.add(row.task);
+        rows.push(projectBrowserToolRow(scope, row, row.task ? bindings.get(row.task) : undefined, row.task ? liveTasks.get(row.task) : undefined));
+    }
+    // Neither the capture tree nor the task index alone answers "which tasks exist".
+    // `tasks.json` is the live authority (and the only source of tabs); the task
+    // index additionally routes a task whose browser runs on ANOTHER device, which
+    // has no local live record. A task bound a second ago is live and closable with
+    // no capture to its name, and deriving rows from captures alone hid exactly that.
+    for (const task of new Set([...liveTasks.keys(), ...bindings.keys()])) {
+        if (captured.has(task))
+            continue;
+        const binding = bindings.get(task);
+        const live = liveTasks.get(task);
+        rows.push(projectBrowserToolRow(scope, boundBrowserRow(task, live ?? binding ?? {}), binding, live));
+    }
+    const computerRows = read(sources.computerRows ?? (() => buildComputerSessionRows({ limit: TOOL_COMPUTER_LIMIT, observer: scope })), []);
+    for (const row of computerRows)
+        rows.push(projectComputerToolRow(scope, row));
+    return { rows: sortToolRows(rows), complete };
+}
+/**
+ * Holds the last projected row set and answers "what changed?".
+ *
+ * Row identity is the projection's own `rowKey`, so a browser task that gains a
+ * capture upserts under the same key, and a closed task — gone from both the
+ * index and the capture tree — comes back as a remove.
+ */
+export class ToolRowSet {
+    rows = new Map();
+    /** The diff from the current set to `next`, and adopt `next` as current. */
+    diff(next) {
+        const upserts = [];
+        const seen = new Set();
+        for (const row of next) {
+            seen.add(row.rowKey);
+            const serialized = JSON.stringify(row);
+            if (this.rows.get(row.rowKey) === serialized)
+                continue;
+            this.rows.set(row.rowKey, serialized);
+            upserts.push(row);
+        }
+        const removes = [];
+        for (const key of [...this.rows.keys()]) {
+            if (seen.has(key))
+                continue;
+            this.rows.delete(key);
+            removes.push(key);
+        }
+        return { upserts, removes };
+    }
+    /** Adopt `rows` as the current set without emitting a diff (a reset). */
+    reset(rows) {
+        this.rows.clear();
+        for (const row of rows)
+            this.rows.set(row.rowKey, JSON.stringify(row));
+    }
+}
+/**
+ * The directory roots whose contents back the tool rows.
+ *
+ * The standalone computer ledger is its OWN root: the engine writes there
+ * directly, without going through agents-cli, so nothing under the event-ledger
+ * or browser roots changes when an operator runs `computer` by hand. Omitting it
+ * meant those actions were only ever noticed on a sweep triggered by unrelated
+ * activity.
+ */
+export function toolWatchRoots() {
+    return [getBrowserRuntimeDir(), getEventsDir(), standaloneComputerActionsDir()];
+}
+/**
+ * One profile's live task records, with the tabs each task addresses.
+ *
+ * THROWS on a read it cannot trust. An absent `tasks.json` is the ordinary "no
+ * live browser on this profile" case and returns nothing — but EACCES, EMFILE, a
+ * truncated file or malformed JSON are failures, and swallowing them returned an
+ * empty list that is indistinguishable from "every task closed". The caller then
+ * published a remove for every live row. Failing loud here is what lets
+ * `collectToolRows` mark the projection incomplete and PRESERVE the rows it has.
+ */
+function readLiveTasksFor(profileDir) {
+    const file = path.join(profileDir, 'tasks.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // Only "it isn't there" is benign. Anything else is a read we cannot trust.
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        // A JSON error is NOT benign: the browser rewrites this file in place, so a
+        // parse failure usually means we caught a write in progress — and the tasks
+        // are still very much alive.
+        throw new Error(`unreadable live task state at ${file}: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`unexpected live task state at ${file}: expected an object of tasks`);
+    }
+    const out = [];
+    for (const [name, value] of Object.entries(parsed)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const record = value;
+        // `tabs` maps the task's SHORT id -> the engine's target id. The short id is
+        // what `browser tab focus` takes and what stays stable across a reconnect,
+        // so it is the id published; the target id is never surfaced.
+        const borrowed = new Set(Array.isArray(record.borrowedTabs) ? record.borrowedTabs.filter((id) => typeof id === 'string') : []);
+        const tabs = [];
+        if (record.tabs && typeof record.tabs === 'object') {
+            for (const id of Object.keys(record.tabs)) {
+                tabs.push({ id, ...(record.currentTabId === id ? { current: true } : {}), ...(borrowed.has(id) ? { borrowed: true } : {}) });
+            }
+        }
+        out.push({
+            task: typeof record.name === 'string' ? record.name : name,
+            ...(typeof record.profile === 'string' ? { profile: record.profile } : {}),
+            ...(typeof record.label === 'string' ? { label: record.label } : {}),
+            tabs,
+            // The real persisted schema is `createdAt` + `lastActionAt` (`browser/types.ts`
+            // `Task`). An earlier revision read `startedAt`, which the DTO at
+            // `service.ts` uses but `tasks.json` never carries — so every zero-capture
+            // task reported no start time at all and sorted to the bottom.
+            ...(typeof record.createdAt === 'number' ? { startedAtMs: record.createdAt } : {}),
+            // `lastActionAt` is refreshed by every task-scoped action, which makes it
+            // the honest freshness key for a task that has produced no capture yet.
+            // Tasks written before RUSH-2622 carry none; `createdAt` is the fallback the
+            // browser's own reader normalizes them to.
+            ...(typeof record.lastActionAt === 'number' ? { lastActionAtMs: record.lastActionAt }
+                : typeof record.createdAt === 'number' ? { lastActionAtMs: record.createdAt } : {}),
+            ...(typeof record.sessionId === 'string' ? { sessionId: record.sessionId } : {}),
+            ...(typeof record.launchId === 'string' ? { launchId: record.launchId } : {}),
+            ...(typeof record.actor === 'string' ? { actor: record.actor } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Every live browser task on this machine, across every profile runtime dir.
+ *
+ * THROWS for the same reason {@link readLiveTasksFor} does. A runtime dir that
+ * does not exist means no browser has ever run here — genuinely no tasks. A
+ * readdir that fails for any other reason (EACCES, EMFILE) is a failure, and
+ * returning `[]` for it would tell the differ every task had closed.
+ */
+export function readLiveBrowserTasks(root = getBrowserRuntimeDir()) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'sessions')
+            continue;
+        out.push(...readLiveTasksFor(path.join(root, entry.name)));
+    }
+    return out;
+}
+/**
+ * Watch the tool roots and report diffs until `signal` aborts.
+ *
+ * `armed()` reports whether every root currently has a live watcher. It is a
+ * FUNCTION, not a flag captured at setup: a watcher can die later (its directory
+ * is removed and recreated, an inotify limit is hit), and a frozen `armed: true`
+ * meant the tick kept short-circuiting on `!dirty` from a watcher that would
+ * never report again — changes were then missed permanently, with the handle
+ * still claiming to be armed. Each tick re-arms whatever is missing and sweeps
+ * until everything is watched again.
+ */
+export function watchToolActivity(options) {
+    const roots = options.roots ?? toolWatchRoots();
+    const set = new ToolRowSet();
+    if (options.initial)
+        set.reset(options.initial);
+    let dirty = false;
+    let stopped = false;
+    /** One entry per root; `undefined` means that root needs re-arming. */
+    const watchers = new Map(roots.map((root) => [root, undefined]));
+    const armRoot = (root) => {
+        if (stopped || watchers.get(root))
+            return;
+        try {
+            // A root that does not exist yet (no browser has ever run here) cannot be
+            // watched, and would never be retried. Creating it arms the watcher now.
+            fs.mkdirSync(root, { recursive: true });
+            // Recursive: a capture lands in <root>/<profile>/sessions/<task>/, several
+            // levels below the root, and a non-recursive watch never sees it.
+            const watcher = fs.watch(root, { recursive: true }, () => { dirty = true; });
+            watcher.on('error', () => {
+                watcher.close();
+                // Release the slot AND mark dirty: the events this watcher dropped
+                // between failing and being replaced have to be picked up by a sweep,
+                // or a change that landed inside that gap is lost for good.
+                if (watchers.get(root) === watcher)
+                    watchers.set(root, undefined);
+                dirty = true;
+            });
+            watchers.set(root, watcher);
+        }
+        catch { /* reported by armed(); the sweep covers it until it arms */ }
+    };
+    for (const root of roots)
+        armRoot(root);
+    const armed = () => [...watchers.values()].every((watcher) => watcher !== undefined);
+    const reproject = () => {
+        const snapshot = collectToolRows(options.scope, options.sources);
+        // An incomplete read is not evidence a task closed. Keep the rows we have and
+        // stay dirty so the next tick retries — publishing removes here is what made
+        // live rows flicker out on a transient failure.
+        if (!snapshot.complete) {
+            dirty = true;
+            return;
+        }
+        const diff = set.diff(snapshot.rows);
+        if (diff.upserts.length > 0 || diff.removes.length > 0)
+            options.onDiff(diff);
+    };
+    const timer = setInterval(() => {
+        for (const root of roots)
+            armRoot(root);
+        // Fully-armed watchers mean a tick with nothing reported does NOTHING — no
+        // directory read, no projection. That is the warm-idle guarantee, and it is
+        // conditional on every root actually being watched right now.
+        if (armed() && !dirty)
+            return;
+        dirty = false;
+        reproject();
+    }, options.sweepMs ?? TOOL_SWEEP_MS);
+    const stop = () => {
+        stopped = true;
+        clearInterval(timer);
+        for (const watcher of watchers.values())
+            watcher?.close();
+        watchers.clear();
+    };
+    options.signal.addEventListener('abort', stop, { once: true });
+    return { armed, stop };
+}

package/dist/lib/feed/tools.d.ts

@@ -0,0 +1,198 @@
+import type { BrowserSessionRow, ArtifactKind } from '../browser/sessions-list.js';
+import type { ComputerRunRow } from '../computer/sessions-list.js';
+/** Newest captures retained per row. A task with hundreds of screenshots must
+ *  not turn one stream envelope into a megabyte. */
+export declare const TOOL_CAPTURE_LIMIT = 20;
+/** Newest actions retained per computer row, for the same reason. */
+export declare const TOOL_ACTION_LIMIT = 50;
+export type ToolKind = 'browser' | 'computer';
+/** Why a row carries no owning session: `linked` resolved one, `unresolved` has
+ *  an id that no indexed session matches, `unlinked` never had one. Mirrors the
+ *  status both source modules already publish. */
+export type ToolLinkStatus = 'linked' | 'unresolved' | 'unlinked';
+/** One artifact a tool produced. Path only — never contents. */
+export interface ToolCapture {
+    kind: ArtifactKind;
+    name: string;
+    /**
+     * Absolute path ON {@link ToolCapture.host}. A capture lives on the machine
+     * whose browser produced it, so a fleet reader on another box must not treat
+     * this as a local path — it has to open it through that host. Carrying the host
+     * per capture is what makes the path meaningful off-box at all.
+     */
+    path: string;
+    /** The device that holds this file. */
+    host: string;
+    bytes?: number;
+    atMs: number;
+}
+/**
+ * One tab a browser task has open, with the id the task itself addresses it by.
+ *
+ * `id` is the task's SHORT tab id (the key of `Task.tabs`), not the underlying
+ * CDP target id: the short id is what `agents browser tab focus <id>` accepts
+ * and what stays stable for the life of the tab, while the target id is an
+ * engine-internal handle that a reconnect can change.
+ */
+export interface ToolTab {
+    id: string;
+    url?: string;
+    title?: string;
+    /** The tab URL-less verbs act on. */
+    current?: boolean;
+    /**
+     * The task drives this tab but did not open it, so no close path touches it.
+     * Surfaced so a UI does not offer to close someone else's tab.
+     */
+    borrowed?: boolean;
+}
+/**
+ * An argv a consumer may run verbatim, plus the device it must run ON.
+ *
+ * `runOn` is load-bearing and is NOT a `--device` flag. A browser task is bound
+ * to its device at `start`, and every later verb resolves that binding from the
+ * local task index — `agents browser done --task x --device y` is explicitly
+ * REJECTED (`browser/task-index.ts` `REJECT_DEVICE_MESSAGE`). So the way to act
+ * on a task observed from another box is to run the plain argv on the host that
+ * holds the binding, which is what this names.
+ */
+export interface ToolCommand {
+    command: 'agents';
+    args: string[];
+    runOn: string;
+}
+/** The agent session that drove the tool, as a click-through target. */
+export interface ToolOwner {
+    sessionId: string;
+    device: string;
+    label?: string;
+    agent?: string;
+}
+interface ToolRowBase {
+    kind: ToolKind;
+    /** Opaque, stable identity for this row within one device scope. */
+    rowKey: string;
+    /** The observing device that reported the row. */
+    scope: string;
+    /** The DRIVEN machine — for `--device` runs this differs from `scope`. */
+    device: string;
+    /** Is this a resource that still exists and can be acted on? */
+    live: boolean;
+    task?: string;
+    sessionId?: string;
+    launchId?: string;
+    agent?: string;
+    owner?: ToolOwner;
+    linkStatus: ToolLinkStatus;
+    startedAtMs: number;
+    updatedAtMs: number;
+    /** Newest first, bounded by {@link TOOL_CAPTURE_LIMIT}. */
+    captures: ToolCapture[];
+    captureCounts: Record<string, number>;
+}
+export interface BrowserToolRow extends ToolRowBase {
+    kind: 'browser';
+    profile: string;
+    /** Redacted by {@link redactToolUrl}; absent when the binding recorded none. */
+    url?: string;
+    /**
+     * Tabs the task has open, newest-known first. Absent — not empty — when this
+     * host holds no live task record to read them from (a task bound to another
+     * device, or one whose run already ended leaving only captures). Absent means
+     * "unknown here", `[]` means "genuinely none".
+     */
+    tabs?: ToolTab[];
+    /**
+     * Focus one of this task's tabs. Present only while `live` and only for a tab
+     * the task actually owns.
+     */
+    showCommand?: ToolCommand;
+    /**
+     * The command that closes this task. Present ONLY while `live` — a task the
+     * index no longer binds has nothing left to close, and offering the command
+     * anyway would fail loud at the operator instead of at this boundary.
+     */
+    closeCommand?: ToolCommand;
+}
+export interface ComputerToolRow extends ToolRowBase {
+    kind: 'computer';
+    /** Always false: see the module docblock. A run is history, not a session. */
+    live: false;
+    bundle?: string;
+    /** Newest first, bounded by {@link TOOL_ACTION_LIMIT}. */
+    actions: {
+        verb: string;
+        atMs: number;
+        host?: string;
+        bundle?: string;
+    }[];
+    actionCounts: Record<string, number>;
+    /** Total actions for a row whose per-verb detail the ledger already pruned. */
+    recoveredActionCount?: number;
+}
+export type ToolRow = BrowserToolRow | ComputerToolRow;
+/**
+ * A task the local browser holds LIVE state for, read from its `tasks.json`.
+ *
+ * This is the only authority on a task's tabs: `tasks.json` is rewritten from
+ * the live task map, so an entry here means the task exists right now, and its
+ * `tabs` map is what `agents browser tab focus` addresses. A task whose run has
+ * ended is absent even though its captures remain, which is exactly the
+ * distinction `live` on a row reports.
+ */
+export interface LiveBrowserTask {
+    task: string;
+    profile?: string;
+    label?: string;
+    tabs?: ToolTab[];
+    /** `Task.createdAt` — when the task was opened. */
+    startedAtMs?: number;
+    /** `Task.lastActionAt` — refreshed by every task-scoped action. */
+    lastActionAtMs?: number;
+    sessionId?: string;
+    launchId?: string;
+    /** `Task.actor` — who launched it, when the record carries one. */
+    actor?: string;
+}
+/** Stable identity for one tool row within one device scope. */
+export declare function toolRowKey(scope: string, kind: ToolKind, identity: string): string;
+/**
+ * A task URL safe to publish: userinfo removed and credential-shaped query
+ * parameters replaced. A string that does not parse as a URL is dropped
+ * entirely rather than published unexamined — it cannot be redacted safely.
+ */
+export declare function redactToolUrl(raw: string | undefined): string | undefined;
+/**
+ * A browser task the task index binds but that has produced no capture yet.
+ *
+ * `buildBrowserSessionRows` derives its rows from captures on disk, so a task
+ * that was just opened — bound, live, drivable, closable — had no row at all
+ * until its first screenshot landed. That is the window an operator most wants
+ * to see, and it is exactly when a Sessions pane showed nothing. This
+ * synthesizes the zero-capture row so it goes through the SAME projection rather
+ * than a second parallel one.
+ */
+export declare function boundBrowserRow(task: string, binding: {
+    profile?: string;
+}): BrowserSessionRow;
+/**
+ * One browser task (or a profile's downloads bucket) as a tool row. Pure: the
+ * liveness verdict is passed in, because only the machine running the browser
+ * daemon holds the task index that answers it.
+ */
+export declare function projectBrowserToolRow(scope: string, row: BrowserSessionRow, binding?: {
+    device?: string;
+    profile?: string;
+    url?: string;
+    createdAt?: number;
+    sessionId?: string;
+    launchId?: string;
+}, live?: LiveBrowserTask): BrowserToolRow;
+/**
+ * One computer run as a tool row. `live` is pinned false and no close/stop
+ * command is produced: the emitting CLI process is already gone.
+ */
+export declare function projectComputerToolRow(scope: string, row: ComputerRunRow): ComputerToolRow;
+/** Newest first across both kinds — the order a consumer renders. */
+export declare function sortToolRows(rows: ToolRow[]): ToolRow[];
+export {};