@phnx-labs/agents-cli 1.22.43 → 1.22.44

package/dist/lib/session/remote/watch.js

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadDevices, isDialableDevice } from '../../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../../devices/connect.js';
+import { machineId, normalizeHost } from '../../machine-id.js';
+import { SSH_OPTS, controlOpts, shellQuote } from '../../ssh-exec.js';
+import { buildWindowsAgentsCommand, remoteShellFor } from '../../hosts/remote-cmd.js';
+import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, } from '../session-cache.js';
+export const SESSION_WATCH_VERSION = 1;
+export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
+/** Stable, opaque identity for one row within one device scope. */
+export function sessionWatchRowKey(scope, row) {
+    const identity = activeSessionJournalIdentity(row);
+    return createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+}
+export function toSessionWatchRow(scope, row) {
+    const rowKey = sessionWatchRowKey(scope, row);
+    const resumable = Boolean(row.sessionId);
+    const viewingIn = row.viewingIn
+        ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
+        : null;
+    return {
+        ...row,
+        rowKey,
+        sourceDevice: scope,
+        resumable,
+        unwatched: !viewingIn,
+        viewingIn,
+        recovery: resumable
+            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', scope], ...(row.cwd ? { cwd: row.cwd } : {}) }
+            : null,
+    };
+}
+function sameRow(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Stream-local sequencer and convergent row diff. */
+export class SessionWatchState {
+    streamId;
+    sequence = 0;
+    rows = new Map();
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    base(type) {
+        return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
+    }
+    reset(scope, sourceRows) {
+        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
+        return { ...this.base('reset'), scope, rows };
+    }
+    update(scope, sourceRows) {
+        const previous = this.rows.get(scope) ?? new Map();
+        const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
+        const events = [];
+        for (const [rowKey, row] of next) {
+            if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
+                events.push({ ...this.base('upsert'), scope, rowKey, row });
+            }
+        }
+        for (const rowKey of previous.keys()) {
+            if (!next.has(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, next);
+        return events;
+    }
+    patch(scope, upserts, removes) {
+        const current = new Map(this.rows.get(scope) ?? []);
+        const events = [];
+        for (const source of upserts) {
+            const row = toSessionWatchRow(scope, source);
+            if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
+                current.set(row.rowKey, row);
+                events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
+            }
+        }
+        for (const identity of removes) {
+            const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
+            if (current.delete(rowKey))
+                events.push({ ...this.base('remove'), scope, rowKey });
+        }
+        this.rows.set(scope, current);
+        return events;
+    }
+    scope(scope, status, reason) {
+        // Deliberately retain rows while unavailable. A reconnecting scope replaces
+        // them with a reset; transient fleet loss must not look like session death.
+        return { ...this.base('scope'), scope, status, ...(reason ? { reason } : {}) };
+    }
+    heartbeat(scope, capturedAt = Date.now()) {
+        return { ...this.base('heartbeat'), scope, capturedAt };
+    }
+}
+/**
+ * Keep one local subscription alive. Startup reads one canonical reset snapshot;
+ * steady state tails the canonical writer journal and never invokes a gather.
+ */
+export async function watchLocalSessions(options) {
+    const state = new SessionWatchState();
+    const readCache = options.readCache ?? readActiveSessionsCache;
+    const journal = options.journalPath ?? activeSessionsJournalPath();
+    const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
+    let offset = 0;
+    try {
+        offset = fs.statSync(journal).size;
+    }
+    catch { /* first publication */ }
+    const initial = readCache('local');
+    options.emit(state.reset(options.scope, initial?.sessions ?? []));
+    options.emit(state.scope(options.scope, initial ? 'available' : 'unavailable', initial ? undefined : 'awaiting publisher'));
+    if (options.signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        let partial = '';
+        let reading = false;
+        const readAppended = () => {
+            if (reading || options.signal.aborted)
+                return;
+            reading = true;
+            try {
+                const size = fs.statSync(journal).size;
+                if (size < offset) {
+                    offset = 0;
+                    partial = '';
+                }
+                if (size === offset)
+                    return;
+                const fd = fs.openSync(journal, 'r');
+                try {
+                    const buffer = Buffer.alloc(size - offset);
+                    fs.readSync(fd, buffer, 0, buffer.length, offset);
+                    offset = size;
+                    const lines = (partial + buffer.toString('utf8')).split('\n');
+                    partial = lines.pop() ?? '';
+                    for (const line of lines) {
+                        if (!line)
+                            continue;
+                        try {
+                            const record = JSON.parse(line);
+                            if (record.version !== 1 || record.scope !== 'local' || !Array.isArray(record.upserts) || !Array.isArray(record.removes))
+                                continue;
+                            for (const event of state.patch(options.scope, record.upserts, record.removes))
+                                options.emit(event);
+                            options.emit(state.scope(options.scope, 'available'));
+                        }
+                        catch { /* partial/corrupt journal lines are not state */ }
+                    }
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            catch { /* journal may not exist until the first publisher write */ }
+            finally {
+                reading = false;
+            }
+        };
+        fs.mkdirSync(path.dirname(journal), { recursive: true });
+        const journalListener = () => readAppended();
+        fs.watchFile(journal, { interval: options.journalPollMs ?? 250 }, journalListener);
+        const heartbeatTimer = setInterval(() => options.emit(state.heartbeat(options.scope)), heartbeatMs);
+        const stop = () => { fs.unwatchFile(journal, journalListener); clearInterval(heartbeatTimer); resolve(); };
+        options.signal.addEventListener('abort', stop, { once: true });
+        // Close the offset/read/watch handoff: a publisher may append after the
+        // startup offset is captured but before watchFile is registered.
+        readAppended();
+    });
+}
+function remoteWatchCommand(os) {
+    const args = ['sessions', 'watch', '--json', '--local'];
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args })
+        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
+}
+/**
+ * Subscribe to every dialable compute device with one persistent SSH process.
+ * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
+ * peer resets only its own scope. There is no recurring fleet list command.
+ */
+export async function watchFleetSessions(options) {
+    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit: options.emit });
+    let devices;
+    try {
+        devices = await loadDevices();
+    }
+    catch {
+        await local;
+        return;
+    }
+    const self = machineId();
+    const peers = Object.values(devices).filter((device) => isDialableDevice(device)
+        && normalizeHost(device.name) !== self
+        && ['windows', 'linux', 'macos'].includes(device.platform));
+    const reconnectMs = options.reconnectMs ?? 2_000;
+    const peerTasks = peers.map(async (device) => {
+        const scope = normalizeHost(device.name);
+        const state = new SessionWatchState();
+        while (!options.signal.aborted) {
+            let target;
+            try {
+                target = sshTargetFor(device);
+            }
+            catch (error) {
+                options.emit(state.scope(scope, 'unavailable', error instanceof Error ? error.message : String(error)));
+                break;
+            }
+            const child = spawn('ssh', [
+                ...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteWatchCommand(device.platform),
+            ], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const stop = () => child.kill('SIGTERM');
+            options.signal.addEventListener('abort', stop, { once: true });
+            const reader = createInterface({ input: child.stdout });
+            reader.on('line', (line) => {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.version === SESSION_WATCH_VERSION && typeof event.sequence === 'number')
+                        options.emit(event);
+                }
+                catch { /* incomplete/non-protocol peer output is not state */ }
+            });
+            const code = await new Promise((resolve) => {
+                child.once('error', () => resolve(null));
+                child.once('close', resolve);
+            });
+            reader.close();
+            options.signal.removeEventListener('abort', stop);
+            if (options.signal.aborted)
+                break;
+            options.emit(state.scope(scope, 'unavailable', code === null ? 'ssh failed' : `ssh exited ${code}`));
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, reconnectMs);
+                options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+        }
+    });
+    await Promise.all([local, ...peerTasks]);
+}

package/dist/lib/session/remote-bundle.d.ts

@@ -1,12 +1 @@
-import { type ParsedBundle } from './bundle.js';
-export interface RemotePullResult {
-    bundles: ParsedBundle[];
-    errors: string[];
-}
-/**
- * Run `agents sessions export …exportArgs --stdout` on each host and parse the
- * streamed bundle. A host that fails (unreachable, remote error, bad output) is
- * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --device (the remote export runs for itself only).
- */
-export declare function pullBundlesFromHosts(hosts: string[], exportArgs: string[]): Promise<RemotePullResult>;
+export * from './remote/remote-bundle.js';

package/dist/lib/session/remote-bundle.js

@@ -1,61 +1,3 @@
-/**
- * Multi-device session transfer over the EXISTING SSH fleet transport
- * (RUSH-1712) — no R2, no daemon. `agents sessions export --device <h>` and
- * `agents sessions import --from-host <h>` both run `agents sessions export
- * … --stdout` ON the peer and stream the bundle back over the same SSH path the
- * cross-machine listing already uses (resolveExplicitTargets + ssh-exec), then
- * either write it (export) or import it (import) locally.
- *
- * This deliberately reuses ssh-exec / resolve-target rather than adding a second
- * transport: the raw form `agents ssh boxA 'agents sessions export --stdout' |
- * agents sessions import -` works with plain export/import; this module is just
- * the one-shot wrapper around it.
- */
-import chalk from 'chalk';
-import { sshExec } from '../ssh-exec.js';
-import { shellQuote } from '../ssh-exec.js';
-import { resolveExplicitTargets } from '../devices/resolve-target.js';
-import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
-import { parseBundle } from './bundle.js';
-/** Remote export can traverse many sessions; give it a generous ceiling. */
-const REMOTE_EXPORT_TIMEOUT_MS = 300_000;
-/** Build `agents <args>` for the peer's login shell (bash or PowerShell). */
-function remoteAgentsCommand(args, os) {
-    if (remoteShellFor(os) === 'powershell') {
-        return buildWindowsAgentsCommand({ args });
-    }
-    const inner = ['agents', ...args].map((t, i) => (i === 0 ? t : shellQuote(t))).join(' ');
-    return `bash -lc ${shellQuote(inner)}`;
-}
-/**
- * Run `agents sessions export …exportArgs --stdout` on each host and parse the
- * streamed bundle. A host that fails (unreachable, remote error, bad output) is
- * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --device (the remote export runs for itself only).
- */
-export async function pullBundlesFromHosts(hosts, exportArgs) {
-    const targets = await resolveExplicitTargets(hosts);
-    const bundles = [];
-    const errors = [];
-    for (const t of targets) {
-        const cmd = remoteAgentsCommand(['sessions', 'export', ...exportArgs, '--stdout'], t.os);
-        process.stderr.write(chalk.dim(`Pulling sessions from ${t.name}…\n`));
-        const res = sshExec(t.target, cmd, { timeoutMs: REMOTE_EXPORT_TIMEOUT_MS, extraSshArgs: t.extraSshArgs });
-        if (res.timedOut) {
-            errors.push(`${t.name}: timed out after ${Math.round(REMOTE_EXPORT_TIMEOUT_MS / 1000)}s`);
-            continue;
-        }
-        if (res.code !== 0) {
-            const tail = res.stderr.trim().split('\n').filter(Boolean).pop();
-            errors.push(`${t.name}: remote export failed (${res.code ?? 'ssh error'})${tail ? ': ' + tail : ''}`);
-            continue;
-        }
-        try {
-            bundles.push(parseBundle(res.stdout));
-        }
-        catch (err) {
-            errors.push(`${t.name}: ${err.message}`);
-        }
-    }
-    return { bundles, errors };
-}
+// Moved to ./remote/remote-bundle.ts (move 4 of the core-module refactor).
+// Kept as a re-export shim so existing importers don't break.
+export * from './remote/remote-bundle.js';

package/dist/lib/session/remote-list.d.ts

@@ -1,148 +1 @@
-import { type DeviceProfile } from '../devices/registry.js';
-import { type RemoteAgentsJsonParseResult } from '../remote-agents-json.js';
-import type { SessionMeta } from './types.js';
-import { type ToolProgramCountEnvelope, type ToolSearchEnvelope } from './tool-index.js';
-export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
-export declare const REMOTE_TOOL_AGGREGATE_MAX_BYTES: number;
-export interface RemoteToolByteBudget {
-    remainingBytes: number;
-    exhausted: boolean;
-}
-/** Claim received bytes against one fleet-query budget before retaining them. */
-export declare function consumeRemoteToolByteBudget(budget: RemoteToolByteBudget, bytes: number): boolean;
-/** Charge sanitized, machine-stamped evidence because redaction may expand it. */
-export declare function consumeParsedRemoteToolSearchBudget(budget: RemoteToolByteBudget, envelope: ToolSearchEnvelope): boolean;
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
-export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
-/**
- * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
- * with `machine`. Defensive against version skew / partial output: non-JSON or
- * a non-array yields `[]`, and non-object entries are dropped rather than
- * throwing. The `machine` we dialed always wins over any value the peer set on
- * its own rows, so grouping keys off the computer we asked. Exported for unit
- * testing without a live tailnet.
- */
-export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
-export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
-    items: SessionMeta[];
-    valid: boolean;
-};
-/** Run one remote `agents sessions … --json` and capture stdout. Resolves
- * `{ code: null }` on spawn error or timeout (host treated as dead). */
-export declare function sshCapture(target: string, remoteCmd: string, timeoutMs: number, aggregateBudget?: RemoteToolByteBudget, options?: {
-    multiplex?: boolean;
-    port?: number;
-    hostKeyOpts?: string[];
-}): Promise<{
-    code: number | null;
-    stdout: string;
-    aggregateBudgetExceeded?: boolean;
-}>;
-export interface RemoteListResult {
-    sessions: SessionMeta[];
-    /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
-    deviceCount: number;
-    /**
-     * Peers that failed to answer, by display name. The stderr note above is
-     * enough for a printed listing, but the interactive browser repaints over it —
-     * so callers rendering a full-screen UI need the outcome as data to tell
-     * "that box is asleep" apart from "that box has no matching sessions".
-     */
-    unreachable: string[];
-}
-/** Keep browse and tool-search fan-out on the same automatic peer set. */
-export declare function isAutomaticSessionPeer(d: DeviceProfile, self: string): boolean;
-/**
- * Gather listing sessions from other machines. With an explicit `hosts` list
- * (from `--device`), fan out to exactly those. Otherwise sweep the registered,
- * online devices from `ag devices`, excluding this machine and any without an
- * address. `forwardedArgs` are the caller's own sessions args (query + filters,
- * already `--json`) so every peer returns the same slice this machine asked for.
- */
-export interface GatherRemoteListOptions {
-    /**
-     * Opt-in early-exit for a globally-unique id lookup (a full UUID): the first
-     * peer to return the matching row resolves the fan-out and cancels the rest.
-     * Omitted for browse/label/prefix sweeps, which must wait for every peer to
-     * know whether the match is unique or conflicting.
-     */
-    isDefinitive?: (session: SessionMeta, machine: string) => boolean;
-    /** Per-peer deadline for slower indexed browse queries. */
-    timeoutMs?: number;
-}
-export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
-export interface RemoteToolSearchResult {
-    envelopes: Array<{
-        machine: string;
-        envelope: ToolSearchEnvelope;
-    }>;
-    deviceCount: number;
-    unreachable: string[];
-    truncated: string[];
-}
-export interface RemoteToolProgramCountResult {
-    envelopes: Array<{
-        machine: string;
-        envelope: ToolProgramCountEnvelope;
-    }>;
-    deviceCount: number;
-    unreachable: string[];
-}
-export declare function parseRemoteToolProgramCount(stdout: string, machine: string, expectedProgram: string): RemoteAgentsJsonParseResult<{
-    machine: string;
-    envelope: ToolProgramCountEnvelope;
-}>;
-export declare function gatherRemoteToolProgramCounts(forwardedArgs: string[], hosts: string[] | undefined, expectedProgram: string): Promise<RemoteToolProgramCountResult>;
-export declare function parseRemoteToolSearch(stdout: string, machine: string, expectedClauses?: string[]): ToolSearchEnvelope | undefined;
-/**
- * Fleet sibling of {@link gatherRemoteList} for the versioned tool-search
- * envelope. Each peer executes the same local-only query against its own
- * SQLite index; only compact matches cross SSH.
- */
-export declare function gatherRemoteToolSearch(forwardedArgs: string[], hosts?: string[], maxAggregateBytes?: number, expectedClauses?: string[]): Promise<RemoteToolSearchResult>;
-/** Resolve a peer's SSH target (and OS) from the device registry by its
- * normalized machine id — the same id the fan-out tags rows with. Returns
- * undefined when no registered device with an address matches. */
-export declare function resolvePeerTarget(machine: string): Promise<{
-    target: string;
-    os?: string;
-} | undefined>;
-/**
- * Fetch one remote session's preview digest from its owning peer — the data
- * behind the picker pane for a `_remote` row, whose transcript file this
- * machine cannot parse. Runs the peer's own `agents sessions preview <id>
- * --local --json` (the same envelope `agents sessions preview` already
- * delegates to for a remote id) and returns its `preview` object, verbatim and
- * UNSANITIZED — the caller owns scrubbing peer-supplied strings before any of
- * them reach a TTY. Undefined on every failure: unregistered machine, SSH
- * error, timeout, version-skewed peer with no `--json` preview envelope.
- */
-export declare function fetchPeerPreviewDigest(sessionId: string, machine: string, timeoutMs?: number): Promise<unknown | undefined>;
-/**
- * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
- * stdio). `args` is the full arg vector after the binary — callers pass e.g.
- * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
- * picked session lives on another machine: its transcript and agent binary are
- * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
- * not via a local `--device` hop, which would discover locally and dead-end for a
- * session that exists only on the peer. Resolves 'no-target' when the machine
- * isn't a dialable registered device; the caller surfaces a clear message.
- *
- * `opts.env` adds variables to the remote command. It deliberately does NOT
- * carry `AGENTS_FLEET_REMOTE` the way the `--device` passthrough does: that marker
- * gates consent-sensitive actions on the far side
- * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
- * that would inherit it for its whole life — `agents browser start` inside it
- * would then be refused as a cross-machine drive. A one-shot `--device` command
- * can carry the marker; a session cannot.
- */
-export declare function runOnPeer(args: string[], machine: string, opts?: {
-    tty?: boolean;
-    env?: Record<string, string>;
-}): Promise<'ok' | 'no-target'>;
+export * from './remote/remote-list.js';