@ai-zen/agents-sdk 0.5.6 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.6.0] - 2026-08-14
+
+### ⚠️ Breaking
+
+- **`SdkCallbackTool` constructor no longer takes `function` — construction is now `super({ env })` only** — the tool definition (`function`) is declared by each tool as a **class-body field**, colocated with its `call` implementation. The constructor now takes an options container (`SdkCallbackToolOptions`, currently containing `env` as its core field and open to future extension). Any custom tool previously writing `super({ function, env })` must move its `function` definition into a class-body field and call `super({ env })`. `SdkCallbackToolOptions` is exported for external consumers
+- **`SdkCallbackTool.call` now forwards the full `ToolCallContext`** — `call(input)` becomes `call(input, ctx?)`. Concrete tools may read the second argument (e.g. `ctx?.signal`) for abort support. This is additive (optional argument), so existing single-argument `call`s keep compiling
+- **`@ai-zen/agents-core` upgraded to 3.4.0** — the `Tool` base class no longer requires passing `function`/`type` via its constructor; `CallbackTool` / `AgentToolLazy.buildAgent` no longer use `this`-injection and now receive `(parsed_args, ctx)`. SDK callbacks that previously read `this.agent` now read `ctx.agent` instead (`call_skill_sub_agent` in skillTools, `buildAgent` in subAgentTools)
+
+### 🛠 Optimized
+
+- **All 18 built-in tools now declare their `function` definition as a class-body field** — the definition lives next to the `call` implementation (single source of truth), instead of being passed separately through the constructor
+- Aligned SDK tool context access with core's explicit `(parsed_args, ctx)` convention
+- **Per-tool abort signal support** — high-value tools now honor interruption via `ctx?.signal`:
+  - **`sleep`** — listening for abort on the wait timer, returning early so a long wait is interrupted instead of blocking
+  - **`exec`** — killing the child process on abort (marking `terminated: "aborted"` distinct from `"timeout"`), with a fallback to avoid hanging if the signal kills the shell
+  - **`downloadFile`** — passing the signal to `fetch`, and cleaning up any partially-written file on abort
+  - **`generateImage`** — passing the signal to the image-model request (the underlying `fetch` already supports it), returning an aborted result on interruption
+  - **`glob` / `findText`** — checking `ctx.signal` during directory-tree traversal (and after each file read), stopping the scan early and returning the partial results with an `aborted` flag when interrupted
+- **MCP tool signal forwarding** — `call_mcp_tool` and `read_mcp_resource` now forward `ctx.signal` into the underlying MCP SDK `callTool` / `readResource` request options, so a remote call can be interrupted
+- **Sub-agent abort linkage** — sub-agent tools (`AgentTool`, `AgentToolLazy`; used by `createSubAgentTool` and `call_skill_sub_agent`) now listen for the outer `ctx.signal` and call `agent.abort()` on the child agent, so a long-running sub-agent is stopped when the parent call is aborted
+
+### ✅ Tests
+
+- Updated `SdkCallbackTool` / `capabilities` tests for the new `function` assignment and `super({ env })` construction; added a test asserting `SdkCallbackTool.call` receives the forwarded `ToolCallContext`
+- **Added abort tests** for `sleep` (early return + immediate abort), `exec` (child killed + `terminated: "aborted"`), `downloadFile` (abort cleanup of the partial file), `generateImage` (aborted result), `glob`/`findText` (early scan stop), plus MCP `callTool`/`readResource` signal forwarding and sub-agent abort linkage. SDK suite now at **435 passed**, **3 skipped**; core at **198 passed**, **17 skipped**
+
+## [0.5.7] - 2026-08-13
+
+### 🛠 Optimized
+
+- **`@ai-zen/agents-core` dependency upgraded to 3.3.1** — dual-set inner-loop task semantics + unified Assistant placeholder at inner-loop start; SDK 426 tests (incl. real DeepSeek e2e) all pass, fully compatible
+
 ## [0.5.6] - 2026-08-14
 
 ### 🚀 New Features

package/dist/capabilities/implements/builtin/BatchEditTool.d.ts

@@ -1,11 +1,13 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 interface Replacement {
     oldText: string;
     newText: string;
     isReplaceAll?: boolean;
 }
 export declare class BatchEditTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path: string;

package/dist/capabilities/implements/builtin/BatchEditTool.js

@@ -1,49 +1,47 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "batchEdit",
-                description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "文件路径",
-                        },
-                        replacements: {
-                            type: "array",
-                            description: "要替换的文本数组",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    oldText: {
-                                        type: "string",
-                                        description: "要替换的文本",
-                                    },
-                                    newText: {
-                                        type: "string",
-                                        description: "替换后的文本",
-                                    },
-                                    isReplaceAll: {
-                                        type: "boolean",
-                                        description: "是否替换所有匹配的文本（默认仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
-                                        default: false,
-                                    },
-                                },
-                                required: ["oldText", "newText"],
-                                additionalProperties: false,
+    function = {
+        name: "batchEdit",
+        description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                replacements: {
+                    type: "array",
+                    description: "要替换的文本数组",
+                    items: {
+                        type: "object",
+                        properties: {
+                            oldText: {
+                                type: "string",
+                                description: "要替换的文本",
+                            },
+                            newText: {
+                                type: "string",
+                                description: "替换后的文本",
+                            },
+                            isReplaceAll: {
+                                type: "boolean",
+                                description: "是否替换所有匹配的文本（默认仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                                default: false,
                             },
                         },
+                        required: ["oldText", "newText"],
+                        additionalProperties: false,
                     },
-                    required: ["path", "replacements"],
-                    additionalProperties: false,
                 },
             },
-            env,
-        });
+            required: ["path", "replacements"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         try {

package/dist/capabilities/implements/builtin/CopyTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class CopyTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         src: string;

package/dist/capabilities/implements/builtin/CopyTool.js

@@ -1,33 +1,31 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class CopyTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "copy",
-                description: "复制文件或目录（相当于 cp 命令）",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        src: {
-                            type: "string",
-                            description: "源路径",
-                        },
-                        dest: {
-                            type: "string",
-                            description: "目标路径",
-                        },
-                        recursive: {
-                            type: "boolean",
-                            description: "是否递归复制目录，复制目录时需设为 true",
-                        },
-                    },
-                    required: ["src", "dest"],
-                    additionalProperties: false,
+    function = {
+        name: "copy",
+        description: "复制文件或目录（相当于 cp 命令）",
+        parameters: {
+            type: "object",
+            properties: {
+                src: {
+                    type: "string",
+                    description: "源路径",
+                },
+                dest: {
+                    type: "string",
+                    description: "目标路径",
+                },
+                recursive: {
+                    type: "boolean",
+                    description: "是否递归复制目录，复制目录时需设为 true",
                 },
             },
-            env,
-        });
+            required: ["src", "dest"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         try {

package/dist/capabilities/implements/builtin/CwdTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class CwdTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(): string;
 }

package/dist/capabilities/implements/builtin/CwdTool.js

@@ -1,18 +1,16 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class CwdTool extends SdkCallbackTool {
+    function = {
+        name: "cwd",
+        description: "获取当前工作目录 cwd",
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    };
     constructor(env) {
-        super({
-            function: {
-                name: "cwd",
-                description: "获取当前工作目录 cwd",
-                parameters: {
-                    type: "object",
-                    properties: {},
-                    required: [],
-                },
-            },
-            env,
-        });
+        super({ env });
     }
     call() {
         return this.env.cwd;

package/dist/capabilities/implements/builtin/DownloadFileTool.d.ts

@@ -1,9 +1,11 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class DownloadFileTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         url: string;
         outputPath?: string;
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/DownloadFileTool.js

@@ -2,36 +2,35 @@ import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class DownloadFileTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "downloadFile",
-                description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        url: {
-                            type: "string",
-                            description: "文件下载链接",
-                        },
-                        outputPath: {
-                            type: "string",
-                            description: "保存路径（可选）。可以是目录或完整文件路径。不指定则下载到当前工作目录，自动从 URL 推断文件名。",
-                        },
-                    },
-                    required: ["url"],
-                    additionalProperties: false,
+    function = {
+        name: "downloadFile",
+        description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
+        parameters: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "文件下载链接",
+                },
+                outputPath: {
+                    type: "string",
+                    description: "保存路径（可选）。可以是目录或完整文件路径。不指定则下载到当前工作目录，自动从 URL 推断文件名。",
                 },
             },
-            env,
-        });
+            required: ["url"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
+        const signal = ctx?.signal;
+        let savePath;
         try {
             const url = input.url;
             if (!url)
                 throw new Error("url 不能为空");
-            let savePath;
             if (input.outputPath) {
                 savePath = this.resolve(input.outputPath);
                 const stat = await fsp.stat(savePath).catch(() => null);
@@ -47,7 +46,7 @@ export class DownloadFileTool extends SdkCallbackTool {
                 savePath = path.join(this.env.cwd, fileName);
             }
             await fsp.mkdir(path.dirname(savePath), { recursive: true });
-            const response = await fetch(url);
+            const response = await fetch(url, { signal });
             if (!response.ok) {
                 throw new Error(`下载失败: HTTP ${response.status} ${response.statusText}`);
             }
@@ -66,6 +65,15 @@ export class DownloadFileTool extends SdkCallbackTool {
             });
         }
         catch (error) {
+            // 中断（abort）时清理可能残留的半成品文件
+            if (signal?.aborted && savePath) {
+                await fsp.rm(savePath, { force: true }).catch(() => { });
+                return JSON.stringify({
+                    success: false,
+                    aborted: true,
+                    error: "下载被中断（aborted）",
+                });
+            }
             return JSON.stringify({
                 success: false,
                 error: error?.message || "下载失败",

package/dist/capabilities/implements/builtin/EditTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class EditTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path: string;

package/dist/capabilities/implements/builtin/EditTool.js

@@ -13,38 +13,36 @@ function countOccurrences(content, text) {
     return count;
 }
 export class EditTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "edit",
-                description: "编辑文件中的文本，支持精确替换或替换所有匹配项",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "文件路径",
-                        },
-                        oldText: {
-                            type: "string",
-                            description: "要替换的文本",
-                        },
-                        newText: {
-                            type: "string",
-                            description: "替换后的文本",
-                        },
-                        isReplaceAll: {
-                            type: "boolean",
-                            description: "是否替换所有匹配的文本（默认 false，仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
-                            default: false,
-                        },
-                    },
-                    required: ["path", "oldText", "newText"],
-                    additionalProperties: false,
+    function = {
+        name: "edit",
+        description: "编辑文件中的文本，支持精确替换或替换所有匹配项",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                oldText: {
+                    type: "string",
+                    description: "要替换的文本",
+                },
+                newText: {
+                    type: "string",
+                    description: "替换后的文本",
+                },
+                isReplaceAll: {
+                    type: "boolean",
+                    description: "是否替换所有匹配的文本（默认 false，仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                    default: false,
                 },
             },
-            env,
-        });
+            required: ["path", "oldText", "newText"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         try {

package/dist/capabilities/implements/builtin/ExecAsyncTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ExecAsyncTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         command: string;

package/dist/capabilities/implements/builtin/ExecAsyncTool.js

@@ -1,33 +1,31 @@
 import { spawn } from "child_process";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class ExecAsyncTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "exec_async",
-                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            description: "要执行的命令（含参数）",
-                        },
-                        cwd: {
-                            type: "string",
-                            description: "工作目录（可选，默认当前工作目录）",
-                        },
-                        detached: {
-                            type: "boolean",
-                            description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
-                        },
-                    },
-                    required: ["command"],
-                    additionalProperties: false,
+    function = {
+        name: "exec_async",
+        description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "要执行的命令（含参数）",
+                },
+                cwd: {
+                    type: "string",
+                    description: "工作目录（可选，默认当前工作目录）",
+                },
+                detached: {
+                    type: "boolean",
+                    description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
                 },
             },
-            env,
-        });
+            required: ["command"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         const command = input.command;

package/dist/capabilities/implements/builtin/ExecTool.d.ts

@@ -1,9 +1,11 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class ExecTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         command: string;
         timeout: number;
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/ExecTool.js

@@ -1,52 +1,85 @@
 import { exec } from "child_process";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class ExecTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "exec",
-                description: "执行命令",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            description: "要执行的命令",
-                        },
-                        timeout: {
-                            type: "number",
-                            description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
-                        },
-                    },
-                    required: ["command", "timeout"],
-                    additionalProperties: false,
+    function = {
+        name: "exec",
+        description: "执行命令",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "要执行的命令",
+                },
+                timeout: {
+                    type: "number",
+                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
                 },
             },
-            env,
-        });
+            required: ["command", "timeout"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
         const command = input.command;
         const { timeout } = input;
         // 运行时双校验：timeout 必填且必须为正数
         if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
             throw new Error(`exec: 参数 timeout 为必填项，且必须是正数（毫秒），当前值: ${JSON.stringify(timeout)}`);
         }
+        const signal = ctx?.signal;
         const result = await new Promise((resolve) => {
-            const child = exec(command, {
-                cwd: this.env.cwd,
-                timeout,
-            }, (error, stdout, stderr) => {
-                const killed = error?.killed ?? false;
+            // 若 signal 已处于 aborted，直接标记中断结果
+            if (signal?.aborted) {
                 resolve({
+                    stdout: "",
+                    stderr: "进程已中断（aborted）",
+                    exitCode: null,
+                    killed: true,
+                    terminated: "aborted",
+                });
+                return;
+            }
+            let child;
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                resolve(value);
+            };
+            child = exec(command, { cwd: this.env.cwd, timeout }, (error, stdout, stderr) => {
+                const killed = error?.killed ?? false;
+                const terminated = killed
+                    ? (signal?.aborted ? "aborted" : "timeout")
+                    : undefined;
+                settle({
                     stdout,
                     stderr,
                     exitCode: error?.code ?? (error ? 1 : null),
                     killed,
-                    // 明确告知 agent 命令是因超时被终止（Node 不会自动在 stderr 写入该提示）
-                    terminated: killed ? "timeout" : undefined,
+                    terminated,
                 });
             });
+            // 中断：kill 子进程，令其尽快结束
+            const onAbort = () => {
+                child?.kill("SIGKILL");
+                // 即便 exec 回调因信号处理而未能及时触发，也立即返回中断结果，避免挂起
+                settle({
+                    stdout: "",
+                    stderr: "进程已中断（aborted）",
+                    exitCode: null,
+                    killed: true,
+                    terminated: "aborted",
+                });
+            };
+            if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
         });
         return JSON.stringify(result);
     }

package/dist/capabilities/implements/builtin/ExistTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ExistTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path: string;