@illuma-ai/agents 1.0.89 → 1.0.93

package/dist/types/tools/AskUser.d.ts

@@ -0,0 +1,408 @@
+import { z } from 'zod';
+import { Constants } from '@/common';
+export declare const AskUserToolName = Constants.ASK_USER;
+export declare const AskUserDescription: string;
+export declare const AskUserStepSchema: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">;
+    type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "single" | "multi";
+    options: {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }[];
+    question: string;
+}, {
+    options: {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }[];
+    question: string;
+    type?: "single" | "multi" | undefined;
+}>;
+export type AskUserStep = z.infer<typeof AskUserStepSchema>;
+/**
+ * Represents a single step selection from the multi-step wizard UI.
+ * Exported for use by both ranger web client and browser extension.
+ */
+export type StepSelection = {
+    values: string[];
+    customInput?: string;
+};
+/** Field names injected into modifiedArgs by the approval flow */
+export declare const HITL_FIELDS: {
+    readonly SELECTIONS: "_selections";
+    readonly SELECTED_OPTION: "_selectedOption";
+    readonly CUSTOM_INPUT: "_customInput";
+};
+/**
+ * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.
+ *
+ * How it works:
+ * 1. LLM calls ask_user(question, options) OR ask_user(steps)
+ * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)
+ * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event
+ * 4. Frontend HumanInputPopover renders option cards + freeform text input
+ * 5. User selects option(s) OR types custom input →
+ *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput
+ * 6. Tool executes, reads the user's choice, returns result to LLM
+ */
+export declare function createAskUserTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodEffects<z.ZodObject<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+    }>, "many">>;
+    context: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        type: z.ZodDefault<z.ZodEnum<["single", "multi"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "single" | "multi";
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+    }, {
+        options: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        question: string;
+        type?: "single" | "multi" | undefined;
+    }>, "many">>;
+}, z.ZodTypeAny, "passthrough">, string>;

package/dist/types/tools/BrowserTools.d.ts

@@ -43,8 +43,8 @@ export interface BrowserActionResult {
 /**
  * Check if browser capability is available based on request headers or context
  * The browser extension sets these headers when connected:
- * - X-Ranger-Browser-Extension: true
- * - X-Ranger-Browser-Capable: true
+ * - X-Illuma-Browser-Extension: true
+ * - X-Illuma-Browser-Capable: true
  */
 export declare function hasBrowserCapability(req?: {
     headers?: Record<string, string | string[] | undefined>;

package/dist/types/tools/CodeExecutor.d.ts

@@ -8,7 +8,7 @@ export declare const CodeExecutionToolSchema: {
     readonly properties: {
         readonly lang: {
             readonly type: "string";
-            readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r"];
+            readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];
             readonly description: "The programming language or runtime to execute the code in.";
         };
         readonly code: {
@@ -35,7 +35,7 @@ export declare const CodeExecutionToolDefinition: {
         readonly properties: {
             readonly lang: {
                 readonly type: "string";
-                readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r"];
+                readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];
                 readonly description: "The programming language or runtime to execute the code in.";
             };
             readonly code: {

package/dist/types/tools/StreamingToolCallBuffer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * StreamingToolCallBuffer — Accumulates raw tool call argument strings
+ * during streaming, providing a fallback when LangChain's parsePartialJson
+ * loses data (e.g., when max_tokens truncates a tool call mid-JSON).
+ *
+ * Architecture:
+ * - handleToolCallChunks feeds raw arg fragments into this buffer
+ * - When a tool call is finalized (or truncated), the ToolNode can access
+ *   the accumulated raw string and extract field values that parsePartialJson
+ *   may have dropped
+ * - This enables "streaming write" semantics: content that streamed to the UI
+ *   is never lost, even if the JSON wrapper was incomplete
+ *
+ * @example
+ * ```ts
+ * const buffer = new StreamingToolCallBuffer();
+ *
+ * // During streaming (called by handleToolCallChunks):
+ * buffer.append(toolCallId, '{"action":"write","content":"func');
+ * buffer.append(toolCallId, 'tion App() {');
+ * buffer.setToolName(toolCallId, 'content_tool');
+ *
+ * // When ToolNode needs the content:
+ * const content = buffer.extractFieldValue(toolCallId, 'content');
+ * // => 'function App() {'
+ * ```
+ */
+export declare class StreamingToolCallBuffer {
+    /** Raw accumulated arg strings keyed by tool call ID */
+    private argBuffers;
+    /** Tool names keyed by tool call ID */
+    private toolNames;
+    /**
+     * Maps chunk index → tool call ID for providers (e.g., Bedrock) that send
+     * START chunks with {id, name, index} and DELTA chunks with {args, index} (no id).
+     * Without this mapping, DELTA chunks cannot be associated with the correct buffer entry.
+     */
+    private indexToIdMap;
+    /**
+     * Tracks the last appended args fragment per tool call ID.
+     * Used to skip exact duplicate fragments caused by LangChain's `streamEvents`
+     * emitting the same `on_chat_model_stream` event multiple times when the model
+     * is wrapped in nested runnables (e.g., `.bind()`, `.withConfig()`).
+     */
+    private lastChunks;
+    /**
+     * Append a raw argument string chunk for a tool call.
+     * Called during streaming as each ToolCallChunk arrives.
+     *
+     * Skips exact duplicate fragments that arrive when LangChain emits the same
+     * streaming event multiple times from nested runnable wrappers. Without this,
+     * each token's args appear twice, producing malformed JSON like:
+     * `{"action": "write"action": "write"...`
+     *
+     * @returns true if the chunk was appended, false if it was a duplicate
+     */
+    append(toolCallId: string, argsChunk: string): boolean;
+    /**
+     * Record the tool name for a tool call ID.
+     * Usually available from the first chunk.
+     */
+    setToolName(toolCallId: string, name: string): void;
+    /**
+     * Get the tool name for a tool call ID.
+     */
+    getToolName(toolCallId: string): string | undefined;
+    /**
+     * Get the raw accumulated argument string for a tool call.
+     */
+    getRawArgs(toolCallId: string): string | undefined;
+    /**
+     * Extract a string field value from the raw accumulated JSON args.
+     *
+     * Uses simple string parsing (not JSON.parse) to handle truncated JSON.
+     * Finds `"fieldName":"` and extracts everything after it until the next
+     * unescaped quote or end of buffer.
+     *
+     * @param toolCallId - The tool call ID
+     * @param fieldName - The JSON field name to extract (e.g., 'content')
+     * @returns The extracted value, or undefined if the field wasn't found
+     */
+    extractFieldValue(toolCallId: string, fieldName: string): string | undefined;
+    /**
+     * Store an index → tool call ID mapping.
+     * Called when a START chunk arrives with both `id` and `index` (e.g., Bedrock).
+     * Subsequent DELTA chunks that only have `index` can resolve the ID via getIdByIndex.
+     */
+    setIndexMapping(index: number, toolCallId: string): void;
+    /**
+     * Resolve a tool call ID from a chunk index.
+     * Returns undefined if no mapping exists (e.g., provider sends id on every chunk).
+     */
+    getIdByIndex(index: number): string | undefined;
+    /**
+     * Check if a tool call has accumulated content.
+     */
+    has(toolCallId: string): boolean;
+    /**
+     * Clear the buffer for a specific tool call (after processing).
+     */
+    clear(toolCallId: string): void;
+    /**
+     * Clear all buffers (at the start of a new callModel cycle).
+     */
+    clearAll(): void;
+}

package/dist/types/tools/ToolNode.d.ts

@@ -12,6 +12,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     private toolUsageCount;
+    /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
+    private toolCallTurns;
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
     /** Cached programmatic tools (computed once on first PTC call) */
@@ -20,13 +22,15 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private sessions?;
     /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
     private eventDrivenMode;
-    /** Tool definitions for event-driven mode */
-    private toolDefinitions?;
     /** Agent ID for event-driven mode */
     private agentId?;
+    /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
+    private directToolNames?;
     /** HITL tool approval configuration */
     private toolApprovalConfig?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, toolDefinitions, agentId, toolApprovalConfig, }: t.ToolNodeConstructorParams);
+    /** Buffer for recovering truncated tool call arguments from streaming data */
+    private streamingToolCallBuffer?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -60,6 +64,54 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * Runs a single tool call with error handling
      */
     protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    /**
+     * Recover truncated tool call arguments using the raw streaming buffer.
+     *
+     * When parsePartialJson drops content (e.g., a large "content" field truncated
+     * at max_tokens), this method extracts the field value from the raw accumulated
+     * arg string and merges it back into the parsed args object.
+     *
+     * This is generic — it checks ALL string fields in the raw buffer, not just
+     * content_tool fields. Any tool with a truncated string value benefits.
+     */
+    /**
+     * Recover truncated tool call arguments using the raw streaming buffer.
+     *
+     * Strategy:
+     * 1. If args are completely empty → try parsePartialJson on the raw buffer
+     * 2. Otherwise → field-level recovery: extract missing fields from raw buffer
+     *
+     * @param toolName - Tool name (for logging)
+     * @param toolCallId - The tool call ID
+     * @param args - The parsed args (potentially incomplete from parsePartialJson)
+     * @returns The args with recovered fields merged in
+     */
+    private recoverTruncatedArgs;
+    /**
+     * Builds code session context for injection into event-driven tool calls.
+     * Mirrors the session injection logic in runTool() for direct execution.
+     */
+    private getCodeSessionContext;
+    /**
+     * Extracts code execution session context from tool results and stores in Graph.sessions.
+     * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
+     */
+    private storeCodeSessionFromResults;
+    /**
+     * Post-processes standard runTool outputs: dispatches ON_RUN_STEP_COMPLETED
+     * and stores code session context. Mirrors the completion handling in
+     * dispatchToolEvents for the event-driven path.
+     *
+     * By handling completions here in graph context (rather than in the
+     * stream consumer via ToolEndHandler), the race between the stream
+     * consumer and graph execution is eliminated.
+     */
+    private handleRunToolCompletions;
+    /**
+     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
+     * Core logic for event-driven execution, separated from output shaping.
+     */
+    private dispatchToolEvents;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
      * Used in event-driven mode where the host handles actual tool execution.

package/dist/types/tools/ToolSearch.d.ts

@@ -25,7 +25,7 @@ export declare const ToolSearchToolSchema: {
             readonly type: "integer";
             readonly minimum: 1;
             readonly maximum: 50;
-            readonly default: 10;
+            readonly default: 5;
             readonly description: "Maximum number of matching tools to return";
         };
         readonly mcp_server: {
@@ -67,7 +67,7 @@ export declare const ToolSearchToolDefinition: {
                 readonly type: "integer";
                 readonly minimum: 1;
                 readonly maximum: 50;
-                readonly default: 10;
+                readonly default: 5;
                 readonly description: "Maximum number of matching tools to return";
             };
             readonly mcp_server: {
@@ -157,8 +157,9 @@ declare function sanitizeRegex(pattern: string): {
 /**
  * Performs BM25-based search for better relevance ranking.
  * Uses Okapi BM25 algorithm for term frequency and document length normalization.
+ * If query is empty, returns all tools (up to maxResults) sorted alphabetically.
  * @param tools - Array of tool metadata to search
- * @param query - The search query
+ * @param query - The search query (empty returns all tools)
  * @param fields - Which fields to search
  * @param maxResults - Maximum results to return
  * @returns Search response with matching tools ranked by BM25 score
@@ -172,7 +173,9 @@ declare function performLocalSearch(tools: t.ToolMetadata[], query: string, fiel
 declare function getBaseToolName(toolName: string): string;
 /**
  * Generates a compact listing of deferred tools grouped by server.
- * Format: "server: tool1, tool2, tool3"
+ * Format: "server: tool1, tool2(\u2026), tool3"
+ * Tools with parameters are annotated with (\u2026) to signal
+ * that the LLM should discover the schema via tool_search before calling.
  * Non-MCP tools are grouped under "other".
  * @param toolRegistry - The tool registry
  * @param onlyDeferred - Whether to only include deferred tools
@@ -184,9 +187,10 @@ declare function getDeferredToolsListing(toolRegistry: t.LCToolRegistry | undefi
  * NOTE: This is a PREVIEW only - tools are NOT discovered/loaded.
  * @param tools - Array of tool metadata from the server(s)
  * @param serverNames - The MCP server name(s)
+ * @param nameFormat - Whether to show 'full' names (tool_mcp_server) or 'base' names (tool only)
  * @returns JSON string showing all tools grouped by server
  */
-declare function formatServerListing(tools: t.ToolMetadata[], serverNames: string | string[]): string;
+declare function formatServerListing(tools: t.ToolMetadata[], serverNames: string | string[], nameFormat?: t.McpNameFormat): string;
 /**
  * Creates a Tool Search tool for discovering tools from a large registry.
  *