@ai-zen/agents-sdk 0.5.7 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [0.7.0] - 2026-08-14
+
+### ⚠️ Breaking
+
+- **`@ai-zen/agents-core` upgraded to 4.0.0** — the SDK now runs on the **official OpenAI SDK**: `createModel(provider, modelId)` returns `{ client, model, modelConfig }` (an `openai` client + model name + params spread into the request) instead of a `ChatCompletionModel`; `SdkAgent` / `createAgent` construct with `{ client, model, modelConfig }`; `GenerateImageTool` calls `client.images.generate`
+- **Plugin mechanism promoted to core** — `AgentPlugin` / `SendContext` / `HookResult` now live in `@ai-zen/agents-core` (re-exported by the SDK for compatibility). `SdkAgent` no longer implements its own `use` / `init` / hook iteration, and the `onUnknownTool` property hack is gone — it inherits everything from Core `Agent`
+- **`SdkAgent.defaultUnknownTool` override removed** — the MCP-aware unknown-tool hint moved out of the class into a standalone plugin (see `UnknownToolHintPlugin` below); Core `Agent` now keeps only a simple built-in hint
+- **`SdkAgent.permissions` field removed** — the Agent no longer carries its own `permissions` copy; read `agent.definition.permissions` instead (single source of truth). `AutoRefreshToolsPlugin` and `call_skill_sub_agent` were updated accordingly
+- **`ContextGuardPlugin` default `ratio` changed from 1.2 to 1.5** — the guard now trips at 50% over `maxTokens` (user setting) instead of 20%
+
+### 🚀 New Features
+
+- **`UnknownToolHintPlugin`** — new standalone plugin providing the MCP-aware unknown-tool hint (replaces the removed `SdkAgent.defaultUnknownTool` override). Register explicitly: `agent.use(new UnknownToolHintPlugin({ provider }))`; without it, unknown tools fall back to Core's simple built-in hint
+- **`Model.vision` field + self-declared tool availability** — models can be marked `vision: true`. `SdkCallbackTool` gains `isAvailable(config, definition)`: tools **self-declare** availability by directly inspecting the full app config and agent definition (e.g. `GenerateImageTool` requires `defaultImageModel`, `ViewImageTool` requires a vision model). All **19 built-in tools** live in `BUILTIN_TOOL_CLASSES` (discovery does no filtering); `Provider.filter`/`buildTools` take the `AgentDefinition` and call `isAvailable` at build time (when the model is already known) to filter the final tool set — no hard-coded tool names, and no runtime duplication (vision checks live only in `ViewImageTool.isAvailable`)
+- **`ViewImageTool`** — let the Agent view/analyze an image (vision models only): a network URL returns an `image_url` content block; a local path is auto-uploaded via the Files API (`client.files.create`, `purpose: "user_data"`) and returned as a `file` content block (no base64). Always registered as a built-in candidate; filtered out by `buildTools` for non-vision models (a runtime check remains as a defensive guard)
+- **`GenerateImageTool` returns a plain string** — it always returns JSON text with the image URLs plus `viewImage` / `downloadFile` hints; how the generated image is consumed (view / download / forward) is left to the model and the caller, instead of forcing image content blocks on vision models
+- **`SdkCallbackTool.exec` passes content-section arrays through** — aligned with Core's `Tool.exec` returning `AgentNS.MessageContent`; other values are still JSON-serialized
+
+### 🎯 Optimized
+
+- `createAgent` / `subAgentTools` / `skillTools` adapted to the new Agent constructor (`{ client, model, modelConfig }`)
+- The plugins (`AutoMigratePlugin` / `AutoRefreshToolsPlugin` / `ContextGuardPlugin` / `UnknownToolHintPlugin`) now type their hooks from core's `AgentPlugin` / `HookResult`
+
+### ✅ Tests
+
+- Adapted `createModel` / `SdkAgent` / `Provider` / `createAgent` / `AutoRefreshToolsPlugin` / `ContextGuardPlugin` / `skillTools` / e2e tests to the core 4.0.0 API — all green (incl. real DeepSeek API e2e)
+
+## [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

package/README.md

@@ -23,7 +23,7 @@ config       ← read/write config.json + migration + in-memory cache + atomic w
 crud         ← capability-entity CRUD (Agent definitions, etc.; conversations/drafts are persisted by each consumer)
 capabilities ← capability discovery & assembly (built-in + user + MCP + Skill + SubAgent)
 runtime      ← Provider + model factory + Agent assembly + MCP connection management + task migration + SdkCallbackTool base
-plugin       ← Agent plugins (autoMigrate, autoRefreshTools)
+plugin       ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
 shared       ← logging, errors
 ```
 
@@ -78,9 +78,9 @@ await agent.send("Hello");
 | `crud` | ✅ Implemented — capability-entity CRUD for Agents, etc. (conversations/drafts persisted by each consumer) |
 | `capabilities` | ✅ Implemented — discovery + permission filtering + safe pre-filtering + enumeration disclosure |
 | `runtime` | ✅ Implemented — Provider, Capabilities, createAgent, MCP connection management, task migration |
-| `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin |
+| `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ Implemented — SdkError + injectable Logger |
-| Tests | ✅ 409 tests, 47 files, all passing (incl. real-API chat e2e) |
+| Tests | ✅ 445 passing, 51 files, all green (incl. real-API chat & viewImage e2e) |
 
 ## Built-in Tools
 
@@ -106,11 +106,12 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | `edit` | Edit text in a file |
 | `sleep` | Wait for a specified number of milliseconds |
 
-Conditionally injected (registered only when `defaultImageModel` is configured):
+Conditionally injected based on the active model / config:
 
-| Tool | Description |
-|------|-------------|
-| `generateImage` | Generate an image from a text description |
+| Tool | Injection Condition | Description |
+|------|---------------------|-------------|
+| `generateImage` | Only when `defaultImageModel` is configured | Generate an image from a text description |
+| `viewImage` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
 
 ## Built-in Plugins
 
@@ -118,6 +119,8 @@ Conditionally injected (registered only when `defaultImageModel` is configured):
 |--------|-------------|
 | `AutoMigratePlugin` | Automatically triggers task migration when the context overflows, generates a handoff document, and transparently replaces the Agent |
 | `AutoRefreshToolsPlugin` | Re-scans the file system before each `send()` to refresh the tool list |
+| `ContextGuardPlugin` | Context safety guard — before each request, throws `ContextOverflowError` (interrupting the conversation) when the previous round's `usage.prompt_tokens` exceeds `maxTokens × ratio` (default 1.5), preventing context runaway from reading oversized files |
+| `UnknownToolHintPlugin` | Smarter unknown-tool hints — when the LLM calls a nonexistent tool, guides it to `call_mcp_tool` / points out permission issues based on MCP config (opt-in via `agent.use`) |
 
 ## Design Principles
 

package/README.zh.md

@@ -22,7 +22,7 @@ config       ← 读写 config.json + 迁移 + 内存缓存 + 原子写入
 crud         ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
 capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
 runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移 + SdkCallbackTool 工具基类
-plugin       ← Agent 插件（autoMigrate、autoRefreshTools）
+plugin       ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
 shared       ← 日志、错误
 ```
 
@@ -77,9 +77,9 @@ await agent.send("你好");
 | `crud` | ✅ 已实现 — Agent 等能力实体 CRUD（会话/草稿由各端自行持久化） |
 | `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
-| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin |
+| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 409 个测试，47 个文件，全通过（含真实 API 聊天 e2e） |
+| 测试 | ✅ 445 通过，51 个文件，全绿（含真实 API 聊天与 viewImage e2e） |
 
 ## 内置工具
 
@@ -105,11 +105,12 @@ await agent.send("你好");
 | `edit` | 编辑文件中的文本 |
 | `sleep` | 等待指定毫秒数后继续 |
 
-条件注入（`GenerateImageTool` 需配置 `defaultImageModel` 才注册）：
+条件注入（按当前模型 / 配置决定是否注册）：
 
-| 工具 | 说明 |
-|------|------|
-| `generateImage` | 根据文字描述生成图片 |
+| 工具 | 注入条件 | 说明 |
+|------|----------|------|
+| `generateImage` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
+| `viewImage` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
 
 ## 内置插件
 
@@ -117,6 +118,8 @@ await agent.send("你好");
 |------|------|
 | `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent |
 | `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
+| `ContextGuardPlugin` | 上下文安全护栏 — 每轮发请求前检测上一轮 `usage.prompt_tokens`，超过 `maxTokens × ratio`（默认 1.5，即 +50%）时抛 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控 |
+| `UnknownToolHintPlugin` | 未知工具智能提示 — LLM 调用不存在的工具时，根据 MCP 配置引导使用 `call_mcp_tool` / 提示权限问题（调用方显式 `agent.use` 注册） |
 
 ## 设计原则
 

package/dist/capabilities/discovery/builtin.d.ts

@@ -1,9 +1,9 @@
 import type { Tool } from "@ai-zen/agents-core";
 import type { ToolEnv } from "../../types/index.js";
 /**
- * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *
- * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
- * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
+ * 工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，入参含完整 config
+ * + 模型信息），在 buildTools/filter 阶段（模型已知）按声明过滤。
  */
 export declare function discoverBuiltinTools(env: ToolEnv): Tool[];

package/dist/capabilities/discovery/builtin.js

@@ -1,18 +1,10 @@
 import { BUILTIN_TOOL_CLASSES } from "../implements/builtin/index.js";
-import { GenerateImageTool } from "../implements/builtin/GenerateImageTool.js";
 /**
- * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *
- * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
- * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
+ * 工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，入参含完整 config
+ * + 模型信息），在 buildTools/filter 阶段（模型已知）按声明过滤。
  */
 export function discoverBuiltinTools(env) {
-    const tools = BUILTIN_TOOL_CLASSES.map((Cls) => new Cls(env));
-    if (env.config.defaultImageModel) {
-        const existingNames = new Set(tools.map((t) => t.function.name));
-        if (!existingNames.has("generateImage")) {
-            tools.push(new GenerateImageTool(env));
-        }
-    }
-    return tools;
+    return BUILTIN_TOOL_CLASSES.map((Cls) => new Cls(env));
 }

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;