@phnx-labs/agents-cli 1.21.3 → 1.22.0

package/dist/commands/sessions-backfill.js

@@ -0,0 +1,186 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { SESSION_AGENTS } from '../lib/session/types.js';
+import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
+import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
+const BACKFILL_REMOTE_TIMEOUT_MS = 10 * 60_000;
+function parseAgent(value) {
+    if (!value)
+        return {};
+    const separator = value.indexOf('@');
+    const name = (separator < 0 ? value : value.slice(0, separator));
+    if (!SESSION_AGENTS.includes(name))
+        throw new Error(`Unknown session agent: ${name}`);
+    return { agent: name, version: separator < 0 ? undefined : value.slice(separator + 1) || undefined };
+}
+function mergeHosts(options) {
+    const values = [options.host, options.device].flatMap((value) => value === undefined ? [] : Array.isArray(value) ? value : [value]);
+    return [...new Set(values)];
+}
+export async function backfillToolsLocal(options, oneBatch = false) {
+    const { agent, version } = parseAgent(options.agent);
+    const sessions = await discoverSessions({
+        agent,
+        version,
+        project: options.project,
+        since: options.since,
+        until: options.until,
+        all: true,
+        unbounded: true,
+        skipExistenceCheck: true,
+        includeUnmanaged: options.unmanaged,
+        excludeTeamOrigin: !options.teams,
+    });
+    let indexedFiles = 0;
+    let indexedCalls = 0;
+    for (;;) {
+        const batch = await ensureToolIndex(sessions);
+        indexedFiles += batch.indexedFiles;
+        indexedCalls += batch.indexedCalls;
+        if (oneBatch || batch.remainingFiles === 0 || batch.indexedFiles === 0)
+            break;
+    }
+    return {
+        machine: machineId(),
+        indexedFiles,
+        indexedCalls,
+        coverage: readToolIndexCoverage(sessions),
+    };
+}
+function parseRemoteBackfill(stdout, machine) {
+    try {
+        const envelope = JSON.parse(stdout);
+        if (envelope.schemaVersion !== 1 || envelope.kind !== 'tools-backfill'
+            || !Array.isArray(envelope.machines) || envelope.machines.length !== 1) {
+            return { items: [], valid: false };
+        }
+        const item = envelope.machines[0];
+        const coverage = item.coverage;
+        const coverageKeys = ['indexedFiles', 'indexedCalls', 'skippedFiles', 'limitedFiles', 'remainingFiles'];
+        if (!coverage || typeof coverage.complete !== 'boolean'
+            || !Number.isSafeInteger(item.indexedFiles) || item.indexedFiles < 0
+            || !Number.isSafeInteger(item.indexedCalls) || item.indexedCalls < 0
+            || coverageKeys.some((key) => !Number.isSafeInteger(coverage[key]) || coverage[key] < 0)) {
+            return { items: [], valid: false };
+        }
+        return { items: [{ ...item, machine }], valid: true };
+    }
+    catch {
+        return { items: [], valid: false };
+    }
+}
+function peerArgs(options) {
+    const args = ['sessions', 'backfill', 'tools', '--json', '--local'];
+    if (options.agent)
+        args.push('--agent', options.agent);
+    if (options.project)
+        args.push('--project', options.project);
+    if (options.since)
+        args.push('--since', options.since);
+    if (options.until)
+        args.push('--until', options.until);
+    if (options.unmanaged)
+        args.push('--unmanaged');
+    if (options.teams)
+        args.push('--teams');
+    return args;
+}
+export async function runToolsBackfill(options) {
+    const hosts = mergeHosts(options);
+    const includeLocal = options.local === true || hosts.length === 0;
+    const fanOut = options.local !== true && (options.fleet === true || hosts.length > 0);
+    if (!fanOut) {
+        const machines = includeLocal
+            ? [await backfillToolsLocal(options, process.env[NO_FANOUT_ENV] === '1')]
+            : [];
+        return {
+            schemaVersion: 1,
+            kind: 'tools-backfill',
+            generatedAt: new Date().toISOString(),
+            complete: machines.every((machine) => machine.coverage.complete),
+            machines,
+        };
+    }
+    const machineTotals = new Map();
+    let unreachable = false;
+    for (;;) {
+        const localPromise = includeLocal ? backfillToolsLocal(options, true) : Promise.resolve(undefined);
+        const [local, remote] = await Promise.all([localPromise, gatherRemoteAgentsJson({
+                args: peerArgs(options),
+                noFanoutEnv: NO_FANOUT_ENV,
+                hosts: hosts.length > 0 ? hosts : undefined,
+                timeoutMs: BACKFILL_REMOTE_TIMEOUT_MS,
+                parse: parseRemoteBackfill,
+            })]);
+        const round = [local, ...remote.items].filter((item) => item !== undefined);
+        for (const item of round) {
+            const prior = machineTotals.get(item.machine);
+            machineTotals.set(item.machine, {
+                ...item,
+                indexedFiles: (prior?.indexedFiles ?? 0) + item.indexedFiles,
+                indexedCalls: (prior?.indexedCalls ?? 0) + item.indexedCalls,
+            });
+        }
+        unreachable = remote.discoveryFailed || remote.skipped.length > 0 || remote.parseFailed.length > 0;
+        const progressed = round.reduce((sum, item) => sum + item.indexedFiles, 0);
+        if (unreachable || progressed === 0 || (round.length > 0 && round.every((item) => item.coverage.complete)))
+            break;
+    }
+    const machines = [...machineTotals.values()];
+    return {
+        schemaVersion: 1,
+        kind: 'tools-backfill',
+        generatedAt: new Date().toISOString(),
+        complete: !unreachable && machines.every((machine) => machine.coverage.complete),
+        machines,
+    };
+}
+export function registerSessionsBackfillCommand(sessionsCmd) {
+    const backfill = sessionsCmd.command('backfill').description('Populate derived session data explicitly.');
+    const tools = backfill.command('tools').description('Parse historical tool calls once into the local SQLite index.');
+    setHelpSections(tools, {
+        examples: `
+      # Backfill this machine once; reruns resume and skip completed transcripts
+      agents sessions backfill tools
+
+      # Backfill every online compute device, keeping each index local
+      agents sessions backfill tools --fleet --json
+
+      # Narrow the historical work
+      agents sessions backfill tools --agent codex --since 7d
+    `,
+        notes: `
+      - This command is the only historical transcript parse for tool indexing. Tool queries never trigger it.
+      - New and changed sessions are indexed during their normal incremental scan.
+      - No embeddings, vector database, network model, or semantic processing is used.
+    `,
+    });
+    tools.action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (options.local && (options.fleet || mergeHosts(options).length > 0)) {
+            console.error(chalk.red('--local cannot be combined with --fleet, --host, or --device.'));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const envelope = await runToolsBackfill(options);
+            if (options.json)
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            else {
+                for (const machine of envelope.machines) {
+                    console.log(`${machine.machine}: indexed ${machine.indexedFiles.toLocaleString()} transcript${machine.indexedFiles === 1 ? '' : 's'} and ${machine.indexedCalls.toLocaleString()} tool call${machine.indexedCalls === 1 ? '' : 's'}.`);
+                }
+                if (!envelope.complete) {
+                    console.log(chalk.yellow('Backfill is partial; rerun the command after resolving skipped or limited transcripts.'));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/sessions.d.ts

@@ -4,6 +4,7 @@ import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type PickedSession } from './sessions-picker.js';
+import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
     agent?: string;
     project?: string;
@@ -17,7 +18,7 @@ interface SessionFilterOptions {
 interface SessionsOptions extends SessionFilterOptions {
     /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
     unmanaged?: boolean;
-    query?: string;
+    query?: string[];
     /** Resolve one historical selector to metadata only (requires --json). */
     resolve?: string;
     /** Versioned internal peer protocol; old/unsafe peers must reject it. */
@@ -55,6 +56,10 @@ interface SessionsOptions extends SessionFilterOptions {
     local?: boolean;
     /** --device <target...> — alias for --host; resolves against the device registry. */
     device?: string[];
+    /** Query every registered online compute device and merge tool evidence. */
+    fleet?: boolean;
+    /** Aggregate static program sites instead of returning matching call evidence. */
+    count?: boolean;
     /** Per-agent shorthands: aliases for `--agent <name>` (prioritized harnesses). */
     claude?: boolean;
     codex?: boolean;
@@ -338,6 +343,15 @@ export declare function renderSessionPreview(query: string, scope: {
  * attached", so those two spell it out.
  */
 export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, favorite?: boolean): string;
+/** Merge local and peer envelopes without changing the versioned JSON shape. */
+export declare function mergeToolSearchEnvelopes(local: ToolSearchEnvelope, remotes: ToolSearchEnvelope[]): ToolSearchEnvelope;
+export declare function mergeToolProgramCountEnvelopes(local: ToolProgramCountEnvelope, remotes: ToolProgramCountEnvelope[]): ToolProgramCountEnvelope;
+/** Partition a fleet query by transcript origin so synced mirrors cannot duplicate results. */
+export declare function toolOriginSessions(sessions: SessionMeta[], machine: string, originOnly: boolean): SessionMeta[];
+export declare function printToolProgramCount(envelope: ToolProgramCountEnvelope): void;
+export declare function toolSearchFleetSortError(sort: string | undefined, spansDevices: boolean): string | undefined;
+/** Compact grouped evidence for humans; JSON retains every bounded field. */
+export declare function printToolSearch(envelope: ToolSearchEnvelope): void;
 /**
  * Whether a session belongs to `team`, from either end: it spawned the team, or
  * it is one of the team's teammates. Case-insensitive, matching the SQL
@@ -605,6 +619,8 @@ export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: strin
 /** Fixed peer argv for the metadata resolver. Scope flags compose identically on
  * every host; `--all` removes the SSH login cwd/time window, not agent/project filters. */
 export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
+/** Build the local-only peer argv for a distributed tool search. */
+export declare function toolSearchForwardedArgs(argv: string[], hosts: string[]): string[];
 /** Resolution must fail closed when any selected peer did not answer. Choosing
  * from a partial fleet can turn an unseen candidate into a false unique match. */
 export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {