@actiondock/mcp 2.9.1 → 2.11.0

package/README.md

@@ -7,7 +7,7 @@ ActionDock 2.x 模型上下文协议适配器。
 [![MCP](https://img.shields.io/badge/MCP-Protocol%20Compliant-purple)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-`@actiondock/mcp` 将 ActionDock 中的原子 Action 映射为标准的模型上下文协议工具，无缝接入各类主流 AI 智能体与开发环境。在 ActionDock 2.x 中，MCP 适配层全面对接 `@actiondock/core` 导出的标准服务端口体系（`DiscoveryPort`、`ExecutionPort` 与 `RunsPort`），彻底消除对底层私有实体的直接穿透。
+`@actiondock/mcp` 将 ActionDock 中的原子 Action 映射为标准的模型上下文协议工具，无缝接入各类主流智能体与宿主环境。MCP 适配层直接对接 `@actiondock/core` 导出的标准服务端口体系，忠实保持工具模式与业务入参契约。
 
 ---
 
@@ -15,15 +15,20 @@ ActionDock 2.x 模型上下文协议适配器。
 
 ### 双协议传输通道
 
-- STDIO 标准输入输出通道：专为本地客户端设计，直接通过子进程标准流双向通信，安全且免配置端口。
+- STDIO 标准输入输出通道：专为本地客户端设计，直接通过子进程标准流双向通信，具备受控诊断流隔离与进程退出协同机制。
 - HTTP 传输通道：专为远程服务与容器化部署设计，基于 Web 标准请求与响应实现流式传输，支持跨域策略配置与鉴权令牌校验。
 
-### 工具模式自动转换
+### 纯净模式映射与契约忠实
 
-- 自动解析每个 Action 的模式规范，转换为标准 MCP Tool 契约。
-- 智能处理多包聚合场景下的动作标识冲突，自动使用包命名空间前缀消除歧义。
-- 严格遵循输入格式校验，在参数违规时向模型返回结构化诊断提示。
-- 执行结果自动封装为包含文本内容块与结构化数据的 MCP 格式信封，并在异常时正确标记错误标识。
+- 原始模式完全保真：工具入参和出参模式完全忠实于 Action 定义，不在模式中注入非业务执行包装字段。
+- 业务入参纯净传递：工具入参直接透明传递至底层执行引擎，不修改或过滤业务自有的入参字段。
+- 命名空间冲突隔离：智能处理多包聚合场景下的动作标识冲突，自动使用包命名空间前缀消除歧义。
+- 结构化结果转换：执行结果自动封装为包含文本内容块与结构化数据的 MCP 标准信封。
+
+### 规程映射为资源与提示词
+
+- 只读资源映射：将 Playbook 操作规程自动注册为只读 MCP Resource，支持客户端直接读取 Markdown 规程文本。
+- 提示词模版映射：将 Playbook 映射为 MCP Prompt，方便智能体快速装配规程指令。
 
 ### 协同取消信号向下传播
 
@@ -31,27 +36,19 @@ ActionDock 2.x 模型上下文协议适配器。
 - 取消信号通过服务端口直接传递至底层的执行服务，并联动激活当前任务上下文中的 `ctx.signal`。
 - 业务代码可通过监听 AbortSignal 安全释放资源或提前终止执行。
 
-### Tasks 异步任务映射扩展
-
-针对长周期、重资源消耗的复杂任务，完整适配 MCP Tasks 异步协议扩展：
-
-- 任务状态查询：通过 `tasks/get` 端点根据任务标识检索当前运行状态、执行进度与部分输出快照。
-- 任务主动取消：通过 `tasks/cancel` 端点向正在后台执行的长周期任务发出中止指令。
-- 任务清单列举：通过 `tasks/list` 端点批量查询当前会话及宿主下的活跃与历史任务列表。
-
 ### 细粒度权限白名单与安全过滤
 
 MCP 适配层原生支持基于包与动作维度的双层白名单控制，通过 `ActionDockMcpOptions` 进行配置：
 
-- 包白名单 `packageAllowlist`（别名 `packageIds`）：限制仅暴露指定包内的工具。
+- 包白名单 `packageAllowlist`（别名 `packageIds`）：限制仅暴露指定包内的工具与规程。
 - 动作白名单 `actionAllowlist`：限制仅暴露指定的动作，支持动作短名 `actionId` 与全限定名 `packageId/actionId`。
-- 联动过滤机制：同时配置包白名单与动作白名单时自动计算权限交集。未获授权的动作不会出现在 `tools/list` 工具列表中；在 `tasks/get`、`tasks/cancel` 与 `tasks/list` 任务扩展中，涉及未授权动作的任务同样予以严格隔离与隐藏。
+- 联动过滤机制：同时配置包白名单与动作白名单时自动计算权限交集，未获授权的动作不会出现在 `tools/list` 工具列表中。
 
 ---
 
 ## 快速使用
 
-通过命令行一键启动 MCP 服务：
+通过命令行启动 MCP 服务：
 
 ```bash
 # 以 STDIO 协议启动
@@ -61,12 +58,12 @@ ad mcp
 ad mcp serve --port 8080
 ```
 
-也可以在代码中通过编程方式创建适配器服务：
+在代码中通过编程方式创建适配器服务：
 
 ```ts
-import { startMcpStdioServer } from "@actiondock/mcp";
+import { startMcpStdio } from "@actiondock/mcp";
 
-await startMcpStdioServer({
+await startMcpStdio({
   projectRoot: process.cwd(),
   packageAllowlist: ["system-tools"],
   actionAllowlist: ["system-tools/status", "ping"],

package/dist/adapter.d.ts

@@ -1,9 +1,11 @@
 import { type ActionDockService } from "@actiondock/core";
-import { type ActionDockHost } from "@actiondock/core/server";
+import type { ActionDockHost } from "@actiondock/core/server";
 import type { PackageRuntime } from "@actiondock/core/package";
 import type { ExecutionResult } from "@actiondock/sdk";
 import { McpServer } from "@modelcontextprotocol/server";
 import type { ActionDockMcpOptions } from "./types.js";
+import { resolveService } from "./service-resolver.js";
+export { resolveService };
 /**
  * 判断目标值是否为普通对象（Plain Object）。
  *
@@ -30,13 +32,6 @@ export declare function toMcpResult(result: ExecutionResult): {
     }[];
     structuredContent?: undefined;
 };
-/**
- * 解析或基于选项创建底层 ActionDockService 统一门面。
- */
-export declare function resolveService(options: ActionDockMcpOptions): Promise<{
-    service: ActionDockService;
-    ownsService: boolean;
-}>;
 export type ActionDockMcpServer = McpServer & {
     close: () => Promise<void>;
     service: ActionDockService;

package/dist/adapter.js

@@ -1,15 +1,10 @@
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { ACTIONDOCK_VERSION, createActionDock, createNodePlatform, findProjectRoot, MCP_TOOL_NAME_COLLISION, } from "@actiondock/core";
-import { createActionDockHost, isActionAllowed, LocalActionDockService, } from "@actiondock/core/server";
-import { resolvePackageRoot } from "@actiondock/core/registry";
-import { createNonClosingStorageView } from "@actiondock/core/package";
-import { parseActionRef } from "@actiondock/core/graph";
+import { ACTIONDOCK_VERSION } from "@actiondock/core";
 import { McpServer } from "@modelcontextprotocol/server";
-import { registerTasksExtension } from "./register-tasks-extension.js";
 import { toMcpSchema } from "./schemas.js";
-import { extractExecutionTimeoutMs, isAsyncExecutionRequested, stripExecutionWrapper, } from "./execution-mode.js";
+import { resolveExecutionTimeout } from "./execution-mode.js";
+import { resolveService } from "./service-resolver.js";
+import { mapAndFilterActions } from "./tool-mapper.js";
+export { resolveService };
 /** 形状缺失告警是否已输出过（每个进程仅告警一次，避免逐请求噪声） */
 let cancelSignalDegradationWarned = false;
 /**
@@ -26,21 +21,6 @@ function extractCancelSignal(ctx) {
     }
     return signal;
 }
-/**
- * 解析 Action 引用字符串为包标识与动作标识（容错语义）。
- *
- * 委派 core 的 parseActionRef 单一事实源完成解析；非法形态（如尾部斜杠、
- * 含冒号等）回退为整体短名处理，与适配层既有的注册容错行为保持一致，
- * 不让目录聚合阶段的脏数据中断服务启动。
- */
-function splitActionRef(ref) {
-    try {
-        return parseActionRef(ref);
-    }
-    catch {
-        return { actionId: ref };
-    }
-}
 /**
  * 判断目标值是否为普通对象（Plain Object）。
  *
@@ -83,155 +63,6 @@ export function toMcpResult(result) {
         ],
     };
 }
-/**
- * 构造携带结构化错误码的工具名冲突异常。
- *
- * @param toolName 冲突的工具名
- */
-function toolNameCollisionError(toolName) {
-    const err = new Error(`MCP tool name collision detected for tool '${toolName}'`);
-    err.code = MCP_TOOL_NAME_COLLISION;
-    return err;
-}
-/**
- * 解析或基于选项创建底层 ActionDockService 统一门面。
- */
-export async function resolveService(options) {
-    if (options.service) {
-        return { service: options.service, ownsService: false };
-    }
-    if (options.host) {
-        const service = new LocalActionDockService(options.host);
-        return { service, ownsService: false };
-    }
-    if (options.runtime) {
-        const host = await createActionDockHost({
-            autoLoadCurrentProject: false,
-            scanLinkedPackages: false,
-        });
-        host.registerRuntime(options.runtime);
-        const service = new LocalActionDockService(host);
-        return { service, ownsService: false };
-    }
-    const packages = [];
-    // 外部注入的 storage 生命周期默认由注入方管理，适配层仅委托读写不接管关闭
-    // （非接管视图复用 core 单一事实源）；显式声明 ownStorageLifecycle 时透传
-    // 原始实例，随 target.close() 级联关闭
-    const appStorage = options.storage
-        ? options.ownStorageLifecycle
-            ? options.storage
-            : createNonClosingStorageView(options.storage)
-        : undefined;
-    // 多分支共享的包选项基底单点构造：storage 视图、家目录与配置覆写
-    // 在此收敛一次，各 push 分支仅叠加自身特有字段
-    const basePkgOpts = {
-        ...(appStorage ? { storage: appStorage } : {}),
-        customHome: options.customHome,
-        configOverrides: options.configOverrides,
-    };
-    if (options.actions) {
-        packages.push({
-            ...basePkgOpts,
-            projectConfig: {
-                id: options.packageId || "default",
-                name: options.packageId || "default",
-                version: ACTIONDOCK_VERSION,
-            },
-            actions: options.actions,
-            inMemory: true,
-        });
-    }
-    if (options.projectRoots && options.projectRoots.length > 0) {
-        for (const root of options.projectRoots) {
-            const abs = resolve(root);
-            const detected = findProjectRoot(abs);
-            if (!detected) {
-                throw new Error(`Project root '${root}' is not a valid ActionDock package (actiondock.json not found)`);
-            }
-            packages.push({
-                ...basePkgOpts,
-                packageRoot: detected,
-            });
-        }
-    }
-    const targetPackageIds = options.packageIds || options.packageAllowlist;
-    if (targetPackageIds && targetPackageIds.length > 0) {
-        for (const pkgId of targetPackageIds) {
-            const root = resolvePackageRoot(pkgId, undefined, options.customHome);
-            if (!root || !existsSync(root)) {
-                throw new Error(`Package '${pkgId}' not found in registry`);
-            }
-            packages.push({
-                ...basePkgOpts,
-                packageRoot: root,
-            });
-        }
-    }
-    let projectRoot = options.projectRoot;
-    if (options.projectRoot) {
-        const abs = resolve(options.projectRoot);
-        const detected = findProjectRoot(abs);
-        if (!detected) {
-            throw new Error(`Project root '${options.projectRoot}' is not a valid ActionDock package (actiondock.json not found)`);
-        }
-        projectRoot = detected;
-    }
-    if (!projectRoot &&
-        packages.length === 0 &&
-        !options.all &&
-        !options.packageId) {
-        const currentRoot = findProjectRoot(process.cwd());
-        if (!currentRoot) {
-            throw new Error("No ActionDock project root found. Run inside an ActionDock package or specify --dir / --package / --all.");
-        }
-        projectRoot = currentRoot;
-    }
-    if (options.packageId && !options.actions && packages.length === 0) {
-        const root = resolvePackageRoot(options.packageId, undefined, options.customHome);
-        if (!root || !existsSync(root)) {
-            throw new Error(`Package '${options.packageId}' not found in registry`);
-        }
-        packages.push({
-            ...basePkgOpts,
-            packageRoot: root,
-            dataDir: options.dataDir,
-        });
-    }
-    let platform = options.platform;
-    if (!platform && typeof process !== "undefined" && process.versions?.node) {
-        platform = createNodePlatform({
-            customHome: options.customHome,
-            dataDir: options.dataDir,
-            rootDir: projectRoot,
-        });
-    }
-    for (const pkg of packages) {
-        if (typeof pkg === "object" && pkg !== null && !("info" in pkg)) {
-            if (platform && !pkg.platform) {
-                pkg.platform = platform;
-            }
-            if (!pkg.dataDir && options.dataDir) {
-                pkg.dataDir = options.dataDir;
-            }
-        }
-    }
-    const service = await createActionDock({
-        type: "local",
-        projectRoot,
-        packages: packages.length > 0 ? packages : undefined,
-        scanLinkedPackages: Boolean(options.all),
-        hostOptions: {
-            autoLoadCurrentProject: packages.length === 0,
-        },
-        // MCP 服务进程是长驻执行宿主，声明数据目录持有者身份，
-        // 打开时收割遗留孤儿运行记录
-        recoverOrphans: true,
-        customHome: options.customHome,
-        dataDir: options.dataDir,
-        platform,
-    });
-    return { service, ownsService: true };
-}
 /**
  * 创建并配置基于 ActionDockService 的 McpServer 适配层实例。
  */
@@ -263,148 +94,27 @@ export async function createActionDockMcpServer(options = {}) {
         name: serverName,
         version: serverVersion,
     });
-    // 任务规范扩展注册集中隔离在独立模块，本层不再直接操作 SDK 内层实例
-    registerTasksExtension(server, service, allowedPackageIds, options.actionAllowlist);
     // 工具注册与模式映射：tools/list 纯粹委托 service.discovery.listActions()
     let rawActions = await service.discovery.listActions();
-    // 引用解析单点归一：每项仅解析一次，后续各轮（白名单过滤、去重、频次统计、
-    // 工具命名）复用同一结果，避免同一列表对 splitActionRef 的三轮重复调用；
-    // 显式 packageId 与解析所得 packageId 分别留存，各轮按既有优先级消费
-    const parsedRefs = new Map();
-    for (const act of rawActions) {
-        if (act.id.includes("/")) {
-            const parsed = splitActionRef(act.id);
-            parsedRefs.set(act, {
-                explicitPkgId: act.packageId || "",
-                parsedPkgId: parsed.packageId,
-                baseId: parsed.actionId,
-            });
-        }
-        else {
-            parsedRefs.set(act, { explicitPkgId: act.packageId || "", baseId: act.id });
-        }
-    }
-    if (allowedPackageIds && allowedPackageIds.length > 0) {
-        // 白名单轮：显式 packageId 优先，缺失时回退解析所得
-        rawActions = rawActions.filter((act) => {
-            const ref = parsedRefs.get(act);
-            const pkgId = ref.explicitPkgId || ref.parsedPkgId || "";
-            return pkgId ? allowedPackageIds.includes(pkgId) : false;
-        });
-    }
-    if (options.actionAllowlist && options.actionAllowlist.length > 0) {
-        rawActions = rawActions.filter((act) => {
-            const ref = parsedRefs.get(act);
-            const pkgId = ref.explicitPkgId || ref.parsedPkgId || undefined;
-            return isActionAllowed({ packageId: pkgId, actionId: ref.baseId }, options.actionAllowlist);
-        });
-    }
-    const seenActionKeys = new Map();
-    for (const act of rawActions) {
-        const ref = parsedRefs.get(act);
-        const pkgId = ref.explicitPkgId || ref.parsedPkgId || "";
-        const key = `${pkgId}:${ref.baseId}`;
-        const existing = seenActionKeys.get(key);
-        if (existing) {
-            // 若已存在的项是全限定名（含 /），而当前项是短名（不含 /），优先保留短名项
-            if (existing.id.includes("/") && !act.id.includes("/")) {
-                seenActionKeys.set(key, act);
-            }
-        }
-        else {
-            seenActionKeys.set(key, act);
-        }
-    }
-    const actions = Array.from(seenActionKeys.values());
-    // 统计 Action 基础 ID 出现频次，用于同名冲突命名空间隔离
-    const baseCounts = new Map();
-    for (const act of actions) {
-        const baseId = parsedRefs.get(act).baseId;
-        baseCounts.set(baseId, (baseCounts.get(baseId) || 0) + 1);
-    }
-    const registeredToolNames = new Set();
-    // 多包判定（循环外一次算清）：不同 packageId 去重计数大于 1，
-    // 或任一 id 含斜杠（跨包限定名形态），则工具描述需附全限定 id 锚点；
-    // 本轮与工具命名轮一致：解析所得 packageId 优先，缺失时回退显式声明
-    const distinctPackageIds = new Set(actions
-        .map((a) => {
-        const ref = parsedRefs.get(a);
-        return ref.parsedPkgId || a.packageId;
-    })
-        .filter((pkg) => Boolean(pkg)));
-    const isMultiPackage = distinctPackageIds.size > 1 || actions.some((a) => a.id.includes("/"));
-    for (const action of actions) {
-        const ref = parsedRefs.get(action);
-        const baseId = ref.baseId;
-        const packageId = ref.parsedPkgId || action.packageId;
-        const count = baseCounts.get(baseId) || 1;
-        let toolName = baseId;
-        if (count > 1 && packageId) {
-            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
-            toolName = `${cleanPkgId}_${baseId}`;
-        }
-        else if (toolName.includes("/") && packageId) {
-            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
-            toolName = `${cleanPkgId}_${baseId}`;
-        }
-        if (toolName.length > 64) {
-            const hash = createHash("sha256").update(toolName).digest("hex").slice(0, 8);
-            toolName = `${toolName.slice(0, 55)}_${hash}`;
-        }
-        if (registeredToolNames.has(toolName)) {
-            throw toolNameCollisionError(toolName);
-        }
-        registeredToolNames.add(toolName);
-        const description = isMultiPackage
-            ? `[${action.id}] ${action.description || ""}`.trim()
-            : action.description;
-        // 工具执行：tools/call 委托 service.execution.run() 或 service.execution.start()
+    const mappedActions = mapAndFilterActions(rawActions, allowedPackageIds, options.actionAllowlist);
+    for (const { toolName, action, description } of mappedActions) {
+        // 工具执行：tools/call 委托 service.execution.run()
         server.registerTool(toolName, {
             description,
             inputSchema: toMcpSchema(action.inputSchema),
-            // 出参 schema 不注入 execution 包装字段：实际 structuredContent 不含该字段，注入会与真实返回结构不符
             outputSchema: action.outputSchema
-                ? toMcpSchema(action.outputSchema, false)
+                ? toMcpSchema(action.outputSchema)
                 : undefined,
         }, async (input, ctx) => {
-            // 异步执行模式只认显式约定字段 execution.mode，旧版 __async 仅作只读兼容探测
-            const isAsync = isAsyncExecutionRequested(input);
             const signal = extractCancelSignal(ctx);
-            // 分发前仅剥离适配层注入的包装字段，业务自有字段（含名为 async 的入参）原样透传
-            const cleanInput = stripExecutionWrapper(input);
-            // 超时组合策略：客户端声明与服务端配置同时存在时取较小值（更防御），
-            // 任一方单独存在则直接生效，双方均缺省时不设置超时
-            const clientTimeoutMs = extractExecutionTimeoutMs(input);
-            const effectiveTimeoutMs = typeof options.timeoutMs === "number" && typeof clientTimeoutMs === "number"
-                ? Math.min(options.timeoutMs, clientTimeoutMs)
-                : clientTimeoutMs ?? options.timeoutMs;
-            if (isAsync) {
-                const ticket = await service.execution.start(action.id, cleanInput, {
-                    signal,
-                    timeoutMs: effectiveTimeoutMs,
-                });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                ok: true,
-                                runId: ticket.runId,
-                                taskId: ticket.runId,
-                                status: "running",
-                            }),
-                        },
-                    ],
-                };
-            }
-            const result = await service.execution.run(action.id, cleanInput, {
+            const effectiveTimeoutMs = resolveExecutionTimeout(options, ctx);
+            const result = await service.execution.run(action.id, input, {
                 signal,
                 timeoutMs: effectiveTimeoutMs,
             });
             return toMcpResult(result);
         });
     }
-    // 任务规范映射（tasks/get、tasks/cancel、tasks/list）已收敛至 registerTasksExtension 隔离模块
     // 资源与规程映射：规程映射为只读 MCP Resource 与 Prompt
     try {
         let playbooks = await service.discovery.listPlaybooks();

package/dist/execution-mode.d.ts

@@ -1,37 +1,18 @@
 /**
- * MCP 工具调用的异步执行模式探测与包装字段剥离。
- *
- * 单一显式约定：异步执行模式只认 input.execution.mode === "async"。
- * 旧版魔法字段（__async 布尔）保留只读兼容探测，但不再参与 schema 注入，
- * 也不再吞没业务自有的 async 入参字段：
- * - 探测阶段仅读取 execution.mode 与 __async，语义不变；
- * - 剥离阶段仅删除适配层实际注入的包装字段 execution 与 __async，
- *   名为 async 的业务字段原样透传给 Action。
- *
- * 保留命名空间权衡：`execution` 与 `__async` 是适配层声明的前缀保留字段；
- * 业务 Action 入参若恰好撞名 `__async: true`，会被误判为异步意图并在转发前剥离。
- * 这是旧版兼容通道的已知代价，新代码统一使用 execution.mode 声明异步，
- * 业务字段命名应避开该前缀保留命名空间。
- */
-/**
- * 从工具调用入参中提取显式声明的异步执行模式。
- *
- * @param input 工具调用入参
- * @returns 是否显式声明了异步执行（execution.mode 为 async，或旧版 __async 为 true）
+ * MCP 工具执行选项与调用上下文中的超时控制解析。
  */
-export declare function isAsyncExecutionRequested(input: unknown): boolean;
 /**
- * 剥离适配层注入的执行控制包装字段，返回纯净的业务入参。
- *
- * 仅删除 WRAPPER_KEYS 中声明的包装字段；业务自有字段（含名为 async 的入参）原样保留。
+ * 解析有效的执行超时毫秒数。
  *
- * @param input 工具调用入参
- */
-export declare function stripExecutionWrapper<T>(input: T): T;
-/**
- * 从工具调用入参的 execution 包装字段中提取客户端显式声明的超时时间。
+ * 优先从调用上下文中读取，缺省时回退到选项中的全局配置。
  *
- * @param input 工具调用入参
- * @returns 客户端声明的超时毫秒数，未声明或非法时返回 undefined
+ * @param options MCP 初始化配置选项
+ * @param context 可选的调用上下文
+ * @returns 超时毫秒数，未指定或非法时返回 undefined
  */
-export declare function extractExecutionTimeoutMs(input: unknown): number | undefined;
+export declare function resolveExecutionTimeout(options?: {
+    timeoutMs?: number;
+}, context?: {
+    timeoutMs?: number;
+}): number | undefined;
+export declare const resolveExecutionTimeoutMs: typeof resolveExecutionTimeout;

package/dist/execution-mode.js

@@ -1,84 +1,19 @@
 /**
- * MCP 工具调用的异步执行模式探测与包装字段剥离。
- *
- * 单一显式约定：异步执行模式只认 input.execution.mode === "async"。
- * 旧版魔法字段（__async 布尔）保留只读兼容探测，但不再参与 schema 注入，
- * 也不再吞没业务自有的 async 入参字段：
- * - 探测阶段仅读取 execution.mode 与 __async，语义不变；
- * - 剥离阶段仅删除适配层实际注入的包装字段 execution 与 __async，
- *   名为 async 的业务字段原样透传给 Action。
- *
- * 保留命名空间权衡：`execution` 与 `__async` 是适配层声明的前缀保留字段；
- * 业务 Action 入参若恰好撞名 `__async: true`，会被误判为异步意图并在转发前剥离。
- * 这是旧版兼容通道的已知代价，新代码统一使用 execution.mode 声明异步，
- * 业务字段命名应避开该前缀保留命名空间。
- */
-/** 适配层注入到工具 schema 的执行控制包装字段名集合。 */
-const WRAPPER_KEYS = ["execution", "__async"];
-/**
- * 从工具调用入参中提取显式声明的异步执行模式。
- *
- * @param input 工具调用入参
- * @returns 是否显式声明了异步执行（execution.mode 为 async，或旧版 __async 为 true）
+ * MCP 工具执行选项与调用上下文中的超时控制解析。
  */
-export function isAsyncExecutionRequested(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
-        return false;
-    }
-    const record = input;
-    const execution = record.execution;
-    if (typeof execution === "object" &&
-        execution !== null &&
-        !Array.isArray(execution) &&
-        execution.mode === "async") {
-        return true;
-    }
-    // 旧版魔法字段兼容探测：仅只读，不再注入 schema 也不再参与剥离以外的影响
-    if (record.__async === true)
-        return true;
-    return false;
-}
 /**
- * 剥离适配层注入的执行控制包装字段，返回纯净的业务入参。
- *
- * 仅删除 WRAPPER_KEYS 中声明的包装字段；业务自有字段（含名为 async 的入参）原样保留。
+ * 解析有效的执行超时毫秒数。
  *
- * @param input 工具调用入参
- */
-export function stripExecutionWrapper(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
-        return input;
-    }
-    const record = input;
-    const hasWrapper = WRAPPER_KEYS.some((key) => key in record);
-    if (!hasWrapper)
-        return input;
-    const rest = {};
-    for (const [key, value] of Object.entries(record)) {
-        if (WRAPPER_KEYS.includes(key))
-            continue;
-        rest[key] = value;
-    }
-    return rest;
-}
-/**
- * 从工具调用入参的 execution 包装字段中提取客户端显式声明的超时时间。
+ * 优先从调用上下文中读取，缺省时回退到选项中的全局配置。
  *
- * @param input 工具调用入参
- * @returns 客户端声明的超时毫秒数，未声明或非法时返回 undefined
+ * @param options MCP 初始化配置选项
+ * @param context 可选的调用上下文
+ * @returns 超时毫秒数，未指定或非法时返回 undefined
  */
-export function extractExecutionTimeoutMs(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
-        return undefined;
-    }
-    const execution = input.execution;
-    if (typeof execution !== "object" ||
-        execution === null ||
-        Array.isArray(execution)) {
-        return undefined;
-    }
-    const timeoutMs = execution.timeoutMs;
+export function resolveExecutionTimeout(options, context) {
+    const timeoutMs = context?.timeoutMs ?? options?.timeoutMs;
     return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
         ? timeoutMs
         : undefined;
 }
+export const resolveExecutionTimeoutMs = resolveExecutionTimeout;

package/dist/http.js

@@ -1,4 +1,4 @@
-import { ACTIONDOCK_VERSION, UNAUTHORIZED } from "@actiondock/core";
+import { ACCESS_DENIED, ACTIONDOCK_VERSION, ActionDockError, UNAUTHORIZED } from "@actiondock/core";
 import { createMcpEndpointHandler, formatHostForUrl, isLoopbackHost, launchHttpServer, resolveCorsHeaders, verifyBearerToken, } from "@actiondock/core/server";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { createActionDockMcpServer, resolveService } from "./adapter.js";
@@ -21,7 +21,7 @@ export function startMcpHttpServer(options = {}) {
     }
     // Non-loopback address requires token authentication by default
     if (!isLoopbackHost(host) && !token && !options.allowInsecureNoAuth) {
-        throw new Error("Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
+        throw new ActionDockError(ACCESS_DENIED, "Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
     }
     return (async () => {
         // 先一次性解析 service，工厂闭包直接捕获已解析产物，消除选项重复展开

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 export * from "./types.js";
 export * from "./schemas.js";
 export * from "./execution-mode.js";
-export { toMcpTaskStatus, toMcpTaskPayload, type McpTaskStatus, type McpTaskPayload } from "./register-tasks-extension.js";
 export * from "./adapter.js";
 export * from "./stdio.js";
 export * from "./http.js";

package/dist/index.js

@@ -1,8 +1,6 @@
 export * from "./types.js";
 export * from "./schemas.js";
 export * from "./execution-mode.js";
-// 任务规范纯函数迁入 register-tasks-extension 后，从此处转引保持包根导出面不变
-export { toMcpTaskStatus, toMcpTaskPayload } from "./register-tasks-extension.js";
 export * from "./adapter.js";
 export * from "./stdio.js";
 export * from "./http.js";

package/dist/schemas.d.ts

@@ -4,8 +4,5 @@ import type { JsonSchema } from "@actiondock/sdk";
  * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
  *
  * @param schema 原始 JSON Schema 定义
- * @param injectExecution 是否向 schema 注入适配层的 execution 执行控制包装字段：
- *   入参 schema 需要注入（客户端借此声明执行模式与超时），
- *   出参 schema 不注入（实际 structuredContent 不含该字段，注入会与真实返回结构不符）
  */
-export declare function toMcpSchema(schema?: JsonSchema, injectExecution?: boolean): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;
+export declare function toMcpSchema(schema?: JsonSchema): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;

package/dist/schemas.js

@@ -4,11 +4,8 @@ import { fromJsonSchema } from "@modelcontextprotocol/server";
  * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
  *
  * @param schema 原始 JSON Schema 定义
- * @param injectExecution 是否向 schema 注入适配层的 execution 执行控制包装字段：
- *   入参 schema 需要注入（客户端借此声明执行模式与超时），
- *   出参 schema 不注入（实际 structuredContent 不含该字段，注入会与真实返回结构不符）
  */
-export function toMcpSchema(schema, injectExecution = true) {
+export function toMcpSchema(schema) {
     if (schema === undefined || schema === true) {
         return fromJsonSchema({});
     }
@@ -19,17 +16,5 @@ export function toMcpSchema(schema, injectExecution = true) {
     }
     // JSON Schema 为纯数据结构，structuredClone 深拷贝避免污染调用方原始定义；布尔分支已穷尽，收窄为对象模式
     const cloned = structuredClone(schema);
-    const properties = (cloned.properties ?? {});
-    if ((cloned.type === "object" || cloned.properties) && injectExecution) {
-        cloned.properties = properties;
-        properties.execution = {
-            type: "object",
-            description: "Execution options",
-            properties: {
-                mode: { type: "string", enum: ["sync", "async"] },
-                timeoutMs: { type: "number" },
-            },
-        };
-    }
     return fromJsonSchema(cloned);
 }

package/dist/service-resolver.d.ts

@@ -0,0 +1,9 @@
+import { type ActionDockService } from "@actiondock/core";
+import type { ActionDockMcpOptions } from "./types.js";
+/**
+ * 解析或基于选项创建底层 ActionDockService 统一门面。
+ */
+export declare function resolveService(options: ActionDockMcpOptions): Promise<{
+    service: ActionDockService;
+    ownsService: boolean;
+}>;

package/dist/service-resolver.js

@@ -0,0 +1,142 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ACTIONDOCK_VERSION, ActionDockError, createActionDock, createNodePlatform, findProjectRoot, PACKAGE_NOT_FOUND, PROJECT_ROOT_NOT_FOUND, } from "@actiondock/core";
+import { createActionDockHost } from "@actiondock/core/server";
+import { resolvePackageRoot } from "@actiondock/core/registry";
+import { createNonClosingStorageView } from "@actiondock/core/package";
+/**
+ * 解析或基于选项创建底层 ActionDockService 统一门面。
+ */
+export async function resolveService(options) {
+    if (options.service) {
+        return { service: options.service, ownsService: false };
+    }
+    if (options.host) {
+        return { service: options.host, ownsService: false };
+    }
+    if (options.runtime) {
+        const host = await createActionDockHost({
+            autoLoadCurrentProject: false,
+            scanLinkedPackages: false,
+        });
+        host.registerRuntime(options.runtime);
+        return { service: host, ownsService: false };
+    }
+    const packages = [];
+    // 外部注入的 storage 生命周期默认由注入方管理，适配层仅委托读写不接管关闭
+    // （非接管视图复用 core 单一事实源）；显式声明 ownStorageLifecycle 时透传
+    // 原始实例，随 target.close() 级联关闭
+    const appStorage = options.storage
+        ? options.ownStorageLifecycle
+            ? options.storage
+            : createNonClosingStorageView(options.storage)
+        : undefined;
+    // 多分支共享的包选项基底单点构造：storage 视图、家目录与配置覆写
+    // 在此收敛一次，各 push 分支仅叠加自身特有字段
+    const basePkgOpts = {
+        ...(appStorage ? { storage: appStorage } : {}),
+        customHome: options.customHome,
+        configOverrides: options.configOverrides,
+    };
+    if (options.actions) {
+        packages.push({
+            ...basePkgOpts,
+            projectConfig: {
+                id: options.packageId || "default",
+                name: options.packageId || "default",
+                version: ACTIONDOCK_VERSION,
+            },
+            actions: options.actions,
+            inMemory: true,
+        });
+    }
+    if (options.projectRoots && options.projectRoots.length > 0) {
+        for (const root of options.projectRoots) {
+            const abs = resolve(root);
+            const detected = findProjectRoot(abs);
+            if (!detected) {
+                throw new ActionDockError(PROJECT_ROOT_NOT_FOUND, `Project root '${root}' is not a valid ActionDock package (actiondock.json not found)`);
+            }
+            packages.push({
+                ...basePkgOpts,
+                packageRoot: detected,
+            });
+        }
+    }
+    const targetPackageIds = options.packageIds || options.packageAllowlist;
+    if (targetPackageIds && targetPackageIds.length > 0) {
+        for (const pkgId of targetPackageIds) {
+            const root = resolvePackageRoot(pkgId, undefined, options.customHome);
+            if (!root || !existsSync(root)) {
+                throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${pkgId}' not found in registry`);
+            }
+            packages.push({
+                ...basePkgOpts,
+                packageRoot: root,
+            });
+        }
+    }
+    let projectRoot = options.projectRoot;
+    if (options.projectRoot) {
+        const abs = resolve(options.projectRoot);
+        const detected = findProjectRoot(abs);
+        if (!detected) {
+            throw new ActionDockError(PROJECT_ROOT_NOT_FOUND, `Project root '${options.projectRoot}' is not a valid ActionDock package (actiondock.json not found)`);
+        }
+        projectRoot = detected;
+    }
+    if (!projectRoot &&
+        packages.length === 0 &&
+        !options.all &&
+        !options.packageId) {
+        const currentRoot = findProjectRoot(process.cwd());
+        if (!currentRoot) {
+            throw new ActionDockError(PROJECT_ROOT_NOT_FOUND, "No ActionDock project root found. Run inside an ActionDock package or specify --dir / --package / --all.");
+        }
+        projectRoot = currentRoot;
+    }
+    if (options.packageId && !options.actions && packages.length === 0) {
+        const root = resolvePackageRoot(options.packageId, undefined, options.customHome);
+        if (!root || !existsSync(root)) {
+            throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${options.packageId}' not found in registry`);
+        }
+        packages.push({
+            ...basePkgOpts,
+            packageRoot: root,
+            dataDir: options.dataDir,
+        });
+    }
+    let platform = options.platform;
+    if (!platform && typeof process !== "undefined" && process.versions?.node) {
+        platform = createNodePlatform({
+            customHome: options.customHome,
+            dataDir: options.dataDir,
+        });
+    }
+    for (const pkg of packages) {
+        if (typeof pkg === "object" && pkg !== null && !("info" in pkg)) {
+            if (platform && !pkg.platform) {
+                pkg.platform = platform;
+            }
+            if (!pkg.dataDir && options.dataDir) {
+                pkg.dataDir = options.dataDir;
+            }
+        }
+    }
+    const service = await createActionDock({
+        type: "local",
+        projectRoot,
+        packages: packages.length > 0 ? packages : undefined,
+        scanLinkedPackages: Boolean(options.all),
+        hostOptions: {
+            autoLoadCurrentProject: packages.length === 0,
+        },
+        // MCP 服务进程是长驻执行宿主，声明数据目录持有者身份，
+        // 打开时收割遗留孤儿运行记录
+        recoverOrphans: true,
+        customHome: options.customHome,
+        dataDir: options.dataDir,
+        platform,
+    });
+    return { service, ownsService: true };
+}

package/dist/stdio.js

@@ -52,8 +52,6 @@ export async function startMcpStdio(options = {}) {
         // 标准输出物理隔离与受控限流排空转入 stderr 诊断流
         serviceToUse = new IpcActionDockService({
             childProcess,
-            maxDiagnosticBytes: 512 * 1024,
-            maxDiagnosticRate: 64 * 1024,
             diagnosticTarget: process.stderr,
         });
         // IPC 代理实例由本入口创建，生命周期归本入口的 cleanup 所有

package/dist/tool-mapper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 构造携带结构化错误码的工具名冲突异常。
+ *
+ * @param toolName 冲突的工具名
+ */
+export declare function toolNameCollisionError(toolName: string): Error & {
+    code: string;
+};
+/**
+ * 解析 Action 引用字符串为包标识与动作标识（容错语义）。
+ *
+ * 委派 core 的 parseActionRef 单一事实源完成解析；非法形态（如尾部斜杠、
+ * 含冒号等）回退为整体短名处理，与适配层既有的注册容错行为保持一致，
+ * 不让目录聚合阶段的脏数据中断服务启动。
+ */
+export declare function splitActionRef(ref: string): {
+    packageId?: string;
+    actionId: string;
+};
+export interface MappedAction<T> {
+    toolName: string;
+    action: T;
+    isMultiPackage: boolean;
+    description?: string;
+}
+/**
+ * 映射与过滤工具，处理冲突检测、去重、白名单过滤及 SHA-256 截断散列逻辑。
+ */
+export declare function mapAndFilterActions<T extends {
+    id: string;
+    packageId?: string;
+    description?: string;
+}>(rawActions: T[], allowedPackageIds?: string[], actionAllowlist?: string[]): MappedAction<T>[];

package/dist/tool-mapper.js

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { MCP_TOOL_NAME_COLLISION } from "@actiondock/core";
+import { parseActionRef } from "@actiondock/core/graph";
+import { isActionAllowed } from "@actiondock/core/server";
+/**
+ * 构造携带结构化错误码的工具名冲突异常。
+ *
+ * @param toolName 冲突的工具名
+ */
+export function toolNameCollisionError(toolName) {
+    const err = new Error(`MCP tool name collision detected for tool '${toolName}'`);
+    err.code = MCP_TOOL_NAME_COLLISION;
+    return err;
+}
+/**
+ * 解析 Action 引用字符串为包标识与动作标识（容错语义）。
+ *
+ * 委派 core 的 parseActionRef 单一事实源完成解析；非法形态（如尾部斜杠、
+ * 含冒号等）回退为整体短名处理，与适配层既有的注册容错行为保持一致，
+ * 不让目录聚合阶段的脏数据中断服务启动。
+ */
+export function splitActionRef(ref) {
+    try {
+        return parseActionRef(ref);
+    }
+    catch {
+        return { actionId: ref };
+    }
+}
+/**
+ * 映射与过滤工具，处理冲突检测、去重、白名单过滤及 SHA-256 截断散列逻辑。
+ */
+export function mapAndFilterActions(rawActions, allowedPackageIds, actionAllowlist) {
+    // 引用解析单点归一：每项仅解析一次，后续各轮（白名单过滤、去重、频次统计、
+    // 工具命名）复用同一结果，避免同一列表对 splitActionRef 的三轮重复调用；
+    // 显式 packageId 与解析所得 packageId 分别留存，各轮按既有优先级消费
+    const parsedRefs = new Map();
+    for (const act of rawActions) {
+        if (act.id.includes("/")) {
+            const parsed = splitActionRef(act.id);
+            parsedRefs.set(act, {
+                explicitPkgId: act.packageId || "",
+                parsedPkgId: parsed.packageId,
+                baseId: parsed.actionId,
+            });
+        }
+        else {
+            parsedRefs.set(act, { explicitPkgId: act.packageId || "", baseId: act.id });
+        }
+    }
+    if (allowedPackageIds && allowedPackageIds.length > 0) {
+        // 白名单轮：显式 packageId 优先，缺失时回退解析所得
+        rawActions = rawActions.filter((act) => {
+            const ref = parsedRefs.get(act);
+            const pkgId = ref.explicitPkgId || ref.parsedPkgId || "";
+            return pkgId ? allowedPackageIds.includes(pkgId) : false;
+        });
+    }
+    if (actionAllowlist && actionAllowlist.length > 0) {
+        rawActions = rawActions.filter((act) => {
+            const ref = parsedRefs.get(act);
+            const pkgId = ref.explicitPkgId || ref.parsedPkgId || undefined;
+            return isActionAllowed({ packageId: pkgId, actionId: ref.baseId }, actionAllowlist);
+        });
+    }
+    const seenActionKeys = new Map();
+    for (const act of rawActions) {
+        const ref = parsedRefs.get(act);
+        const pkgId = ref.explicitPkgId || ref.parsedPkgId || "";
+        const key = `${pkgId}:${ref.baseId}`;
+        const existing = seenActionKeys.get(key);
+        if (existing) {
+            // 若已存在的项是全限定名（含 /），而当前项是短名（不含 /），优先保留短名项
+            if (existing.id.includes("/") && !act.id.includes("/")) {
+                seenActionKeys.set(key, act);
+            }
+        }
+        else {
+            seenActionKeys.set(key, act);
+        }
+    }
+    const actions = Array.from(seenActionKeys.values());
+    // 统计 Action 基础 ID 出现频次，用于同名冲突命名空间隔离
+    const baseCounts = new Map();
+    for (const act of actions) {
+        const baseId = parsedRefs.get(act).baseId;
+        baseCounts.set(baseId, (baseCounts.get(baseId) || 0) + 1);
+    }
+    const registeredToolNames = new Set();
+    // 多包判定（循环外一次算清）：不同 packageId 去重计数大于 1，
+    // 或任一 id 含斜杠（跨包限定名形态），则工具描述需附全限定 id 锚点；
+    // 本轮与工具命名轮一致：解析所得 packageId 优先，缺失时回退显式声明
+    const distinctPackageIds = new Set(actions
+        .map((a) => {
+        const ref = parsedRefs.get(a);
+        return ref.parsedPkgId || a.packageId;
+    })
+        .filter((pkg) => Boolean(pkg)));
+    const isMultiPackage = distinctPackageIds.size > 1 || actions.some((a) => a.id.includes("/"));
+    const mappedActions = [];
+    for (const action of actions) {
+        const ref = parsedRefs.get(action);
+        const baseId = ref.baseId;
+        const packageId = ref.parsedPkgId || action.packageId;
+        const count = baseCounts.get(baseId) || 1;
+        let toolName = baseId;
+        if (count > 1 && packageId) {
+            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
+            toolName = `${cleanPkgId}_${baseId}`;
+        }
+        else if (toolName.includes("/") && packageId) {
+            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
+            toolName = `${cleanPkgId}_${baseId}`;
+        }
+        if (toolName.length > 64) {
+            const hash = createHash("sha256").update(toolName).digest("hex").slice(0, 8);
+            toolName = `${toolName.slice(0, 55)}_${hash}`;
+        }
+        if (registeredToolNames.has(toolName)) {
+            throw toolNameCollisionError(toolName);
+        }
+        registeredToolNames.add(toolName);
+        const description = isMultiPackage
+            ? `[${action.id}] ${action.description || ""}`.trim()
+            : action.description;
+        mappedActions.push({ toolName, action, isMultiPackage, description });
+    }
+    return mappedActions;
+}

package/dist/types.d.ts

@@ -60,8 +60,6 @@ export interface ActionDockMcpOptions {
      */
     cascadeServiceClose?: boolean;
 }
-/** ActionDock MCP 适配层初始化选项别名 */
-export type ActionDockMcpServerOptions = ActionDockMcpOptions;
 /**
  * HTTP 传输协议安全配置项。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/mcp",
-  "version": "2.9.1",
+  "version": "2.11.0",
   "description": "ActionDock MCP Adapter for exposing Actions as Model Context Protocol (MCP) Tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.9.1",
-    "@actiondock/sdk": "^2.9.1",
+    "@actiondock/core": "^2.11.0",
+    "@actiondock/sdk": "^2.11.0",
     "@modelcontextprotocol/server": "^2.0.0"
   },
   "devDependencies": {

package/dist/register-tasks-extension.d.ts

@@ -1,34 +0,0 @@
-import type { ActionDockService } from "@actiondock/core";
-import type { RunRecord, RunStatus } from "@actiondock/sdk";
-import { McpServer } from "@modelcontextprotocol/server";
-/**
- * MCP 任务状态枚举（兼容 Model Context Protocol Task 规范）。
- */
-export type McpTaskStatus = "working" | "completed" | "failed" | "cancelled";
-/**
- * MCP 任务状态数据载荷结构体。
- */
-export interface McpTaskPayload {
-    taskId: string;
-    status: McpTaskStatus;
-    createdAt: string;
-    finishedAt?: string;
-    input?: unknown;
-    output?: unknown;
-    error?: unknown;
-}
-/**
- * 将 ActionDock 内部的 RunStatus 转换为 MCP 标准的 TaskStatus。
- */
-export declare function toMcpTaskStatus(status: RunStatus): McpTaskStatus;
-/**
- * 将内部 RunRecord 实体转换为向 MCP 客户端暴露的 McpTaskPayload。
- */
-export declare function toMcpTaskPayload(run: RunRecord): McpTaskPayload;
-/**
- * 在低层 Server 实例上注册 tasks 能力声明与三个请求处理器。
- *
- * @param server MCP 高层服务实例
- * @param service ActionDockService 公共服务实例
- */
-export declare function registerTasksExtension(server: McpServer, service: ActionDockService, allowedPackageIds?: string[], actionAllowlist?: string[]): void;

package/dist/register-tasks-extension.js

@@ -1,171 +0,0 @@
-import { isActionAllowed } from "@actiondock/core/server";
-import { fromJsonSchema } from "@modelcontextprotocol/server";
-/**
- * 将 ActionDock 内部的 RunStatus 转换为 MCP 标准的 TaskStatus。
- */
-export function toMcpTaskStatus(status) {
-    switch (status) {
-        case "running":
-            return "working";
-        case "success":
-            return "completed";
-        case "failed":
-        case "timed_out":
-        case "interrupted":
-            return "failed";
-        case "cancelled":
-            return "cancelled";
-        default:
-            return "failed";
-    }
-}
-/**
- * 将内部 RunRecord 实体转换为向 MCP 客户端暴露的 McpTaskPayload。
- */
-export function toMcpTaskPayload(run) {
-    return {
-        taskId: run.id,
-        status: toMcpTaskStatus(run.status),
-        createdAt: run.startedAt,
-        finishedAt: run.finishedAt,
-        input: run.input,
-        output: run.output,
-        error: run.error,
-    };
-}
-/** JSON-RPC 保留码段：协议保留区为 -32000 至 -32099，服务端自定义错误码必须落在该区段内。 */
-const TASK_NOT_FOUND_CODE = -32001;
-/** 无效的 limit 参数错误码，同样落在服务端自定义码段。 */
-const INVALID_LIMIT_CODE = -32002;
-/** tasks/list 允许的最大单页数量上限。 */
-const MAX_TASK_LIST_LIMIT = 500;
-/**
- * 构造携带 JSON-RPC 语义码的任务不存在异常。
- *
- * MCP SDK 对处理器抛出的异常会读取数字型 code 字段并原样透传到错误响应，
- * 裸 Error 缺少 code 会被映射为内部错误（-32603），丢失调用方可分辨的语义。
- *
- * @param taskId 未找到的任务标识
- */
-function taskNotFoundError(taskId) {
-    return Object.assign(new Error(`Task '${taskId}' not found`), { code: TASK_NOT_FOUND_CODE });
-}
-/**
- * 构造携带 JSON-RPC 语义码的非法 limit 参数异常。
- *
- * @param limit 非法的 limit 入参
- */
-function invalidLimitError(limit) {
-    return Object.assign(new Error(`Invalid tasks/list limit: expected an integer between 1 and ${MAX_TASK_LIST_LIMIT}, got ${JSON.stringify(limit)}`), { code: INVALID_LIMIT_CODE });
-}
-const TASK_ID_PARAMS = fromJsonSchema({
-    type: "object",
-    properties: {
-        taskId: { type: "string" },
-        reason: { type: "string" },
-    },
-    required: ["taskId"],
-});
-const TASK_LIST_PARAMS = fromJsonSchema({
-    type: "object",
-    properties: {
-        limit: { type: "number" },
-        actionId: { type: "string" },
-    },
-});
-/**
- * 将内部 RunRecord 的 ISO 时间字符串转为毫秒时间戳，用于任务排序比较。
- *
- * @param value 待解析的时间字符串
- */
-function toTimeMillis(value) {
-    const parsed = Date.parse(value);
-    return Number.isNaN(parsed) ? 0 : parsed;
-}
-/**
- * 在低层 Server 实例上注册 tasks 能力声明与三个请求处理器。
- *
- * @param server MCP 高层服务实例
- * @param service ActionDockService 公共服务实例
- */
-export function registerTasksExtension(server, service, allowedPackageIds, actionAllowlist) {
-    server.server.registerCapabilities({
-        tasks: {
-            list: {},
-            cancel: {},
-        },
-    });
-    server.server.setRequestHandler("tasks/get", { params: TASK_ID_PARAMS }, async (params) => {
-        const run = await service.runs.get(params.taskId);
-        if (!run) {
-            // 携带语义码透传，避免被 SDK 映射为内部错误
-            throw taskNotFoundError(params.taskId);
-        }
-        if (allowedPackageIds &&
-            allowedPackageIds.length > 0 &&
-            (!run.packageId || !allowedPackageIds.includes(run.packageId))) {
-            throw taskNotFoundError(params.taskId);
-        }
-        if (actionAllowlist &&
-            actionAllowlist.length > 0 &&
-            !isActionAllowed({ packageId: run.packageId, actionId: run.actionId }, actionAllowlist)) {
-            throw taskNotFoundError(params.taskId);
-        }
-        return { task: toMcpTaskPayload(run) };
-    });
-    server.server.setRequestHandler("tasks/cancel", { params: TASK_ID_PARAMS }, async (params) => {
-        const hasPackageFilter = Boolean(allowedPackageIds && allowedPackageIds.length > 0);
-        const hasActionFilter = Boolean(actionAllowlist && actionAllowlist.length > 0);
-        if (hasPackageFilter || hasActionFilter) {
-            const existingRun = await service.runs.get(params.taskId);
-            if (!existingRun) {
-                throw taskNotFoundError(params.taskId);
-            }
-            if (hasPackageFilter) {
-                if (!existingRun.packageId || !allowedPackageIds.includes(existingRun.packageId)) {
-                    throw taskNotFoundError(params.taskId);
-                }
-            }
-            if (hasActionFilter) {
-                if (!isActionAllowed({ packageId: existingRun.packageId, actionId: existingRun.actionId }, actionAllowlist)) {
-                    throw taskNotFoundError(params.taskId);
-                }
-            }
-        }
-        const reason = params.reason || "Cancelled via MCP tasks/cancel";
-        const cancelRes = await service.runs.cancel(params.taskId, reason);
-        if (cancelRes.outcome === "requested") {
-            return { taskId: params.taskId, status: "cancelled" };
-        }
-        if (cancelRes.outcome === "already_terminal") {
-            return { taskId: params.taskId, status: toMcpTaskStatus(cancelRes.status) };
-        }
-        const run = await service.runs.get(params.taskId);
-        if (!run) {
-            // 携带语义码透传，避免被 SDK 映射为内部错误
-            throw taskNotFoundError(params.taskId);
-        }
-        return { taskId: params.taskId, status: toMcpTaskStatus(run.status) };
-    });
-    server.server.setRequestHandler("tasks/list", { params: TASK_LIST_PARAMS }, async (params) => {
-        // 边界防御：limit 必须为整数，缺省取 50；超限钳制到 [1, 500]，非法值抛带语义码的参数错误
-        let limit = 50;
-        if (params.limit !== undefined) {
-            if (typeof params.limit !== "number" || !Number.isInteger(params.limit)) {
-                throw invalidLimitError(params.limit);
-            }
-            limit = Math.min(Math.max(params.limit, 1), MAX_TASK_LIST_LIMIT);
-        }
-        const actionId = params.actionId;
-        // limit 单处截断：下推到 service.runs.list 的 limit 参数，此处不再重复 slice
-        let runs = await service.runs.list({ limit, actionId });
-        if (allowedPackageIds && allowedPackageIds.length > 0) {
-            runs = runs.filter((r) => Boolean(r.packageId && allowedPackageIds.includes(r.packageId)));
-        }
-        if (actionAllowlist && actionAllowlist.length > 0) {
-            runs = runs.filter((r) => isActionAllowed({ packageId: r.packageId, actionId: r.actionId }, actionAllowlist));
-        }
-        const ordered = [...runs].sort((a, b) => toTimeMillis(b.startedAt) - toTimeMillis(a.startedAt));
-        return { tasks: ordered.map(toMcpTaskPayload) };
-    });
-}