@actiondock/core 2.7.0 → 2.9.0

package/dist/catalog/resolve-action.js

@@ -0,0 +1,119 @@
+import { ActionDockError, ACTION_NOT_FOUND, INVALID_ACTION_REF, PACKAGE_NOT_FOUND, } from "../errors.js";
+/**
+ * 规范化解析动作引用字符串或对象为 ActionRef。
+ * 铁律：ActionRef 解析只有一个事实源。
+ */
+export function parseActionRef(ref) {
+    if (typeof ref === "object" && ref !== null) {
+        if (!ref.actionId) {
+            throw new ActionDockError(INVALID_ACTION_REF, "INVALID_ACTION_REF: Invalid action identifier: actionId is required");
+        }
+        return ref;
+    }
+    const str = String(ref).trim();
+    if (!str) {
+        throw new ActionDockError(INVALID_ACTION_REF, "INVALID_ACTION_REF: Invalid action identifier: cannot be empty");
+    }
+    if (str.includes("/")) {
+        const lastSlashIndex = str.lastIndexOf("/");
+        const packageId = str.slice(0, lastSlashIndex);
+        const actionId = str.slice(lastSlashIndex + 1);
+        if (!packageId || !actionId || actionId.includes(":") || actionId.includes("/") || actionId.includes("..")) {
+            throw new ActionDockError(INVALID_ACTION_REF, `INVALID_ACTION_REF: Invalid action identifier: '${str}'`);
+        }
+        return { packageId, actionId };
+    }
+    if (str.includes(":")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `INVALID_ACTION_REF: Invalid action identifier: '${str}'`);
+    }
+    return { actionId: str };
+}
+/**
+ * 纯领域动作解析函数 resolveAction。
+ * 铁律：ActionRef 解析只有一个事实源，禁止各模块各自编写短名匹配或启发式搜索。
+ *
+ * 解析次序：
+ * 1. 显式包限定标识符精确查找目标包与动作
+ * 2. 裸标识符优先查找 caller 调用者所在包
+ * 3. 裸标识符全局搜索：单命中返回、多命中抛出歧义异常、零命中抛出未找到异常
+ */
+export function resolveAction(ref, context) {
+    const parsed = parseActionRef(ref);
+    // 1. 显式指定 packageId
+    if (parsed.packageId) {
+        const node = context.graph.packages.get(parsed.packageId);
+        if (!node) {
+            throw new ActionDockError(PACKAGE_NOT_FOUND, `PACKAGE_NOT_FOUND: Package '${parsed.packageId}' not found`);
+        }
+        const matches = context.catalog.find({
+            packageId: parsed.packageId,
+            actionId: parsed.actionId,
+        });
+        if (matches.length === 0) {
+            throw new ActionDockError(ACTION_NOT_FOUND, `ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in package '${parsed.packageId}'`);
+        }
+        const candidate = matches[0];
+        return {
+            ref: {
+                packageId: node.identity.id,
+                packageInstanceId: node.identity.instanceId,
+                actionId: parsed.actionId,
+                generationId: node.identity.generation,
+            },
+            package: node.identity,
+            entry: candidate.entry,
+            contract: candidate.contract,
+        };
+    }
+    // 2. 裸标识符优先匹配 caller 当前包
+    if (context.caller) {
+        const callerId = typeof context.caller === "string" ? context.caller : context.caller.id;
+        const inCaller = context.catalog.find({
+            packageId: callerId,
+            actionId: parsed.actionId,
+        });
+        if (inCaller.length > 0) {
+            const candidate = inCaller[0];
+            const node = context.graph.packages.get(callerId);
+            return {
+                ref: {
+                    packageId: node.identity.id,
+                    packageInstanceId: node.identity.instanceId,
+                    actionId: parsed.actionId,
+                    generationId: node.identity.generation,
+                },
+                package: node.identity,
+                entry: candidate.entry,
+                contract: candidate.contract,
+            };
+        }
+    }
+    // 3. 全局唯一匹配检查
+    const allMatches = context.catalog.find(parsed.actionId);
+    if (allMatches.length === 0) {
+        const message = context.caller
+            ? `ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in current project or any registered package`
+            : `ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in any registered package`;
+        throw new ActionDockError(ACTION_NOT_FOUND, message);
+    }
+    if (allMatches.length > 1) {
+        const candidates = allMatches.map((m) => `${m.packageId}/${m.actionId}`).join(", ");
+        throw new ActionDockError(INVALID_ACTION_REF, `INVALID_ACTION_REF: Action '${parsed.actionId}' is ambiguous and provided by multiple packages: ${candidates}. Please specify '<package-id>/${parsed.actionId}'. (AMBIGUOUS_ACTION_REF)`, {
+            alias: "AMBIGUOUS_ACTION_REF",
+            candidates: allMatches.map((m) => m.packageId),
+        });
+    }
+    const candidate = allMatches[0];
+    const node = context.graph.packages.get(candidate.packageId);
+    return {
+        ref: {
+            packageId: node.identity.id,
+            packageInstanceId: node.identity.instanceId,
+            actionId: parsed.actionId,
+            generationId: node.identity.generation,
+        },
+        package: node.identity,
+        entry: candidate.entry,
+        contract: candidate.contract,
+    };
+}

package/dist/catalog/resolve-playbook.d.ts

@@ -0,0 +1,26 @@
+import type { PlaybookDefinition } from "../project/types.js";
+import type { PackageGraph } from "./graph.js";
+/**
+ * Playbook 解析结果。
+ */
+export interface ResolvedPlaybook {
+    /** 所属包标识 */
+    readonly packageId: string;
+    /** 项目物理根目录绝对路径 */
+    readonly projectRoot: string;
+    /** 规程标识 */
+    readonly playbookId: string;
+    /** 规程定义实体 */
+    readonly playbook: PlaybookDefinition;
+}
+export interface ResolvePlaybookContext {
+    /** 包拓扑图单一事实源 */
+    readonly graph: PackageGraph;
+    /** 调用方所在包标识（可选） */
+    readonly caller?: string;
+}
+/**
+ * 纯领域规程解析函数 resolvePlaybook。
+ * 基于 PackageGraph 替代原 registry 内部的 resolvePlaybookProject 启发式搜索。
+ */
+export declare function resolvePlaybook(identifier: string, context: ResolvePlaybookContext): ResolvedPlaybook;

package/dist/catalog/resolve-playbook.js

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadPlaybooks } from "../project/loader.js";
+import { getPackageSlug } from "../utils/index.js";
+import { ActionDockError, INVALID_ACTION_REF, NOT_FOUND, PACKAGE_NOT_FOUND } from "../errors.js";
+function getNodePlaybooks(node) {
+    const map = new Map();
+    if (node.root && existsSync(node.root)) {
+        try {
+            const diskPlaybooks = loadPlaybooks(node.root, node.manifest?.playbooksDir);
+            for (const [k, v] of diskPlaybooks) {
+                map.set(k, v);
+            }
+        }
+        catch {
+            // 忽略磁盘规程目录扫描异常
+        }
+    }
+    if (node.manifest?.playbooks && typeof node.manifest.playbooks === "object") {
+        for (const [id, item] of Object.entries(node.manifest.playbooks)) {
+            const existing = map.get(id);
+            let content = item.content ?? existing?.content ?? "";
+            let filePath = item.entry && node.root
+                ? resolve(node.root, item.entry)
+                : existing?.filePath;
+            if (!content && filePath && existsSync(filePath)) {
+                try {
+                    content = readFileSync(filePath, "utf-8");
+                }
+                catch { }
+            }
+            map.set(id, {
+                id,
+                description: item.description ?? existing?.description,
+                actions: item.actions ?? existing?.actions ?? [],
+                content,
+                filePath: filePath || "",
+            });
+        }
+    }
+    return map;
+}
+/**
+ * 纯领域规程解析函数 resolvePlaybook。
+ * 基于 PackageGraph 替代原 registry 内部的 resolvePlaybookProject 启发式搜索。
+ */
+export function resolvePlaybook(identifier, context) {
+    const str = identifier.trim();
+    // 1. scoped 形式解析：<package-id>/<playbook-id>
+    if (str.includes("/")) {
+        const lastSlashIndex = str.lastIndexOf("/");
+        const targetPackage = str.slice(0, lastSlashIndex);
+        const playbookId = str.slice(lastSlashIndex + 1);
+        const node = context.graph.packages.get(targetPackage) ||
+            Array.from(context.graph.packages.values()).find((n) => getPackageSlug(n.identity.id) === targetPackage);
+        if (!node) {
+            throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${targetPackage}' not found`);
+        }
+        const playbooks = getNodePlaybooks(node);
+        const playbook = playbooks.get(playbookId);
+        if (!playbook) {
+            throw new ActionDockError(NOT_FOUND, `Playbook '${playbookId}' not found in package '${node.identity.id}' (${node.root})`);
+        }
+        return {
+            packageId: node.identity.id,
+            projectRoot: node.root,
+            playbookId,
+            playbook,
+        };
+    }
+    // 2. 优先在 caller 调用方包中匹配
+    if (context.caller) {
+        const callerNode = context.graph.packages.get(context.caller);
+        if (callerNode) {
+            const playbooks = getNodePlaybooks(callerNode);
+            const pb = playbooks.get(str);
+            if (pb) {
+                return {
+                    packageId: callerNode.identity.id,
+                    projectRoot: callerNode.root,
+                    playbookId: str,
+                    playbook: pb,
+                };
+            }
+        }
+    }
+    // 3. 全局搜索
+    const matches = [];
+    for (const node of context.graph.packages.values()) {
+        try {
+            const playbooks = getNodePlaybooks(node);
+            const pb = playbooks.get(str);
+            if (pb) {
+                matches.push({
+                    packageId: node.identity.id,
+                    projectRoot: node.root,
+                    playbookId: str,
+                    playbook: pb,
+                });
+            }
+        }
+        catch {
+            // 忽略单个包加载异常
+        }
+    }
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        const pkgList = matches.map((m) => `'${m.packageId}'`).join(", ");
+        throw new ActionDockError(INVALID_ACTION_REF, `Playbook '${str}' is provided by multiple linked packages: ${pkgList}. Please specify using '<package-id>/${str}'.`);
+    }
+    throw new ActionDockError(NOT_FOUND, `Playbook '${str}' not found in any registered package`);
+}

package/dist/doctor/checks/project.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { discoverActionFiles, loadActions, loadPlaybooks, loadProjectConfig } from "../../project/loader.js";
 import { loadManifest, MANIFEST_FILE_NAME } from "../../project/manifest.js";
@@ -46,33 +46,52 @@ function checkProjectSdk(scope) {
 }
 /**
  * 检查工程运行时数据库可写性。
+ *
+ * 探测写入独立临时数据库文件，避免对生产运行库产生写副作用：
+ * 体检是诊断行为，不得在真实库上执行写加删事务引入额外写竞争。
  */
 async function checkProjectStorage(scope) {
     const { ctx, config } = scope;
     const dbPath = resolveDatabasePath(config.id, { customHome: ctx.customHome });
+    const probeDir = dirname(dbPath);
+    // 探测库：与生产库同目录但独立命名，结束后整体删除，不留探测残留
+    const probeId = `doctor.probe.${Date.now()}`;
+    const probePkgDir = dirname(resolveDatabasePath(probeId, { customHome: ctx.customHome }));
+    const probeStorage = createStorage(probeId, { customHome: ctx.customHome });
     try {
-        const projectStorage = createStorage(config.id, { customHome: ctx.customHome });
-        await projectStorage.setConfig("_doctor_probe_", "ok");
-        await projectStorage.deleteConfig("_doctor_probe_");
-        projectStorage.close();
+        await probeStorage.setConfig("probe", "ok");
+        probeStorage.close();
         ctx.checks.push({
             id: "project.storage",
             category: "project",
             name: "Project Database",
             status: "ok",
-            message: `Database writable at ${dbPath}`,
+            message: `Database directory writable at ${probeDir}`,
         });
     }
     catch (err) {
+        try {
+            probeStorage.close();
+        }
+        catch { }
         ctx.checks.push({
             id: "project.storage",
             category: "project",
             name: "Project Database",
             status: "error",
-            message: `Failed to write project runtime database: ${err.message}`,
-            fix: `Check write permissions for '${dirname(dbPath)}'`,
+            message: `Failed to write project runtime database directory: ${err.message}`,
+            fix: `Check write permissions for '${probeDir}'`,
         });
     }
+    finally {
+        // 清理探测库目录（含 WAL/SHM 侧车文件）
+        try {
+            if (existsSync(probePkgDir)) {
+                rmSync(probePkgDir, { recursive: true, force: true });
+            }
+        }
+        catch { }
+    }
 }
 /**
  * 检查工程 Actions 可加载性与数量。

package/dist/doctor/checks/registry.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { ActionResolver } from "../../catalog/action-resolver.js";
+import { parseActionRef } from "../../catalog/resolve-action.js";
 import { findProjectRoot, loadProjectConfig } from "../../project/loader.js";
 import { loadManifest } from "../../project/manifest.js";
 import { getRegistryStatus, listLinkedPackages, resolvePackageRoot } from "../../registry/registry.js";
@@ -158,7 +158,7 @@ export const checkUsesClosure = {
                             continue;
                         let parsed;
                         try {
-                            parsed = ActionResolver.parseRef(rawRef);
+                            parsed = parseActionRef(rawRef);
                         }
                         catch {
                             unresolvableUses.push(`${pkg.id}/${actionId} -> '${rawRef}'`);

package/dist/doctor/checks/runtime.js

@@ -1,5 +1,38 @@
-import { findExecutable } from "../../utils/index.js";
+import { findExecutable, parseSemVer } from "../../utils/index.js";
+/**
+ * 比较两个版本字符串（基于 utils.parseSemVer 单一事实源）。
+ *
+ * 行为契约（与历史手写实现逐字节对齐）：
+ * - 双方均为严格三段式语义化版本且无预发布后缀时，按 major/minor/patch 逐段数值比较；
+ * - 其余形态（两段式、带 v 前缀的四段式、携带预发布后缀等）回退到历史宽松语义：
+ *   去 v 前缀后按点分段数值比较，缺段补零、非数值段作零。
+ *   宽松回退保留历史行为的尾段数值比较（预发布后缀的数字段参与比较），
+ *   与 parseSemVer 的严格语义存在刻意差异，不得合并。
+ */
 function compareSemver(v1, v2) {
+    // 预检：parseSemVer 会剥离 = 前缀而历史宽松语义不会（NaN 段作零），
+    // 携带 = 前缀的输入必须回退宽松分支以保持历史行为完全一致。
+    if (v1[0] === "=" || v2[0] === "=") {
+        return compareLooseVersion(v1, v2);
+    }
+    const s1 = parseSemVer(v1);
+    const s2 = parseSemVer(v2);
+    if (s1 && s2 && !s1.prerelease && !s2.prerelease) {
+        if (s1.major !== s2.major)
+            return s1.major > s2.major ? 1 : -1;
+        if (s1.minor !== s2.minor)
+            return s1.minor > s2.minor ? 1 : -1;
+        if (s1.patch !== s2.patch)
+            return s1.patch > s2.patch ? 1 : -1;
+        return 0;
+    }
+    return compareLooseVersion(v1, v2);
+}
+/**
+ * 历史宽松版本比较（去 v 前缀后按点分段数值比较，缺段补零、非数值段作零）。
+ * 仅供 compareSemver 的非严格形态回退分支使用，禁止断开对外直接引用。
+ */
+function compareLooseVersion(v1, v2) {
     const p1 = v1.replace(/^v/, "").split(".").map(Number);
     const p2 = v2.replace(/^v/, "").split(".").map(Number);
     for (let i = 0; i < Math.max(p1.length, p2.length); i++) {

package/dist/errors.d.ts

@@ -29,14 +29,8 @@ export declare const INPUT_NOT_JSON = "INPUT_NOT_JSON";
 export declare const OUTPUT_NOT_JSON = "OUTPUT_NOT_JSON";
 /** 根运行并发子任务数达到上限 */
 export declare const ACTION_SUBRUN_LIMIT = "ACTION_SUBRUN_LIMIT";
-/** 子任务数达限错误的别名标记（details.alias 专用，非独立错误码） */
-export declare const MAX_SUBRUNS_REACHED = "MAX_SUBRUNS_REACHED";
 /** Action 调用链出现环路 */
 export declare const ACTION_CALL_CYCLE = "ACTION_CALL_CYCLE";
-/** 调用链环路检测的别名标记（details.alias 专用，非独立错误码） */
-export declare const ACTION_CYCLE_DETECTED = "ACTION_CYCLE_DETECTED";
-/** 调用链深度超限的别名标记（details.alias 专用，非独立错误码） */
-export declare const ACTION_MAX_DEPTH_EXCEEDED = "ACTION_MAX_DEPTH_EXCEEDED";
 /** 跨包调用未在 uses 中声明依赖 */
 export declare const UNDECLARED_ACTION_DEPENDENCY = "UNDECLARED_ACTION_DEPENDENCY";
 /** Action 引用存在多包歧义 */
@@ -53,14 +47,22 @@ export declare const RUN_REPOSITORY_UNAVAILABLE = "RUN_REPOSITORY_UNAVAILABLE";
 export declare const RUN_PERSISTENCE_FAILED = "RUN_PERSISTENCE_FAILED";
 /** 独立单执行二进制拒绝异步启动语义 */
 export declare const STANDALONE_ASYNC_UNSUPPORTED = "STANDALONE_ASYNC_UNSUPPORTED";
+/** 独立运行模式不支持级联调用 */
+export declare const INVOCATION_UNSUPPORTED = "INVOCATION_UNSUPPORTED";
 /** 宿主子进程已退出，调用无法送达 */
 export declare const HOST_PROCESS_EXITED = "HOST_PROCESS_EXITED";
 /** 调用在启动前已被取消 */
 export declare const EXECUTION_ABORTED = "EXECUTION_ABORTED";
 /** 远程运行等待超时 */
 export declare const TIMEOUT = "TIMEOUT";
+/** 服务已关闭拒绝继续调用 */
+export declare const SERVICE_CLOSED = "SERVICE_CLOSED";
 /** 远程服务器网络连接失败 */
 export declare const NETWORK_ERROR = "NETWORK_ERROR";
+/** 非本地明文 HTTP 传输违规 */
+export declare const INSECURE_TRANSPORT = "INSECURE_TRANSPORT";
+/** 远程 HTTP 请求失败 */
+export declare const REMOTE_REQUEST_FAILED = "REMOTE_REQUEST_FAILED";
 /** 远程事件流全部候选路由均不可用 */
 export declare const REMOTE_STREAM_UNAVAILABLE = "REMOTE_STREAM_UNAVAILABLE";
 /** 远程目标未启用管理接口能力 */
@@ -92,6 +94,72 @@ export declare const UNAUTHORIZED = "UNAUTHORIZED";
 export declare const NOT_FOUND = "NOT_FOUND";
 /** HTTP 服务内部错误 */
 export declare const SERVER_ERROR = "SERVER_ERROR";
+/** HTTP 服务请求非法 */
+export declare const BAD_REQUEST = "BAD_REQUEST";
+/** 目标包未列入允许白名单（403 禁止访问） */
+export declare const PACKAGE_FORBIDDEN = "PACKAGE_FORBIDDEN";
+/** 目标动作未列入允许白名单（403 禁止访问） */
+export declare const ACTION_FORBIDDEN = "ACTION_FORBIDDEN";
+/** 目标规程未找到 */
+export declare const PLAYBOOK_NOT_FOUND = "PLAYBOOK_NOT_FOUND";
+/** 请求体体积超出安全限制 */
+export declare const REQUEST_TOO_LARGE = "REQUEST_TOO_LARGE";
+/** 动作异步启动失败 */
+export declare const ACTION_START_FAILED = "ACTION_START_FAILED";
+/** 动作执行发生内部错误 */
+export declare const ACTION_EXECUTION_ERROR = "ACTION_EXECUTION_ERROR";
+/** 动作列表检索失败 */
+export declare const ACTIONS_LIST_ERROR = "ACTIONS_LIST_ERROR";
+/** 规程列表检索失败 */
+export declare const PLAYBOOKS_LIST_ERROR = "PLAYBOOKS_LIST_ERROR";
+/** 运行记录列表检索失败 */
+export declare const RUNS_LIST_ERROR = "RUNS_LIST_ERROR";
+/** 运行记录清空操作失败 */
+export declare const RUNS_CLEAR_ERROR = "RUNS_CLEAR_ERROR";
+/** 服务大纲信息自省失败 */
+export declare const INFO_ERROR = "INFO_ERROR";
+/** 包信息检索失败 */
+export declare const PACKAGES_INFO_ERROR = "PACKAGES_INFO_ERROR";
+/** 环境诊断体检执行失败 */
+export declare const DOCTOR_ERROR = "DOCTOR_ERROR";
+/** 运行由于服务中断或异常退出被置为中断态 */
+export declare const RUN_INTERRUPTED = "RUN_INTERRUPTED";
+/** 配置项环境变量生成失败 */
+export declare const CONFIG_ENV_ERROR = "CONFIG_ENV_ERROR";
+/** 配置项列表检索失败 */
+export declare const CONFIG_LIST_ERROR = "CONFIG_LIST_ERROR";
+/** 配置项写入失败 */
+export declare const CONFIG_SET_ERROR = "CONFIG_SET_ERROR";
+/** 配置项删除失败 */
+export declare const CONFIG_DELETE_ERROR = "CONFIG_DELETE_ERROR";
+/** 状态条目列表检索失败 */
+export declare const STATE_LIST_ERROR = "STATE_LIST_ERROR";
+/** 状态清空操作失败 */
+export declare const STATE_CLEAR_ERROR = "STATE_CLEAR_ERROR";
+/** 状态键操作异常 */
+export declare const STATE_KEY_ERROR = "STATE_KEY_ERROR";
+/** 数据目录已被其他活跃会话持有 */
+export declare const DATA_DIR_IN_USE = "DATA_DIR_IN_USE";
+/** 数据目录存在未完成的事务，需执行恢复 */
+export declare const DATA_DIR_RECOVERY_REQUIRED = "DATA_DIR_RECOVERY_REQUIRED";
+/** 存储底层 Schema 版本不受支持 */
+export declare const UNSUPPORTED_STORAGE_SCHEMA = "UNSUPPORTED_STORAGE_SCHEMA";
+/** 持久化运行错误对象反序列化解码失败 */
+export declare const STORED_ERROR_DECODE_FAILED = "STORED_ERROR_DECODE_FAILED";
+/** 子进程执行失败终结 */
+export declare const PROCESS_FAILED = "PROCESS_FAILED";
+/** 生成的类型定义已过期 */
+export declare const GENERATED_TYPES_OUTDATED = "GENERATED_TYPES_OUTDATED";
+/** 通信协议版本或格式不受支持 */
+export declare const PROTOCOL_UNSUPPORTED = "PROTOCOL_UNSUPPORTED";
+/** 服务调用结果未知 */
+export declare const SERVICE_RESULT_UNKNOWN = "SERVICE_RESULT_UNKNOWN";
+/** MCP 工具命名发生冲突 */
+export declare const MCP_TOOL_NAME_COLLISION = "MCP_TOOL_NAME_COLLISION";
+/** 跨进程 IPC 通信或调用异常 */
+export declare const IPC_ERROR = "IPC_ERROR";
+/** 服务调用层内部异常回退错误码 */
+export declare const SERVICE_ERROR = "SERVICE_ERROR";
 /**
  * 判定错误消息根因是否为依赖模块缺失。
  * 兼容 Node.js 与打包器（Bun 等）两类加载器的报错文案。
@@ -172,11 +240,39 @@ export declare const INPUT_CONFLICT = "INPUT_CONFLICT";
 export declare const INPUT_FILE_NOT_FOUND = "INPUT_FILE_NOT_FOUND";
 /** 输入文件或流读取失败 */
 export declare const INPUT_FILE_READ_FAILED = "INPUT_FILE_READ_FAILED";
+/** 命令参数或选项非法 */
+export declare const INVALID_ARGUMENT = "INVALID_ARGUMENT";
+/** 目标包未列入白名单 */
+export declare const PACKAGE_NOT_ALLOWED = "PACKAGE_NOT_ALLOWED";
+/** 包标识符格式非法或包含越界字符 */
+export declare const INVALID_PACKAGE_ID = "INVALID_PACKAGE_ID";
+/** 路径越界违规访问 */
+export declare const PATH_TRAVERSAL = "PATH_TRAVERSAL";
+/** 状态键存在多命名空间歧义 */
+export declare const AMBIGUOUS_STATE_KEY = "AMBIGUOUS_STATE_KEY";
+/** 目标运行记录未找到 */
+export declare const RUN_NOT_FOUND = "RUN_NOT_FOUND";
+/** 目标运行已进入终态不可操作 */
+export declare const RUN_ALREADY_FINISHED = "RUN_ALREADY_FINISHED";
+/**
+ * ActionDock 统一基础结构化异常类。
+ * 全仓各领域异常与跨层透传异常的统一事实源基类。
+ */
+export declare class ActionDockError<T = any> extends Error {
+    readonly code: ErrorCode;
+    readonly details?: T;
+    readonly status?: number;
+    constructor(code: ErrorCode, message: string, details?: T, status?: number);
+}
+/**
+ * 集中定义的标准结构化错误码联合类型。
+ */
+export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof STORAGE_WORKER_EXITED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof ACTION_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR;
+/** 全仓统一错误码类型别名 */
+export type ActionDockErrorCode = ErrorCode;
 /**
  * 进程领域结构化异常类。
  */
-export declare class ProcessError extends Error {
-    readonly code: string;
-    readonly details?: Record<string, unknown>;
-    constructor(code: string, message: string, details?: Record<string, unknown>);
+export declare class ProcessError extends ActionDockError {
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
 }