@librechat/agents 3.1.2 → 3.1.21

package/dist/esm/tools/createSchemaOnlyTool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSchemaOnlyTool.mjs","sources":["../../../src/tools/createSchemaOnlyTool.ts"],"sourcesContent":["import { tool, type StructuredToolInterface } from '@langchain/core/tools';\nimport type { LCTool } from '@/types';\n\n/**\n * Creates a schema-only tool for LLM binding in event-driven mode.\n * These tools have valid schemas for the LLM to understand but should\n * never be invoked directly - ToolNode handles execution via events.\n */\nexport function createSchemaOnlyTool(\n  definition: LCTool\n): StructuredToolInterface {\n  const { name, description, parameters, responseFormat } = definition;\n\n  return tool(\n    async () => {\n      throw new Error(\n        `Tool \"${name}\" should not be invoked directly in event-driven mode. ` +\n          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'\n      );\n    },\n    {\n      name,\n      description: description ?? '',\n      schema: parameters ?? { type: 'object', properties: {} },\n      responseFormat: responseFormat ?? 'content_and_artifact',\n    }\n  );\n}\n\n/**\n * Creates schema-only tools for all definitions in an array.\n */\nexport function createSchemaOnlyTools(\n  definitions: LCTool[]\n): StructuredToolInterface[] {\n  return definitions.map((def) => createSchemaOnlyTool(def));\n}\n"],"names":[],"mappings":";;AAGA;;;;AAIG;AACG,SAAU,oBAAoB,CAClC,UAAkB,EAAA;IAElB,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,UAAU;AAEpE,IAAA,OAAO,IAAI,CACT,YAAW;AACT,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,MAAA,EAAS,IAAI,CAAyD,uDAAA,CAAA;AACpE,YAAA,0DAA0D,CAC7D;AACH,KAAC,EACD;QACE,IAAI;QACJ,WAAW,EAAE,WAAW,IAAI,EAAE;QAC9B,MAAM,EAAE,UAAU,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QACxD,cAAc,EAAE,cAAc,IAAI,sBAAsB;AACzD,KAAA,CACF;AACH;AAEA;;AAEG;AACG,SAAU,qBAAqB,CACnC,WAAqB,EAAA;AAErB,IAAA,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,oBAAoB,CAAC,GAAG,CAAC,CAAC;AAC5D;;;;"}

package/dist/types/agents/AgentContext.d.ts

@@ -45,6 +45,11 @@ export declare class AgentContext {
      * Used for tool search and programmatic tool calling.
      */
     toolRegistry?: t.LCToolRegistry;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode.
+     */
+    toolDefinitions?: t.LCTool[];
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames: Set<string>;
     /** Instructions for this agent */
@@ -81,7 +86,7 @@ export declare class AgentContext {
         /** Names of sibling agents executing in parallel (empty if sequential) */
         parallelSiblings: string[];
     };
-    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         name?: string;
         provider: Providers;
@@ -92,6 +97,7 @@ export declare class AgentContext {
         tools?: t.GraphTools;
         toolMap?: t.ToolMap;
         toolRegistry?: t.LCToolRegistry;
+        toolDefinitions?: t.LCTool[];
         instructions?: string;
         additionalInstructions?: string;
         reasoningKey?: 'reasoning_content' | 'reasoning';

package/dist/types/common/enum.d.ts

@@ -17,6 +17,8 @@ export declare enum GraphEvents {
     ON_MESSAGE_DELTA = "on_message_delta",
     /** [Custom] Reasoning Delta events for messages */
     ON_REASONING_DELTA = "on_reasoning_delta",
+    /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+    ON_TOOL_EXECUTE = "on_tool_execute",
     /** Custom event, emitted by system */
     ON_CUSTOM_EVENT = "on_custom_event",
     /** Emitted when a chat model starts processing. */

package/dist/types/index.d.ts

@@ -8,6 +8,8 @@ export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
+export * from './tools/ToolNode';
+export * from './tools/createSchemaOnlyTool';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';

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

@@ -18,7 +18,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private programmaticCache?;
     /** Reference to Graph's sessions map for automatic session injection */
     private sessions?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, }: t.ToolNodeConstructorParams);
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    private eventDrivenMode;
+    /** Tool definitions for event-driven mode */
+    private toolDefinitions?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, toolDefinitions, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -33,6 +37,11 @@ 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>;
+    /**
+     * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+     * Used in event-driven mode where the host handles actual tool execution.
+     */
+    private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;
     private isSendInput;
     private isMessagesState;

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

@@ -0,0 +1,12 @@
+import { type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export declare function createSchemaOnlyTool(definition: LCTool): StructuredToolInterface;
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export declare function createSchemaOnlyTools(definitions: LCTool[]): StructuredToolInterface[];

package/dist/types/types/graph.d.ts

@@ -256,4 +256,10 @@ export interface AgentInputs {
      * Maps tool name to LCTool definition.
      */
     toolRegistry?: Map<string, LCTool>;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode, dispatching
+     * ON_TOOL_EXECUTE events instead of invoking tools directly.
+     */
+    toolDefinitions?: LCTool[];
 }

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

@@ -31,6 +31,10 @@ export type ToolNodeOptions = {
     toolRegistry?: LCToolRegistry;
     /** Reference to Graph's sessions map for automatic session injection */
     sessions?: ToolSessionMap;
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    eventDrivenMode?: boolean;
+    /** Tool definitions for event-driven mode (used for context, not invocation) */
+    toolDefinitions?: Map<string, LCTool>;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -96,6 +100,51 @@ export type LCTool = {
      * Options: 'direct', 'code_execution'
      */
     allowed_callers?: AllowedCaller[];
+    /** Response format for the tool output */
+    responseFormat?: 'content' | 'content_and_artifact';
+    /** Server name for MCP tools */
+    serverName?: string;
+    /** Tool type classification */
+    toolType?: 'builtin' | 'mcp' | 'action';
+};
+/** Single tool call within a batch request for event-driven execution */
+export type ToolCallRequest = {
+    /** Tool call ID from the LLM */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Step ID for tracking */
+    stepId?: string;
+    /** Usage turn count for this tool */
+    turn?: number;
+};
+/** Batch request containing ALL tool calls for a graph step */
+export type ToolExecuteBatchRequest = {
+    /** All tool calls from the AIMessage */
+    toolCalls: ToolCallRequest[];
+    /** User ID for context */
+    userId?: string;
+    /** Agent ID for context */
+    agentId?: string;
+    /** Promise resolver - handler calls this with ALL results */
+    resolve: (results: ToolExecuteResult[]) => void;
+    /** Promise rejector - handler calls this on fatal error */
+    reject: (error: Error) => void;
+};
+/** Result for a single tool call in event-driven execution */
+export type ToolExecuteResult = {
+    /** Matches ToolCallRequest.id */
+    toolCallId: string;
+    /** Tool output content */
+    content: string | unknown[];
+    /** Optional artifact (for content_and_artifact format) */
+    artifact?: unknown;
+    /** Execution status */
+    status: 'success' | 'error';
+    /** Error message if status is 'error' */
+    errorMessage?: string;
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.2",
+  "version": "3.1.21",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -34,6 +34,7 @@ export class AgentContext {
       toolMap,
       toolEnd,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additional_instructions,
       streamBuffer,
@@ -52,6 +53,7 @@ export class AgentContext {
       tools,
       toolMap,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additionalInstructions: additional_instructions,
       reasoningKey,
@@ -118,6 +120,11 @@ export class AgentContext {
    * Used for tool search and programmatic tool calling.
    */
   toolRegistry?: t.LCToolRegistry;
+  /**
+   * Serializable tool definitions for event-driven execution.
+   * When provided, ToolNode operates in event-driven mode.
+   */
+  toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
   /** Instructions for this agent */
@@ -171,6 +178,7 @@ export class AgentContext {
     tools,
     toolMap,
     toolRegistry,
+    toolDefinitions,
     instructions,
     additionalInstructions,
     reasoningKey,
@@ -188,6 +196,7 @@ export class AgentContext {
     tools?: t.GraphTools;
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
+    toolDefinitions?: t.LCTool[];
     instructions?: string;
     additionalInstructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -205,6 +214,7 @@ export class AgentContext {
     this.tools = tools;
     this.toolMap = toolMap;
     this.toolRegistry = toolRegistry;
+    this.toolDefinitions = toolDefinitions;
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
     if (reasoningKey) {

package/src/common/enum.ts

@@ -19,6 +19,8 @@ export enum GraphEvents {
   ON_MESSAGE_DELTA = 'on_message_delta',
   /** [Custom] Reasoning Delta events for messages */
   ON_REASONING_DELTA = 'on_reasoning_delta',
+  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+  ON_TOOL_EXECUTE = 'on_tool_execute',
 
   /* Official Events */
 

package/src/graphs/Graph.ts

@@ -58,6 +58,7 @@ import {
 } from '@/utils';
 import { getChatModelClass, manualToolStreamProviders } from '@/llm/providers';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { createSchemaOnlyTools } from '@/tools/createSchemaOnlyTool';
 import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { AgentContext } from '@/agents/AgentContext';
@@ -453,6 +454,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     currentToolMap?: t.ToolMap;
     agentContext?: AgentContext;
   }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
+    const toolDefinitions = agentContext?.toolDefinitions;
+    const eventDrivenMode =
+      toolDefinitions != null && toolDefinitions.length > 0;
+
+    if (eventDrivenMode) {
+      const schemaTools = createSchemaOnlyTools(toolDefinitions);
+      const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
+
+      return new CustomToolNode<t.BaseGraphState>({
+        tools: schemaTools as t.GenericTool[],
+        toolMap: new Map(schemaTools.map((tool) => [tool.name, tool])),
+        toolCallStepIds: this.toolCallStepIds,
+        errorHandler: (data, metadata) =>
+          StandardGraph.handleToolCallErrorStatic(this, data, metadata),
+        toolRegistry: agentContext?.toolRegistry,
+        sessions: this.sessions,
+        eventDrivenMode: true,
+        toolDefinitions: toolDefMap,
+      });
+    }
+
     return new CustomToolNode<t.BaseGraphState>({
       tools: (currentTools as t.GenericTool[] | undefined) ?? [],
       toolMap: currentToolMap,

package/src/index.ts

@@ -13,6 +13,8 @@ export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
+export * from './tools/ToolNode';
+export * from './tools/createSchemaOnlyTool';
 export * from './tools/handlers';
 export * from './tools/search';
 

package/src/tools/ToolNode.ts

@@ -20,7 +20,8 @@ import type { BaseMessage, AIMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
-import { Constants } from '@/common';
+import { safeDispatchCustomEvent } from '@/utils/events';
+import { Constants, GraphEvents } from '@/common';
 
 /**
  * Helper to check if a value is a Send object
@@ -44,6 +45,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private programmaticCache?: t.ProgrammaticCache;
   /** Reference to Graph's sessions map for automatic session injection */
   private sessions?: t.ToolSessionMap;
+  /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+  private eventDrivenMode: boolean = false;
+  /** Tool definitions for event-driven mode */
+  private toolDefinitions?: Map<string, t.LCTool>;
 
   constructor({
     tools,
@@ -56,6 +61,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     loadRuntimeTools,
     toolRegistry,
     sessions,
+    eventDrivenMode,
+    toolDefinitions,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -66,6 +73,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.toolUsageCount = new Map<string, number>();
     this.toolRegistry = toolRegistry;
     this.sessions = sessions;
+    this.eventDrivenMode = eventDrivenMode ?? false;
+    this.toolDefinitions = toolDefinitions;
   }
 
   /**
@@ -243,11 +252,77 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     }
   }
 
+  /**
+   * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+   * Used in event-driven mode where the host handles actual tool execution.
+   */
+  private async executeViaEvent(
+    toolCalls: ToolCall[],
+    config: RunnableConfig,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any
+  ): Promise<T> {
+    const requests: t.ToolCallRequest[] = toolCalls.map((call) => {
+      const turn = this.toolUsageCount.get(call.name) ?? 0;
+      this.toolUsageCount.set(call.name, turn + 1);
+      return {
+        id: call.id!,
+        name: call.name,
+        args: call.args as Record<string, unknown>,
+        stepId: this.toolCallStepIds?.get(call.id!),
+        turn,
+      };
+    });
+
+    const results = await new Promise<t.ToolExecuteResult[]>(
+      (resolve, reject) => {
+        const request: t.ToolExecuteBatchRequest = {
+          toolCalls: requests,
+          userId: config.configurable?.user_id as string | undefined,
+          agentId: config.configurable?.agent_id as string | undefined,
+          resolve,
+          reject,
+        };
+
+        safeDispatchCustomEvent(GraphEvents.ON_TOOL_EXECUTE, request, config);
+      }
+    );
+
+    const outputs: ToolMessage[] = results.map((result) => {
+      const toolName =
+        requests.find((r) => r.id === result.toolCallId)?.name ?? 'unknown';
+
+      if (result.status === 'error') {
+        return new ToolMessage({
+          status: 'error',
+          content: `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`,
+          name: toolName,
+          tool_call_id: result.toolCallId,
+        });
+      }
+
+      return new ToolMessage({
+        status: 'success',
+        content:
+          typeof result.content === 'string'
+            ? result.content
+            : JSON.stringify(result.content),
+        name: toolName,
+        tool_call_id: result.toolCallId,
+      });
+    });
+
+    return (Array.isArray(input) ? outputs : { messages: outputs }) as T;
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   protected async run(input: any, config: RunnableConfig): Promise<T> {
     let outputs: (BaseMessage | Command)[];
 
     if (this.isSendInput(input)) {
+      if (this.eventDrivenMode) {
+        return this.executeViaEvent([input.lg_tool_call], config, input);
+      }
       outputs = [await this.runTool(input.lg_tool_call, config)];
     } else {
       let messages: BaseMessage[];
@@ -289,21 +364,26 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         this.programmaticCache = undefined; // Invalidate cache on toolMap change
       }
 
+      const filteredCalls =
+        aiMessage.tool_calls?.filter((call) => {
+          /**
+           * Filter out:
+           * 1. Already processed tool calls (present in toolMessageIds)
+           * 2. Server tool calls (e.g., web_search with IDs starting with 'srvtoolu_')
+           *    which are executed by the provider's API and don't require invocation
+           */
+          return (
+            (call.id == null || !toolMessageIds.has(call.id)) &&
+            !(call.id?.startsWith('srvtoolu_') ?? false)
+          );
+        }) ?? [];
+
+      if (this.eventDrivenMode && filteredCalls.length > 0) {
+        return this.executeViaEvent(filteredCalls, config, input);
+      }
+
       outputs = await Promise.all(
-        aiMessage.tool_calls
-          ?.filter((call) => {
-            /**
-             * Filter out:
-             * 1. Already processed tool calls (present in toolMessageIds)
-             * 2. Server tool calls (e.g., web_search with IDs starting with 'srvtoolu_')
-             *    which are executed by the provider's API and don't require invocation
-             */
-            return (
-              (call.id == null || !toolMessageIds.has(call.id)) &&
-              !(call.id?.startsWith('srvtoolu_') ?? false)
-            );
-          })
-          .map((call) => this.runTool(call, config)) ?? []
+        filteredCalls.map((call) => this.runTool(call, config))
       );
     }
 

package/src/tools/createSchemaOnlyTool.ts

@@ -0,0 +1,37 @@
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export function createSchemaOnlyTool(
+  definition: LCTool
+): StructuredToolInterface {
+  const { name, description, parameters, responseFormat } = definition;
+
+  return tool(
+    async () => {
+      throw new Error(
+        `Tool "${name}" should not be invoked directly in event-driven mode. ` +
+          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'
+      );
+    },
+    {
+      name,
+      description: description ?? '',
+      schema: parameters ?? { type: 'object', properties: {} },
+      responseFormat: responseFormat ?? 'content_and_artifact',
+    }
+  );
+}
+
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export function createSchemaOnlyTools(
+  definitions: LCTool[]
+): StructuredToolInterface[] {
+  return definitions.map((def) => createSchemaOnlyTool(def));
+}

package/src/types/graph.ts

@@ -377,4 +377,10 @@ export interface AgentInputs {
    * Maps tool name to LCTool definition.
    */
   toolRegistry?: Map<string, LCTool>;
+  /**
+   * Serializable tool definitions for event-driven execution.
+   * When provided, ToolNode operates in event-driven mode, dispatching
+   * ON_TOOL_EXECUTE events instead of invoking tools directly.
+   */
+  toolDefinitions?: LCTool[];
 }

package/src/types/tools.ts

@@ -41,6 +41,10 @@ export type ToolNodeOptions = {
   toolRegistry?: LCToolRegistry;
   /** Reference to Graph's sessions map for automatic session injection */
   sessions?: ToolSessionMap;
+  /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+  eventDrivenMode?: boolean;
+  /** Tool definitions for event-driven mode (used for context, not invocation) */
+  toolDefinitions?: Map<string, LCTool>;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -125,6 +129,54 @@ export type LCTool = {
    * Options: 'direct', 'code_execution'
    */
   allowed_callers?: AllowedCaller[];
+  /** Response format for the tool output */
+  responseFormat?: 'content' | 'content_and_artifact';
+  /** Server name for MCP tools */
+  serverName?: string;
+  /** Tool type classification */
+  toolType?: 'builtin' | 'mcp' | 'action';
+};
+
+/** Single tool call within a batch request for event-driven execution */
+export type ToolCallRequest = {
+  /** Tool call ID from the LLM */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Tool arguments */
+  args: Record<string, unknown>;
+  /** Step ID for tracking */
+  stepId?: string;
+  /** Usage turn count for this tool */
+  turn?: number;
+};
+
+/** Batch request containing ALL tool calls for a graph step */
+export type ToolExecuteBatchRequest = {
+  /** All tool calls from the AIMessage */
+  toolCalls: ToolCallRequest[];
+  /** User ID for context */
+  userId?: string;
+  /** Agent ID for context */
+  agentId?: string;
+  /** Promise resolver - handler calls this with ALL results */
+  resolve: (results: ToolExecuteResult[]) => void;
+  /** Promise rejector - handler calls this on fatal error */
+  reject: (error: Error) => void;
+};
+
+/** Result for a single tool call in event-driven execution */
+export type ToolExecuteResult = {
+  /** Matches ToolCallRequest.id */
+  toolCallId: string;
+  /** Tool output content */
+  content: string | unknown[];
+  /** Optional artifact (for content_and_artifact format) */
+  artifact?: unknown;
+  /** Execution status */
+  status: 'success' | 'error';
+  /** Error message if status is 'error' */
+  errorMessage?: string;
 };
 
 /** Map of tool names to tool definitions */