@tambo-ai/client 0.0.1

package/esm/utils/tool-call-tracker.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Tool Call Tracker
+ *
+ * Tracks tool calls during streaming, accumulating arguments until complete.
+ * Owns the tool name → JSON Schema mapping and handles unstrictification
+ * so callers don't need to know about schema conversion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolCallTracker = void 0;
+const core_1 = require("@ag-ui/core");
+const partial_json_1 = require("partial-json");
+const schema_1 = require("../schema/schema.js");
+const unstrictify_1 = require("./unstrictify.js");
+/**
+ * Build a tool-name → JSONSchema7 map from the tool registry.
+ * Handles both modern `inputSchema` and deprecated `toolSchema` formats.
+ * Tools whose schema can't be converted are silently skipped.
+ * @param toolRegistry - Record of tool name → tool definition
+ * @returns Map of tool name → JSON Schema
+ */
+function buildToolSchemas(toolRegistry) {
+    const schemas = new Map();
+    for (const tool of Object.values(toolRegistry)) {
+        try {
+            if ("inputSchema" in tool && tool.inputSchema) {
+                schemas.set(tool.name, (0, schema_1.schemaToJsonSchema)(tool.inputSchema));
+            }
+            else if ("toolSchema" in tool && tool.toolSchema) {
+                schemas.set(tool.name, (0, schema_1.schemaToJsonSchema)(tool.toolSchema));
+            }
+        }
+        catch {
+            // Schema conversion failed — tool still works, just without unstrictification
+        }
+    }
+    return schemas;
+}
+/**
+ * Tracks tool calls during streaming, accumulating arguments until complete.
+ *
+ * Tool calls arrive as a sequence of events:
+ * 1. TOOL_CALL_START - initializes the tool call with name
+ * 2. TOOL_CALL_ARGS (multiple) - streams JSON argument fragments
+ * 3. TOOL_CALL_END - marks the tool call as complete, triggers JSON parsing
+ *
+ * When constructed with a tool registry, the tracker unstrictifies parsed
+ * args (both partial and final) using the original JSON Schemas.
+ */
+class ToolCallTracker {
+    pendingToolCalls = new Map();
+    accumulatingArgs = new Map();
+    _toolSchemas;
+    constructor(toolRegistry) {
+        this._toolSchemas = toolRegistry
+            ? buildToolSchemas(toolRegistry)
+            : new Map();
+    }
+    /**
+     * The tool-name → JSONSchema7 map, for passing to the reducer.
+     * @returns The tool schemas map
+     */
+    get toolSchemas() {
+        return this._toolSchemas;
+    }
+    /**
+     * Handles a streaming event, tracking tool call state as needed.
+     * @param event - The streaming event to process
+     * @throws {Error} If JSON parsing fails on TOOL_CALL_END (fail-fast, no silent fallback)
+     */
+    handleEvent(event) {
+        switch (event.type) {
+            case core_1.EventType.TOOL_CALL_START:
+                this.pendingToolCalls.set(event.toolCallId, {
+                    name: event.toolCallName,
+                    input: {},
+                });
+                this.accumulatingArgs.set(event.toolCallId, "");
+                break;
+            case core_1.EventType.TOOL_CALL_ARGS: {
+                const current = this.accumulatingArgs.get(event.toolCallId);
+                this.accumulatingArgs.set(event.toolCallId, (current ?? "") + event.delta);
+                break;
+            }
+            case core_1.EventType.TOOL_CALL_END: {
+                const jsonStr = this.accumulatingArgs.get(event.toolCallId);
+                const toolCall = this.pendingToolCalls.get(event.toolCallId);
+                if (toolCall && jsonStr) {
+                    let parsedInput;
+                    try {
+                        parsedInput = JSON.parse(jsonStr);
+                    }
+                    catch (error) {
+                        // Fail-fast: don't silently continue with empty input
+                        throw new Error(`Failed to parse tool call arguments for ${event.toolCallId}: ${error instanceof Error ? error.message : "Unknown error"}. JSON: ${jsonStr.slice(0, 100)}${jsonStr.length > 100 ? "..." : ""}`);
+                    }
+                    parsedInput = this.unstrictify(toolCall.name, parsedInput);
+                    toolCall.input = parsedInput;
+                }
+                break;
+            }
+            default:
+                // Other event types are ignored - only tool call events are tracked
+                break;
+        }
+    }
+    /**
+     * Parses partial JSON from the accumulated args for a tool call and
+     * unstrictifies the result. Used during streaming to get the current
+     * best-effort parsed args.
+     * @param toolCallId - ID of the tool call to parse
+     * @returns Parsed and unstrictified args, or undefined if not parseable yet
+     */
+    parsePartialArgs(toolCallId) {
+        const accToolCall = this.getAccumulatingToolCall(toolCallId);
+        if (!accToolCall)
+            return undefined;
+        try {
+            const parsed = (0, partial_json_1.parse)(accToolCall.accumulatedArgs);
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                !Array.isArray(parsed)) {
+                return this.unstrictify(accToolCall.name, parsed);
+            }
+        }
+        catch {
+            /* not parseable yet */
+        }
+        return undefined;
+    }
+    /**
+     * Gets the name and accumulated args for a tool call that is still accumulating.
+     * @param toolCallId - ID of the tool call to look up
+     * @returns The tool name and raw accumulated args string, or undefined if not found
+     */
+    getAccumulatingToolCall(toolCallId) {
+        const toolCall = this.pendingToolCalls.get(toolCallId);
+        const args = this.accumulatingArgs.get(toolCallId);
+        if (!toolCall || args === undefined)
+            return undefined;
+        return { name: toolCall.name, accumulatedArgs: args };
+    }
+    /**
+     * Gets tool calls for the given IDs, filtered to only those that exist.
+     * @param toolCallIds - IDs of tool calls to retrieve
+     * @returns Map of tool call ID to pending tool call
+     */
+    getToolCallsById(toolCallIds) {
+        const result = new Map();
+        for (const id of toolCallIds) {
+            const toolCall = this.pendingToolCalls.get(id);
+            if (toolCall) {
+                result.set(id, toolCall);
+            }
+        }
+        return result;
+    }
+    /**
+     * Clears tracked tool calls for the given IDs.
+     * @param toolCallIds - IDs of tool calls to clear
+     */
+    clearToolCalls(toolCallIds) {
+        for (const id of toolCallIds) {
+            this.pendingToolCalls.delete(id);
+            this.accumulatingArgs.delete(id);
+        }
+    }
+    /**
+     * Unstrictify params using the schema for the given tool name.
+     * Returns params unchanged if no schema is available.
+     * @returns The unstrictified params.
+     */
+    unstrictify(toolName, params) {
+        const schema = this._toolSchemas.get(toolName);
+        if (!schema)
+            return params;
+        return (0, unstrictify_1.unstrictifyToolCallParamsFromSchema)(schema, params);
+    }
+}
+exports.ToolCallTracker = ToolCallTracker;
+//# sourceMappingURL=tool-call-tracker.js.map

package/esm/utils/tool-call-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-tracker.js","sourceRoot":"","sources":["../../src/utils/tool-call-tracker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Tool Call Tracker\n *\n * Tracks tool calls during streaming, accumulating arguments until complete.\n * Owns the tool name → JSON Schema mapping and handles unstrictification\n * so callers don't need to know about schema conversion.\n */\n\nimport { EventType, type AGUIEvent } from \"@ag-ui/core\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport { parse as parsePartialJson } from \"partial-json\";\nimport type { TamboTool } from \"../model/component-metadata\";\nimport { schemaToJsonSchema } from \"../schema/schema\";\nimport type { PendingToolCall } from \"./tool-executor\";\nimport { unstrictifyToolCallParamsFromSchema } from \"./unstrictify\";\n\n/**\n * Build a tool-name → JSONSchema7 map from the tool registry.\n * Handles both modern `inputSchema` and deprecated `toolSchema` formats.\n * Tools whose schema can't be converted are silently skipped.\n * @param toolRegistry - Record of tool name → tool definition\n * @returns Map of tool name → JSON Schema\n */\nfunction buildToolSchemas(\n  toolRegistry: Record<string, TamboTool>,\n): Map<string, JSONSchema7> {\n  const schemas = new Map<string, JSONSchema7>();\n  for (const tool of Object.values(toolRegistry)) {\n    try {\n      if (\"inputSchema\" in tool && tool.inputSchema) {\n        schemas.set(tool.name, schemaToJsonSchema(tool.inputSchema));\n      } else if (\"toolSchema\" in tool && tool.toolSchema) {\n        schemas.set(tool.name, schemaToJsonSchema(tool.toolSchema));\n      }\n    } catch {\n      // Schema conversion failed — tool still works, just without unstrictification\n    }\n  }\n  return schemas;\n}\n\n/**\n * Tracks tool calls during streaming, accumulating arguments until complete.\n *\n * Tool calls arrive as a sequence of events:\n * 1. TOOL_CALL_START - initializes the tool call with name\n * 2. TOOL_CALL_ARGS (multiple) - streams JSON argument fragments\n * 3. TOOL_CALL_END - marks the tool call as complete, triggers JSON parsing\n *\n * When constructed with a tool registry, the tracker unstrictifies parsed\n * args (both partial and final) using the original JSON Schemas.\n */\nexport class ToolCallTracker {\n  private pendingToolCalls = new Map<string, PendingToolCall>();\n  private accumulatingArgs = new Map<string, string>();\n  private _toolSchemas: Map<string, JSONSchema7>;\n\n  constructor(toolRegistry?: Record<string, TamboTool>) {\n    this._toolSchemas = toolRegistry\n      ? buildToolSchemas(toolRegistry)\n      : new Map();\n  }\n\n  /**\n   * The tool-name → JSONSchema7 map, for passing to the reducer.\n   * @returns The tool schemas map\n   */\n  get toolSchemas(): Map<string, JSONSchema7> {\n    return this._toolSchemas;\n  }\n\n  /**\n   * Handles a streaming event, tracking tool call state as needed.\n   * @param event - The streaming event to process\n   * @throws {Error} If JSON parsing fails on TOOL_CALL_END (fail-fast, no silent fallback)\n   */\n  handleEvent(event: AGUIEvent): void {\n    switch (event.type) {\n      case EventType.TOOL_CALL_START:\n        this.pendingToolCalls.set(event.toolCallId, {\n          name: event.toolCallName,\n          input: {},\n        });\n        this.accumulatingArgs.set(event.toolCallId, \"\");\n        break;\n\n      case EventType.TOOL_CALL_ARGS: {\n        const current = this.accumulatingArgs.get(event.toolCallId);\n        this.accumulatingArgs.set(\n          event.toolCallId,\n          (current ?? \"\") + event.delta,\n        );\n        break;\n      }\n\n      case EventType.TOOL_CALL_END: {\n        const jsonStr = this.accumulatingArgs.get(event.toolCallId);\n        const toolCall = this.pendingToolCalls.get(event.toolCallId);\n        if (toolCall && jsonStr) {\n          let parsedInput: Record<string, unknown>;\n          try {\n            parsedInput = JSON.parse(jsonStr) as Record<string, unknown>;\n          } catch (error) {\n            // Fail-fast: don't silently continue with empty input\n            throw new Error(\n              `Failed to parse tool call arguments for ${event.toolCallId}: ${error instanceof Error ? error.message : \"Unknown error\"}. JSON: ${jsonStr.slice(0, 100)}${jsonStr.length > 100 ? \"...\" : \"\"}`,\n            );\n          }\n\n          parsedInput = this.unstrictify(toolCall.name, parsedInput);\n          toolCall.input = parsedInput;\n        }\n        break;\n      }\n\n      default:\n        // Other event types are ignored - only tool call events are tracked\n        break;\n    }\n  }\n\n  /**\n   * Parses partial JSON from the accumulated args for a tool call and\n   * unstrictifies the result. Used during streaming to get the current\n   * best-effort parsed args.\n   * @param toolCallId - ID of the tool call to parse\n   * @returns Parsed and unstrictified args, or undefined if not parseable yet\n   */\n  parsePartialArgs(toolCallId: string): Record<string, unknown> | undefined {\n    const accToolCall = this.getAccumulatingToolCall(toolCallId);\n    if (!accToolCall) return undefined;\n\n    try {\n      const parsed: unknown = parsePartialJson(accToolCall.accumulatedArgs);\n      if (\n        typeof parsed === \"object\" &&\n        parsed !== null &&\n        !Array.isArray(parsed)\n      ) {\n        return this.unstrictify(\n          accToolCall.name,\n          parsed as Record<string, unknown>,\n        );\n      }\n    } catch {\n      /* not parseable yet */\n    }\n    return undefined;\n  }\n\n  /**\n   * Gets the name and accumulated args for a tool call that is still accumulating.\n   * @param toolCallId - ID of the tool call to look up\n   * @returns The tool name and raw accumulated args string, or undefined if not found\n   */\n  getAccumulatingToolCall(\n    toolCallId: string,\n  ): { name: string; accumulatedArgs: string } | undefined {\n    const toolCall = this.pendingToolCalls.get(toolCallId);\n    const args = this.accumulatingArgs.get(toolCallId);\n    if (!toolCall || args === undefined) return undefined;\n    return { name: toolCall.name, accumulatedArgs: args };\n  }\n\n  /**\n   * Gets tool calls for the given IDs, filtered to only those that exist.\n   * @param toolCallIds - IDs of tool calls to retrieve\n   * @returns Map of tool call ID to pending tool call\n   */\n  getToolCallsById(toolCallIds: string[]): Map<string, PendingToolCall> {\n    const result = new Map<string, PendingToolCall>();\n    for (const id of toolCallIds) {\n      const toolCall = this.pendingToolCalls.get(id);\n      if (toolCall) {\n        result.set(id, toolCall);\n      }\n    }\n    return result;\n  }\n\n  /**\n   * Clears tracked tool calls for the given IDs.\n   * @param toolCallIds - IDs of tool calls to clear\n   */\n  clearToolCalls(toolCallIds: string[]): void {\n    for (const id of toolCallIds) {\n      this.pendingToolCalls.delete(id);\n      this.accumulatingArgs.delete(id);\n    }\n  }\n\n  /**\n   * Unstrictify params using the schema for the given tool name.\n   * Returns params unchanged if no schema is available.\n   * @returns The unstrictified params.\n   */\n  private unstrictify(\n    toolName: string,\n    params: Record<string, unknown>,\n  ): Record<string, unknown> {\n    const schema = this._toolSchemas.get(toolName);\n    if (!schema) return params;\n    return unstrictifyToolCallParamsFromSchema(schema, params);\n  }\n}\n"]}

package/esm/utils/tool-executor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Tool Executor
+ *
+ * Handles automatic execution of client-side tools when the model
+ * requests them via `tambo.run.awaiting_input` events.
+ */
+import type { TamboTool } from "../model/component-metadata.js";
+import type { ToolResultContent } from "@tambo-ai/typescript-sdk/resources/threads/threads";
+import type { ToolCallTracker } from "./tool-call-tracker.js";
+import { type KeyedThrottle } from "./keyed-throttle.js";
+/**
+ * Pending tool call from the stream accumulator
+ */
+export interface PendingToolCall {
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Execute a streamable tool call during streaming with pre-parsed partial args.
+ *
+ * Called on each TOOL_CALL_ARGS event for tools annotated with
+ * `tamboStreamableHint: true`. Enables incremental UI updates while
+ * the model is still generating arguments.
+ *
+ * Errors are caught silently — streaming tool execution is non-fatal since
+ * the final execution via `awaiting_input` is what matters.
+ * @param toolCallId - The tool call ID being accumulated
+ * @param parsedArgs - Pre-parsed partial JSON args
+ * @param toolTracker - Tracker holding pending tool call state
+ * @param toolRegistry - Record of tool name to tool definition
+ */
+export declare function executeStreamableToolCall(toolCallId: string, parsedArgs: Record<string, unknown>, toolTracker: ToolCallTracker, toolRegistry: Record<string, TamboTool>): Promise<void>;
+/**
+ * Creates a throttled wrapper around executeStreamableToolCall.
+ *
+ * Each tool call ID gets its own independent leading+trailing throttle via
+ * {@link createKeyedThrottle}. The first call for a tool ID fires immediately
+ * (leading edge). Subsequent calls during the cooldown window update the
+ * stored args. After `delay` ms, if new args arrived, the tool re-executes
+ * with the latest args (trailing edge). This repeats as long as new args
+ * keep arriving — roughly one execution per `delay` ms during streaming.
+ *
+ * Call `flush()` to force-execute all pending trailing calls and reset to idle.
+ * @param toolTracker - Tracker holding pending tool call state
+ * @param toolRegistry - Record of tool name to tool definition
+ * @param delay - Throttle interval in milliseconds
+ * @returns Keyed throttle controller (schedule / flush)
+ */
+export declare function createThrottledStreamableExecutor(toolTracker: ToolCallTracker, toolRegistry: Record<string, TamboTool>, delay?: number): KeyedThrottle<Record<string, unknown>>;
+/**
+ * Execute a single client-side tool and return the result.
+ * @param tool - The tool definition from the registry
+ * @param toolCallId - The ID of the tool call to respond to
+ * @param args - The parsed arguments for the tool
+ * @returns ToolResultContent with the execution result or error
+ */
+export declare function executeClientTool(tool: TamboTool, toolCallId: string, args: Record<string, unknown>): Promise<ToolResultContent>;
+/**
+ * Execute all pending tool calls and return their results.
+ * Tools are executed sequentially to avoid race conditions when
+ * tools may have side effects that depend on each other.
+ * @param toolCalls - Map of tool call IDs to their call details
+ * @param registry - Registry of tool names to their definitions (Map or Record)
+ * @returns Array of ToolResultContent for all executed tools
+ */
+export declare function executeAllPendingTools(toolCalls: Map<string, PendingToolCall>, registry: Map<string, TamboTool> | Record<string, TamboTool>): Promise<ToolResultContent[]>;
+//# sourceMappingURL=tool-executor.d.ts.map

package/esm/utils/tool-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../src/utils/tool-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,eAAe,EAC5B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,eAAe,EAC5B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACvC,KAAK,SAAiC,GACrC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAIxC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAiD5B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAC3D,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiC9B"}

package/esm/utils/tool-executor.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Tool Executor
+ *
+ * Handles automatic execution of client-side tools when the model
+ * requests them via `tambo.run.awaiting_input` events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeStreamableToolCall = executeStreamableToolCall;
+exports.createThrottledStreamableExecutor = createThrottledStreamableExecutor;
+exports.executeClientTool = executeClientTool;
+exports.executeAllPendingTools = executeAllPendingTools;
+const keyed_throttle_1 = require("./keyed-throttle.js");
+/**
+ * Execute a streamable tool call during streaming with pre-parsed partial args.
+ *
+ * Called on each TOOL_CALL_ARGS event for tools annotated with
+ * `tamboStreamableHint: true`. Enables incremental UI updates while
+ * the model is still generating arguments.
+ *
+ * Errors are caught silently — streaming tool execution is non-fatal since
+ * the final execution via `awaiting_input` is what matters.
+ * @param toolCallId - The tool call ID being accumulated
+ * @param parsedArgs - Pre-parsed partial JSON args
+ * @param toolTracker - Tracker holding pending tool call state
+ * @param toolRegistry - Record of tool name to tool definition
+ */
+async function executeStreamableToolCall(toolCallId, parsedArgs, toolTracker, toolRegistry) {
+    const accumulating = toolTracker.getAccumulatingToolCall(toolCallId);
+    if (!accumulating)
+        return;
+    const tool = toolRegistry[accumulating.name];
+    if (!tool?.annotations?.tamboStreamableHint)
+        return;
+    try {
+        await tool.tool(parsedArgs);
+    }
+    catch (error) {
+        console.warn(`[ToolExecutor] Non-fatal error in streamable tool "${accumulating.name}" ` +
+            `(toolCallId: ${toolCallId}). This likely indicates a bug in the tool ` +
+            `implementation; fix the tool to avoid repeated warnings.`, error);
+    }
+}
+const DEFAULT_STREAMABLE_THROTTLE_MS = 100;
+/**
+ * Creates a throttled wrapper around executeStreamableToolCall.
+ *
+ * Each tool call ID gets its own independent leading+trailing throttle via
+ * {@link createKeyedThrottle}. The first call for a tool ID fires immediately
+ * (leading edge). Subsequent calls during the cooldown window update the
+ * stored args. After `delay` ms, if new args arrived, the tool re-executes
+ * with the latest args (trailing edge). This repeats as long as new args
+ * keep arriving — roughly one execution per `delay` ms during streaming.
+ *
+ * Call `flush()` to force-execute all pending trailing calls and reset to idle.
+ * @param toolTracker - Tracker holding pending tool call state
+ * @param toolRegistry - Record of tool name to tool definition
+ * @param delay - Throttle interval in milliseconds
+ * @returns Keyed throttle controller (schedule / flush)
+ */
+function createThrottledStreamableExecutor(toolTracker, toolRegistry, delay = DEFAULT_STREAMABLE_THROTTLE_MS) {
+    return (0, keyed_throttle_1.createKeyedThrottle)((toolCallId, args) => {
+        void executeStreamableToolCall(toolCallId, args, toolTracker, toolRegistry);
+    }, delay);
+}
+/**
+ * Execute a single client-side tool and return the result.
+ * @param tool - The tool definition from the registry
+ * @param toolCallId - The ID of the tool call to respond to
+ * @param args - The parsed arguments for the tool
+ * @returns ToolResultContent with the execution result or error
+ */
+async function executeClientTool(tool, toolCallId, args) {
+    try {
+        const result = await tool.tool(args);
+        // Transform result to content if transformer provided
+        let content;
+        if (tool.transformToContent) {
+            // transformToContent may return content parts in beta format
+            // Convert to content format (TextContent | ResourceContent)
+            const transformed = await tool.transformToContent(result);
+            content = transformed.map((part) => {
+                if (part.type === "text" && "text" in part && part.text) {
+                    return { type: "text", text: part.text };
+                }
+                // For other types, stringify as text
+                return {
+                    type: "text",
+                    text: JSON.stringify(part),
+                };
+            });
+        }
+        else {
+            // Default: stringify result as text
+            content = [
+                {
+                    type: "text",
+                    text: typeof result === "string" ? result : JSON.stringify(result),
+                },
+            ];
+        }
+        return {
+            type: "tool_result",
+            toolUseId: toolCallId,
+            content,
+        };
+    }
+    catch (error) {
+        return {
+            type: "tool_result",
+            toolUseId: toolCallId,
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: error instanceof Error ? error.message : "Tool execution failed",
+                },
+            ],
+        };
+    }
+}
+/**
+ * Execute all pending tool calls and return their results.
+ * Tools are executed sequentially to avoid race conditions when
+ * tools may have side effects that depend on each other.
+ * @param toolCalls - Map of tool call IDs to their call details
+ * @param registry - Registry of tool names to their definitions (Map or Record)
+ * @returns Array of ToolResultContent for all executed tools
+ */
+async function executeAllPendingTools(toolCalls, registry) {
+    const results = [];
+    // Normalize registry to allow lookup regardless of Map or Record
+    const getTool = (name) => {
+        if (registry instanceof Map) {
+            return registry.get(name);
+        }
+        return registry[name];
+    };
+    for (const [toolCallId, { name, input }] of toolCalls) {
+        const tool = getTool(name);
+        if (!tool) {
+            results.push({
+                type: "tool_result",
+                toolUseId: toolCallId,
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Tool "${name}" not found in registry`,
+                    },
+                ],
+            });
+            continue;
+        }
+        const result = await executeClientTool(tool, toolCallId, input);
+        results.push(result);
+    }
+    return results;
+}
+//# sourceMappingURL=tool-executor.js.map

package/esm/utils/tool-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.js","sourceRoot":"","sources":["../../src/utils/tool-executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Tool Executor\n *\n * Handles automatic execution of client-side tools when the model\n * requests them via `tambo.run.awaiting_input` events.\n */\n\nimport type { TamboTool } from \"../model/component-metadata\";\nimport type {\n  ToolResultContent,\n  TextContent,\n  ResourceContent,\n} from \"@tambo-ai/typescript-sdk/resources/threads/threads\";\nimport type { ToolCallTracker } from \"./tool-call-tracker\";\nimport { createKeyedThrottle, type KeyedThrottle } from \"./keyed-throttle\";\n\n/**\n * Pending tool call from the stream accumulator\n */\nexport interface PendingToolCall {\n  name: string;\n  input: Record<string, unknown>;\n}\n\n/**\n * Execute a streamable tool call during streaming with pre-parsed partial args.\n *\n * Called on each TOOL_CALL_ARGS event for tools annotated with\n * `tamboStreamableHint: true`. Enables incremental UI updates while\n * the model is still generating arguments.\n *\n * Errors are caught silently — streaming tool execution is non-fatal since\n * the final execution via `awaiting_input` is what matters.\n * @param toolCallId - The tool call ID being accumulated\n * @param parsedArgs - Pre-parsed partial JSON args\n * @param toolTracker - Tracker holding pending tool call state\n * @param toolRegistry - Record of tool name to tool definition\n */\nexport async function executeStreamableToolCall(\n  toolCallId: string,\n  parsedArgs: Record<string, unknown>,\n  toolTracker: ToolCallTracker,\n  toolRegistry: Record<string, TamboTool>,\n): Promise<void> {\n  const accumulating = toolTracker.getAccumulatingToolCall(toolCallId);\n  if (!accumulating) return;\n\n  const tool = toolRegistry[accumulating.name];\n  if (!tool?.annotations?.tamboStreamableHint) return;\n\n  try {\n    await tool.tool(parsedArgs);\n  } catch (error) {\n    console.warn(\n      `[ToolExecutor] Non-fatal error in streamable tool \"${accumulating.name}\" ` +\n        `(toolCallId: ${toolCallId}). This likely indicates a bug in the tool ` +\n        `implementation; fix the tool to avoid repeated warnings.`,\n      error,\n    );\n  }\n}\n\nconst DEFAULT_STREAMABLE_THROTTLE_MS = 100;\n\n/**\n * Creates a throttled wrapper around executeStreamableToolCall.\n *\n * Each tool call ID gets its own independent leading+trailing throttle via\n * {@link createKeyedThrottle}. The first call for a tool ID fires immediately\n * (leading edge). Subsequent calls during the cooldown window update the\n * stored args. After `delay` ms, if new args arrived, the tool re-executes\n * with the latest args (trailing edge). This repeats as long as new args\n * keep arriving — roughly one execution per `delay` ms during streaming.\n *\n * Call `flush()` to force-execute all pending trailing calls and reset to idle.\n * @param toolTracker - Tracker holding pending tool call state\n * @param toolRegistry - Record of tool name to tool definition\n * @param delay - Throttle interval in milliseconds\n * @returns Keyed throttle controller (schedule / flush)\n */\nexport function createThrottledStreamableExecutor(\n  toolTracker: ToolCallTracker,\n  toolRegistry: Record<string, TamboTool>,\n  delay = DEFAULT_STREAMABLE_THROTTLE_MS,\n): KeyedThrottle<Record<string, unknown>> {\n  return createKeyedThrottle<Record<string, unknown>>((toolCallId, args) => {\n    void executeStreamableToolCall(toolCallId, args, toolTracker, toolRegistry);\n  }, delay);\n}\n\n/**\n * Execute a single client-side tool and return the result.\n * @param tool - The tool definition from the registry\n * @param toolCallId - The ID of the tool call to respond to\n * @param args - The parsed arguments for the tool\n * @returns ToolResultContent with the execution result or error\n */\nexport async function executeClientTool(\n  tool: TamboTool,\n  toolCallId: string,\n  args: Record<string, unknown>,\n): Promise<ToolResultContent> {\n  try {\n    const result = await tool.tool(args);\n\n    // Transform result to content if transformer provided\n    let content: (TextContent | ResourceContent)[];\n    if (tool.transformToContent) {\n      // transformToContent may return content parts in beta format\n      // Convert to content format (TextContent | ResourceContent)\n      const transformed = await tool.transformToContent(result);\n      content = transformed.map((part) => {\n        if (part.type === \"text\" && \"text\" in part && part.text) {\n          return { type: \"text\" as const, text: part.text };\n        }\n        // For other types, stringify as text\n        return {\n          type: \"text\" as const,\n          text: JSON.stringify(part),\n        };\n      });\n    } else {\n      // Default: stringify result as text\n      content = [\n        {\n          type: \"text\" as const,\n          text: typeof result === \"string\" ? result : JSON.stringify(result),\n        },\n      ];\n    }\n\n    return {\n      type: \"tool_result\",\n      toolUseId: toolCallId,\n      content,\n    };\n  } catch (error) {\n    return {\n      type: \"tool_result\",\n      toolUseId: toolCallId,\n      isError: true,\n      content: [\n        {\n          type: \"text\" as const,\n          text:\n            error instanceof Error ? error.message : \"Tool execution failed\",\n        },\n      ],\n    };\n  }\n}\n\n/**\n * Execute all pending tool calls and return their results.\n * Tools are executed sequentially to avoid race conditions when\n * tools may have side effects that depend on each other.\n * @param toolCalls - Map of tool call IDs to their call details\n * @param registry - Registry of tool names to their definitions (Map or Record)\n * @returns Array of ToolResultContent for all executed tools\n */\nexport async function executeAllPendingTools(\n  toolCalls: Map<string, PendingToolCall>,\n  registry: Map<string, TamboTool> | Record<string, TamboTool>,\n): Promise<ToolResultContent[]> {\n  const results: ToolResultContent[] = [];\n\n  // Normalize registry to allow lookup regardless of Map or Record\n  const getTool = (name: string): TamboTool | undefined => {\n    if (registry instanceof Map) {\n      return registry.get(name);\n    }\n    return registry[name];\n  };\n\n  for (const [toolCallId, { name, input }] of toolCalls) {\n    const tool = getTool(name);\n    if (!tool) {\n      results.push({\n        type: \"tool_result\",\n        toolUseId: toolCallId,\n        isError: true,\n        content: [\n          {\n            type: \"text\" as const,\n            text: `Tool \"${name}\" not found in registry`,\n          },\n        ],\n      });\n      continue;\n    }\n\n    const result = await executeClientTool(tool, toolCallId, input);\n    results.push(result);\n  }\n\n  return results;\n}\n"]}

package/esm/utils/unstrictify.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unstrictify tool call parameters using the original JSON Schema.
+ *
+ * When OpenAI's structured outputs mode is enabled, all optional parameters
+ * become required-and-nullable. The LLM then sends `null` for parameters the
+ * user didn't specify. This module reverses that transformation by comparing
+ * the LLM's output against the original schema and stripping nulls for
+ * parameters that were originally optional and non-nullable.
+ *
+ * Copied from packages/core/src/strictness/tool-call-strict.ts (minus the
+ * OpenAI-specific `unstrictifyToolCallRequest` wrapper).
+ */
+import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+/**
+ * Unstrictify tool call params using the original JSON Schema.
+ *
+ * Unlike the private `unstrictifyToolCallParams` which throws on unknown params,
+ * this function separates params into schema-defined vs `_tambo_*` pass-through
+ * (server-injected params not in the original schema), unstrictifies only the
+ * schema-defined ones, and merges pass-through params back. Unknown keys that
+ * aren't in the schema and don't have the `_tambo_` prefix are dropped.
+ * @returns The params with strictification-induced nulls stripped for optional
+ * non-nullable properties, and pass-through params preserved as-is.
+ */
+export declare function unstrictifyToolCallParamsFromSchema(originalSchema: JSONSchema7, params: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Check if a JSON Schema definition allows null values.
+ * @param originalSchema - The schema definition to check
+ * @returns True if the schema allows null values
+ */
+export declare function canBeNull(originalSchema: JSONSchema7Definition): boolean;
+//# sourceMappingURL=unstrictify.d.ts.map

package/esm/utils/unstrictify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unstrictify.d.ts","sourceRoot":"","sources":["../../src/utils/unstrictify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAuItE;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,WAAW,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,cAAc,EAAE,qBAAqB,GAAG,OAAO,CAaxE"}

package/esm/utils/unstrictify.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Unstrictify tool call parameters using the original JSON Schema.
+ *
+ * When OpenAI's structured outputs mode is enabled, all optional parameters
+ * become required-and-nullable. The LLM then sends `null` for parameters the
+ * user didn't specify. This module reverses that transformation by comparing
+ * the LLM's output against the original schema and stripping nulls for
+ * parameters that were originally optional and non-nullable.
+ *
+ * Copied from packages/core/src/strictness/tool-call-strict.ts (minus the
+ * OpenAI-specific `unstrictifyToolCallRequest` wrapper).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unstrictifyToolCallParamsFromSchema = unstrictifyToolCallParamsFromSchema;
+exports.canBeNull = canBeNull;
+/**
+ * Unstrictify the parameters of a tool call request.
+ *
+ * This effectively reverses the process of strictifyToolCallParams, for a
+ * tool call request that was built from a strict JSON Schema, by returning a
+ * updated tool call request with the parameter values unstrictified.
+ * @returns The params with strictification-induced nulls stripped.
+ */
+function unstrictifyToolCallParams(originalToolParamSchema, toolCallRequestParams) {
+    if (originalToolParamSchema.type !== "object") {
+        throw new Error(`tool call parameter schema must be an object, instead got ${originalToolParamSchema.type} / ${typeof originalToolParamSchema}`);
+    }
+    const newParams = Object.entries(toolCallRequestParams)
+        .map(([parameterName, parameterValue]) => {
+        const isRequired = originalToolParamSchema.required?.includes(parameterName);
+        // find the param in the original tool schema
+        const originalParamSchema = parameterName in (originalToolParamSchema.properties ?? {})
+            ? originalToolParamSchema.properties?.[parameterName]
+            : undefined;
+        // This should never happen, because the strict schema was derived from
+        // the original schema, so the parameter should always be present.
+        if (!originalParamSchema) {
+            throw new Error(`Tool call request parameter ${parameterName} not found in original tool`);
+        }
+        if (parameterValue === null &&
+            !canBeNull(originalParamSchema) &&
+            !isRequired) {
+            // This is the meat of this function. In the strict schema, this is
+            // "required and can be null", but in the original schema, the param was
+            // not required.
+            if (typeof originalParamSchema === "object" &&
+                "default" in originalParamSchema) {
+                return [parameterName, originalParamSchema.default];
+            }
+            return undefined;
+        }
+        // recurse into arrays
+        if (typeof originalParamSchema === "object" &&
+            originalParamSchema.type === "array") {
+            const arrayValue = parameterValue;
+            const itemSchema = originalParamSchema.items;
+            if (Array.isArray(arrayValue) &&
+                itemSchema &&
+                typeof itemSchema === "object" &&
+                !Array.isArray(itemSchema)) {
+                const newArrayValue = arrayValue.map((item) => {
+                    if (itemSchema.type === "object" &&
+                        typeof item === "object" &&
+                        item !== null) {
+                        // recurse into each object in the array
+                        return unstrictifyToolCallParams(itemSchema, item);
+                    }
+                    return item;
+                });
+                return [parameterName, newArrayValue];
+            }
+            return [parameterName, parameterValue];
+        }
+        // recurse into the parameter value, passing along the matching original schema
+        if (typeof originalParamSchema === "object" &&
+            originalParamSchema.type === "object") {
+            // If the LLM sent a JSON string instead of an object (common with z.any() schemas),
+            // try to parse it
+            let objectValue = parameterValue;
+            if (typeof parameterValue === "string") {
+                try {
+                    const parsed = JSON.parse(parameterValue);
+                    if (typeof parsed === "object" && parsed !== null) {
+                        objectValue = parsed;
+                    }
+                }
+                catch {
+                    // Not valid JSON, keep original value
+                }
+            }
+            // Only recurse if we have an actual object AND the schema has properties defined.
+            // If the schema has no properties (e.g., z.any() which produces {type: 'object', anyOf: [...]}),
+            // just return the value as-is without recursing.
+            const hasProperties = originalParamSchema.properties &&
+                Object.keys(originalParamSchema.properties).length > 0;
+            if (hasProperties &&
+                typeof objectValue === "object" &&
+                objectValue !== null &&
+                !Array.isArray(objectValue)) {
+                const newParamValue = unstrictifyToolCallParams(originalParamSchema, objectValue);
+                return [parameterName, newParamValue];
+            }
+            // Return the (possibly parsed) object value without recursing
+            return [parameterName, objectValue];
+        }
+        return [parameterName, parameterValue];
+    })
+        .filter((param) => param !== undefined);
+    return Object.fromEntries(newParams);
+}
+/**
+ * Unstrictify tool call params using the original JSON Schema.
+ *
+ * Unlike the private `unstrictifyToolCallParams` which throws on unknown params,
+ * this function separates params into schema-defined vs `_tambo_*` pass-through
+ * (server-injected params not in the original schema), unstrictifies only the
+ * schema-defined ones, and merges pass-through params back. Unknown keys that
+ * aren't in the schema and don't have the `_tambo_` prefix are dropped.
+ * @returns The params with strictification-induced nulls stripped for optional
+ * non-nullable properties, and pass-through params preserved as-is.
+ */
+function unstrictifyToolCallParamsFromSchema(originalSchema, params) {
+    if (originalSchema.type !== "object") {
+        return params;
+    }
+    const schemaProperties = originalSchema.properties ?? {};
+    const schemaDefinedParams = {};
+    const passThroughParams = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (key in schemaProperties) {
+            schemaDefinedParams[key] = value;
+        }
+        else if (key.startsWith("_tambo_")) {
+            passThroughParams[key] = value;
+        }
+        // Unknown keys not in schema and not _tambo_* are dropped —
+        // they're likely hallucinated by the model.
+    }
+    const unstrictified = unstrictifyToolCallParams(originalSchema, schemaDefinedParams);
+    return { ...unstrictified, ...passThroughParams };
+}
+/**
+ * Check if a JSON Schema definition allows null values.
+ * @param originalSchema - The schema definition to check
+ * @returns True if the schema allows null values
+ */
+function canBeNull(originalSchema) {
+    if (typeof originalSchema !== "object") {
+        return false;
+    }
+    if (originalSchema.type === "null") {
+        return true;
+    }
+    if (originalSchema.anyOf?.some((anyOf) => canBeNull(anyOf))) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=unstrictify.js.map