@tanstack/ai 0.36.0 → 0.37.0

package/dist/esm/activities/chat/tools/tool-calls.d.ts

@@ -0,0 +1,140 @@
+import { AnyTool, CustomEvent, ModelMessage, RunFinishedEvent, Tool, ToolCall, ToolCallArgsEvent, ToolCallEndEvent, ToolCallStartEvent } from '../../../types.js';
+import { AfterToolCallInfo, BeforeToolCallDecision } from '../middleware/types.js';
+import { ContextFromTool, DefinedContext, MergeContext, UnionToIntersection } from '../runtime-context-types.js';
+/**
+ * Optional middleware hooks for tool execution.
+ * When provided, these callbacks are invoked before/after each tool execution.
+ */
+export interface ToolExecutionMiddlewareHooks {
+    onBeforeToolCall?: (toolCall: ToolCall, tool: Tool | undefined, args: unknown) => Promise<BeforeToolCallDecision>;
+    onAfterToolCall?: (info: AfterToolCallInfo) => Promise<void>;
+}
+/**
+ * Error thrown when middleware decides to abort the chat run during tool execution.
+ */
+export declare class MiddlewareAbortError extends Error {
+    constructor(reason: string);
+}
+type RequiredContextFromToolUnion<T> = T extends unknown ? undefined extends ContextFromTool<T> ? never : ContextFromTool<T> : never;
+type ContextFromToolUnion<T> = [
+    UnionToIntersection<DefinedContext<ContextFromTool<T>>>
+] extends [never] ? unknown : [RequiredContextFromToolUnion<T>] extends [never] ? UnionToIntersection<DefinedContext<ContextFromTool<T>>> | undefined : UnionToIntersection<DefinedContext<ContextFromTool<T>>>;
+type ContextFromTools<TTools> = TTools extends readonly [
+    infer THead,
+    ...infer TTail
+] ? MergeContext<ContextFromTool<THead>, ContextFromTools<TTail>> : TTools extends ReadonlyArray<infer TTool> ? ContextFromToolUnion<TTool> : unknown;
+type ExecuteToolsContextArgs<TContext> = undefined extends TContext ? [userContext?: TContext] : [userContext: TContext];
+/**
+ * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
+ *
+ * Responsibilities:
+ * - Accumulates streaming tool call events (ID, name, arguments)
+ * - Validates tool calls (filters out incomplete ones)
+ * - Executes tool `execute` functions with parsed arguments
+ * - Emits `TOOL_CALL_END` events for client visibility
+ * - Returns tool result messages for conversation history
+ *
+ * This class is used internally by the AI.chat() method to handle the automatic
+ * tool execution loop. It can also be used independently for custom tool execution logic.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ToolCallManager(tools);
+ *
+ * // During streaming, accumulate tool calls
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'TOOL_CALL_START') {
+ *     manager.addToolCallStartEvent(chunk);
+ *   } else if (chunk.type === 'TOOL_CALL_ARGS') {
+ *     manager.addToolCallArgsEvent(chunk);
+ *   }
+ * }
+ *
+ * // After stream completes, execute tools
+ * if (manager.hasToolCalls()) {
+ *   const toolResults = yield* manager.executeTools(finishEvent);
+ *   messages = [...messages, ...toolResults];
+ *   manager.clear();
+ * }
+ * ```
+ */
+export declare class ToolCallManager<TToolsOrContext = ReadonlyArray<AnyTool>, TContext = TToolsOrContext extends ReadonlyArray<AnyTool> ? ContextFromTools<TToolsOrContext> : TToolsOrContext> {
+    private readonly toolCallsMap;
+    private readonly tools;
+    constructor(tools: TToolsOrContext extends ReadonlyArray<AnyTool> ? TToolsOrContext : ReadonlyArray<AnyTool>);
+    /**
+     * Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)
+     */
+    addToolCallStartEvent(event: ToolCallStartEvent): void;
+    /**
+     * Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)
+     */
+    addToolCallArgsEvent(event: ToolCallArgsEvent): void;
+    /**
+     * Complete a tool call with its final input
+     * Called when TOOL_CALL_END is received
+     */
+    completeToolCall(event: ToolCallEndEvent): void;
+    /**
+     * Check if there are any complete tool calls to execute
+     */
+    hasToolCalls(): boolean;
+    /**
+     * Get all complete tool calls (filtered for valid ID and name)
+     */
+    getToolCalls(): Array<ToolCall>;
+    /**
+     * Execute all tool calls and return tool result messages
+     * Yields TOOL_CALL_END events for streaming
+     * @param finishEvent - RUN_FINISHED event from the stream
+     */
+    executeTools(finishEvent: RunFinishedEvent, ...contextArgs: ExecuteToolsContextArgs<TContext>): AsyncGenerator<ToolCallEndEvent, Array<ModelMessage>, void>;
+    /**
+     * Clear the tool calls map for the next iteration
+     */
+    clear(): void;
+}
+export interface ToolResult {
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    state?: 'output-available' | 'output-error';
+    /** Duration of tool execution in milliseconds (only for server-executed tools) */
+    duration?: number;
+}
+export interface ApprovalRequest {
+    toolCallId: string;
+    toolName: string;
+    input: any;
+    approvalId: string;
+}
+export interface ClientToolRequest {
+    toolCallId: string;
+    toolName: string;
+    input: any;
+}
+interface ExecuteToolCallsResult {
+    /** Tool results ready to send to LLM */
+    results: Array<ToolResult>;
+    /** Tools that need user approval before execution */
+    needsApproval: Array<ApprovalRequest>;
+    /** Tools that need client-side execution */
+    needsClientExecution: Array<ClientToolRequest>;
+}
+/**
+ * Execute tool calls based on their configuration.
+ * Yields CustomEvent chunks during tool execution for real-time progress updates.
+ *
+ * Handles three cases:
+ * 1. Client tools (no execute) - request client to execute
+ * 2. Server tools with approval - check approval before executing
+ * 3. Normal server tools - execute immediately
+ *
+ * @param toolCalls - Tool calls from the LLM
+ * @param tools - Available tools with their configurations
+ * @param approvals - Map of approval decisions (approval.id -> approved boolean)
+ * @param clientResults - Map of client-side execution results (toolCallId -> result)
+ * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
+ */
+export declare function executeToolCalls<TContext = unknown>(toolCalls: Array<ToolCall>, tools: ReadonlyArray<AnyTool>, approvals?: Map<string, boolean>, clientResults?: Map<string, any>, createCustomEventChunk?: (eventName: string, value: Record<string, any>) => CustomEvent, middlewareHooks?: ToolExecutionMiddlewareHooks, userContext?: TContext, abortSignal?: AbortSignal): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void>;
+export {};

package/dist/esm/activities/chat/tools/tool-calls.js

@@ -0,0 +1,512 @@
+import { normalizeToolResult } from "../../../utilities/tool-result.js";
+import { isStandardSchema, parseWithStandardSchema } from "./schema-converter.js";
+function safeJsonParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+class MiddlewareAbortError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "MiddlewareAbortError";
+  }
+}
+class ToolCallManager {
+  toolCallsMap = /* @__PURE__ */ new Map();
+  tools;
+  constructor(tools) {
+    this.tools = tools;
+  }
+  /**
+   * Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)
+   */
+  addToolCallStartEvent(event) {
+    const index = event.index ?? this.toolCallsMap.size;
+    const runtimeEvent = event;
+    const name = runtimeEvent.toolCallName ?? runtimeEvent.toolName;
+    this.toolCallsMap.set(index, {
+      id: event.toolCallId,
+      type: "function",
+      function: {
+        name,
+        arguments: ""
+      },
+      ...event.metadata !== void 0 && { metadata: event.metadata }
+    });
+  }
+  /**
+   * Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)
+   */
+  addToolCallArgsEvent(event) {
+    for (const [, toolCall] of this.toolCallsMap.entries()) {
+      if (toolCall.id === event.toolCallId) {
+        toolCall.function.arguments += event.delta;
+        break;
+      }
+    }
+  }
+  /**
+   * Complete a tool call with its final input
+   * Called when TOOL_CALL_END is received
+   */
+  completeToolCall(event) {
+    for (const [, toolCall] of this.toolCallsMap.entries()) {
+      if (toolCall.id === event.toolCallId) {
+        if (event.input !== void 0) {
+          const normalized = event.input && typeof event.input === "object" ? event.input : {};
+          toolCall.function.arguments = JSON.stringify(normalized);
+        }
+        break;
+      }
+    }
+  }
+  /**
+   * Check if there are any complete tool calls to execute
+   */
+  hasToolCalls() {
+    return this.getToolCalls().length > 0;
+  }
+  /**
+   * Get all complete tool calls (filtered for valid ID and name)
+   */
+  getToolCalls() {
+    return Array.from(this.toolCallsMap.values()).filter(
+      (tc) => tc.id && tc.function.name && tc.function.name.trim().length > 0
+    );
+  }
+  /**
+   * Execute all tool calls and return tool result messages
+   * Yields TOOL_CALL_END events for streaming
+   * @param finishEvent - RUN_FINISHED event from the stream
+   */
+  async *executeTools(finishEvent, ...contextArgs) {
+    const toolCallsArray = this.getToolCalls();
+    const toolResults = [];
+    const hasRuntimeContext = contextArgs.length > 0;
+    const userContext = contextArgs[0];
+    for (const toolCall of toolCallsArray) {
+      const tool = this.tools.find((t) => t.name === toolCall.function.name);
+      let toolResultContent;
+      let toolResultState;
+      if (tool?.execute) {
+        try {
+          let args;
+          try {
+            const argsString = toolCall.function.arguments.trim() || "{}";
+            const parsed = JSON.parse(argsString);
+            args = parsed && typeof parsed === "object" ? parsed : {};
+          } catch (parseError) {
+            throw new Error(
+              `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`
+            );
+          }
+          if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {
+            try {
+              args = parseWithStandardSchema(tool.inputSchema, args);
+            } catch (validationError) {
+              const message = validationError instanceof Error ? validationError.message : "Validation failed";
+              throw new Error(
+                `Input validation failed for tool ${tool.name}: ${message}`
+              );
+            }
+          }
+          const executionContext = {
+            toolCallId: toolCall.id,
+            context: userContext,
+            emitCustomEvent: () => {
+            }
+          };
+          let result = hasRuntimeContext ? await tool.execute(args, executionContext) : await tool.execute(args);
+          if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
+            try {
+              result = parseWithStandardSchema(tool.outputSchema, result);
+            } catch (validationError) {
+              const message = validationError instanceof Error ? validationError.message : "Validation failed";
+              throw new Error(
+                `Output validation failed for tool ${tool.name}: ${message}`
+              );
+            }
+          }
+          toolResultContent = normalizeToolResult(result);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Unknown error";
+          toolResultContent = `Error executing tool: ${message}`;
+          toolResultState = "output-error";
+        }
+      } else {
+        toolResultContent = `Tool ${toolCall.function.name} does not have an execute function`;
+      }
+      yield {
+        type: "TOOL_CALL_END",
+        toolCallId: toolCall.id,
+        toolCallName: toolCall.function.name,
+        toolName: toolCall.function.name,
+        model: finishEvent.model,
+        timestamp: Date.now(),
+        result: toolResultContent,
+        ...toolResultState !== void 0 && { state: toolResultState }
+      };
+      toolResults.push({
+        role: "tool",
+        content: toolResultContent,
+        toolCallId: toolCall.id
+      });
+    }
+    return toolResults;
+  }
+  /**
+   * Clear the tool calls map for the next iteration
+   */
+  clear() {
+    this.toolCallsMap.clear();
+  }
+}
+async function* executeWithEventPolling(executionPromise, pendingEvents) {
+  const state = { done: false, result: void 0 };
+  const executionWithFlag = executionPromise.then((r) => {
+    state.done = true;
+    state.result = r;
+    return r;
+  });
+  while (!state.done) {
+    await Promise.race([
+      executionWithFlag,
+      new Promise((resolve) => setTimeout(resolve, 10))
+    ]);
+    let event2;
+    while ((event2 = pendingEvents.shift()) !== void 0) {
+      yield event2;
+    }
+  }
+  let event;
+  while ((event = pendingEvents.shift()) !== void 0) {
+    yield event;
+  }
+  return state.result;
+}
+async function applyBeforeToolCallDecision(toolCall, tool, input, toolName, middlewareHooks, results) {
+  if (!middlewareHooks.onBeforeToolCall) {
+    return { proceed: true, input };
+  }
+  const decision = await middlewareHooks.onBeforeToolCall(toolCall, tool, input);
+  if (!decision) {
+    return { proceed: true, input };
+  }
+  if (decision.type === "abort") {
+    throw new MiddlewareAbortError(decision.reason || "Aborted by middleware");
+  }
+  if (decision.type === "skip") {
+    const skipResult = decision.result;
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: typeof skipResult === "string" ? safeJsonParse(skipResult) : skipResult ?? null,
+      duration: 0
+    });
+    if (middlewareHooks.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: true,
+        duration: 0,
+        result: skipResult
+      });
+    }
+    return { proceed: false };
+  }
+  return { proceed: true, input: decision.args };
+}
+async function* executeServerTool(toolCall, tool, toolName, input, context, pendingEvents, results, middlewareHooks) {
+  const startTime = Date.now();
+  try {
+    if (!tool.execute) {
+      throw new Error(`Tool ${toolName} has no execute() implementation`);
+    }
+    const executionPromise = Promise.resolve(tool.execute(input, context));
+    let result = yield* executeWithEventPolling(executionPromise, pendingEvents);
+    const duration = Date.now() - startTime;
+    let pendingEvent;
+    while ((pendingEvent = pendingEvents.shift()) !== void 0) {
+      yield pendingEvent;
+    }
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
+      result = parseWithStandardSchema(tool.outputSchema, result);
+    }
+    const finalResult = typeof result === "string" ? safeJsonParse(result) : result ?? null;
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: finalResult,
+      duration
+    });
+    if (middlewareHooks?.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: true,
+        duration,
+        result: finalResult
+      });
+    }
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    let pendingEvent;
+    while ((pendingEvent = pendingEvents.shift()) !== void 0) {
+      yield pendingEvent;
+    }
+    if (error instanceof MiddlewareAbortError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown error";
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: { error: message },
+      state: "output-error",
+      duration
+    });
+    if (middlewareHooks?.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: false,
+        duration,
+        error
+      });
+    }
+  }
+}
+function buildClientToolResult(toolCallId, toolName, tool, rawResult) {
+  try {
+    let result = rawResult;
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
+      result = parseWithStandardSchema(tool.outputSchema, result);
+    }
+    return {
+      toolCallId,
+      toolName,
+      result: typeof result === "string" ? safeJsonParse(result) : result ?? null
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Validation failed";
+    return {
+      toolCallId,
+      toolName,
+      result: { error: message },
+      state: "output-error"
+    };
+  }
+}
+async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ new Map(), clientResults = /* @__PURE__ */ new Map(), createCustomEventChunk, middlewareHooks, userContext, abortSignal) {
+  const results = [];
+  const needsApproval = [];
+  const needsClientExecution = [];
+  const toolMap = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    toolMap.set(tool.name, tool);
+  }
+  const hasPendingApprovals = toolCalls.some((tc) => {
+    const t = toolMap.get(tc.function.name);
+    return t?.needsApproval && !approvals.has(`approval_${tc.id}`);
+  });
+  for (const toolCall of toolCalls) {
+    const tool = toolMap.get(toolCall.function.name);
+    const toolName = toolCall.function.name;
+    if (!tool) {
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: `Unknown tool: ${toolName}` },
+        state: "output-error"
+      });
+      continue;
+    }
+    if (hasPendingApprovals) {
+      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {
+        continue;
+      }
+    }
+    let input = {};
+    const argsStr = toolCall.function.arguments.trim() || "{}";
+    {
+      try {
+        const parsed = JSON.parse(argsStr);
+        input = parsed && typeof parsed === "object" ? parsed : {};
+      } catch (parseError) {
+        throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`);
+      }
+    }
+    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {
+      try {
+        input = parseWithStandardSchema(tool.inputSchema, input);
+      } catch (validationError) {
+        const message = validationError instanceof Error ? validationError.message : "Validation failed";
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result: {
+            error: `Input validation failed for tool ${tool.name}: ${message}`
+          },
+          state: "output-error"
+        });
+        continue;
+      }
+    }
+    const pendingEvents = [];
+    const context = {
+      toolCallId: toolCall.id,
+      context: userContext,
+      abortSignal,
+      emitCustomEvent: (eventName, value) => {
+        if (createCustomEventChunk) {
+          pendingEvents.push(
+            createCustomEventChunk(eventName, {
+              ...value,
+              toolCallId: toolCall.id
+            })
+          );
+        }
+      }
+    };
+    if (!tool.execute) {
+      if (tool.needsApproval) {
+        const approvalId = `approval_${toolCall.id}`;
+        if (approvals.has(approvalId)) {
+          const approved = approvals.get(approvalId);
+          if (approved) {
+            if (clientResults.has(toolCall.id)) {
+              results.push(
+                buildClientToolResult(
+                  toolCall.id,
+                  toolName,
+                  tool,
+                  clientResults.get(toolCall.id)
+                )
+              );
+            } else {
+              needsClientExecution.push({
+                toolCallId: toolCall.id,
+                toolName,
+                input
+              });
+            }
+          } else {
+            results.push({
+              toolCallId: toolCall.id,
+              toolName,
+              result: { error: "User declined tool execution" },
+              state: "output-error"
+            });
+          }
+        } else {
+          needsApproval.push({
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            input,
+            approvalId
+          });
+        }
+      } else {
+        if (clientResults.has(toolCall.id)) {
+          results.push(
+            buildClientToolResult(
+              toolCall.id,
+              toolName,
+              tool,
+              clientResults.get(toolCall.id)
+            )
+          );
+        } else {
+          needsClientExecution.push({
+            toolCallId: toolCall.id,
+            toolName,
+            input
+          });
+        }
+      }
+      continue;
+    }
+    if (tool.needsApproval) {
+      const approvalId = `approval_${toolCall.id}`;
+      if (approvals.has(approvalId)) {
+        const approved = approvals.get(approvalId);
+        if (approved) {
+          if (middlewareHooks) {
+            const decision = await applyBeforeToolCallDecision(
+              toolCall,
+              tool,
+              input,
+              toolName,
+              middlewareHooks,
+              results
+            );
+            if (!decision.proceed) continue;
+            input = decision.input;
+          }
+          yield* executeServerTool(
+            toolCall,
+            tool,
+            toolName,
+            input,
+            context,
+            pendingEvents,
+            results,
+            middlewareHooks
+          );
+        } else {
+          results.push({
+            toolCallId: toolCall.id,
+            toolName,
+            result: { error: "User declined tool execution" },
+            state: "output-error"
+          });
+        }
+      } else {
+        needsApproval.push({
+          toolCallId: toolCall.id,
+          toolName,
+          input,
+          approvalId
+        });
+      }
+      continue;
+    }
+    if (middlewareHooks) {
+      const decision = await applyBeforeToolCallDecision(
+        toolCall,
+        tool,
+        input,
+        toolName,
+        middlewareHooks,
+        results
+      );
+      if (!decision.proceed) continue;
+      input = decision.input;
+    }
+    yield* executeServerTool(
+      toolCall,
+      tool,
+      toolName,
+      input,
+      context,
+      pendingEvents,
+      results,
+      middlewareHooks
+    );
+  }
+  return { results, needsApproval, needsClientExecution };
+}
+export {
+  MiddlewareAbortError,
+  ToolCallManager,
+  executeToolCalls
+};
+//# sourceMappingURL=tool-calls.js.map