@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/lib/session/parse.js

@@ -7,9 +7,11 @@
  */
 import * as fs from 'fs';
 import { truncate } from '../format.js';
+import { sanitizeForTerminal } from '../redact.js';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { isSyntheticUserMessage } from './prompt.js';
+import { isSyntheticUserMessage, extractSlashCommandName, extractSlashCommandFromToolInput } from './prompt.js';
+import { structuredToolResult } from './tool-calls.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -23,12 +25,7 @@ export const SESSION_FILE_MAX_BYTES = 200_000_000;
  * carriage return (0x0d). Everything else in the C0/C1 range and every CSI/OSC
  * escape is dropped.
  */
-const TERMINAL_ESCAPE_REGEX = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[@-_]|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
-export function sanitizeForTerminal(s) {
-    if (typeof s !== 'string' || !s)
-        return s;
-    return s.replace(TERMINAL_ESCAPE_REGEX, '');
-}
+export { sanitizeForTerminal } from '../redact.js';
 /** Recursively sanitize every string value within a tool-args object. */
 function sanitizeArgsDeep(value) {
     if (typeof value === 'string')
@@ -373,12 +370,21 @@ export function parseClaudeContent(content) {
                         agent: 'claude',
                         timestamp,
                         tool: toolName,
+                        callId: toolId,
                         args: toolInput,
                         path: toolInput.file_path || undefined,
                         command: toolName === 'Bash' ? toolInput.command : undefined,
                     };
                     if (isLocal)
                         event._local = true;
+                    // SlashCommand: the MODEL invoking a slash command programmatically
+                    // (distinct from the <command-name> wrapper below, which is the
+                    // USER typing one) — see prompt.ts's extractSlashCommandFromToolInput.
+                    if (toolName === 'SlashCommand') {
+                        const slashCommand = extractSlashCommandFromToolInput(toolInput);
+                        if (slashCommand)
+                            event.slashCommand = slashCommand;
+                    }
                     events.push(event);
                 }
             }
@@ -403,13 +409,21 @@ export function parseClaudeContent(content) {
                 // Simple user text
                 const text = contentBlocks.trim();
                 if (text) {
-                    events.push({
+                    const event = {
                         type: 'message',
                         agent: 'claude',
                         timestamp,
                         role: 'user',
                         content: text,
-                    });
+                    };
+                    // The USER typing a slash command — Claude injects a <command-name>
+                    // wrapper as the message content (see prompt.ts's
+                    // extractSlashCommandName; distinct from the SlashCommand tool-use
+                    // above, which is the model invoking one programmatically).
+                    const slashCommand = extractSlashCommandName(text);
+                    if (slashCommand)
+                        event.slashCommand = slashCommand;
+                    events.push(event);
                 }
             }
             else if (Array.isArray(contentBlocks)) {
@@ -444,6 +458,7 @@ export function parseClaudeContent(content) {
                         const toolId = block.tool_use_id;
                         const toolInfo = toolId ? toolUseMap.get(toolId) : undefined;
                         const isError = block.is_error === true;
+                        const structured = structuredToolResult(block);
                         // Extract output text from tool result
                         let output = '';
                         if (typeof block.content === 'string') {
@@ -461,6 +476,11 @@ export function parseClaudeContent(content) {
                                 agent: 'claude',
                                 timestamp,
                                 tool: toolInfo?.tool,
+                                callId: toolId,
+                                outcome: 'error',
+                                exitCode: structured.exitCode,
+                                statusCode: structured.statusCode,
+                                errorCode: structured.errorCode,
                                 content: output || 'Tool execution failed',
                             });
                         }
@@ -470,7 +490,12 @@ export function parseClaudeContent(content) {
                                 agent: 'claude',
                                 timestamp,
                                 tool: toolInfo?.tool,
+                                callId: toolId,
                                 success: true,
+                                outcome: 'ok',
+                                exitCode: structured.exitCode,
+                                statusCode: structured.statusCode,
+                                errorCode: structured.errorCode,
                                 output: output.length > 500 ? output.slice(0, 497) + '...' : output,
                             });
                         }
@@ -640,6 +665,7 @@ export function parseCodexContent(content) {
                     agent: 'codex',
                     timestamp,
                     tool: name,
+                    callId,
                     args,
                     command: name === 'exec_command' ? (args.command || args.cmd) : undefined,
                     path: args.file_path || args.path || undefined,
@@ -648,14 +674,19 @@ export function parseCodexContent(content) {
             else if (ptype === 'function_call_output') {
                 const callId = payload.call_id || payload.id;
                 const callInfo = callId ? callMap.get(callId) : undefined;
-                const output = String(payload.output || '');
+                const result = structuredToolResult(payload.output);
                 events.push({
                     type: 'tool_result',
                     agent: 'codex',
                     timestamp,
                     tool: callInfo?.name,
-                    success: true,
-                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                    callId,
+                    success: result.outcome === 'error' ? false : true,
+                    outcome: result.outcome,
+                    exitCode: result.exitCode,
+                    statusCode: result.statusCode,
+                    errorCode: result.errorCode,
+                    output: result.text.length > 500 ? result.text.slice(0, 497) + '...' : result.text,
                 });
                 if (callId)
                     callMap.delete(callId);
@@ -682,6 +713,7 @@ export function parseCodexContent(content) {
                         agent: 'codex',
                         timestamp,
                         tool,
+                        callId,
                         args,
                         path: patchPath,
                     });
@@ -697,14 +729,19 @@ export function parseCodexContent(content) {
             else if (ptype === 'custom_tool_call_output') {
                 const callId = payload.call_id || payload.id;
                 const callInfo = callId ? callMap.get(callId) : undefined;
-                const output = String(payload.output || '');
+                const result = structuredToolResult(payload.output);
                 events.push({
                     type: 'tool_result',
                     agent: 'codex',
                     timestamp,
                     tool: callInfo?.name,
-                    success: true,
-                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                    callId,
+                    success: result.outcome === 'error' ? false : true,
+                    outcome: result.outcome,
+                    exitCode: result.exitCode,
+                    statusCode: result.statusCode,
+                    errorCode: result.errorCode,
+                    output: result.text.length > 500 ? result.text.slice(0, 497) + '...' : result.text,
                 });
                 if (callId)
                     callMap.delete(callId);
@@ -802,6 +839,7 @@ export function parseGemini(filePath) {
                         agent: 'gemini',
                         timestamp: tc.timestamp || timestamp,
                         tool: toolName,
+                        callId: typeof tc.id === 'string' ? tc.id : undefined,
                         args,
                         command: ['run_shell_command', 'shell', 'bash'].includes(toolName) ? args.command : undefined,
                         path: args.file_path || args.path || undefined,
@@ -825,6 +863,7 @@ export function parseGemini(filePath) {
                             agent: 'gemini',
                             timestamp: tc.timestamp || timestamp,
                             tool: toolName,
+                            callId: typeof tc.id === 'string' ? tc.id : undefined,
                             success: tc.status === 'success',
                             output: output.length > 500 ? output.slice(0, 497) + '...' : output,
                         });
@@ -1044,6 +1083,7 @@ export function parseAntigravity(dbPath) {
             agent: 'antigravity',
             timestamp,
             tool: norm,
+            callId: call.id,
             args: a,
             command: norm === 'Bash' ? a.CommandLine : undefined,
             // Antigravity uses PascalCase arg keys; probe the known path-bearing ones.
@@ -1175,6 +1215,7 @@ export function parseGrok(filePath) {
                     agent: 'grok',
                     timestamp,
                     tool: toolName,
+                    callId: typeof call?.id === 'string' ? call.id : undefined,
                     args,
                     path: args.path || args.file_path || undefined,
                     command: typeof args.command === 'string' ? args.command : undefined,
@@ -1190,13 +1231,17 @@ export function parseGrok(filePath) {
             const callId = typeof msg.tool_call_id === 'string' ? msg.tool_call_id : undefined;
             const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
             const output = typeof msg.content === 'string' ? msg.content : extractText(msg.content);
-            const isError = typeof output === 'string' && output.startsWith('Error:');
+            const structuredError = msg.is_error === true;
+            const structuredSuccess = msg.is_error === false;
+            const displayAsError = structuredError || (typeof output === 'string' && output.startsWith('Error:'));
             events.push({
-                type: isError ? 'error' : 'tool_result',
+                type: displayAsError ? 'error' : 'tool_result',
                 agent: 'grok',
                 timestamp,
                 tool: toolName,
-                success: !isError,
+                callId,
+                success: structuredError ? false : structuredSuccess ? true : undefined,
+                outcome: structuredError ? 'error' : structuredSuccess ? 'ok' : 'unknown',
                 output: output.length > 500 ? output.slice(0, 497) + '...' : output,
             });
             if (callId)
@@ -1295,11 +1340,13 @@ export function parseOpenCode(filePath) {
                     const state = partData.state || {};
                     const input = state.input || {};
                     const output = state.output || '';
+                    const callId = typeof partData.callID === 'string' ? partData.callID : undefined;
                     events.push({
                         type: 'tool_use',
                         agent: 'opencode',
                         timestamp,
                         tool: toolName,
+                        callId,
                         args: input,
                         command: toolName === 'shell' ? input.command : undefined,
                         path: input.filePath || input.path || undefined,
@@ -1311,6 +1358,7 @@ export function parseOpenCode(filePath) {
                             agent: 'opencode',
                             timestamp,
                             tool: toolName,
+                            callId,
                             success: state.status === 'completed',
                             output: outputStr.length > 500 ? outputStr.slice(0, 497) + '...' : outputStr,
                         });
@@ -1354,8 +1402,10 @@ export function parseRush(filePath) {
             continue;
         }
         const type = raw.type;
-        const timestamp = raw.created_at || new Date().toISOString();
-        const content = raw.content || {};
+        const timestamp = typeof raw.created_at === 'string' ? raw.created_at : new Date().toISOString();
+        const content = raw.content && typeof raw.content === 'object' && !Array.isArray(raw.content)
+            ? raw.content
+            : {};
         if (type === 'message') {
             const text = typeof content.text === 'string' ? content.text.trim() : '';
             if (!text)
@@ -1378,9 +1428,11 @@ export function parseRush(filePath) {
             });
         }
         else if (type === 'tool_call') {
-            const toolName = raw.name || 'unknown';
-            const args = content.input || {};
-            const callId = raw.tool_call_id;
+            const toolName = typeof raw.name === 'string' && raw.name.length > 0 ? raw.name : 'unknown';
+            const args = content.input && typeof content.input === 'object' && !Array.isArray(content.input)
+                ? content.input
+                : {};
+            const callId = typeof raw.tool_call_id === 'string' ? raw.tool_call_id : undefined;
             if (callId)
                 toolCallMap.set(callId, { tool: toolName, args });
             events.push({
@@ -1388,13 +1440,14 @@ export function parseRush(filePath) {
                 agent: 'rush',
                 timestamp,
                 tool: toolName,
+                callId,
                 args,
                 path: args.file_path || args.path || undefined,
                 command: (toolName === 'Bash' || toolName === 'shell') ? args.command : undefined,
             });
         }
         else if (type === 'tool_result') {
-            const callId = raw.tool_call_id;
+            const callId = typeof raw.tool_call_id === 'string' ? raw.tool_call_id : undefined;
             const info = callId ? toolCallMap.get(callId) : undefined;
             const output = content.output;
             let outputStr = '';
@@ -1414,7 +1467,8 @@ export function parseRush(filePath) {
                 type: success ? 'tool_result' : 'error',
                 agent: 'rush',
                 timestamp,
-                tool: info?.tool ?? raw.name,
+                tool: info?.tool ?? (typeof raw.name === 'string' ? raw.name : 'unknown'),
+                callId,
                 success,
                 output: outputStr.length > 500 ? outputStr.slice(0, 497) + '...' : outputStr,
             });
@@ -1575,9 +1629,11 @@ export function parseKimi(filePath) {
             }
             else if (eventType === 'tool.call') {
                 const fn = event.function || {};
-                const toolName = typeof event.name === 'string' ? event.name : (fn.name || 'unknown');
+                const toolName = typeof event.name === 'string'
+                    ? event.name
+                    : typeof fn.name === 'string' ? fn.name : 'unknown';
                 let args = {};
-                if (event.args && typeof event.args === 'object') {
+                if (event.args && typeof event.args === 'object' && !Array.isArray(event.args)) {
                     args = event.args;
                 }
                 else if (typeof fn.arguments === 'string') {
@@ -1588,10 +1644,11 @@ export function parseKimi(filePath) {
                         args = { _raw: fn.arguments };
                     }
                 }
-                else if (fn.arguments && typeof fn.arguments === 'object') {
+                else if (fn.arguments && typeof fn.arguments === 'object' && !Array.isArray(fn.arguments)) {
                     args = fn.arguments;
                 }
-                const callId = event.toolCallId || event.uuid;
+                const rawCallId = event.toolCallId || event.uuid;
+                const callId = typeof rawCallId === 'string' ? rawCallId : undefined;
                 if (callId) {
                     toolCallMap.set(callId, toolName);
                 }
@@ -1600,23 +1657,29 @@ export function parseKimi(filePath) {
                     agent: 'kimi',
                     timestamp,
                     tool: toolName,
+                    callId,
                     args,
                     path: args.path || args.file_path || undefined,
                     command: toolName === 'Bash' ? args.command : undefined,
                 });
             }
             else if (eventType === 'tool.result') {
-                const callId = event.toolCallId || event.parentUuid;
+                const rawCallId = event.toolCallId || event.parentUuid;
+                const callId = typeof rawCallId === 'string' ? rawCallId : undefined;
                 const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
                 const result = event.result || {};
                 const output = typeof result.output === 'string' ? result.output : '';
-                const isError = result.isError === true || (output && output.startsWith('Error:'));
+                const structuredError = result.isError === true;
+                const structuredSuccess = result.isError === false;
+                const displayAsError = structuredError || (output && output.startsWith('Error:'));
                 events.push({
-                    type: isError ? 'error' : 'tool_result',
+                    type: displayAsError ? 'error' : 'tool_result',
                     agent: 'kimi',
                     timestamp,
                     tool: toolName,
-                    success: !isError,
+                    callId,
+                    success: structuredError ? false : structuredSuccess ? true : undefined,
+                    outcome: structuredError ? 'error' : structuredSuccess ? 'ok' : 'unknown',
                     output: output.length > 500 ? output.slice(0, 497) + '...' : output,
                 });
                 if (callId) {
@@ -1738,6 +1801,7 @@ function parseAnthropicMessageJsonl(filePath, agent) {
                     agent,
                     timestamp,
                     tool: toolName,
+                    callId: typeof block.id === 'string' ? block.id : undefined,
                     args: toolInput,
                     path: toolInput.file_path || toolInput.path || undefined,
                     command: (toolName === 'Bash' || toolName === 'Execute' || toolName === 'Shell') ? toolInput.command : undefined,
@@ -1753,11 +1817,14 @@ function parseAnthropicMessageJsonl(filePath, agent) {
                         ? block.content.filter((c) => c.type === 'text').map((c) => c.text || '').join('\n')
                         : '';
                 if (isError) {
-                    events.push({ type: 'error', agent, timestamp, tool: toolInfo?.tool, content: output || 'Tool execution failed' });
+                    events.push({
+                        type: 'error', agent, timestamp, tool: toolInfo?.tool,
+                        callId: toolId, outcome: 'error', content: output || 'Tool execution failed',
+                    });
                 }
                 else {
                     events.push({
-                        type: 'tool_result', agent, timestamp, tool: toolInfo?.tool, success: true,
+                        type: 'tool_result', agent, timestamp, tool: toolInfo?.tool, callId: toolId, success: true,
                         output: output.length > 500 ? output.slice(0, 497) + '...' : output,
                     });
                 }

package/dist/lib/session/prompt.d.ts

@@ -12,6 +12,25 @@
  * own scaffolding at parse time simply never reach here.
  */
 export declare function isSyntheticUserMessage(raw: string | undefined): boolean;
+/**
+ * Extract the invoked slash-command name from a raw `role=user` message, or
+ * undefined when the message carries no `<command-name>` wrapper. Used by
+ * `parseClaudeContent` to populate `SessionEvent.slashCommand`.
+ *
+ * Normalizes a leading `/` onto the result: current Claude Code wraps the
+ * name WITH the slash already (`/recap`), but the wrapper predates that and
+ * older transcripts carry the bare name (`recap`) — normalizing here means
+ * every consumer sees one consistent `/name` shape regardless of vintage.
+ */
+export declare function extractSlashCommandName(raw: string | undefined): string | undefined;
+/**
+ * Extract the invoked slash-command name from the `SlashCommand` tool's input
+ * — the MODEL invoking a command programmatically, not the user typing it.
+ * The tool's `command` field carries the full invocation text (name plus any
+ * args, e.g. `/code:commit fix the bug`); only the leading command token is
+ * the name, matching {@link extractSlashCommandName}'s shape.
+ */
+export declare function extractSlashCommandFromToolInput(toolInput: Record<string, any> | undefined): string | undefined;
 export declare const HEADLESS_PLAN_MODE_PREFIX = "You are running in HEADLESS PLAN MODE.";
 /** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export declare function cleanSessionPrompt(raw: string): string;

package/dist/lib/session/prompt.js

@@ -63,6 +63,49 @@ export function isSyntheticUserMessage(raw) {
         return false;
     return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
 }
+/**
+ * The `<command-name>` wrapper Claude injects into a `role=user` message when
+ * a typed slash command is invoked, e.g.:
+ *   <command-message>recap</command-message>
+ *   <command-name>/recap</command-name>
+ * Captures the name INCLUDING its leading slash (`/recap`), matching how the
+ * `SlashCommand` tool's own `command` input is formatted (see
+ * `extractSlashCommandFromToolInput`) so both sources land on the same shape.
+ */
+const COMMAND_NAME_WRAPPER_RE = /<command-name>\s*([^<]*?)\s*<\/command-name>/i;
+/**
+ * Extract the invoked slash-command name from a raw `role=user` message, or
+ * undefined when the message carries no `<command-name>` wrapper. Used by
+ * `parseClaudeContent` to populate `SessionEvent.slashCommand`.
+ *
+ * Normalizes a leading `/` onto the result: current Claude Code wraps the
+ * name WITH the slash already (`/recap`), but the wrapper predates that and
+ * older transcripts carry the bare name (`recap`) — normalizing here means
+ * every consumer sees one consistent `/name` shape regardless of vintage.
+ */
+export function extractSlashCommandName(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.match(COMMAND_NAME_WRAPPER_RE);
+    const name = m?.[1]?.trim();
+    if (!name)
+        return undefined;
+    return name.startsWith('/') ? name : `/${name}`;
+}
+/**
+ * Extract the invoked slash-command name from the `SlashCommand` tool's input
+ * — the MODEL invoking a command programmatically, not the user typing it.
+ * The tool's `command` field carries the full invocation text (name plus any
+ * args, e.g. `/code:commit fix the bug`); only the leading command token is
+ * the name, matching {@link extractSlashCommandName}'s shape.
+ */
+export function extractSlashCommandFromToolInput(toolInput) {
+    const command = toolInput?.command;
+    if (typeof command !== 'string')
+        return undefined;
+    const name = command.trim().split(/\s+/)[0];
+    return name || undefined;
+}
 // Prefix prepended to every Claude-in-plan-mode team spawn prompt.
 // Ends at a blank line before the real user task.
 export const HEADLESS_PLAN_MODE_PREFIX = 'You are running in HEADLESS PLAN MODE.';

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

@@ -1,4 +1,33 @@
+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 declare const REMOTE_STDOUT_MAX_BYTES: number;
+export declare const REMOTE_TOOL_AGGREGATE_MAX_BYTES: number;
+export interface RemoteToolByteBudget {
+    remainingBytes: number;
+    exhausted: boolean;
+}
+/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
+export declare class RemoteUtf8Accumulator {
+    private readonly decoder;
+    private value;
+    write(chunk: Buffer): void;
+    end(): string;
+    current(): string;
+}
+/** 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
@@ -12,6 +41,17 @@ export declare function parseRemoteListPayload(stdout: string, machine: string,
     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). */
@@ -24,6 +64,8 @@ export interface RemoteListResult {
      */
     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 `--host`), fan out to exactly those. Otherwise sweep the registered,
@@ -32,6 +74,35 @@ export interface RemoteListResult {
  * already `--json`) so every peer returns the same slice this machine asked for.
  */
 export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[]): 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. */