@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/feed/hub.js

@@ -0,0 +1,255 @@
+/**
+ * One fleet fan-out, many readers.
+ *
+ * THE COST THIS EXISTS TO AVOID. `watchFleetFeed` opens a persistent
+ * `ssh <peer> agents feed watch --json --local` per dialable device — that is
+ * correct, and it is also per CALLER. Every consumer that wanted the operator
+ * stream ran its own copy: the extension's leader child, a menu-bar helper, an
+ * operator's `agents feed watch --json`. Three readers on a thirteen-device
+ * fleet is thirty-nine long-lived ssh children carrying byte-identical NDJSON,
+ * three copies of the local activity cursor, and three independent backoff
+ * ladders that each re-dial the same offline box.
+ *
+ * WHAT REPLACES IT. The hub owns exactly ONE {@link watchFleetFeed} — so one ssh
+ * child per reachable peer, one collector, one backoff ladder — and broadcasts
+ * to every subscriber. The fan-out starts on the FIRST subscriber and stops on
+ * the LAST, so an idle box with no reader open holds no peer connections at all.
+ *
+ * A LATE SUBSCRIBER COSTS NOTHING. The hub keeps the per-scope row state the
+ * stream has delivered so far, so subscriber two is served a synthesized reset
+ * per scope out of that state — no second fan-out, no re-dial, no waiting for
+ * the peers to re-announce. Its `streamId`/`sequence` are its own and start at
+ * 1, which is exactly what the published contract ("order by streamId +
+ * sequence") lets a consumer rely on.
+ *
+ * RESET SEMANTICS ARE PRESERVED, NOT REINVENTED. A peer's reset replaces that
+ * ONE scope's rows in the held state and is forwarded verbatim; a peer going
+ * unavailable forwards the `scope` event and leaves its rows in place, so a
+ * reader that attaches while a box is offline still sees that box's last-known
+ * rows marked unavailable rather than an empty fleet.
+ */
+import { machineId, normalizeHost } from '../machine-id.js';
+import { FeedWatchState } from './envelope.js';
+/** Activity events replayed to a late subscriber. The lane is a rolling view,
+ *  so a bounded tail is the honest amount of history to hand over. */
+export const HUB_ACTIVITY_REPLAY = 50;
+function emptyScope() {
+    return { agents: new Map(), attention: new Map(), tools: new Map(), setup: [], capturedAt: 0 };
+}
+/**
+ * The per-scope row state the hub has observed. This is a projection of the
+ * events already delivered, never an independent gather: nothing here reads a
+ * file, runs a command, or dials a peer.
+ */
+export class FeedHubState {
+    scopes = new Map();
+    activity = [];
+    scope(name) {
+        const key = normalizeHost(name);
+        let scope = this.scopes.get(key);
+        if (!scope) {
+            scope = emptyScope();
+            this.scopes.set(key, scope);
+        }
+        return scope;
+    }
+    apply(event) {
+        const scope = this.scope(event.scope);
+        switch (event.type) {
+            case 'reset':
+                // One scope only. A peer reconnecting must not erase another's rows.
+                scope.agents = new Map(event.agents.map((agent) => [agent.rowKey, agent]));
+                scope.attention = new Map(event.attention.map((item) => [item.key, item]));
+                scope.tools = new Map(event.tools.map((tool) => [tool.rowKey, tool]));
+                scope.setup = event.setup;
+                scope.capturedAt = event.capturedAt;
+                break;
+            case 'agent.upsert':
+                scope.agents.set(event.rowKey, event.agent);
+                break;
+            case 'agent.remove':
+                scope.agents.delete(event.rowKey);
+                break;
+            case 'attention.upsert':
+                scope.attention.set(event.rowKey, event.attention);
+                break;
+            case 'attention.remove':
+                scope.attention.delete(event.rowKey);
+                break;
+            case 'tool.upsert':
+                scope.tools.set(event.rowKey, event.tool);
+                break;
+            case 'tool.remove':
+                scope.tools.delete(event.rowKey);
+                break;
+            case 'setup.snapshot':
+                scope.setup = event.setup;
+                break;
+            case 'scope':
+                // Rows are deliberately RETAINED: transient fleet loss is not session
+                // death, the same rule `watchLocalSessions` states for its own scope.
+                scope.status = { status: event.status, ...(event.reason ? { reason: event.reason } : {}) };
+                break;
+            case 'activity.append':
+                this.activity.push(event.event);
+                if (this.activity.length > HUB_ACTIVITY_REPLAY)
+                    this.activity.shift();
+                break;
+            case 'heartbeat': break;
+        }
+    }
+    /** The envelopes that bring a fresh subscriber to the current state. */
+    snapshot(state) {
+        const out = [];
+        for (const [name, scope] of this.scopes) {
+            out.push(state.emit({
+                type: 'reset', scope: name, capturedAt: scope.capturedAt || Date.now(),
+                agents: [...scope.agents.values()], attention: [...scope.attention.values()],
+                tools: [...scope.tools.values()], setup: scope.setup,
+            }));
+            if (scope.status)
+                out.push(state.emit({ type: 'scope', scope: name, capturedAt: Date.now(), ...scope.status }));
+        }
+        // Chronological, matching the order they were first delivered in.
+        for (const event of this.activity) {
+            out.push(state.emit({ type: 'activity.append', scope: normalizeHost(machineId()), event }));
+        }
+        return out;
+    }
+    /** Scopes the hub has seen. Observability + tests. */
+    get scopeNames() { return [...this.scopes.keys()]; }
+}
+/**
+ * The shared collector. Construct one per process; call {@link subscribe} per
+ * reader.
+ */
+export class FeedHub {
+    options;
+    subscribers = new Set();
+    held = new FeedHubState();
+    controller = null;
+    running = null;
+    /**
+     * Bumped on every start/stop. A fan-out's completion handler only clears state
+     * when its own generation is still current, so a run winding down cannot clear
+     * a newer one's controller.
+     */
+    generation = 0;
+    /** The most recent fan-out failure, if the current generation hit one. */
+    lastFailure = null;
+    /**
+     * Called when the fan-out rejects. Without this the failure lived only in a
+     * dropped promise, so readers sat attached to a collector that had already died
+     * and saw an idle stream instead of an error. Settable so the socket server can
+     * attach after construction.
+     */
+    onFailure = null;
+    watch;
+    constructor(options) {
+        this.options = options;
+        this.watch = options.watch;
+    }
+    /** Readers currently attached. The fan-out runs iff this is > 0. */
+    get readerCount() { return this.subscribers.size; }
+    /** Is the single shared fan-out running right now? */
+    get active() { return this.controller !== null; }
+    /** The held per-scope state, for observability and tests. */
+    get state() { return this.held; }
+    /**
+     * Attach a reader. It is immediately served a snapshot of the held state, then
+     * every later event. Returns the detach function; the fan-out stops when the
+     * last reader detaches.
+     */
+    subscribe(emit) {
+        const subscriber = { emit, state: new FeedWatchState() };
+        this.subscribers.add(subscriber);
+        for (const event of this.held.snapshot(subscriber.state))
+            emit(event);
+        this.start();
+        let detached = false;
+        return () => {
+            if (detached)
+                return;
+            detached = true;
+            this.subscribers.delete(subscriber);
+            if (this.subscribers.size === 0)
+                this.stop();
+        };
+    }
+    /** Stop the fan-out and detach every reader. */
+    async close() {
+        this.subscribers.clear();
+        this.stop();
+        const running = this.running;
+        this.running = null;
+        if (running)
+            await running.catch(() => { });
+    }
+    /** Await the in-flight fan-out's teardown. Tests assert no overlap with it. */
+    async settled() {
+        await this.running?.catch(() => { });
+    }
+    /**
+     * Start the single fan-out, waiting for any previous one to finish first.
+     *
+     * The wait is the whole point. `stop()` aborts and returns immediately, but the
+     * fan-out it aborted is still tearing down ssh children. A reader that detaches
+     * and immediately reattaches — a VS Code window reloading, a menu-bar popover
+     * closing and reopening — therefore used to start a SECOND fan-out alongside
+     * the dying one: two ssh children per peer, two collectors, for as long as the
+     * overlap lasted. Serializing on the previous run makes that impossible.
+     */
+    start() {
+        if (this.controller)
+            return;
+        const generation = ++this.generation;
+        this.lastFailure = null;
+        const controller = new AbortController();
+        this.controller = controller;
+        const previous = this.running ?? Promise.resolve();
+        this.running = previous
+            .catch(() => { })
+            .then(() => {
+            // The readers may all have left while we waited for the old run to
+            // drain; starting then would dial every peer for nobody.
+            if (generation !== this.generation || controller.signal.aborted)
+                return;
+            return this.watch({
+                signal: controller.signal,
+                ...(this.options.reconnectMs !== undefined ? { reconnectMs: this.options.reconnectMs } : {}),
+                // Generation-guarded: an aborted fan-out can still emit while it drains
+                // (a peer's last buffered line, a pending promise resolving). Those
+                // envelopes describe the OLD subscription and must not reach the new
+                // generation's readers or mutate its held state.
+                emit: (event) => { if (generation === this.generation)
+                    this.broadcast(event); },
+            });
+        })
+            .catch((error) => {
+            // Surfaced, never swallowed: a reader attached to a dead collector would
+            // otherwise be indistinguishable from a quiet fleet.
+            if (generation === this.generation) {
+                this.lastFailure = error instanceof Error ? error : new Error(String(error));
+                this.onFailure?.(this.lastFailure);
+            }
+        })
+            .finally(() => {
+            // Only clear if this is still the live run: a stop/start cycle may have
+            // replaced it, and clearing then would strand the newer controller.
+            if (generation === this.generation)
+                this.controller = null;
+        });
+    }
+    stop() {
+        this.generation += 1;
+        this.controller?.abort();
+        this.controller = null;
+    }
+    broadcast(event) {
+        this.held.apply(event);
+        const { v: _v, streamId: _streamId, sequence: _sequence, ...payload } = event;
+        for (const subscriber of this.subscribers) {
+            subscriber.emit(subscriber.state.emit(payload));
+        }
+    }
+}

package/dist/lib/feed/pr-status.d.ts

@@ -7,9 +7,17 @@ export interface PullRequestStatus extends PullRequestAttentionSignal {
     statusCheckRollup?: unknown[];
 }
 /** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
+export declare const PR_STATUS_DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * @param options.timeoutMs bound for the underlying `gh` call. An operator-facing
+ *   caller working against a deadline (the feed answer path) passes its remaining
+ *   budget so one unreachable PR cannot consume the whole operation; a timed-out
+ *   read is negative-cached for the TTL like any other failure.
+ */
 export declare function readPullRequestStatus(session: ActiveSession, options?: {
     nowMs?: number;
     ttlMs?: number;
+    timeoutMs?: number;
     gh?: GhExec;
 }): Promise<PullRequestStatus | undefined>;
 export declare function resetPullRequestStatusCache(): void;

package/dist/lib/feed/pr-status.js

@@ -15,6 +15,13 @@ function needsHuman(value) {
     return value.reviewDecision !== 'APPROVED' || (value.mergeable === 'MERGEABLE' && checksSettled);
 }
 /** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
+export const PR_STATUS_DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * @param options.timeoutMs bound for the underlying `gh` call. An operator-facing
+ *   caller working against a deadline (the feed answer path) passes its remaining
+ *   budget so one unreachable PR cannot consume the whole operation; a timed-out
+ *   read is negative-cached for the TTL like any other failure.
+ */
 export async function readPullRequestStatus(session, options = {}) {
     const ref = session.pr?.url ?? session.pr?.number;
     if (!ref || !session.cwd)
@@ -25,7 +32,8 @@ export async function readPullRequestStatus(session, options = {}) {
     if (hit && hit.expiresAt > now)
         return hit.value;
     const cwd = session.cwd;
-    const gh = options.gh ?? (async (args) => (await execFileAsync('gh', args, { cwd, timeout: 15_000, maxBuffer: 1024 * 1024 })).stdout);
+    const timeout = options.timeoutMs ?? PR_STATUS_DEFAULT_TIMEOUT_MS;
+    const gh = options.gh ?? (async (args) => (await execFileAsync('gh', args, { cwd, timeout, maxBuffer: 1024 * 1024 })).stdout);
     try {
         const stdout = await gh(['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS]);
         const raw = JSON.parse(stdout);

package/dist/lib/feed/tool-activity.d.ts

@@ -0,0 +1,108 @@
+import { type BrowserSessionRow } from '../browser/sessions-list.js';
+import { type ComputerRunRow } from '../computer/sessions-list.js';
+import type { LiveBrowserTask } from './tools.js';
+import { type ToolRow } from './tools.js';
+/** Re-projection cadence used only while no directory watcher could arm. */
+export declare const TOOL_SWEEP_MS = 5000;
+/** What one re-projection changed. Empty on both sides means nothing moved. */
+export interface ToolDiff {
+    upserts: ToolRow[];
+    removes: string[];
+}
+interface ToolSources {
+    browserRows?: () => BrowserSessionRow[];
+    computerRows?: () => ComputerRunRow[];
+    bindings?: () => Array<{
+        name: string;
+        device?: string;
+        profile?: string;
+        url?: string;
+        createdAt?: number;
+        sessionId?: string;
+        launchId?: string;
+    }>;
+    liveTasks?: () => LiveBrowserTask[];
+}
+/**
+ * One projection attempt. `complete` is false when any source threw.
+ *
+ * The flag is load-bearing, not diagnostic. A transient read failure — the
+ * browser rewriting `tasks.json`, a rotating ledger, an EMFILE — used to yield an
+ * EMPTY row list, which the differ then read as "every task closed" and published
+ * as a remove for every row. The operator watched their live tasks vanish and
+ * come back. An incomplete projection is not evidence of absence, so the caller
+ * keeps the state it already had.
+ */
+export interface ToolSnapshot {
+    rows: ToolRow[];
+    complete: boolean;
+}
+/**
+ * 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 declare function collectToolRows(scope: string, sources?: ToolSources): ToolSnapshot;
+/**
+ * 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 declare class ToolRowSet {
+    private readonly rows;
+    /** The diff from the current set to `next`, and adopt `next` as current. */
+    diff(next: ToolRow[]): ToolDiff;
+    /** Adopt `rows` as the current set without emitting a diff (a reset). */
+    reset(rows: ToolRow[]): void;
+}
+interface ToolWatchOptions {
+    scope: string;
+    signal: AbortSignal;
+    /** Called with every non-empty diff. */
+    onDiff: (diff: ToolDiff) => void;
+    /** Re-projection cadence while no watcher is armed. */
+    sweepMs?: number;
+    /** Roots to watch (tests pass temp dirs). */
+    roots?: string[];
+    /** Row sources, forwarded to {@link collectToolRows}. */
+    sources?: ToolSources;
+    /** Seed the set so the first diff reports only later changes. */
+    initial?: ToolRow[];
+}
+/**
+ * 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 declare function toolWatchRoots(): string[];
+/**
+ * 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 declare function readLiveBrowserTasks(root?: string): LiveBrowserTask[];
+/**
+ * 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 declare function watchToolActivity(options: ToolWatchOptions): {
+    armed: () => boolean;
+    stop: () => void;
+};
+export {};