@illuma-ai/agents 1.0.90 → 1.0.94

package/src/tools/ProgrammaticToolCalling.ts

@@ -29,25 +29,25 @@ const DEFAULT_MAX_ROUND_TRIPS = 20;
 const DEFAULT_TIMEOUT = 60000;
 
 // ============================================================================
-// Schema
+// Description Components (Single Source of Truth)
 // ============================================================================
 
-export const ProgrammaticToolCallingSchema = {
-  type: 'object',
-  properties: {
-    code: {
-      type: 'string',
-      minLength: 1,
-      description: `Python code that calls tools programmatically. Tools are available as async functions.
-
-CRITICAL - STATELESS EXECUTION:
+const STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:
 Each call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.
 You MUST complete your entire workflow in ONE code block: query → process → output.
-DO NOT split work across multiple calls expecting to reuse variables.
+DO NOT split work across multiple calls expecting to reuse variables.`;
 
-Your code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.
+const CORE_RULES = `Rules:
+- EVERYTHING in one call—no state persists between executions
+- Just write code with await—auto-wrapped in async context
+- DO NOT define async def main() or call asyncio.run()
+- Tools are pre-defined—DO NOT write function definitions
+- Only print() output returns to the model`;
+
+const ADDITIONAL_RULES = `- Generated files are automatically available in /mnt/data/ for subsequent executions
+- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix`;
 
-Example (Complete workflow in one call):
+const EXAMPLES = `Example (Complete workflow in one call):
   # Query data
   data = await query_database(sql="SELECT * FROM users")
   # Process it
@@ -59,14 +59,29 @@ Example (Complete workflow in one call):
 
 Example (Parallel calls):
   sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
-  print(f"SF: {sf}, NY: {ny}")
+  print(f"SF: {sf}, NY: {ny}")`;
 
-Rules:
-- EVERYTHING in one call—no state persists between executions
-- Just write code with await—auto-wrapped in async context
-- DO NOT define async def main() or call asyncio.run()
-- Tools are pre-defined—DO NOT write function definitions
-- Only print() output returns to the model`,
+// ============================================================================
+// Schema
+// ============================================================================
+
+const CODE_PARAM_DESCRIPTION = `Python code that calls tools programmatically. Tools are available as async functions.
+
+${STATELESS_WARNING}
+
+Your code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.
+
+${EXAMPLES}
+
+${CORE_RULES}`;
+
+export const ProgrammaticToolCallingSchema = {
+  type: 'object',
+  properties: {
+    code: {
+      type: 'string',
+      minLength: 1,
+      description: CODE_PARAM_DESCRIPTION,
     },
     timeout: {
       type: 'integer',
@@ -85,21 +100,14 @@ export const ProgrammaticToolCallingName = Constants.PROGRAMMATIC_TOOL_CALLING;
 export const ProgrammaticToolCallingDescription = `
 Run tools via Python code. Auto-wrapped in async context—just use \`await\` directly.
 
-CRITICAL - STATELESS: Each call is a fresh interpreter. Variables/imports do NOT persist.
-Complete your ENTIRE workflow in ONE call: fetch → process → save. No splitting across calls.
+${STATELESS_WARNING}
 
-Rules:
-- Everything in ONE code block—no state carries over between executions
-- Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
-- Tools are pre-defined—DO NOT write function definitions
-- Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
+${CORE_RULES}
+${ADDITIONAL_RULES}
 
 When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
 
-Example (complete pipeline):
-  data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
+${EXAMPLES}
 `.trim();
 
 export const ProgrammaticToolCallingDefinition = {
@@ -624,26 +632,6 @@ export function createProgrammaticToolCallingTool(
   const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
 
-  const description = `
-Run tools via Python code. Auto-wrapped in async context—just use \`await\` directly.
-
-CRITICAL - STATELESS: Each call is a fresh interpreter. Variables/imports do NOT persist.
-Complete your ENTIRE workflow in ONE call: fetch → process → save. No splitting across calls.
-
-Rules:
-- Everything in ONE code block—no state carries over between executions
-- Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
-- Tools are pre-defined—DO NOT write function definitions
-- Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
-
-When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
-
-Example (complete pipeline):
-  data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
-`.trim();
-
   return tool(
     async (rawParams, config) => {
       const params = rawParams as { code: string; timeout?: number };
@@ -777,7 +765,7 @@ Example (complete pipeline):
     },
     {
       name: Constants.PROGRAMMATIC_TOOL_CALLING,
-      description,
+      description: ProgrammaticToolCallingDescription,
       schema: ProgrammaticToolCallingSchema,
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }

package/src/tools/StreamingToolCallBuffer.js

@@ -0,0 +1,179 @@
+/**
+ * StreamingToolCallBuffer — Accumulates raw tool call argument strings
+ * during streaming, providing a fallback when LangChain's parsePartialJson
+ * loses data (e.g., when max_tokens truncates a tool call mid-JSON).
+ *
+ * Architecture:
+ * - handleToolCallChunks feeds raw arg fragments into this buffer
+ * - When a tool call is finalized (or truncated), the ToolNode can access
+ *   the accumulated raw string and extract field values that parsePartialJson
+ *   may have dropped
+ * - This enables "streaming write" semantics: content that streamed to the UI
+ *   is never lost, even if the JSON wrapper was incomplete
+ *
+ * @example
+ * ```ts
+ * const buffer = new StreamingToolCallBuffer();
+ *
+ * // During streaming (called by handleToolCallChunks):
+ * buffer.append(toolCallId, '{"action":"write","content":"func');
+ * buffer.append(toolCallId, 'tion App() {');
+ * buffer.setToolName(toolCallId, 'content_tool');
+ *
+ * // When ToolNode needs the content:
+ * const content = buffer.extractFieldValue(toolCallId, 'content');
+ * // => 'function App() {'
+ * ```
+ */
+export class StreamingToolCallBuffer {
+    /** Raw accumulated arg strings keyed by tool call ID */
+    argBuffers = new Map();
+    /** Tool names keyed by tool call ID */
+    toolNames = new Map();
+    /**
+     * Maps chunk index → tool call ID for providers (e.g., Bedrock) that send
+     * START chunks with {id, name, index} and DELTA chunks with {args, index} (no id).
+     * Without this mapping, DELTA chunks cannot be associated with the correct buffer entry.
+     */
+    indexToIdMap = new Map();
+    /**
+     * Append a raw argument string chunk for a tool call.
+     * Called during streaming as each ToolCallChunk arrives.
+     */
+    append(toolCallId, argsChunk) {
+        const existing = this.argBuffers.get(toolCallId) ?? '';
+        this.argBuffers.set(toolCallId, existing + argsChunk);
+    }
+    /**
+     * Record the tool name for a tool call ID.
+     * Usually available from the first chunk.
+     */
+    setToolName(toolCallId, name) {
+        if (name && !this.toolNames.has(toolCallId)) {
+            this.toolNames.set(toolCallId, name);
+        }
+    }
+    /**
+     * Get the tool name for a tool call ID.
+     */
+    getToolName(toolCallId) {
+        return this.toolNames.get(toolCallId);
+    }
+    /**
+     * Get the raw accumulated argument string for a tool call.
+     */
+    getRawArgs(toolCallId) {
+        return this.argBuffers.get(toolCallId);
+    }
+    /**
+     * Extract a string field value from the raw accumulated JSON args.
+     *
+     * Uses simple string parsing (not JSON.parse) to handle truncated JSON.
+     * Finds `"fieldName":"` and extracts everything after it until the next
+     * unescaped quote or end of buffer.
+     *
+     * @param toolCallId - The tool call ID
+     * @param fieldName - The JSON field name to extract (e.g., 'content')
+     * @returns The extracted value, or undefined if the field wasn't found
+     */
+    extractFieldValue(toolCallId, fieldName) {
+        const raw = this.argBuffers.get(toolCallId);
+        if (!raw)
+            return undefined;
+        // Find the field key in the JSON string: "fieldName":"
+        // Handle both `"fieldName":"value"` and `"fieldName": "value"` (with space)
+        const patterns = [
+            `"${fieldName}":"`,
+            `"${fieldName}": "`,
+            `"${fieldName}" : "`,
+        ];
+        let startIdx = -1;
+        for (const pattern of patterns) {
+            const idx = raw.indexOf(pattern);
+            if (idx !== -1) {
+                startIdx = idx + pattern.length;
+                break;
+            }
+        }
+        if (startIdx === -1)
+            return undefined;
+        // Extract the value — handle escaped characters
+        let value = '';
+        let escaped = false;
+        for (let i = startIdx; i < raw.length; i++) {
+            const ch = raw[i];
+            if (escaped) {
+                // Handle common escape sequences
+                switch (ch) {
+                    case 'n':
+                        value += '\n';
+                        break;
+                    case 't':
+                        value += '\t';
+                        break;
+                    case 'r':
+                        value += '\r';
+                        break;
+                    case '"':
+                        value += '"';
+                        break;
+                    case '\\':
+                        value += '\\';
+                        break;
+                    default:
+                        value += ch;
+                        break;
+                }
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                // End of the string value
+                break;
+            }
+            value += ch;
+        }
+        return value || undefined;
+    }
+    /**
+     * Store an index → tool call ID mapping.
+     * Called when a START chunk arrives with both `id` and `index` (e.g., Bedrock).
+     * Subsequent DELTA chunks that only have `index` can resolve the ID via getIdByIndex.
+     */
+    setIndexMapping(index, toolCallId) {
+        this.indexToIdMap.set(index, toolCallId);
+    }
+    /**
+     * Resolve a tool call ID from a chunk index.
+     * Returns undefined if no mapping exists (e.g., provider sends id on every chunk).
+     */
+    getIdByIndex(index) {
+        return this.indexToIdMap.get(index);
+    }
+    /**
+     * Check if a tool call has accumulated content.
+     */
+    has(toolCallId) {
+        return this.argBuffers.has(toolCallId);
+    }
+    /**
+     * Clear the buffer for a specific tool call (after processing).
+     */
+    clear(toolCallId) {
+        this.argBuffers.delete(toolCallId);
+        this.toolNames.delete(toolCallId);
+    }
+    /**
+     * Clear all buffers (at the start of a new callModel cycle).
+     */
+    clearAll() {
+        this.argBuffers.clear();
+        this.toolNames.clear();
+        this.indexToIdMap.clear();
+    }
+}
+//# sourceMappingURL=StreamingToolCallBuffer.js.map

package/src/tools/StreamingToolCallBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingToolCallBuffer.js","sourceRoot":"","sources":["StreamingToolCallBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,OAAO,uBAAuB;IAClC,wDAAwD;IAChD,UAAU,GAAwB,IAAI,GAAG,EAAE,CAAC;IACpD,uCAAuC;IAC/B,SAAS,GAAwB,IAAI,GAAG,EAAE,CAAC;IACnD;;;;OAIG;IACK,YAAY,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEtD;;;OAGG;IACH,MAAM,CAAC,UAAkB,EAAE,SAAiB;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACvD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IACxD,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,UAAkB,EAAE,IAAY;QAC1C,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,UAAkB;QAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,UAAkB;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,UAAkB,EAAE,SAAiB;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAE3B,uDAAuD;QACvD,4EAA4E;QAC5E,MAAM,QAAQ,GAAG;YACf,IAAI,SAAS,KAAK;YAClB,IAAI,SAAS,MAAM;YACnB,IAAI,SAAS,OAAO;SACrB,CAAC;QAEF,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;QAClB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACjC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,QAAQ,GAAG,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;gBAChC,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QAEtC,gDAAgD;QAChD,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YAClB,IAAI,OAAO,EAAE,CAAC;gBACZ,iCAAiC;gBACjC,QAAQ,EAAE,EAAE,CAAC;oBACX,KAAK,GAAG;wBAAE,KAAK,IAAI,IAAI,CAAC;wBAAC,MAAM;oBAC/B,KAAK,GAAG;wBAAE,KAAK,IAAI,IAAI,CAAC;wBAAC,MAAM;oBAC/B,KAAK,GAAG;wBAAE,KAAK,IAAI,IAAI,CAAC;wBAAC,MAAM;oBAC/B,KAAK,GAAG;wBAAE,KAAK,IAAI,GAAG,CAAC;wBAAC,MAAM;oBAC9B,KAAK,IAAI;wBAAE,KAAK,IAAI,IAAI,CAAC;wBAAC,MAAM;oBAChC;wBAAS,KAAK,IAAI,EAAE,CAAC;wBAAC,MAAM;gBAC9B,CAAC;gBACD,OAAO,GAAG,KAAK,CAAC;gBAChB,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChB,OAAO,GAAG,IAAI,CAAC;gBACf,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,0BAA0B;gBAC1B,MAAM;YACR,CAAC;YACD,KAAK,IAAI,EAAE,CAAC;QACd,CAAC;QAED,OAAO,KAAK,IAAI,SAAS,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,KAAa,EAAE,UAAkB;QAC/C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,KAAa;QACxB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAkB;QACtB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/src/tools/StreamingToolCallBuffer.ts

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