@ai-zen/agents-sdk 0.12.0 → 1.0.0-alpha.1

package/dist/{capabilities/implements → scope/plugins}/builtin/ReadFileTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ReadFileTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/ReadFileTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
 export class ReadFileTool extends SdkCallbackTool {
     function = {

package/dist/{capabilities/implements → scope/plugins}/builtin/RenameTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class RenameTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/RenameTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class RenameTool extends SdkCallbackTool {
     function = {
         name: "rename",

package/dist/{capabilities/implements → scope/plugins}/builtin/RmTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class RmTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/RmTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class RmTool extends SdkCallbackTool {
     function = {
         name: "rm",

package/dist/{runtime → scope/plugins/builtin}/SdkCallbackTool.d.ts

@@ -1,6 +1,6 @@
 import { Tool, ToolCallContext } from "@ai-zen/agents-core";
 import type { AgentNS } from "@ai-zen/agents-core";
-import type { AgentDefinition, AppConfig, ToolEnv } from "../types/index.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /** SdkCallbackTool 构造选项。env 为核心字段，未来可在此扩展可选项。 */
 export interface SdkCallbackToolOptions {
     /** 注入的工具环境 */

package/dist/{capabilities/implements → scope/plugins}/builtin/SleepTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class SleepTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/SleepTool.js

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class SleepTool extends SdkCallbackTool {
     function = {
         name: "sleep",

package/dist/{capabilities/implements → scope/plugins}/builtin/ViewImageTool.d.ts

@@ -1,5 +1,5 @@
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /**
  * 查看图片工具 — 让 Agent 主动查看/分析一张图片。**仅对视觉模型可用**：

package/dist/{capabilities/implements → scope/plugins}/builtin/ViewImageTool.js

@@ -1,7 +1,7 @@
 import OpenAI, { toFile } from "openai";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
 /**
  * 是否为"本地 URL"——指向本地/回环地址，API 服务商无法下载访问。

package/dist/{capabilities/implements → scope/plugins}/builtin/WriteFileTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class WriteFileTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/WriteFileTool.js

@@ -1,6 +1,6 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class WriteFileTool extends SdkCallbackTool {
     function = {
         name: "writeFile",

package/dist/{capabilities/discovery/builtin.d.ts → scope/plugins/builtin/discover.d.ts}

@@ -1,5 +1,5 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { ToolEnv } from "../../types/index.js";
+import type { ToolEnv } from "../../../types/index.js";
 /**
  * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *

package/dist/{capabilities/discovery/builtin.js → scope/plugins/builtin/discover.js}

@@ -1,4 +1,4 @@
-import { BUILTIN_TOOL_CLASSES } from "../implements/builtin/index.js";
+import { BUILTIN_TOOL_CLASSES } from "./index.js";
 /**
  * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *

package/dist/{capabilities/implements → scope/plugins}/builtin/index.d.ts

@@ -1,4 +1,4 @@
-import type { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import { CwdTool } from "./CwdTool.js";
 import { ReadFileTool } from "./ReadFileTool.js";
@@ -22,7 +22,7 @@ import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
  * 全部内置工具类（20 个）。
- * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ * 工具类由 Scope 的内置工具插件（BuiltinToolsScopePlugin）用 ToolEnv 实例化（每个 Scope 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
  * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。

package/dist/{capabilities/implements → scope/plugins}/builtin/index.js

@@ -20,7 +20,7 @@ import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
  * 全部内置工具类（20 个）。
- * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ * 工具类由 Scope 的内置工具插件（BuiltinToolsScopePlugin）用 ToolEnv 实例化（每个 Scope 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
  * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。

package/dist/{runtime → scope/plugins/mcp}/McpConnectionManager.d.ts

@@ -1,6 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { McpServerConfig, McpServerManifest, McpConnectionState } from "../types/index.js";
+import type { McpServerConfig, McpServerManifest, McpConnectionState } from "../../../types/index.js";
 export interface McpConnectOptions {
     /** 空闲超时（毫秒），默认 stdio: 30min, http: 5min */
     idleTimeoutMs?: number;

package/dist/{runtime → scope/plugins/mcp}/McpConnectionManager.js

@@ -2,7 +2,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { getLogger } from "../shared/logger.js";
+import { getLogger } from "../../../shared/logger.js";
 const DEFAULT_IDLE_TIMEOUT = {
     stdio: 30 * 60 * 1000,
     http: 5 * 60 * 1000,

package/dist/scope/plugins/mcp/McpScopePlugin.d.ts

@@ -0,0 +1,29 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { Scope, FilterOutput } from "../../Scope.js";
+import type { ScopeCandidates, ScopePlugin } from "../../ScopePlugin.js";
+/**
+ * MCP 插件 —— 发现 mcp.json + 自持连接管理器 + 装配渐进式披露元工具。
+ *
+ * 渐进式披露设计原样保留：
+ *   - `load_mcp`            枚举所有允许的 server（含 include_manifest 开关）
+ *   - `call_mcp_tool`       调用已连接 server 的工具
+ *   - `read_mcp_resource`   读取已连接 server 的资源
+ * 三个元工具名恒上报 `tools` 维度；`mcpManager` 由本插件私有持有，
+ * 有配置路径时在构造时创建，`dispose()` 时统一断开。
+ */
+export declare class McpScopePlugin implements ScopePlugin {
+    static readonly ID = "mcp";
+    readonly id = "mcp";
+    private readonly paths;
+    private readonly mcpManager;
+    private servers;
+    constructor(options?: {
+        paths?: string[];
+    });
+    discover(scope: Scope): Promise<void>;
+    /** 是否配置了 MCP（供外部代码判定，如 UnknownToolHintPlugin） */
+    hasConfig(): boolean;
+    candidates(): ScopeCandidates;
+    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+    dispose(): Promise<void>;
+}

package/dist/scope/plugins/mcp/McpScopePlugin.js

@@ -0,0 +1,60 @@
+import { isAbsolute, join } from "node:path";
+import { discoverMcpServers } from "./discover.js";
+import { createCallMcpTool, createLoadMcpTool, createReadMcpResourceTool, } from "./mcpTools.js";
+import { McpConnectionManager } from "./McpConnectionManager.js";
+/**
+ * MCP 插件 —— 发现 mcp.json + 自持连接管理器 + 装配渐进式披露元工具。
+ *
+ * 渐进式披露设计原样保留：
+ *   - `load_mcp`            枚举所有允许的 server（含 include_manifest 开关）
+ *   - `call_mcp_tool`       调用已连接 server 的工具
+ *   - `read_mcp_resource`   读取已连接 server 的资源
+ * 三个元工具名恒上报 `tools` 维度；`mcpManager` 由本插件私有持有，
+ * 有配置路径时在构造时创建，`dispose()` 时统一断开。
+ */
+export class McpScopePlugin {
+    static ID = "mcp";
+    id = McpScopePlugin.ID;
+    paths;
+    mcpManager;
+    servers = [];
+    constructor(options) {
+        this.paths = options?.paths ?? [];
+        this.mcpManager =
+            this.paths.length > 0 ? new McpConnectionManager() : undefined;
+    }
+    async discover(scope) {
+        const files = this.paths.map((p) => (isAbsolute(p) ? p : join(scope.cwd, p)));
+        this.servers = await discoverMcpServers(files);
+    }
+    /** 是否配置了 MCP（供外部代码判定，如 UnknownToolHintPlugin） */
+    hasConfig() {
+        return this.paths.length > 0;
+    }
+    candidates() {
+        return {
+            mcps: this.servers.map((s) => s.id),
+            tools: ["load_mcp", "call_mcp_tool", "read_mcp_resource"],
+        };
+    }
+    instantiate(_scope, filtered) {
+        const allow = new Set(filtered.tools);
+        const allowedMcps = new Set(filtered.mcps);
+        const filteredMcps = this.servers.filter((s) => allowedMcps.has(s.id));
+        const m = this.mcpManager;
+        const result = [];
+        if (allow.has("load_mcp") && m && filteredMcps.length > 0) {
+            result.push(createLoadMcpTool(m, filteredMcps));
+        }
+        if (allow.has("call_mcp_tool") && m) {
+            result.push(createCallMcpTool(m));
+        }
+        if (allow.has("read_mcp_resource") && m) {
+            result.push(createReadMcpResourceTool(m));
+        }
+        return result;
+    }
+    async dispose() {
+        await this.mcpManager?.disconnectAll();
+    }
+}

package/dist/{capabilities/discovery/mcp.d.ts → scope/plugins/mcp/discover.d.ts}

@@ -1,4 +1,4 @@
-import type { McpServerConfig } from "../../types/index.js";
+import type { McpServerConfig } from "../../../types/index.js";
 /**
  * 从 mcp.json 文件列表中发现所有 MCP server 配置。
  *

package/dist/{capabilities/discovery/mcp.js → scope/plugins/mcp/discover.js}

@@ -1,5 +1,5 @@
 import { promises as fs } from "node:fs";
-import { getLogger } from "../../shared/logger.js";
+import { getLogger } from "../../../shared/logger.js";
 /**
  * 归一化原始 MCP server 配置为内部 McpServerConfig。
  * 处理业界标准中的字段别名差异。

package/dist/{capabilities/implements → scope/plugins/mcp}/mcpTools.d.ts

@@ -1,6 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
-import type { McpConnectionManager } from "../../runtime/McpConnectionManager.js";
-import type { McpServerConfig } from "../../types/index.js";
+import type { McpConnectionManager } from "./McpConnectionManager.js";
+import type { McpServerConfig } from "../../../types/index.js";
 /**
  * 创建 load_mcp 工具。
  * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，

package/dist/{capabilities/implements → scope/plugins/mcp}/mcpTools.js

@@ -1,6 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
-import { createDisclosureParam } from "../disclosure.js";
-import { getLogger } from "../../shared/logger.js";
+import { createDisclosureParam } from "../../disclosure.js";
+import { getLogger } from "../../../shared/logger.js";
 const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
 const log = getLogger();
 /**

package/dist/scope/plugins/skills/SkillsScopePlugin.d.ts

@@ -0,0 +1,28 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { Scope, FilterOutput } from "../../Scope.js";
+import type { ScopeCandidates, ScopePlugin } from "../../ScopePlugin.js";
+/**
+ * Skill 插件 —— 发现 SKILL.md + 装配渐进式披露元工具。
+ *
+ * 渐进式披露设计原样保留：
+ *   - `load_skill`            枚举所有允许的 skill
+ *   - `call_skill_sub_agent`  枚举 subAgent: true 的 skill（AgentToolLazy）
+ * 两个元工具名恒上报 `tools` 维度（供权限允许/拒绝 → 拒绝即切断披露通道）；
+ * 是否真正注册由 `instantiate()` 按允许名 + 候选条件决定。
+ */
+export declare class SkillsScopePlugin implements ScopePlugin {
+    static readonly ID = "skills";
+    readonly id = "skills";
+    private readonly paths;
+    private skills;
+    /** 解析后的 skill 目录（供 instantiate 时传给工具读取正文） */
+    private dirs;
+    constructor(options?: {
+        paths?: string[];
+    });
+    discover(scope: Scope, options?: {
+        silent?: boolean;
+    }): Promise<void>;
+    candidates(): ScopeCandidates;
+    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+}

package/dist/scope/plugins/skills/SkillsScopePlugin.js

@@ -0,0 +1,48 @@
+import { isAbsolute, join } from "node:path";
+import { discoverSkills } from "./discover.js";
+import { createCallSkillSubAgentTool, createLoadSkillTool, } from "./skillTools.js";
+/**
+ * Skill 插件 —— 发现 SKILL.md + 装配渐进式披露元工具。
+ *
+ * 渐进式披露设计原样保留：
+ *   - `load_skill`            枚举所有允许的 skill
+ *   - `call_skill_sub_agent`  枚举 subAgent: true 的 skill（AgentToolLazy）
+ * 两个元工具名恒上报 `tools` 维度（供权限允许/拒绝 → 拒绝即切断披露通道）；
+ * 是否真正注册由 `instantiate()` 按允许名 + 候选条件决定。
+ */
+export class SkillsScopePlugin {
+    static ID = "skills";
+    id = SkillsScopePlugin.ID;
+    paths;
+    skills = [];
+    /** 解析后的 skill 目录（供 instantiate 时传给工具读取正文） */
+    dirs = [];
+    constructor(options) {
+        this.paths = options?.paths ?? [];
+    }
+    async discover(scope, options) {
+        this.dirs = this.paths.map((p) => (isAbsolute(p) ? p : join(scope.cwd, p)));
+        this.skills = await discoverSkills(this.dirs, options);
+    }
+    candidates() {
+        return {
+            skills: this.skills.map((s) => s.id),
+            tools: ["load_skill", "call_skill_sub_agent"],
+        };
+    }
+    instantiate(_scope, filtered) {
+        const allow = new Set(filtered.tools);
+        const allowedSkills = new Set(filtered.skills);
+        const filteredSkills = this.skills.filter((s) => allowedSkills.has(s.id));
+        const result = [];
+        if (allow.has("load_skill") && filteredSkills.length > 0) {
+            result.push(createLoadSkillTool(this.dirs, filteredSkills));
+        }
+        // call_skill_sub_agent：只要有支持子 Agent 的 skill 就注册
+        if (allow.has("call_skill_sub_agent") &&
+            filteredSkills.some((s) => s.subAgent)) {
+            result.push(createCallSkillSubAgentTool(this.dirs, filteredSkills));
+        }
+        return result;
+    }
+}

package/dist/{capabilities/discovery/skills.js → scope/plugins/skills/discover.js}

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
-import { getLogger } from "../../shared/logger.js";
+import { getLogger } from "../../../shared/logger.js";
 const log = getLogger();
 // ---- 发现（返回完整 SkillInfo，不再丢失 subAgent 等信息）----
 /**

package/dist/{capabilities/implements → scope/plugins/skills}/skillTools.d.ts

@@ -1,5 +1,5 @@
 import { CallbackTool, AgentToolLazy } from "@ai-zen/agents-core";
-import type { SkillInfo } from "../discovery/skills.js";
+import type { SkillInfo } from "./discover.js";
 /**
  * 创建 load_skill 工具。
  * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。

package/dist/{capabilities/implements → scope/plugins/skills}/skillTools.js

@@ -1,7 +1,7 @@
 import { CallbackTool, Agent, AgentToolLazy, Message } from "@ai-zen/agents-core";
-import { createDisclosureParam } from "../disclosure.js";
-import { readSkill } from "../discovery/skills.js";
-import { getLogger } from "../../shared/logger.js";
+import { createDisclosureParam } from "../../disclosure.js";
+import { readSkill } from "./discover.js";
+import { getLogger } from "../../../shared/logger.js";
 import { promises as fs } from "node:fs";
 const log = getLogger();
 const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";

package/dist/scope/plugins/subagents/SubAgentsScopePlugin.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { Scope, FilterOutput } from "../../Scope.js";
+import type { ScopeCandidates, ScopePlugin } from "../../ScopePlugin.js";
+/**
+ * SubAgent 插件 —— 发现 `sub-agents/*.json`，将含 function 的定义注册为工具。
+ *
+ * 产物为 `AgentToolLazy`（延迟构建，避免工具列表构建阶段的递归创建）。
+ */
+export declare class SubAgentsScopePlugin implements ScopePlugin {
+    static readonly ID = "subagents";
+    readonly id = "subagents";
+    private readonly paths;
+    private subagents;
+    constructor(options?: {
+        paths?: string[];
+    });
+    discover(scope: Scope): Promise<void>;
+    candidates(): ScopeCandidates;
+    instantiate(scope: Scope, filtered: FilterOutput): Tool[];
+}

package/dist/scope/plugins/subagents/SubAgentsScopePlugin.js

@@ -0,0 +1,34 @@
+import { isAbsolute, join } from "node:path";
+import { discoverSubAgents } from "./discover.js";
+import { createSubAgentTool } from "./subAgentTools.js";
+/**
+ * SubAgent 插件 —— 发现 `sub-agents/*.json`，将含 function 的定义注册为工具。
+ *
+ * 产物为 `AgentToolLazy`（延迟构建，避免工具列表构建阶段的递归创建）。
+ */
+export class SubAgentsScopePlugin {
+    static ID = "subagents";
+    id = SubAgentsScopePlugin.ID;
+    paths;
+    subagents = [];
+    constructor(options) {
+        this.paths = options?.paths ?? [];
+    }
+    async discover(scope) {
+        const dirs = this.paths.map((p) => (isAbsolute(p) ? p : join(scope.cwd, p)));
+        this.subagents = await discoverSubAgents(dirs);
+    }
+    candidates() {
+        return {
+            subagents: this.subagents
+                .filter((d) => d.function)
+                .map((d) => d.function.name),
+        };
+    }
+    instantiate(scope, filtered) {
+        const allow = new Set(filtered.subagents);
+        return this.subagents
+            .filter((d) => d.function && allow.has(d.function.name))
+            .map((d) => createSubAgentTool(d, scope));
+    }
+}

package/dist/{capabilities/discovery/subagents.d.ts → scope/plugins/subagents/discover.d.ts}

@@ -1,4 +1,4 @@
-import type { AgentDefinition } from "../../types/index.js";
+import type { AgentDefinition } from "../../../types/index.js";
 /**
  * 扫描多个目录中发现的所有 SubAgent 完整定义。
  * 按优先级从高到低传入路径列表，同名 function.name 靠前的路径优先（先到先得）。

package/dist/{capabilities/implements → scope/plugins/subagents}/subAgentTools.d.ts

@@ -1,10 +1,10 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { AgentDefinition } from "../../types/index.js";
-import type { Provider } from "../../runtime/Provider.js";
+import type { AgentDefinition } from "../../../types/index.js";
+import type { Scope } from "../../Scope.js";
 /**
  * 创建 SubAgent 工具（AgentToolLazy）。
  *
  * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
  * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
  */
-export declare function createSubAgentTool(def: AgentDefinition, provider: Provider): Tool;
+export declare function createSubAgentTool(def: AgentDefinition, scope: Scope): Tool;

package/dist/{capabilities/implements → scope/plugins/subagents}/subAgentTools.js

@@ -1,12 +1,12 @@
 import { Agent, AgentToolLazy } from "@ai-zen/agents-core";
-import { createModel } from "../../runtime/createModel.js";
+import { createModel } from "../../../runtime/createModel.js";
 /**
  * 创建 SubAgent 工具（AgentToolLazy）。
  *
  * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
  * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
  */
-export function createSubAgentTool(def, provider) {
+export function createSubAgentTool(def, scope) {
     if (!def.function) {
         throw new Error(`Agent "${def.id}" 没有 function 字段，不能作为 SubAgent 工具`);
     }
@@ -24,7 +24,7 @@ export function createSubAgentTool(def, provider) {
             let model;
             let modelConfig;
             if (def.modelId) {
-                const m = createModel(provider, def.modelId);
+                const m = createModel(scope, def.modelId);
                 client = m.client;
                 model = m.model;
                 modelConfig = m.modelConfig;
@@ -39,12 +39,12 @@ export function createSubAgentTool(def, provider) {
                 modelConfig = parent.modelConfig;
             }
             // SubAgent 独立解析自己的工具（排除自身，防止递归）
-            const subFiltered = provider.filter(def, {
+            const subFiltered = scope.filter(def, {
                 exclude: {
                     subagents: def.function?.name ? [def.function.name] : undefined,
                 },
             });
-            const tools = provider.instantiate(subFiltered);
+            const tools = scope.instantiate(subFiltered);
             const subAgent = new Agent({
                 client,
                 model,

package/dist/scope/plugins/usertools/UserToolsScopePlugin.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../../../types/index.js";
+import type { Scope, FilterOutput } from "../../Scope.js";
+import type { ScopeCandidates, ScopePlugin } from "../../ScopePlugin.js";
+/**
+ * 用户工具插件 —— 扫描 `tools/*.js` / `*.mjs` 动态加载。
+ *
+ * 与内置工具插件分开，以便单独替换/停用其中一类。
+ * 路径可为绝对路径或相对路径（相对则按 scope.cwd join）。
+ */
+export declare class UserToolsScopePlugin implements ScopePlugin {
+    static readonly ID = "user-tools";
+    readonly id = "user-tools";
+    private readonly paths;
+    private tools;
+    constructor(options?: {
+        paths?: string[];
+    });
+    discover(scope: Scope, options?: {
+        silent?: boolean;
+    }): Promise<void>;
+    candidates(_scope: Scope, _definition: AgentDefinition): ScopeCandidates;
+    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+}

package/dist/scope/plugins/usertools/UserToolsScopePlugin.js

@@ -0,0 +1,28 @@
+import { isAbsolute, join } from "node:path";
+import { discoverUserTools } from "./discover.js";
+/**
+ * 用户工具插件 —— 扫描 `tools/*.js` / `*.mjs` 动态加载。
+ *
+ * 与内置工具插件分开，以便单独替换/停用其中一类。
+ * 路径可为绝对路径或相对路径（相对则按 scope.cwd join）。
+ */
+export class UserToolsScopePlugin {
+    static ID = "user-tools";
+    id = UserToolsScopePlugin.ID;
+    paths;
+    tools = [];
+    constructor(options) {
+        this.paths = options?.paths ?? [];
+    }
+    async discover(scope, options) {
+        const dirs = this.paths.map((p) => (isAbsolute(p) ? p : join(scope.cwd, p)));
+        this.tools = await discoverUserTools(dirs, options);
+    }
+    candidates(_scope, _definition) {
+        return { tools: this.tools.map((t) => t.function.name) };
+    }
+    instantiate(_scope, filtered) {
+        const allow = new Set(filtered.tools);
+        return this.tools.filter((t) => allow.has(t.function.name));
+    }
+}

package/dist/{capabilities/discovery/usertools.js → scope/plugins/usertools/discover.js}

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Tool, CallbackTool } from "@ai-zen/agents-core";
-import { getLogger } from "../../shared/logger.js";
+import { getLogger } from "../../../shared/logger.js";
 /**
  * 扫描多个 tools/ 目录，发现所有 .js / .mjs 文件，动态加载为 Tool 实例。
  * 使用原生 dynamic import() 加载（在 "type": "module" 下 .js 也是 ESM），