@phnx-labs/agents-cli 1.21.3 → 1.22.0

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

@@ -14,15 +14,72 @@
  * never fatal — one asleep laptop must not blank the list.
  */
 import { spawn } from 'child_process';
+import { StringDecoder } from 'string_decoder';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
-import { loadDevices } from '../devices/registry.js';
+import { resolveExplicitTargetSet } from '../devices/resolve-target.js';
+import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
-import { normalizeHost } from './sync/config.js';
+import { machineId, normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
 import { terminalWidth } from './width.js';
+import { sanitizeForTerminal } from '../redact.js';
+import { mapBounded } from '../concurrency.js';
+import { TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CALL_ROWS, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, TOOL_QUERY_MAX_SERIALIZED_BYTES, serializedToolSearchEnvelopeBytes, } from './tool-index.js';
+import { TOOL_ERROR_OUTPUT_MAX_BYTES, TOOL_INPUT_MAX_BYTES, TOOL_SUCCESS_OUTPUT_MAX_BYTES, sanitizeToolEvidenceText, } from './tool-calls.js';
+const REMOTE_TOOL_TIMEOUT_MS = 60_000;
+export const REMOTE_STDOUT_MAX_BYTES = 16 * 1024 * 1024;
+export const REMOTE_TOOL_AGGREGATE_MAX_BYTES = TOOL_QUERY_MAX_SERIALIZED_BYTES;
+/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
+export class RemoteUtf8Accumulator {
+    decoder = new StringDecoder('utf8');
+    value = '';
+    write(chunk) {
+        this.value += this.decoder.write(chunk);
+    }
+    end() {
+        this.value += this.decoder.end();
+        return this.value;
+    }
+    current() {
+        return this.value;
+    }
+}
+/** Claim received bytes against one fleet-query budget before retaining them. */
+export function consumeRemoteToolByteBudget(budget, bytes) {
+    if (budget.exhausted || bytes > budget.remainingBytes) {
+        budget.remainingBytes = 0;
+        budget.exhausted = true;
+        return false;
+    }
+    budget.remainingBytes -= bytes;
+    if (budget.remainingBytes === 0)
+        budget.exhausted = true;
+    return true;
+}
+/** Charge sanitized, machine-stamped evidence because redaction may expand it. */
+export function consumeParsedRemoteToolSearchBudget(budget, envelope) {
+    return consumeRemoteToolByteBudget(budget, serializedToolSearchEnvelopeBytes(envelope));
+}
+/**
+ * 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 function remoteListCommand(forwardedArgs, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({
+            args: forwardedArgs,
+            env: { [NO_FANOUT_ENV]: '1' },
+        });
+    }
+    const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
 /**
  * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
@@ -80,6 +137,60 @@ export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
     }
     return { items: out, valid: true };
 }
+/** Run one remote `agents sessions … --json` and capture stdout. Resolves
+ * `{ code: null }` on spawn error or timeout (host treated as dead). */
+export function sshCapture(target, remoteCmd, timeoutMs, aggregateBudget, options = {}) {
+    assertValidSshTarget(target);
+    return new Promise((resolve) => {
+        const args = [
+            ...(options.hostKeyOpts ?? []),
+            ...SSH_OPTS,
+            ...(options.multiplex === false ? [] : controlOpts()),
+            ...(options.port === undefined ? [] : ['-p', String(options.port)]),
+            target,
+            remoteCmd,
+        ];
+        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        const decoded = new RemoteUtf8Accumulator();
+        let stdoutBytes = 0;
+        let aggregateBudgetExceeded = false;
+        let settled = false;
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const stdout = code === null ? decoded.current() : decoded.end();
+            resolve({ code, stdout, aggregateBudgetExceeded: aggregateBudgetExceeded || undefined });
+        };
+        const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
+        child.stdout.on('data', (d) => {
+            if (stdoutBytes + d.byteLength > REMOTE_STDOUT_MAX_BYTES) {
+                child.kill('SIGKILL');
+                done(null);
+                return;
+            }
+            if (aggregateBudget && !consumeRemoteToolByteBudget(aggregateBudget, d.byteLength)) {
+                aggregateBudgetExceeded = true;
+                child.kill('SIGKILL');
+                done(null);
+                return;
+            }
+            stdoutBytes += d.byteLength;
+            decoded.write(d);
+        });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+    });
+}
+/** Keep browse and tool-search fan-out on the same automatic peer set. */
+export function isAutomaticSessionPeer(d, self) {
+    if (!isDialableDevice(d))
+        return false;
+    if (normalizeHost(d.name) === self || isControlDevice(d))
+        return false;
+    return d.platform === 'windows' || d.platform === 'linux' || d.platform === 'macos';
+}
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
  * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
@@ -105,6 +216,303 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
         ],
     };
 }
+export function parseRemoteToolProgramCount(stdout, machine, expectedProgram) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const query = parsed.query;
+        const coverage = parsed.coverage;
+        const totals = parsed.totals;
+        const machines = parsed.machines;
+        const coverageKeys = ['indexedFiles', 'indexedCalls', 'skippedFiles', 'limitedFiles', 'remainingFiles'];
+        const totalKeys = ['occurrences', 'toolCalls', 'sessions'];
+        if (parsed.schemaVersion !== 1 || parsed.kind !== 'tool-program-count'
+            || !query || query.program !== expectedProgram || query.semantics !== 'static-program-occurrences-v1'
+            || !coverage || typeof coverage.complete !== 'boolean'
+            || coverageKeys.some((key) => !Number.isSafeInteger(coverage[key]) || coverage[key] < 0)
+            || !totals || totalKeys.some((key) => !Number.isSafeInteger(totals[key]) || totals[key] < 0)
+            || !Array.isArray(machines) || machines.length !== 1
+            || boundedRemoteString(parsed.generatedAt, 128) === undefined) {
+            return { items: [], valid: false };
+        }
+        return {
+            valid: true,
+            items: [{
+                    machine,
+                    envelope: {
+                        schemaVersion: 1,
+                        kind: 'tool-program-count',
+                        generatedAt: parsed.generatedAt,
+                        query: { program: expectedProgram, semantics: 'static-program-occurrences-v1' },
+                        coverage: coverage,
+                        totals: totals,
+                        machines: [{
+                                machine,
+                                coverage: coverage,
+                                totals: totals,
+                            }],
+                    },
+                }],
+        };
+    }
+    catch {
+        return { items: [], valid: false };
+    }
+}
+export async function gatherRemoteToolProgramCounts(forwardedArgs, hosts, expectedProgram) {
+    const result = await gatherRemoteAgentsJson({
+        args: forwardedArgs,
+        noFanoutEnv: NO_FANOUT_ENV,
+        hosts,
+        timeoutMs: REMOTE_TOOL_TIMEOUT_MS,
+        parse: (stdout, machine) => parseRemoteToolProgramCount(stdout, machine, expectedProgram),
+    });
+    return {
+        envelopes: result.items,
+        deviceCount: result.deviceCount,
+        unreachable: [
+            ...(result.discoveryFailed ? ['device registry'] : []),
+            ...result.skipped,
+            ...result.parseFailed,
+        ],
+    };
+}
+function boundedRemoteString(value, maxBytes) {
+    if (typeof value !== 'string' || Buffer.byteLength(value) > maxBytes)
+        return undefined;
+    return sanitizeToolEvidenceText(value, maxBytes);
+}
+function optionalRemoteString(value, maxBytes) {
+    if (value === undefined || value === null)
+        return undefined;
+    return boundedRemoteString(value, maxBytes) ?? null;
+}
+function parseRemoteCall(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const call = value;
+    const id = boundedRemoteString(call.id, 512);
+    const timestamp = boundedRemoteString(call.timestamp, 128);
+    const tool = boundedRemoteString(call.tool, 512);
+    const input = boundedRemoteString(call.input, TOOL_INPUT_MAX_BYTES);
+    const sourceCallId = optionalRemoteString(call.sourceCallId, 512);
+    const output = optionalRemoteString(call.output, TOOL_SUCCESS_OUTPUT_MAX_BYTES);
+    const error = optionalRemoteString(call.error, TOOL_ERROR_OUTPUT_MAX_BYTES);
+    const errorCode = optionalRemoteString(call.errorCode, 512);
+    const parseError = optionalRemoteString(call.parseError, 1024);
+    if (call.programs !== undefined
+        && (!Array.isArray(call.programs) || call.programs.length > 128))
+        return undefined;
+    const programs = Array.isArray(call.programs)
+        ? call.programs.map((program) => boundedRemoteString(program, 512))
+        : [];
+    if (!Array.isArray(call.programOccurrences) || call.programOccurrences.length > 10_000)
+        return undefined;
+    const programOccurrences = call.programOccurrences.map((value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const occurrence = value;
+        const program = boundedRemoteString(occurrence.program, 512);
+        if (!program || (occurrence.role !== 'wrapper' && occurrence.role !== 'effective'))
+            return undefined;
+        return { program, role: occurrence.role };
+    });
+    if (!id || !timestamp || !tool || input === undefined
+        || !Number.isSafeInteger(call.ordinal) || call.ordinal < 0
+        || !['ok', 'error', 'unknown'].includes(String(call.outcome))
+        || sourceCallId === null || output === null || error === null || errorCode === null || parseError === null
+        || programs.some((program) => program === undefined)
+        || programOccurrences.some((occurrence) => occurrence === undefined))
+        return undefined;
+    for (const code of [call.exitCode, call.statusCode]) {
+        if (code !== undefined && (!Number.isSafeInteger(code) || code < 0))
+            return undefined;
+    }
+    return {
+        id,
+        ordinal: call.ordinal,
+        sourceCallId,
+        timestamp,
+        tool,
+        programs: programs,
+        programOccurrences: programOccurrences,
+        input,
+        outcome: call.outcome,
+        exitCode: call.exitCode,
+        statusCode: call.statusCode,
+        errorCode,
+        output,
+        error,
+        parseError,
+    };
+}
+function parseRemoteToolSession(value, machine) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const session = value;
+    const id = boundedRemoteString(session.id, 512);
+    const shortId = boundedRemoteString(session.shortId, 128);
+    const agent = boundedRemoteString(session.agent, 128);
+    const timestamp = boundedRemoteString(session.timestamp, 128);
+    const project = optionalRemoteString(session.project, 4096);
+    const cwd = optionalRemoteString(session.cwd, 4096);
+    const topic = optionalRemoteString(session.topic, 4096);
+    const label = optionalRemoteString(session.label, 4096);
+    const originMachine = optionalRemoteString(session.machine, 512);
+    const dialedMachine = boundedRemoteString(machine, 512);
+    if (!id || !shortId || !agent || !timestamp || !dialedMachine || originMachine === null
+        || project === null || cwd === null || topic === null || label === null
+        || !Array.isArray(session.calls) || session.calls.length > TOOL_QUERY_MAX_CALL_ROWS)
+        return undefined;
+    const calls = session.calls.map(parseRemoteCall);
+    if (calls.some((call) => call === undefined))
+        return undefined;
+    return {
+        id,
+        shortId,
+        agent,
+        machine: originMachine ?? dialedMachine,
+        timestamp,
+        project,
+        cwd,
+        topic,
+        label,
+        calls: calls,
+    };
+}
+export function parseRemoteToolSearch(stdout, machine, expectedClauses) {
+    if (Buffer.byteLength(stdout) > REMOTE_STDOUT_MAX_BYTES)
+        return undefined;
+    try {
+        const parsed = JSON.parse(stdout);
+        const coverage = parsed?.coverage;
+        const query = parsed?.query;
+        if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.sessions)
+            || parsed.sessions.length > TOOL_QUERY_MAX_RESULT_SESSIONS || !coverage || !query
+            || !Array.isArray(query.clauses) || query.clauses.length > TOOL_QUERY_MAX_CLAUSES
+            || query.clauses.some((clause) => boundedRemoteString(clause, TOOL_QUERY_MAX_CLAUSE_BYTES) === undefined))
+            return undefined;
+        let totalCalls = 0;
+        for (const sessionValue of parsed.sessions) {
+            if (!sessionValue || typeof sessionValue !== 'object' || Array.isArray(sessionValue))
+                return undefined;
+            const calls = sessionValue.calls;
+            if (!Array.isArray(calls) || calls.length > TOOL_QUERY_MAX_CALL_ROWS)
+                return undefined;
+            totalCalls += calls.length;
+            if (totalCalls > TOOL_QUERY_MAX_CALL_ROWS)
+                return undefined;
+        }
+        const clauses = query.clauses.map((clause) => sanitizeForTerminal(clause));
+        const expected = expectedClauses?.map((clause) => sanitizeForTerminal(clause));
+        if (expected && (clauses.length !== expected.length
+            || clauses.some((clause, index) => clause !== expected[index])))
+            return undefined;
+        const coverageNumbers = ['indexedFiles', 'indexedCalls', 'skippedFiles', 'limitedFiles', 'remainingFiles'];
+        if (coverageNumbers.some((key) => !Number.isSafeInteger(coverage[key]) || coverage[key] < 0)
+            || typeof coverage.complete !== 'boolean')
+            return undefined;
+        const sessions = parsed.sessions.map((session) => parseRemoteToolSession(session, machine));
+        const generatedAt = boundedRemoteString(parsed.generatedAt, 128);
+        if (!generatedAt || sessions.some((session) => session === undefined))
+            return undefined;
+        return {
+            schemaVersion: 1,
+            generatedAt,
+            query: { clauses },
+            coverage: {
+                indexedFiles: coverage.indexedFiles,
+                indexedCalls: coverage.indexedCalls,
+                skippedFiles: coverage.skippedFiles,
+                limitedFiles: coverage.limitedFiles,
+                remainingFiles: coverage.remainingFiles,
+                complete: coverage.complete,
+            },
+            sessions: sessions,
+        };
+    }
+    catch {
+        return 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 async function gatherRemoteToolSearch(forwardedArgs, hosts, maxAggregateBytes = REMOTE_TOOL_AGGREGATE_MAX_BYTES, expectedClauses = []) {
+    const self = machineId();
+    const targets = [];
+    const unresolved = [];
+    if (hosts && hosts.length > 0) {
+        const resolved = await resolveExplicitTargetSet(hosts);
+        targets.push(...resolved.targets);
+        unresolved.push(...resolved.unresolved);
+    }
+    else {
+        let reg;
+        try {
+            reg = await loadDevices();
+        }
+        catch {
+            return { envelopes: [], deviceCount: 0, unreachable: ['device registry'], truncated: [] };
+        }
+        for (const d of Object.values(reg)) {
+            if (!isAutomaticSessionPeer(d, self))
+                continue;
+            try {
+                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
+            }
+            catch {
+                // A registered control record without a dialable address is not a query target.
+            }
+        }
+    }
+    const remainingBytes = Math.max(0, Math.min(REMOTE_TOOL_AGGREGATE_MAX_BYTES, maxAggregateBytes));
+    const aggregateBudget = {
+        remainingBytes,
+        exhausted: remainingBytes === 0,
+    };
+    const parsedBudget = {
+        remainingBytes,
+        exhausted: remainingBytes === 0,
+    };
+    const results = await mapBounded(targets, async (target) => {
+        if (aggregateBudget.exhausted)
+            return { target, truncated: target.name };
+        const capture = await sshCapture(target.target, remoteListCommand(forwardedArgs, target.os), REMOTE_TOOL_TIMEOUT_MS, aggregateBudget, 
+        // A tool-index deadline must own the SSH connection. Killing a
+        // multiplexed child would leave its remote command running on the
+        // persistent control master.
+        { multiplex: false });
+        if (capture.aggregateBudgetExceeded)
+            return { target, truncated: target.name };
+        if (capture.code !== 0)
+            return { target, unreachable: target.name };
+        const envelope = parseRemoteToolSearch(capture.stdout, target.machine, expectedClauses);
+        if (!envelope)
+            return { target, unreachable: target.name };
+        if (!consumeParsedRemoteToolSearchBudget(parsedBudget, envelope)) {
+            return { target, truncated: target.name };
+        }
+        return { target, envelope };
+    }, { concurrency: 6 });
+    for (const result of results) {
+        if (result.unreachable) {
+            process.stderr.write(chalk.gray(`  ${result.unreachable}: unreachable, incompatible, or no agents CLI — skipped\n`));
+        }
+        if (result.truncated) {
+            process.stderr.write(chalk.gray(`  ${result.truncated}: fleet tool-result budget exhausted — skipped\n`));
+        }
+    }
+    return {
+        envelopes: results.flatMap((result) => result.envelope
+            ? [{ machine: result.target.machine, envelope: result.envelope }]
+            : []),
+        deviceCount: targets.length,
+        unreachable: [...unresolved, ...results.map((result) => result.unreachable).filter((name) => !!name)],
+        truncated: results.map((result) => result.truncated).filter((name) => !!name),
+    };
+}
 /** 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. */

package/dist/lib/session/shell-programs.d.ts

@@ -0,0 +1,15 @@
+import { type Word } from 'unbash';
+export interface ShellProgramExtraction {
+    programs: string[];
+    occurrences: ShellProgramOccurrence[];
+    diagnostics: string[];
+}
+export type ShellProgramRole = 'wrapper' | 'effective';
+export interface ShellProgramOccurrence {
+    program: string;
+    role: ShellProgramRole;
+}
+/** Return a word only when Bash expansion cannot change its value. */
+export declare function staticShellWord(word: Word | undefined): string | undefined;
+/** Parse Bash without executing it and return every statically identifiable program. */
+export declare function extractShellPrograms(source: string, depth?: number): ShellProgramExtraction;