@ai-zen/agents-sdk 0.4.0 → 0.5.1

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

@@ -0,0 +1,37 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class ReadFileTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "readFile",
+                description: "读取文件",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "文件路径",
+                        },
+                    },
+                    required: ["path"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            const stats = await fsp.stat(filePath);
+            if (stats.size > 300 * 1024) {
+                throw new Error(`文件过大，无法读取，当前文件大小 ${stats.size} 字节`);
+            }
+            return await fsp.readFile(filePath, "utf-8");
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class RenameTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        oldPath: string;
+        newPath: string;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,37 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class RenameTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "rename",
+                description: "重命名或移动文件/目录（相当于 mv 命令）",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        oldPath: {
+                            type: "string",
+                            description: "原路径",
+                        },
+                        newPath: {
+                            type: "string",
+                            description: "新路径",
+                        },
+                    },
+                    required: ["oldPath", "newPath"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            await fsp.rename(this.resolve(input.oldPath), this.resolve(input.newPath));
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class RmTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        recursive?: boolean;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,39 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class RmTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "rm",
+                description: "删除文件或目录",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "文件或目录路径",
+                        },
+                        recursive: {
+                            type: "boolean",
+                            description: "是否递归删除子目录",
+                        },
+                    },
+                    required: ["path"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            await fsp.rm(this.resolve(input.path), {
+                recursive: input.recursive ?? false,
+            });
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class SleepTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        ms: number;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,46 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class SleepTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "sleep",
+                description: "等待指定的时间（毫秒）。用于需要延迟执行的场景，例如等待其他操作完成、操作间隔控制等。注意：过长的等待时间会影响响应速度，建议不超过 30000 毫秒（30 秒）。",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        ms: {
+                            type: "number",
+                            description: "等待的毫秒数（1 秒 = 1000 毫秒）。建议不超过 30000（30 秒）。",
+                        },
+                    },
+                    required: ["ms"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        const ms = input.ms;
+        if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+            return JSON.stringify({
+                success: false,
+                error: "ms 必须是正整数",
+            });
+        }
+        if (ms > 300_000) {
+            // 超过 5 分钟给出警告
+            return JSON.stringify({
+                success: false,
+                error: `等待时间 ${ms}ms 过长，建议不超过 300000ms（5 分钟）。如需长时间等待请分段执行。`,
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return JSON.stringify({
+            success: true,
+            waitedMs: ms,
+            waitedSeconds: (ms / 1000).toFixed(1),
+            message: `已等待 ${ms}ms（${(ms / 1000).toFixed(1)} 秒）`,
+        });
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class WriteFileTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        content: string;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,40 @@
+import * as fsp from "fs/promises";
+import * as path from "path";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class WriteFileTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "writeFile",
+                description: "写入文件",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "文件路径",
+                        },
+                        content: {
+                            type: "string",
+                            description: "文件内容",
+                        },
+                    },
+                    required: ["path", "content"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            await fsp.mkdir(path.dirname(filePath), { recursive: true });
+            await fsp.writeFile(filePath, input.content);
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -1,21 +1,29 @@
-import type { Tool } from "@ai-zen/agents-core";
-import { cwdTool } from "./cwd.js";
-import { readFileTool } from "./readFile.js";
-import { writeFileTool } from "./writeFile.js";
-import { execTool } from "./exec.js";
-import { mkdirTool } from "./mkdir.js";
-import { rmTool } from "./rm.js";
-import { globTool } from "./glob.js";
-import { lsTool } from "./ls.js";
-import { existTool } from "./exist.js";
-import { findTextTool } from "./findText.js";
-import { downloadFileTool } from "./downloadFile.js";
-import { renameTool } from "./rename.js";
-import { copyTool } from "./copy.js";
-import { batchEditTool } from "./batchEdit.js";
-import { editTool } from "./edit.js";
-import { execAsyncTool } from "./execAsync.js";
-import { sleepTool } from "./sleep.js";
-/** 17 个内置工具实例，注册与实现一体。 */
-export declare const BUILTIN_TOOLS: Tool[];
-export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool, execAsyncTool, sleepTool };
+import type { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+import { CwdTool } from "./CwdTool.js";
+import { ReadFileTool } from "./ReadFileTool.js";
+import { WriteFileTool } from "./WriteFileTool.js";
+import { ExecTool } from "./ExecTool.js";
+import { MkdirTool } from "./MkdirTool.js";
+import { RmTool } from "./RmTool.js";
+import { GlobTool } from "./GlobTool.js";
+import { LsTool } from "./LsTool.js";
+import { ExistTool } from "./ExistTool.js";
+import { FindTextTool } from "./FindTextTool.js";
+import { DownloadFileTool } from "./DownloadFileTool.js";
+import { RenameTool } from "./RenameTool.js";
+import { CopyTool } from "./CopyTool.js";
+import { BatchEditTool } from "./BatchEditTool.js";
+import { EditTool } from "./EditTool.js";
+import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SleepTool } from "./SleepTool.js";
+import { GenerateImageTool } from "./GenerateImageTool.js";
+/**
+ * 17 个无条件注册的内置工具类。
+ * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ *
+ * 注意：GenerateImageTool 依赖图片模型配置（defaultImageModel），
+ * 由 discoverBuiltinTools 按条件实例化，不在此静态注册表中。
+ */
+export declare const BUILTIN_TOOL_CLASSES: Array<new (env: ToolEnv) => SdkCallbackTool>;
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, GenerateImageTool, };

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

@@ -1,38 +1,45 @@
-import { cwdTool } from "./cwd.js";
-import { readFileTool } from "./readFile.js";
-import { writeFileTool } from "./writeFile.js";
-import { execTool } from "./exec.js";
-import { mkdirTool } from "./mkdir.js";
-import { rmTool } from "./rm.js";
-import { globTool } from "./glob.js";
-import { lsTool } from "./ls.js";
-import { existTool } from "./exist.js";
-import { findTextTool } from "./findText.js";
-import { downloadFileTool } from "./downloadFile.js";
-import { renameTool } from "./rename.js";
-import { copyTool } from "./copy.js";
-import { batchEditTool } from "./batchEdit.js";
-import { editTool } from "./edit.js";
-import { execAsyncTool } from "./execAsync.js";
-import { sleepTool } from "./sleep.js";
-/** 17 个内置工具实例，注册与实现一体。 */
-export const BUILTIN_TOOLS = [
-    cwdTool,
-    readFileTool,
-    writeFileTool,
-    execTool,
-    mkdirTool,
-    rmTool,
-    globTool,
-    lsTool,
-    existTool,
-    findTextTool,
-    downloadFileTool,
-    renameTool,
-    copyTool,
-    batchEditTool,
-    editTool,
-    execAsyncTool,
-    sleepTool,
+import { CwdTool } from "./CwdTool.js";
+import { ReadFileTool } from "./ReadFileTool.js";
+import { WriteFileTool } from "./WriteFileTool.js";
+import { ExecTool } from "./ExecTool.js";
+import { MkdirTool } from "./MkdirTool.js";
+import { RmTool } from "./RmTool.js";
+import { GlobTool } from "./GlobTool.js";
+import { LsTool } from "./LsTool.js";
+import { ExistTool } from "./ExistTool.js";
+import { FindTextTool } from "./FindTextTool.js";
+import { DownloadFileTool } from "./DownloadFileTool.js";
+import { RenameTool } from "./RenameTool.js";
+import { CopyTool } from "./CopyTool.js";
+import { BatchEditTool } from "./BatchEditTool.js";
+import { EditTool } from "./EditTool.js";
+import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SleepTool } from "./SleepTool.js";
+import { GenerateImageTool } from "./GenerateImageTool.js";
+/**
+ * 17 个无条件注册的内置工具类。
+ * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ *
+ * 注意：GenerateImageTool 依赖图片模型配置（defaultImageModel），
+ * 由 discoverBuiltinTools 按条件实例化，不在此静态注册表中。
+ */
+export const BUILTIN_TOOL_CLASSES = [
+    CwdTool,
+    ReadFileTool,
+    WriteFileTool,
+    ExecTool,
+    MkdirTool,
+    RmTool,
+    GlobTool,
+    LsTool,
+    ExistTool,
+    FindTextTool,
+    DownloadFileTool,
+    RenameTool,
+    CopyTool,
+    BatchEditTool,
+    EditTool,
+    ExecAsyncTool,
+    SleepTool,
 ];
-export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool, execAsyncTool, sleepTool };
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, GenerateImageTool, };

package/dist/capabilities/implements/builtin/test-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { AppConfig, ToolEnv } from "../../../types/index.js";
+/** 构造测试用 ToolEnv */
+export declare function makeEnv(cwd?: string, config?: AppConfig): ToolEnv;

package/dist/capabilities/implements/builtin/test-helpers.js

@@ -0,0 +1,4 @@
+/** 构造测试用 ToolEnv */
+export function makeEnv(cwd = process.cwd(), config = {}) {
+    return { cwd, config };
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { PermissionPolicy, AgentPermissions, Endpoint, Model, ImageModel, AgentDefinition, Conversation, Draft, AppConfig, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
+export type { PermissionPolicy, AgentPermissions, Endpoint, Model, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
 export { PermissionEvaluator } from "./capabilities/PermissionEvaluator.js";
 export type { CandidateSets } from "./capabilities/PermissionEvaluator.js";
 export { createDisclosureParam } from "./capabilities/disclosure.js";
@@ -12,8 +12,6 @@ export { discoverUserTools } from "./capabilities/discovery/usertools.js";
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
-export { ConversationRepository } from "./crud/ConversationRepository.js";
-export { DraftRepository } from "./crud/DraftRepository.js";
 export { Provider } from "./runtime/Provider.js";
 export type { FilterOutput, ExcludeOptions } from "./runtime/Provider.js";
 export { createModel } from "./runtime/createModel.js";
@@ -22,17 +20,15 @@ export type { AgentPlugin, SendContext } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
 export { McpConnectionManager } from "./runtime/McpConnectionManager.js";
 export type { McpConnectOptions } from "./runtime/McpConnectionManager.js";
+export { SdkCallbackTool } from "./runtime/SdkCallbackTool.js";
 export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
 export type { BuildMigrationAgentOptions } from "./runtime/TaskMigrationService.js";
 export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
 export type { AutoMigrateOptions } from "./plugin/AutoMigratePlugin.js";
-export { AutoDraftPlugin } from "./plugin/AutoDraftPlugin.js";
-export type { AutoDraftOptions } from "./plugin/AutoDraftPlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
-export { BUILTIN_TOOLS } from "./capabilities/implements/builtin/index.js";
-export { createGenerateImageTool } from "./capabilities/implements/builtin/generateImage.js";
-export { execAsyncTool } from "./capabilities/implements/builtin/execAsync.js";
-export { sleepTool } from "./capabilities/implements/builtin/sleep.js";
+export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
+export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";

package/dist/index.js

@@ -9,27 +9,24 @@ export { discoverMcpServers } from "./capabilities/discovery/mcp.js";
 export { discoverUserTools } from "./capabilities/discovery/usertools.js";
 // 配置 — ConfigManager
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
-// CRUD — EntityRepository + 实体仓储
+// CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
-export { ConversationRepository } from "./crud/ConversationRepository.js";
-export { DraftRepository } from "./crud/DraftRepository.js";
 // 运行时
 export { Provider } from "./runtime/Provider.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
 export { McpConnectionManager } from "./runtime/McpConnectionManager.js";
+export { SdkCallbackTool } from "./runtime/SdkCallbackTool.js";
 export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
 // 插件
 export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
-export { AutoDraftPlugin } from "./plugin/AutoDraftPlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
-// 工具
-export { BUILTIN_TOOLS } from "./capabilities/implements/builtin/index.js";
-export { createGenerateImageTool } from "./capabilities/implements/builtin/generateImage.js";
-export { execAsyncTool } from "./capabilities/implements/builtin/execAsync.js";
-export { sleepTool } from "./capabilities/implements/builtin/sleep.js";
+// 工具 — 内置工具类 + 动态工具工厂
+export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
+export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";

package/dist/runtime/Provider.d.ts

@@ -1,5 +1,5 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { AppConfig, AgentDefinition, AgentPermissions, McpServerConfig } from "../types/index.js";
+import type { AppConfig, AgentDefinition, AgentPermissions, McpServerConfig, ToolEnv } from "../types/index.js";
 import type { SkillInfo } from "../capabilities/discovery/skills.js";
 import { McpConnectionManager } from "./McpConnectionManager.js";
 /**
@@ -48,6 +48,10 @@ export interface ExcludeOptions {
 export declare class Provider {
     /** 应用配置（端点、模型等） */
     readonly config: AppConfig;
+    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
+    readonly cwd: string;
+    /** 工具环境 — 实例化内置工具时注入 */
+    readonly env: ToolEnv;
     readonly agentsDir: string;
     readonly subAgentsPaths: string[];
     readonly skillsPaths: string[];
@@ -68,6 +72,8 @@ export declare class Provider {
         skillsPaths?: string[];
         toolsPaths?: string[];
         mcpPaths?: string[];
+        /** 当前工作目录，默认 process.cwd() */
+        cwd?: string;
     });
     /**
      * 异步创建 Provider，一步完成构造 + 全局能力发现。
@@ -79,6 +85,8 @@ export declare class Provider {
         skillsPaths?: string[];
         toolsPaths?: string[];
         mcpPaths?: string[];
+        /** 当前工作目录，默认 process.cwd() */
+        cwd?: string;
     }): Promise<Provider>;
     /**
      * 初始化：执行全局能力发现。

package/dist/runtime/Provider.js

@@ -34,6 +34,10 @@ import { discoverUserTools } from "../capabilities/discovery/usertools.js";
 export class Provider {
     /** 应用配置（端点、模型等） */
     config;
+    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
+    cwd;
+    /** 工具环境 — 实例化内置工具时注入 */
+    env;
     // ---- 路径 ----
     agentsDir;
     subAgentsPaths;
@@ -52,6 +56,8 @@ export class Provider {
     mcpManager;
     constructor(options) {
         this.config = options.config;
+        this.cwd = options.cwd ?? process.cwd();
+        this.env = { cwd: this.cwd, config: this.config };
         this.agentsDir = options.agentsDir;
         this.subAgentsPaths = options.subAgentsPaths ?? [];
         this.skillsPaths = options.skillsPaths ?? [];
@@ -181,7 +187,7 @@ export class Provider {
      */
     async refresh(options) {
         const silent = options?.silent ?? false;
-        this.builtinTools = discoverBuiltinTools(this.config);
+        this.builtinTools = discoverBuiltinTools(this.env);
         this.userTools = await discoverUserTools(this.toolsPaths, { silent });
         this.subagents = await discoverSubAgents(this.subAgentsPaths);
         this.skills = await discoverSkills(this.skillsPaths, { silent });

package/dist/runtime/SdkCallbackTool.d.ts

@@ -0,0 +1,28 @@
+import { Tool, FunctionCallContext } from "@ai-zen/agents-core";
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { ToolEnv } from "../types/index.js";
+/**
+ * SdkCallbackTool — SDK 内置工具基类。
+ *
+ * 环境（ToolEnv）在构造时注入，工具逻辑在子类的 call() 中实现，
+ * 不再依赖全局 process.cwd()，也不需要在运行时反查 Agent 上下文。
+ *
+ * 设计原则：
+ *   - 一个工具一个类，文件名 = 类名（PascalCase）
+ *   - 依赖环境（cwd、config）通过构造参数显式注入
+ *   - 相对路径统一用 resolve() 解析到 env.cwd
+ */
+export declare abstract class SdkCallbackTool extends Tool {
+    /** 注入的工具环境 */
+    readonly env: ToolEnv;
+    constructor(options: {
+        function: AgentNS.FunctionDefine;
+        env: ToolEnv;
+    });
+    /** 工具核心逻辑（由子类实现，参数为 parsed_args） */
+    abstract call(input: unknown): unknown | Promise<unknown>;
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
+    exec(ctx: FunctionCallContext): Promise<string>;
+    /** 将相对路径解析到 env.cwd，绝对路径原样返回 */
+    resolve(p: string): string;
+}

package/dist/runtime/SdkCallbackTool.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { Tool } from "@ai-zen/agents-core";
+/**
+ * SdkCallbackTool — SDK 内置工具基类。
+ *
+ * 环境（ToolEnv）在构造时注入，工具逻辑在子类的 call() 中实现，
+ * 不再依赖全局 process.cwd()，也不需要在运行时反查 Agent 上下文。
+ *
+ * 设计原则：
+ *   - 一个工具一个类，文件名 = 类名（PascalCase）
+ *   - 依赖环境（cwd、config）通过构造参数显式注入
+ *   - 相对路径统一用 resolve() 解析到 env.cwd
+ */
+export class SdkCallbackTool extends Tool {
+    /** 注入的工具环境 */
+    env;
+    constructor(options) {
+        super({ function: options.function });
+        this.env = options.env;
+    }
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
+    async exec(ctx) {
+        const result = await this.call(ctx.parsed_args);
+        if (typeof result === "string")
+            return result;
+        // JSON.stringify(undefined) 返回 undefined（非字符串），会破坏 Promise<string> 契约
+        return JSON.stringify(result) ?? "";
+    }
+    /** 将相对路径解析到 env.cwd，绝对路径原样返回 */
+    resolve(p) {
+        return path.isAbsolute(p) ? p : path.join(this.env.cwd, p);
+    }
+}

package/dist/types/index.d.ts

@@ -45,26 +45,6 @@ export interface AgentDefinition {
     updatedAt: string;
     version?: number;
 }
-/** 对话记录 */
-export interface Conversation {
-    id: string;
-    agentId: string;
-    modelId: string;
-    messages: AgentNS.Message[];
-    lastPromptTokens?: number;
-    cwd?: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/** 当前会话草稿 */
-export interface Draft {
-    conversationId?: string;
-    agentId: string;
-    modelId: string;
-    messages: AgentNS.Message[];
-    cwd?: string;
-    updatedAt: string;
-}
 /** 图片生成模型配置 */
 export interface ImageModel {
     id: string;
@@ -90,6 +70,18 @@ export interface AppConfig {
     /** 默认迁移模型 ID */
     defaultMigrationModel?: string;
 }
+/**
+ * 工具环境 — Provider 在实例化内置工具时注入的环境信息。
+ *
+ * cwd 是相对路径解析的基准（每个 Provider 对应一个工作目录）；
+ * config 供需要模型/端点配置的工具（如 generateImage）使用。
+ */
+export interface ToolEnv {
+    /** 当前工作目录 */
+    cwd: string;
+    /** 应用配置 */
+    config: AppConfig;
+}
 /** MCP 连接状态 */
 export type McpConnectionState = "disconnected" | "connecting" | "connected" | "error";
 /** MCP 服务器配置 */