@sisu-ai/mw-tool-calling 2.0.0 → 3.0.0

package/README.md

@@ -11,16 +11,76 @@ npm i @sisu-ai/mw-tool-calling
 Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu
 
 ## Behavior
-- First turn: calls `ctx.model.generate(messages, { tools, toolChoice:'auto' })`.
-- If assistant returns `tool_calls`, appends the assistant message and executes each tool.
-  - Executes each unique `(name, args)` once and responds to every `tool_call_id`.
-  - Handles provider quirks (e.g., missing args on duplicates) by reusing last args.
-- Second turn: asks for a pure completion (`toolChoice:'none'`).
+- `toolCalling`: single-round tool calling.
+  - First turn: calls `ctx.model.generate(messages, { tools, toolChoice:'auto' })`.
+  - If assistant returns `tool_calls`, appends the assistant message and executes each tool.
+    - Executes each unique `(name, args)` once and responds to every `tool_call_id`.
+    - Handles provider quirks by reusing last args for identical tool names with missing args.
+  - Second turn: asks for a pure completion (`toolChoice:'none'`).
+```mermaid
+sequenceDiagram
+  autonumber
+  participant A as Agent toolCalling
+  participant M as Model Adapter
+  participant R as Tools Registry
+  participant H as Tool Handler
+
+  A->>R: list
+  R-->>A: tools
+  A->>M: generate with tools auto
+  alt tool calls
+    M-->>A: assistant with tool calls
+    loop each unique name args
+      A->>R: resolve and validate
+      R-->>A: handler
+      A->>H: execute
+      H-->>A: append tool message
+    end
+    A->>M: generate finalize none
+    M-->>A: assistant completion
+  else no tool calls
+    M-->>A: assistant completion
+  end
+
+```
+- `iterativeToolCalling`: multi-round tool calling.
+  - Repeats calls with `toolChoice:'auto'` until the model returns a message with no `tool_calls` (max 12 iters).
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant A as Agent iterativeToolCalling
+  participant M as Model Adapter
+  participant R as Tools Registry
+  participant H as Tool Handler
+
+  A->>R: list
+  R-->>A: tools
+  loop max twelve iterations until no tool calls
+    A->>M: generate with tools auto
+    alt tool calls present
+      M-->>A: assistant with tool calls
+      loop each unique name args
+        A->>R: resolve and validate
+        R-->>A: handler
+        A->>H: execute
+        H-->>A: append tool message
+      end
+    else no tool calls
+      M-->>A: assistant no tools
+    end
+  end
+  A->>M: generate finalize none
+  M-->>A: assistant completion
+```
 
 ## Usage
 ```ts
-import { toolCalling } from '@sisu-ai/mw-tool-calling';
+import { toolCalling, iterativeToolCalling } from '@sisu-ai/mw-tool-calling';
+
+// Single-round
+agent.use(toolCalling);
 
-const app = new Agent()
-  .use(toolCalling);
+// OR multi-round
+agent.use(iterativeToolCalling);
 ```

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 import type { Middleware } from '@sisu-ai/core';
 export declare const toolCalling: Middleware;
+export declare const iterativeToolCalling: Middleware;

package/dist/index.js

@@ -61,6 +61,61 @@ export const toolCalling = async (ctx, next) => {
         }
     }
 };
+export const iterativeToolCalling = async (ctx, next) => {
+    await next();
+    const maxIters = 12;
+    for (let i = 0; i < maxIters; i++) {
+        ctx.log.debug?.('[iterative-tool-calling] iteration start', { i, messages: ctx.messages.length });
+        const toolList = ctx.tools.list();
+        const genOpts = { toolChoice: 'auto', tools: toolList, parallelToolCalls: false, signal: ctx.signal };
+        const out = await ctx.model.generate(ctx.messages, genOpts);
+        const msg = out.message;
+        const toolCalls = msg.tool_calls;
+        if (toolCalls && toolCalls.length > 0) {
+            // include the assistant message that requested tools
+            ctx.messages.push(msg);
+            ctx.log.info?.('[iterative-tool-calling] model requested tools', toolCalls.map(tc => ({ id: tc.id, name: tc.name, hasArgs: typeof tc.arguments !== 'undefined' })));
+            const cache = new Map();
+            const keyOf = (tc) => `${tc.name}:${safeStableStringify(tc.arguments)}`;
+            const lastArgsByName = new Map();
+            const resolvedCalls = toolCalls.map((tc) => {
+                if (typeof tc.arguments === 'undefined' && lastArgsByName.has(tc.name)) {
+                    return { ...tc, arguments: lastArgsByName.get(tc.name) };
+                }
+                return tc;
+            });
+            for (const call of resolvedCalls) {
+                const tool = ctx.tools.get(call.name);
+                if (!tool)
+                    throw new Error('Unknown tool: ' + call.name);
+                const key = keyOf(call);
+                let result = cache.get(key);
+                if (result === undefined) {
+                    const args = tool.schema?.parse ? tool.schema.parse(call.arguments) : call.arguments;
+                    ctx.log.debug?.('[iterative-tool-calling] invoking tool', { name: call.name, id: call.id, args });
+                    result = await tool.handler(args, ctx);
+                    cache.set(key, result);
+                    lastArgsByName.set(call.name, args);
+                }
+                else {
+                    ctx.log.debug?.('[iterative-tool-calling] reusing cached result', { name: call.name, id: call.id });
+                }
+                const toolMsg = { role: 'tool', content: JSON.stringify(result) };
+                if (call.id)
+                    toolMsg.tool_call_id = call.id;
+                else
+                    toolMsg.name = call.name;
+                ctx.messages.push(toolMsg);
+            }
+            continue; // next round may call more tools
+        }
+        else {
+            ctx.log.info?.('[iterative-tool-calling] no tool calls; appending assistant message');
+            ctx.messages.push(msg);
+            break;
+        }
+    }
+};
 function safeStableStringify(v) {
     try {
         if (v && typeof v === 'object' && !Array.isArray(v)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/mw-tool-calling",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
     "build": "tsc -b"
   },
   "peerDependencies": {
-    "@sisu-ai/core": "0.3.0"
+    "@sisu-ai/core": "1.0.0"
   },
   "repository": {
     "type": "git",