@sisu-ai/mw-tool-calling 11.0.0 → 12.0.0

package/README.md

@@ -1,6 +1,10 @@
 # @sisu-ai/mw-tool-calling
 
-Execute provider-native tool call loops with robust iteration, validation, and tool result handling.
+Legacy compatibility middleware for provider-native tool call loops.
+
+> **Recommended for new code:** use core execution middleware from `@sisu-ai/core`:
+> - `execute` / `executeWith(opts)` for non-streaming
+> - `executeStream` (optionally as `executeStream(opts)`) for streaming
 
 [![Tests](https://github.com/finger-gun/sisu/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/finger-gun/sisu/actions/workflows/tests.yml)
 [![CodeQL](https://github.com/finger-gun/sisu/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/finger-gun/sisu/actions/workflows/github-code-scanning/codeql)
@@ -14,7 +18,7 @@ npm i @sisu-ai/mw-tool-calling
 ```
 
 ## Behavior
-- `toolCalling`: single-round tool calling.
+- `toolCalling`: single-round compatibility mode.
   - 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`.
@@ -46,7 +50,7 @@ sequenceDiagram
   end
 
 ```
-- `iterativeToolCalling`: multi-round tool calling.
+- `iterativeToolCalling`: multi-round compatibility mode.
   - Repeats calls with `toolChoice:'auto'` until the model returns a message with no `tool_calls` (max 12 iters).
 
 ```mermaid
@@ -88,6 +92,22 @@ agent.use(toolCalling);
 agent.use(iterativeToolCalling);
 ```
 
+## Migration to Core Execution APIs
+
+```ts
+import { Agent, execute, getExecutionResult } from '@sisu-ai/core';
+import { registerTools } from '@sisu-ai/mw-register-tools';
+import { inputToMessage } from '@sisu-ai/mw-conversation-buffer';
+
+const app = new Agent()
+  .use(registerTools([myTool]))
+  .use(inputToMessage)
+  .use(execute);
+
+await app.handler()(ctx); // primary path
+console.log(getExecutionResult(ctx)?.text);
+```
+
 ## Tool Execution Records
 
 Each executed tool call is appended to `ctx.state.toolExecutions`:

package/dist/index.d.ts

@@ -1,3 +1,20 @@
 import type { Middleware } from "@sisu-ai/core";
+/**
+ * Legacy compatibility middleware.
+ *
+ * @deprecated Prefer core execution middleware from `@sisu-ai/core`:
+ * - `.use(execute)` or `.use(executeWith(opts))`
+ * - `.use(executeStream)` or `.use(executeStream(opts))`
+ *
+ * Migration guide: https://github.com/finger-gun/sisu/tree/main/packages/core#execution-apis-recommended
+ */
 export declare const toolCalling: Middleware;
+/**
+ * Legacy compatibility middleware.
+ *
+ * @deprecated Prefer `.use(execute)` (iterative by default) or
+ * `.use(executeWith({ strategy: "iterative" }))` from `@sisu-ai/core`.
+ *
+ * Migration guide: https://github.com/finger-gun/sisu/tree/main/packages/core#execution-apis-recommended
+ */
 export declare const iterativeToolCalling: Middleware;

package/dist/index.js

@@ -1,297 +1,24 @@
-function pushToolExecution(ctx, record) {
-    const existing = ctx.state.toolExecutions;
-    if (Array.isArray(existing)) {
-        existing.push(record);
-        return;
-    }
-    ctx.state.toolExecutions = [record];
-}
+import { executeWith } from "@sisu-ai/core";
 /**
- * Apply user-configured aliases to tools before passing to adapter.
- * Creates new tool objects with aliased names while keeping originals in registry.
+ * Legacy compatibility middleware.
+ *
+ * @deprecated Prefer core execution middleware from `@sisu-ai/core`:
+ * - `.use(execute)` or `.use(executeWith(opts))`
+ * - `.use(executeStream)` or `.use(executeStream(opts))`
+ *
+ * Migration guide: https://github.com/finger-gun/sisu/tree/main/packages/core#execution-apis-recommended
  */
-function applyAliasesToTools(tools, aliasMap) {
-    if (!aliasMap || aliasMap.size === 0) {
-        // No aliases configured - return tools as-is with identity map
-        const reverseMap = new Map();
-        for (const tool of tools) {
-            reverseMap.set(tool.name, tool.name);
-        }
-        return { aliasedTools: tools, reverseMap };
-    }
-    const aliasedTools = [];
-    const reverseMap = new Map();
-    for (const tool of tools) {
-        const alias = aliasMap.get(tool.name);
-        if (alias) {
-            // Create new tool object with aliased name
-            const aliasedTool = { ...tool, name: alias };
-            aliasedTools.push(aliasedTool);
-            reverseMap.set(alias, tool.name); // alias -> canonical
-        }
-        else {
-            // No alias for this tool - use as-is
-            aliasedTools.push(tool);
-            reverseMap.set(tool.name, tool.name); // identity mapping
-        }
-    }
-    return { aliasedTools, reverseMap };
-}
-function hasParseSchema(schema) {
-    if (!schema || typeof schema !== "object") {
-        return false;
-    }
-    const maybeSchema = schema;
-    return typeof maybeSchema.parse === "function";
-}
-function normalizeToolArguments(args) {
-    if (typeof args !== "string") {
-        return args;
-    }
-    let current = args;
-    for (let i = 0; i < 2; i++) {
-        if (typeof current !== "string") {
-            return current;
-        }
-        const trimmed = current.trim();
-        if (!trimmed) {
-            return args;
-        }
-        try {
-            current = JSON.parse(trimmed);
-        }
-        catch {
-            return current;
-        }
-    }
-    return current;
-}
 export const toolCalling = async (ctx, next) => {
-    await next();
-    const toolList = ctx.tools.list();
-    const userAliases = ctx.state.toolAliases;
-    const { aliasedTools, reverseMap } = applyAliasesToTools(toolList, userAliases);
-    for (let i = 0; i < 6; i++) {
-        ctx.log.debug?.("[tool-calling] iteration start", {
-            i,
-            messages: ctx.messages.length,
-        });
-        const allowTools = i === 0 ? "auto" : "none";
-        const genOpts = {
-            toolChoice: allowTools,
-            signal: ctx.signal,
-        };
-        if (allowTools !== "none") {
-            genOpts.tools = aliasedTools; // Pass renamed tools to adapter
-            genOpts.parallelToolCalls = false;
-        }
-        const out = await ctx.model.generate(ctx.messages, genOpts);
-        if (!out || typeof out !== "object" || !("message" in out)) {
-            throw new Error("[tool-calling] model did not return a message");
-        }
-        const msg = out.message;
-        const toolCalls = msg.tool_calls;
-        if (toolCalls && toolCalls.length > 0) {
-            // Important: include the assistant message that requested tools so tool_call_id has a valid anchor.
-            ctx.messages.push(msg);
-            ctx.log.info?.("[tool-calling] model requested tools", toolCalls.map((tc) => ({
-                id: tc.id,
-                name: tc.name,
-                hasArgs: typeof tc.arguments !== "undefined",
-            })));
-            // Execute each unique (name,args) once, but reply to every tool_call_id.
-            const cache = new Map();
-            const keyOf = (tc) => `${tc.name}:${safeStableStringify(tc.arguments)}`;
-            const lastArgsByName = new Map();
-            // Pre-pass: fill missing arguments from last seen arguments of same tool name (provider quirk)
-            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) {
-                // Resolve alias back to canonical tool name
-                const canonicalName = reverseMap.get(call.name);
-                if (!canonicalName)
-                    throw new Error("Unknown tool: " + call.name);
-                const tool = ctx.tools.get(canonicalName);
-                if (!tool)
-                    throw new Error("Unknown tool: " + canonicalName);
-                const key = keyOf(call);
-                let result = cache.get(key);
-                if (result === undefined) {
-                    const schema = tool.schema;
-                    const normalizedArgs = normalizeToolArguments(call.arguments);
-                    const args = hasParseSchema(schema)
-                        ? schema.parse(normalizedArgs)
-                        : normalizedArgs;
-                    ctx.log.debug?.("[tool-calling] invoking tool", {
-                        aliasName: call.name,
-                        canonicalName: canonicalName,
-                        id: call.id,
-                        args,
-                    });
-                    // Create restricted context for tool execution
-                    const toolCtx = {
-                        memory: ctx.memory,
-                        signal: ctx.signal,
-                        log: ctx.log,
-                        model: ctx.model,
-                        // Pass deps from state for dependency injection (testing/configuration)
-                        deps: ctx.state?.toolDeps,
-                    };
-                    result = await tool.handler(args, toolCtx);
-                    cache.set(key, result);
-                    lastArgsByName.set(call.name, args);
-                }
-                else {
-                    ctx.log.debug?.("[tool-calling] reusing cached tool result for duplicate call", { name: call.name, id: call.id });
-                }
-                // Prefer tool_call_id when available (tools API)
-                const toolMsg = {
-                    role: "tool",
-                    content: JSON.stringify(result),
-                    ...(call.id ? { tool_call_id: call.id } : { name: call.name }),
-                };
-                ctx.messages.push(toolMsg);
-                pushToolExecution(ctx, {
-                    aliasName: call.name,
-                    canonicalName,
-                    callId: call.id,
-                    args: lastArgsByName.get(call.name),
-                    result,
-                });
-                ctx.log.debug?.("[tool-calling] tool result appended", {
-                    name: call.name,
-                    id: call.id,
-                    contentBytes: toolMsg.content.length,
-                });
-            }
-            continue;
-        }
-        else {
-            ctx.log.info?.("[tool-calling] no tool calls; appending assistant message");
-            ctx.messages.push(msg);
-            break;
-        }
-    }
+    await executeWith({ strategy: "single", maxRounds: 6 })(ctx, next);
 };
+/**
+ * Legacy compatibility middleware.
+ *
+ * @deprecated Prefer `.use(execute)` (iterative by default) or
+ * `.use(executeWith({ strategy: "iterative" }))` from `@sisu-ai/core`.
+ *
+ * Migration guide: https://github.com/finger-gun/sisu/tree/main/packages/core#execution-apis-recommended
+ */
 export const iterativeToolCalling = async (ctx, next) => {
-    await next();
-    const maxIters = 12;
-    const toolList = ctx.tools.list();
-    const userAliases = ctx.state.toolAliases;
-    const { aliasedTools, reverseMap } = applyAliasesToTools(toolList, userAliases);
-    for (let i = 0; i < maxIters; i++) {
-        ctx.log.debug?.("[iterative-tool-calling] iteration start", {
-            i,
-            messages: ctx.messages.length,
-        });
-        const genOpts = {
-            toolChoice: "auto",
-            tools: aliasedTools, // Pass renamed tools to adapter
-            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) {
-                // Resolve alias back to canonical tool name
-                const canonicalName = reverseMap.get(call.name);
-                if (!canonicalName)
-                    throw new Error("Unknown tool: " + call.name);
-                const tool = ctx.tools.get(canonicalName);
-                if (!tool)
-                    throw new Error("Unknown tool: " + canonicalName);
-                const key = keyOf(call);
-                let result = cache.get(key);
-                if (result === undefined) {
-                    const schema = tool.schema;
-                    const normalizedArgs = normalizeToolArguments(call.arguments);
-                    const args = hasParseSchema(schema)
-                        ? schema.parse(normalizedArgs)
-                        : normalizedArgs;
-                    ctx.log.debug?.("[iterative-tool-calling] invoking tool", {
-                        aliasName: call.name,
-                        canonicalName: canonicalName,
-                        id: call.id,
-                        args,
-                    });
-                    // Create restricted context for tool execution
-                    const toolCtx = {
-                        memory: ctx.memory,
-                        signal: ctx.signal,
-                        log: ctx.log,
-                        model: ctx.model,
-                        // Pass deps from state for dependency injection (testing/configuration)
-                        deps: ctx.state?.toolDeps,
-                    };
-                    result = await tool.handler(args, toolCtx);
-                    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),
-                    ...(call.id ? { tool_call_id: call.id } : { name: call.name }),
-                };
-                ctx.messages.push(toolMsg);
-                pushToolExecution(ctx, {
-                    aliasName: call.name,
-                    canonicalName,
-                    callId: call.id,
-                    args: lastArgsByName.get(call.name),
-                    result,
-                });
-            }
-            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;
-        }
-    }
+    await executeWith({ strategy: "iterative", maxRounds: 12 })(ctx, next);
 };
-function safeStableStringify(v) {
-    try {
-        if (v && typeof v === "object" && !Array.isArray(v)) {
-            const keys = Object.keys(v).sort();
-            const obj = {};
-            for (const k of keys)
-                obj[k] = v[k];
-            return JSON.stringify(obj);
-        }
-        return JSON.stringify(v);
-    }
-    catch {
-        return String(v);
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/mw-tool-calling",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@sisu-ai/core": "^2.5.0"
+    "@sisu-ai/core": "^2.6.0"
+  },
+  "devDependencies": {
+    "@sisu-ai/core": "2.6.0",
+    "@sisu-ai/mw-register-tools": "12.0.0"
   },
   "repository": {
     "type": "git",