@tanstack/ai 0.35.0 → 0.36.0

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

@@ -1,140 +0,0 @@
-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

@@ -1,512 +0,0 @@
-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