@phnx-labs/agents-cli 1.22.114 → 1.22.115

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

package/dist/lib/feed/tools.js

@@ -0,0 +1,265 @@
+/**
+ * Canonical tool activity on the feed stream — browser tasks and computer runs
+ * projected into one row contract, alongside the agent and attention rows.
+ *
+ * WHY A PROJECTION AND NOT A NEW STORE. Both sources already exist and already
+ * have an owner: `agents browser sessions` groups a profile's captures into
+ * task-first rows (`browser/sessions-list.ts`), and `agents computer sessions`
+ * groups `computer.action` ledger entries into run rows
+ * (`computer/sessions-list.ts`). A menu-bar or Fleet view that wanted the same
+ * information had only one way to get it: shell out to those two commands, per
+ * tool, per device, on a timer. That is the per-tool polling this module
+ * removes — the rows ride the ONE stream `agents feed watch --json` already
+ * holds open, so a consumer switching its All/Agents/Browser/Computer filter
+ * spawns zero commands.
+ *
+ * WHAT IS DELIBERATELY DIFFERENT BETWEEN THE TWO KINDS. A browser task is a
+ * LIVE resource: it is bound in the task index while it exists, it can be
+ * driven, and it can be closed (`agents browser done --task <name>`). A
+ * computer run is a LEDGER ENTRY: the actions already happened, the CLI process
+ * that performed them has exited, and there is nothing to stop. So
+ * {@link ComputerToolRow} pins `live: false` and carries no close/stop command
+ * at all — inventing one would offer an operator a control that cannot work.
+ *
+ * PRIVACY. Rows carry capture PATHS and names, never contents, and a task URL
+ * is redacted ({@link redactToolUrl}) before it leaves this process: userinfo
+ * is stripped and credential-shaped query parameters are replaced. The feed is
+ * read by the menu bar, the extension, and any `--json` consumer; a bearer
+ * token in a `?access_token=` is exactly the value that must not ride it.
+ */
+import { createHash } from 'node:crypto';
+import { normalizeHost } from '../machine-id.js';
+import { sessionHeadline } from '../session/title.js';
+/** Newest captures retained per row. A task with hundreds of screenshots must
+ *  not turn one stream envelope into a megabyte. */
+export const TOOL_CAPTURE_LIMIT = 20;
+/** Newest actions retained per computer row, for the same reason. */
+export const TOOL_ACTION_LIMIT = 50;
+/** Stable identity for one tool row within one device scope. */
+export function toolRowKey(scope, kind, identity) {
+    return createHash('sha256').update(`${scope}\0${kind}\0${identity}`).digest('base64url').slice(0, 22);
+}
+/** Query parameters whose value is a credential, not a locator. */
+const CREDENTIAL_PARAM = /(token|secret|password|passwd|pwd|api[-_]?key|auth|session|signature|sig|code)/i;
+const REDACTED = '<redacted>';
+/**
+ * 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 function redactToolUrl(raw) {
+    if (!raw)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    url.username = '';
+    url.password = '';
+    for (const key of [...url.searchParams.keys()]) {
+        if (CREDENTIAL_PARAM.test(key))
+            url.searchParams.set(key, REDACTED);
+    }
+    // A fragment is where OAuth implicit flows put the token, and nothing on a
+    // status row needs it.
+    if (url.hash)
+        url.hash = '';
+    return url.toString();
+}
+/**
+ * The owning agent session, or nothing.
+ *
+ * `sessionId` is passed in as the EFFECTIVE identity rather than read off the
+ * capture row: a task's session is recorded in the live task record and in the
+ * device binding as well as in the durable capture history, and a row assembled
+ * from only one of those had an owner on some paths and not others. Resolving the
+ * effective id first is what makes the owner link consistent for one task however
+ * its row was assembled.
+ *
+ * Returns undefined when no id is known. `recordBrowserSession`/`emit` are
+ * pre-existing no-ops for some paths, so closed history genuinely lacks an owner
+ * sometimes — and an invented link would be worse than an absent one.
+ */
+function ownerOf(sessionId, linkedSession, scope) {
+    if (!sessionId)
+        return undefined;
+    const session = linkedSession ?? undefined;
+    // One headline ladder for the whole CLI (SES-14c): a row's own `label`, then the
+    // daemon-generated title, then the first-prompt topic. Re-deriving it here would
+    // silently drop the generated-title rung and show a different name for the same
+    // session than `agents sessions` does.
+    const label = session ? sessionHeadline(session) : undefined;
+    return {
+        sessionId,
+        device: normalizeHost(session?.machine ?? scope),
+        ...(label ? { label } : {}),
+        ...(session?.agent ? { agent: session.agent } : {}),
+    };
+}
+/** A machine name, or undefined for the `unknown` not-identified sentinel. */
+function knownMachine(machine) {
+    return machine && machine !== 'unknown' ? machine : undefined;
+}
+function countBy(items, key) {
+    const counts = {};
+    for (const item of items)
+        counts[key(item)] = (counts[key(item)] ?? 0) + 1;
+    return counts;
+}
+/**
+ * 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 function boundBrowserRow(task, binding) {
+    return {
+        kind: 'task', task, profile: binding.profile ?? '',
+        linkStatus: 'unlinked', artifacts: [],
+        counts: { screenshot: 0, pdf: 0, recording: 0, download: 0 },
+        latestMtimeMs: 0,
+    };
+}
+/**
+ * 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 function projectBrowserToolRow(scope, row, binding, live) {
+    const host = normalizeHost(scope);
+    // Live means the task still EXISTS: either this host's browser holds a live
+    // record for it, or the task index still routes it (which is the case for a
+    // task whose browser runs on another device).
+    const isLive = Boolean(row.task) && (live !== undefined || binding !== undefined);
+    const captures = row.artifacts.slice(0, TOOL_CAPTURE_LIMIT).map((artifact) => ({
+        kind: artifact.kind, name: artifact.name, path: artifact.path, host, bytes: artifact.bytes, atMs: artifact.mtimeMs,
+    }));
+    const oldest = row.artifacts.length > 0 ? row.artifacts[row.artifacts.length - 1].mtimeMs : row.latestMtimeMs;
+    const url = redactToolUrl(binding?.url);
+    // One effective identity for the row AND its owner link, resolved before either
+    // is built: durable capture history first (it survives the task), then the live
+    // record, then the device binding.
+    const sessionId = row.sessionId ?? live?.sessionId ?? binding?.sessionId;
+    const launchId = row.launchId ?? live?.launchId ?? binding?.launchId;
+    const owner = ownerOf(sessionId, row.linkedSession, host);
+    // Tabs are only knowable from a LIVE task record on THIS host; a row projected
+    // from captures alone, or from a binding pointing at another device, genuinely
+    // does not know them and says so by omitting the field.
+    const tabs = live?.tabs;
+    const showTab = tabs?.find((tab) => tab.current && !tab.borrowed)?.id
+        ?? tabs?.find((tab) => !tab.borrowed)?.id;
+    const startedAtMs = live?.startedAtMs ?? binding?.createdAt ?? oldest;
+    // A task with no captures has no capture mtime to sort by. `lastActionAt` is
+    // refreshed by every task-scoped action, so it is the honest freshness key;
+    // its own start is the fallback. Reporting 0 would sort a brand-new live task
+    // to the very bottom of a newest-first list.
+    const updatedAtMs = Math.max(row.latestMtimeMs, live?.lastActionAtMs ?? 0) || startedAtMs;
+    return {
+        kind: 'browser',
+        // Keyed on the TASK, never on the profile. A task with no captures yet is
+        // discovered from the task index, where the profile may not be recorded, so
+        // folding the profile into the identity would give the same task two
+        // different keys and render it twice the moment its first capture landed.
+        // Task names are unique within a machine's task index, which is the scope
+        // this key is already qualified by. The downloads bucket has no task, so it
+        // keys on its profile — one such row per profile, which is what it is.
+        rowKey: toolRowKey(host, 'browser', row.task ? `task\0${row.task}` : `downloads\0${row.profile}`),
+        scope: host,
+        device: normalizeHost(binding?.device ?? host),
+        live: isLive,
+        ...(row.task ? { task: row.task } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(launchId ? { launchId } : {}),
+        ...(row.linkedSession?.agent ? { agent: row.linkedSession.agent } : {}),
+        ...(owner ? { owner } : {}),
+        linkStatus: row.linkedSession ? 'linked' : sessionId ? 'unresolved' : 'unlinked',
+        startedAtMs,
+        updatedAtMs,
+        captures,
+        captureCounts: countBy(row.artifacts, (artifact) => artifact.kind),
+        profile: row.profile || live?.profile || '',
+        ...(url ? { url } : {}),
+        ...(tabs ? { tabs } : {}),
+        // `runOn` is the OBSERVING host, not `device`: the binding that resolves the
+        // task's device lives here, and passing `--device` to a later verb is
+        // refused outright. See {@link ToolCommand}.
+        ...(isLive && showTab ? { showCommand: { command: 'agents', args: ['browser', 'tab', 'focus', showTab, '--task', row.task], runOn: host } } : {}),
+        ...(isLive ? { closeCommand: { command: 'agents', args: ['browser', 'done', '--task', row.task], runOn: host } } : {}),
+    };
+}
+/**
+ * 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 function projectComputerToolRow(scope, row) {
+    const host = normalizeHost(scope);
+    const owner = ownerOf(row.sessionId, row.linkedSession, host);
+    const agent = row.agent ?? row.linkedSession?.agent;
+    // Captures come ONLY from a `capture` the producer recorded after the file was
+    // written. A screenshot action from before the producer carried that field has
+    // no path to report, and this deliberately reports none rather than guessing one
+    // from an output flag — a fabricated path is worse than an honest absence.
+    //
+    // `host` is the INVOKING machine, never `remoteHost`. The engine's helper RPC
+    // returns the image as base64 and the invoking process resolves `--out` and
+    // writes the file locally, so even a remote-desktop run leaves its screenshot
+    // on the box that ran the command. Naming the driven host would send a consumer
+    // looking for the file on a machine it was never written to.
+    const captures = [];
+    const captureCounts = {};
+    for (const action of row.actions) {
+        if (!action.capture)
+            continue;
+        captureCounts[action.capture.kind] = (captureCounts[action.capture.kind] ?? 0) + 1;
+        if (captures.length >= TOOL_CAPTURE_LIMIT)
+            continue;
+        captures.push({
+            kind: action.capture.kind, name: action.capture.name, path: action.capture.path,
+            host,
+            ...(action.capture.bytes !== undefined ? { bytes: action.capture.bytes } : {}),
+            atMs: action.tsMs,
+        });
+    }
+    const actions = row.actions.slice(0, TOOL_ACTION_LIMIT).map((action) => ({
+        verb: action.verb, atMs: action.tsMs,
+        ...(action.host ? { host: action.host } : {}),
+        ...(action.bundle ? { bundle: action.bundle } : {}),
+    }));
+    return {
+        kind: 'computer',
+        rowKey: toolRowKey(host, 'computer', row.invocationId ?? `${row.machine}\0${row.pid ?? ''}\0${row.startMs}`),
+        scope: host,
+        // `groupIntoComputerRuns` writes the literal 'unknown' when no record in the
+        // run identified a machine, which is a sentinel for "not identified" and not a
+        // device name. Publishing it made a locally-run action unaddressable and made
+        // it disappear under a device filter, so it resolves to the observing host —
+        // which is the machine whose ledger the run was read from.
+        device: normalizeHost(row.remoteHost ?? knownMachine(row.machine) ?? host),
+        live: false,
+        ...(row.task ? { task: row.task } : {}),
+        ...(row.sessionId ? { sessionId: row.sessionId } : {}),
+        ...(row.launchId ? { launchId: row.launchId } : {}),
+        ...(agent ? { agent } : {}),
+        ...(owner ? { owner } : {}),
+        linkStatus: row.linkStatus,
+        startedAtMs: row.startMs,
+        updatedAtMs: row.endMs,
+        captures,
+        captureCounts,
+        ...(row.bundle ? { bundle: row.bundle } : {}),
+        actions,
+        actionCounts: { ...row.counts },
+        ...(row.recoveredActionCount !== undefined ? { recoveredActionCount: row.recoveredActionCount } : {}),
+    };
+}
+/** Newest first across both kinds — the order a consumer renders. */
+export function sortToolRows(rows) {
+    return [...rows].sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+}

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

@@ -1,62 +1,29 @@
-import { type SessionWatchEnvelope, type SessionWatchRow, type SessionWatchScopeStatus, type WatchLocalOptions } from '../session/watch.js';
-import { type AttentionItem } from './attention.js';
-import { type ActivityEvent } from './activity.js';
+import { type SessionWatchEnvelope, type WatchLocalOptions } from '../session/watch.js';
+import { watchToolActivity } from './tool-activity.js';
+import { type ToolRow } from './tools.js';
+import { FeedWatchState, type FeedWatchEnvelope } from './envelope.js';
+import { FeedHub } from './hub.js';
+import { getCachedToolSetup, subscribeToolSetup, type ToolSetupRow } from '../setup-tool-status.js';
 import type { GhExec } from '../github/pr-mergeable.js';
-type Base = {
-    v: 1;
-    type: string;
-    streamId: string;
-    sequence: number;
-    scope: string;
-};
-export type FeedWatchEnvelope = Base & {
-    type: 'reset';
-    capturedAt: number;
-    agents: SessionWatchRow[];
-    attention: AttentionItem[];
-} | Base & {
-    type: 'agent.upsert';
-    rowKey: string;
-    agent: SessionWatchRow;
-} | Base & {
-    type: 'agent.remove';
-    rowKey: string;
-} | Base & {
-    type: 'attention.upsert';
-    rowKey: string;
-    attention: AttentionItem;
-} | Base & {
-    type: 'attention.remove';
-    rowKey: string;
-} | Base & {
-    type: 'activity.append';
-    event: ActivityEvent;
-} | Base & {
-    type: 'scope';
-    capturedAt: number;
-    status: SessionWatchScopeStatus;
-    reason?: string;
-} | Base & {
-    type: 'heartbeat';
-    capturedAt: number;
-};
-type FeedWatchPayload = FeedWatchEnvelope extends infer Envelope ? Envelope extends FeedWatchEnvelope ? Omit<Envelope, 'v' | 'streamId' | 'sequence'> : never : never;
-export declare class FeedWatchState {
-    readonly streamId: string;
-    private sequence;
-    constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
-    emit(event: FeedWatchPayload): FeedWatchEnvelope;
-}
+export { FeedWatchState, type FeedWatchEnvelope, type FeedWatchPayload } from './envelope.js';
 /** Reuse session ownership reconciliation for the combined operator stream. */
 export declare class FeedSessionProjection {
     private readonly state;
     private readonly sessions;
     private readonly observations;
     private projectedAttention;
+    /**
+     * Tool rows per observing scope. A reset replaces one scope's rows and must
+     * not touch another's — the same per-scope rule the agent rows follow, and
+     * the reason a peer reconnecting cannot erase the local machine's tasks.
+     */
+    private readonly toolsByScope;
+    /** Whole-set per scope; see the `setup.snapshot` docblock in `envelope.ts`. */
+    private readonly setupByScope;
     constructor(state?: FeedWatchState);
     apply(event: FeedWatchEnvelope): FeedWatchEnvelope[];
 }
-export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState, gh?: GhExec): Promise<FeedWatchEnvelope[]>;
+export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState, gh?: GhExec, tools?: ToolRow[], setup?: ToolSetupRow[]): Promise<FeedWatchEnvelope[]>;
 interface WatchLocalFeedOptions {
     scope: string;
     signal: AbortSignal;
@@ -69,11 +36,44 @@ interface WatchLocalFeedOptions {
     sessions?: Pick<WatchLocalOptions, 'readCache' | 'readPrevious' | 'journalPath' | 'journalPollMs' | 'heartbeatMs'>;
     /** The `gh` runner behind PR status; a test passes a recorded table. */
     gh?: GhExec;
+    /** Tool-activity inputs, forwarded verbatim to {@link watchToolActivity}. */
+    tools?: Pick<Parameters<typeof watchToolActivity>[0], 'sweepMs' | 'roots' | 'sources'>;
+    /**
+     * Tool-setup readers. The setup teammate owns DETECTION
+     * (`lib/setup-tool-status.ts`); this stream only publishes what its cache
+     * already holds, and never triggers a probe of its own.
+     */
+    setup?: {
+        read?: typeof getCachedToolSetup;
+        subscribe?: typeof subscribeToolSetup;
+    };
 }
 export declare function watchLocalFeed(options: WatchLocalFeedOptions): Promise<void>;
+/**
+ * The one ingress for an envelope produced by ANOTHER agents-cli.
+ *
+ * `tools` was added to the `reset` payload within protocol v1, so a peer on an
+ * older CLI is a correct v1 producer that simply reports no tool rows — which is
+ * true of it, not a data defect to paper over. Normalizing HERE, at the single
+ * place a foreign envelope enters, is what keeps every consumer downstream able
+ * to treat the field as present instead of each re-checking it. A mixed-version
+ * fleet is the normal state during a rollout, so an absent field must not take
+ * the whole fan-out down.
+ */
+export declare function normalizePeerEnvelope(event: FeedWatchEnvelope): FeedWatchEnvelope;
+/** The shared local collector, constructed on first use. Exposed for tests. */
+export declare function sharedLocalFeedHub(): FeedHub;
+/** Reset the shared collector. Tests only — it must not leak across cases. */
+export declare function resetSharedLocalFeedHub(): Promise<void>;
+/**
+ * Subscribe to this machine's rows through the shared collector, until abort.
+ */
+export declare function subscribeSharedLocalFeed(options: {
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+}): Promise<void>;
 export declare function watchFleetFeed(options: {
     signal: AbortSignal;
     emit: (event: FeedWatchEnvelope) => void;
     reconnectMs?: number;
 }): Promise<void>;
-export {};