@actiondock/core 2.6.0 → 2.8.0

package/dist/json/value-validator.js

@@ -0,0 +1,330 @@
+import { isForbiddenActionInputPropertyName } from "../input/flat-predicates.js";
+/** 默认 JSON 最大嵌套深度限制（防止恶意超深结构） */
+export const DEFAULT_MAX_JSON_DEPTH = 256;
+/**
+ * 按照 RFC 6901 转义单个 JSON Pointer 路径段。
+ *
+ * @param segment 路径段（属性名或数组索引）
+ * @returns 转义后的路径段
+ */
+export function escapeJsonPointerSegment(segment) {
+    return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/**
+ * 将路径段追加到基础 RFC 6901 JSON Pointer 路径后。
+ *
+ * @param basePath 基础路径
+ * @param segment 待追加的路径段
+ * @returns 拼接后的 JSON Pointer
+ */
+export function appendJsonPointer(basePath, segment) {
+    return `${basePath}/${escapeJsonPointerSegment(segment)}`;
+}
+/**
+ * 内部统一 JSON 值与输入策略遍历校验引擎。
+ *
+ * 遍历规范：
+ * - 迭代式显式栈遍历：模拟调用栈，杜绝深层结构造成的堆栈溢出。
+ * - 严格数值有限性：全链路检查所有数值满足 Number.isFinite，拦截 NaN 与 Infinity。
+ * - 活跃祖先集合环路检测：仅在当前子树遍历期间在祖先集合中保留，完美放行有向无环（DAG）共享子结构。
+ * - 严格对象与原型校验：仅允许 Object.prototype 与 null 原型，拒绝 Date、Map、Set 等非纯数据对象与类实例。
+ * - 严格数组紧凑性：校验 0..length-1 全部存在，拒绝稀疏数组、额外属性与访问器元素。
+ * - Proxy 异常防御：对所有反射与属性检查执行防护拦截，杜绝未分类异常泄漏。
+ * - RFC 6901 路径追踪：全链路维护转义标准 JSON Pointer 路径。
+ */
+function walkJsonValue(value, options, checkForbiddenProperties = false) {
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    const ancestors = new Set();
+    const stack = [{ type: "ENTER", value, depth: 0, path: "" }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.type === "EXIT") {
+            ancestors.delete(frame.target);
+            continue;
+        }
+        const { value: val, depth, path } = frame;
+        if (val === null || typeof val === "boolean" || typeof val === "string") {
+            continue;
+        }
+        if (typeof val === "number") {
+            if (!Number.isFinite(val) || Number.isNaN(val)) {
+                return {
+                    valid: false,
+                    kind: "json-value",
+                    code: "NON_FINITE_NUMBER",
+                    reason: `Number is non-finite or NaN (${val})`,
+                    path,
+                };
+            }
+            continue;
+        }
+        if (typeof val === "undefined") {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "UNDEFINED_JSON_VALUE",
+                reason: "Undefined value is not allowed in JSON",
+                path,
+            };
+        }
+        if (typeof val === "function" ||
+            typeof val === "symbol" ||
+            typeof val === "bigint") {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "UNSUPPORTED_JSON_TYPE",
+                reason: `Unsupported JSON type '${typeof val}'`,
+                path,
+            };
+        }
+        if (typeof val === "object") {
+            try {
+                if (ancestors.has(val)) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "CIRCULAR_REFERENCE",
+                        reason: "Circular reference detected in object structure",
+                        path,
+                    };
+                }
+                if (depth > maxDepth) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "MAX_JSON_DEPTH",
+                        reason: `Max JSON depth limit (${maxDepth}) exceeded`,
+                        path,
+                    };
+                }
+                const proto = Object.getPrototypeOf(val);
+                const isArr = Array.isArray(val);
+                if (isArr) {
+                    if (proto !== Array.prototype) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array prototype must be Array.prototype",
+                            path,
+                        };
+                    }
+                    const len = val.length;
+                    if (typeof len !== "number" ||
+                        !Number.isInteger(len) ||
+                        len < 0 ||
+                        len > Number.MAX_SAFE_INTEGER) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array length is invalid",
+                            path,
+                        };
+                    }
+                    const ownKeys = Reflect.ownKeys(val);
+                    if (ownKeys.length !== len + 1) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array must be dense without extra properties or holes",
+                            path,
+                        };
+                    }
+                    ancestors.add(val);
+                    stack.push({ type: "EXIT", target: val });
+                    for (let i = len - 1; i >= 0; i--) {
+                        const keyStr = String(i);
+                        const desc = Object.getOwnPropertyDescriptor(val, keyStr);
+                        const elemPath = appendJsonPointer(path, i);
+                        if (!desc) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Sparse array (missing element at index ${i})`,
+                                path: elemPath,
+                            };
+                        }
+                        if (desc.get !== undefined || desc.set !== undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Accessor property not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        if (!desc.enumerable) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Non-enumerable property not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        if (desc.value === undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "UNDEFINED_JSON_VALUE",
+                                reason: `Undefined value is not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        stack.push({
+                            type: "ENTER",
+                            value: desc.value,
+                            depth: depth + 1,
+                            path: elemPath,
+                        });
+                    }
+                }
+                else {
+                    if (proto !== Object.prototype && proto !== null) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Object prototype must be Object.prototype or null",
+                            path,
+                        };
+                    }
+                    const ownKeys = Reflect.ownKeys(val);
+                    ancestors.add(val);
+                    stack.push({ type: "EXIT", target: val });
+                    for (let i = ownKeys.length - 1; i >= 0; i--) {
+                        const key = ownKeys[i];
+                        if (typeof key !== "string") {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: "Symbol-keyed properties are not allowed in JSON object",
+                                path: appendJsonPointer(path, String(key)),
+                            };
+                        }
+                        const propPath = appendJsonPointer(path, key);
+                        if (checkForbiddenProperties &&
+                            isForbiddenActionInputPropertyName(key)) {
+                            return {
+                                valid: false,
+                                kind: "input-policy",
+                                code: "FORBIDDEN_PROPERTY",
+                                property: key,
+                                path: propPath,
+                                reason: `Forbidden property "${key}" is not allowed in Action input`,
+                            };
+                        }
+                        const desc = Object.getOwnPropertyDescriptor(val, key);
+                        if (!desc) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Property descriptor missing for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (desc.get !== undefined || desc.set !== undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Accessor properties (getters/setters) are not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (!desc.enumerable) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Non-enumerable properties are not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (desc.value === undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "UNDEFINED_JSON_VALUE",
+                                reason: `Undefined value is not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        stack.push({
+                            type: "ENTER",
+                            value: desc.value,
+                            depth: depth + 1,
+                            path: propPath,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                return {
+                    valid: false,
+                    kind: "json-value",
+                    code: "INVALID_JSON_OBJECT",
+                    reason: `Failed to inspect object: ${err instanceof Error ? err.message : String(err)}`,
+                    path,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * 校验值是否为合法的 Canonical JSON 兼容结构。
+ *
+ * @param value 待校验的目标值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export function validateJsonValue(value, options) {
+    const res = walkJsonValue(value, options, false);
+    if (res.valid) {
+        return { valid: true };
+    }
+    if (res.kind === "input-policy") {
+        return {
+            valid: false,
+            code: "INVALID_JSON_OBJECT",
+            reason: res.reason,
+            path: res.path,
+        };
+    }
+    return {
+        valid: false,
+        code: res.code,
+        reason: res.reason,
+        path: res.path,
+    };
+}
+/**
+ * 校验 Action 输入值是否满足 Canonical JsonValue 规范且符合 ActionDock 安全策略。
+ * 在遍历过程中递归检查是否存在禁止属性（__proto__、constructor、prototype）。
+ *
+ * @param value 待校验的 Action 输入值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export function validateActionInputValue(value, options) {
+    return walkJsonValue(value, options, true);
+}
+/**
+ * 断言值必须为合法的 Canonical JSON 兼容结构，若非法则抛出 TypeError。
+ *
+ * @param value 待断言的目标值
+ * @param options 校验配置选项
+ */
+export function assertJsonValue(value, options) {
+    const result = validateJsonValue(value, options);
+    if (!result.valid) {
+        throw new TypeError(`Invalid JSON value: ${result.reason}`);
+    }
+}

package/dist/node/index.d.ts

@@ -0,0 +1 @@
+export * from "./module-loader.js";

package/dist/node/index.js

@@ -0,0 +1 @@
+export * from "./module-loader.js";

package/dist/node/module-loader.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 统一源码模块加载器接口。
+ * 解耦 Action 与各类扩展模块的具体加载机制（如 ECMAScript 原生 import、tsx 动态转译加载等）。
+ */
+export interface ModuleLoader {
+    /**
+     * 解析模块标识符为绝对路径或完整 URL。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve?(specifier: string, parentPath?: string): string;
+    /**
+     * 动态加载模块并返回命名空间全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    load<T = any>(specifier: string, parentPath?: string): Promise<T>;
+    /**
+     * 加载模块并解包其默认导出（default 或 action 属性）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    loadDefault?<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}
+/**
+ * 解包模块的默认导出对象，优先获取 default 或 action，自动解开嵌套互操作对象。
+ *
+ * @param moduleExports 待解包的模块导出对象
+ */
+export declare function unwrapDefaultExport<T = any>(moduleExports: any): T;
+/**
+ * 基于 Node.js 原生 ESM 动态 import 的源码模块加载器。
+ * 遵循 Node 原生模块规范：
+ * - 严格要求显式入口扩展名（.ts, .mts, .js, .mjs）
+ * - 彻底拒绝无扩展名自动推断与 CommonJS 目录索引解析
+ * - 完全移除第三方转译运行时依赖
+ */
+export declare class NodeModuleLoader implements ModuleLoader {
+    /**
+     * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
+     *
+     * @param specifier 模块规范说明符或相对/绝对物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve(specifier: string, parentPath?: string): string;
+    /**
+     * 基于 Node 原生 ESM 动态 import 加载模块并返回其全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    load<T = any>(specifier: string, parentPath?: string): Promise<T>;
+    /**
+     * 加载模块并解包其默认导出（default 或 action）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    loadDefault<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}

package/dist/node/module-loader.js

@@ -0,0 +1,112 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ActionDockError, ACTION_LOAD_FAILED } from "../errors.js";
+/**
+ * Node 原生 TypeScript 与 ESM 模块支持的扩展名集合。
+ */
+const ALLOWED_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+/**
+ * 解包模块的默认导出对象，优先获取 default 或 action，自动解开嵌套互操作对象。
+ *
+ * @param moduleExports 待解包的模块导出对象
+ */
+export function unwrapDefaultExport(moduleExports) {
+    if (moduleExports === null || moduleExports === undefined) {
+        return moduleExports;
+    }
+    let target = moduleExports.default !== undefined
+        ? moduleExports.default
+        : moduleExports.action !== undefined
+            ? moduleExports.action
+            : moduleExports;
+    if (target &&
+        typeof target === "object" &&
+        "default" in target &&
+        Object.keys(target).length === 1) {
+        target = target.default;
+    }
+    return target;
+}
+/**
+ * 基于 Node.js 原生 ESM 动态 import 的源码模块加载器。
+ * 遵循 Node 原生模块规范：
+ * - 严格要求显式入口扩展名（.ts, .mts, .js, .mjs）
+ * - 彻底拒绝无扩展名自动推断与 CommonJS 目录索引解析
+ * - 完全移除第三方转译运行时依赖
+ */
+export class NodeModuleLoader {
+    /**
+     * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
+     *
+     * @param specifier 模块规范说明符或相对/绝对物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve(specifier, parentPath) {
+        let target = specifier;
+        if (target.startsWith("file://")) {
+            target = fileURLToPath(target);
+        }
+        let baseDir = process.cwd();
+        if (parentPath) {
+            try {
+                const p = parentPath.startsWith("file://")
+                    ? fileURLToPath(parentPath)
+                    : parentPath;
+                if (existsSync(p)) {
+                    const stat = statSync(p);
+                    baseDir = stat.isDirectory() ? resolve(p) : dirname(resolve(p));
+                }
+                else {
+                    baseDir = dirname(resolve(p));
+                }
+            }
+            catch {
+                baseDir = process.cwd();
+            }
+        }
+        const candidateBasePath = isAbsolute(target) ? target : resolve(baseDir, target);
+        const ext = extname(candidateBasePath);
+        if (!ext) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': missing file extension. Explicit .ts, .mts, .js, or .mjs extension is required.`);
+        }
+        if (!ALLOWED_EXTENSIONS.has(ext)) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': unsupported extension '${ext}'. Only .ts, .mts, .js, and .mjs are supported.`);
+        }
+        if (!existsSync(candidateBasePath)) {
+            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': file not found`);
+        }
+        let stat;
+        try {
+            stat = statSync(candidateBasePath);
+        }
+        catch (err) {
+            throw new ActionDockError(ACTION_LOAD_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': ${err.message}`);
+        }
+        if (!stat.isFile()) {
+            throw new ActionDockError(ACTION_LOAD_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': path is not a file`);
+        }
+        return candidateBasePath;
+    }
+    /**
+     * 基于 Node 原生 ESM 动态 import 加载模块并返回其全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    async load(specifier, parentPath) {
+        const resolvedPath = this.resolve(specifier, parentPath);
+        const fileUrl = pathToFileURL(resolvedPath).href;
+        return (await import(fileUrl));
+    }
+    /**
+     * 加载模块并解包其默认导出（default 或 action）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    async loadDefault(specifier, parentPath) {
+        const mod = await this.load(specifier, parentPath);
+        return unwrapDefaultExport(mod);
+    }
+}

package/dist/package/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ActionDock 包级运行时必要门面与契约。
+ *
+ * 遵循 Minimal 暴露准则：仅对外输出 PackageRuntime、PackageRuntimeOptions、
+ * createPackageRuntime 以及包与动作元数据契约（PackageInfo、ActionSpec、ActionSummary、
+ * PlaybookSpec、PlaybookSummary）。
+ * 底层存储驱动、独立分发器与平台大对象统一由核心根入口导出。
+ */
+export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
+export { createNonClosingStorageView } from "./storage-view.js";
+export { findExecutable } from "../utils/index.js";
+export type { PackageRuntime, PackageRuntimeOptions, PackageInfo, ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, } from "./types.js";
+export type { RuntimePlatform, FileSystem, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
+export { type Clock, SystemClock, } from "../runtime/clock.js";
+export type { ModuleLoader } from "../node/module-loader.js";
+export { InMemoryEventSink, type EventSink, } from "../runtime/events.js";
+export { ProcessManager, type ProcessOwner, } from "../process/process-manager.js";
+export type { ProcessExecutor } from "../runtime/process.js";
+export { NodeProcessExecutor } from "../process/process-executor.js";
+export type { ProcessDriver, ProcessDriverCallbacks, ProcessDriverHandle, ProcessHandle, ProcessObserver, } from "../process/driver.js";
+export { createStorage, resolveDatabasePath, } from "../storage/index.js";
+export { SqliteRuntimeStorage } from "../storage/sqlite.js";
+export type { RuntimeStorage, SqliteDriver, StateEntry, } from "../storage/types.js";

package/dist/package/index.js

@@ -0,0 +1,18 @@
+/**
+ * ActionDock 包级运行时必要门面与契约。
+ *
+ * 遵循 Minimal 暴露准则：仅对外输出 PackageRuntime、PackageRuntimeOptions、
+ * createPackageRuntime 以及包与动作元数据契约（PackageInfo、ActionSpec、ActionSummary、
+ * PlaybookSpec、PlaybookSummary）。
+ * 底层存储驱动、独立分发器与平台大对象统一由核心根入口导出。
+ */
+export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
+export { createNonClosingStorageView } from "./storage-view.js";
+export { findExecutable } from "../utils/index.js";
+export { SystemClock, } from "../runtime/clock.js";
+export { InMemoryEventSink, } from "../runtime/events.js";
+export { ProcessManager, } from "../process/process-manager.js";
+export { NodeProcessExecutor } from "../process/process-executor.js";
+// 存储契约与驱动
+export { createStorage, resolveDatabasePath, } from "../storage/index.js";
+export { SqliteRuntimeStorage } from "../storage/sqlite.js";

package/dist/{app/app.d.ts → package/runtime.d.ts}

@@ -1,31 +1,33 @@
-import type { ActionDefinition, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
-import type { CancelResult, ExecuteOptions, ExecutionService, ExecutionTicket } from "../execution/types.js";
-import { type RuntimePlatform } from "../platform/index.js";
+import type { ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionInvoker, CancelResult, ExecutionTicket } from "../execution/types.js";
 import type { ProjectConfig } from "../project/types.js";
-import type { RuntimeStorage } from "../storage/types.js";
-import type { ActionDockApp, ActionDockAppOptions, ActionSpec, ActionSummary, ConfigValueView, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary, StateScopeOptions } from "./types.js";
+import { type PackageIdentity } from "../runtime/identity.js";
+import { type InvocationContext, type RunOptions } from "../invocation/types.js";
+import type { ActionSpec, ActionSummary, ConfigValueView, HostManagedPackageRuntime, ListActionsOptions, ListRunsOptions, PackageInfo, PackageRuntime, PackageRuntimeOptions, PackageRuntimeInternalOptions, PlaybookSpec, PlaybookSummary, StateScopeOptions } from "./types.js";
 /**
- * ActionDock 统一应用默认实现。
+ * ActionDock 统一包运行时默认实现。
  * 封装并管理单个 Action Package 的执行引擎、静态元数据索引、配置与状态存储生命周期。
  */
-export declare class DefaultActionDockApp implements ActionDockApp {
+export declare class DefaultPackageRuntime implements HostManagedPackageRuntime {
+    readonly identity: PackageIdentity;
     readonly packageId: string;
     readonly packageInstanceId: string;
     readonly generationId: string;
     readonly packageRoot?: string;
     readonly projectConfig: ProjectConfig;
-    readonly platform: RuntimePlatform;
-    readonly storage: RuntimeStorage;
-    readonly globalStorage?: RuntimeStorage;
-    readonly executionService: ExecutionService;
-    readonly actionsMap: Map<string, ActionDefinition>;
+    private readonly platform;
+    private readonly storage;
+    private readonly globalStorage?;
+    private readonly executionService;
+    private readonly actionsMap;
     private readonly options;
     private runtimeConfig;
     private isClosed;
+    private injectedGlobalStorage;
     /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
     private staticActionIndex?;
     private staticPlaybookIndex?;
-    constructor(options?: ActionDockAppOptions);
+    constructor(options?: PackageRuntimeInternalOptions);
     /**
      * 静态读取并聚合当前包的 Action 规范索引。
      * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果，
@@ -44,8 +46,10 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     describeAction(id: string): Promise<ActionSpec>;
     listPlaybooks(): Promise<PlaybookSummary[]>;
     describePlaybook(id: string): Promise<PlaybookSpec>;
-    runAction(id: string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
-    startAction(id: string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    private buildRootInvocationContext;
+    runAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
+    startAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
+    startInvocation(actionId: string, input: JsonValue, context: InvocationContext): Promise<ExecutionTicket>;
     getRun(runId: string): Promise<RunRecord | undefined>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
@@ -53,6 +57,8 @@ export declare class DefaultActionDockApp implements ActionDockApp {
         signal?: AbortSignal;
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
+    setActionInvoker(invoker?: ActionInvoker): void;
+    recoverDeadSessionRuns(sessionId?: string): void;
     listConfig(): Promise<ConfigValueView[]>;
     getConfig(key: string): Promise<ConfigValueView>;
     setConfig(key: string, value: JsonValue): Promise<void>;
@@ -60,11 +66,20 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     /**
      * 状态作用域统一解析辅助函数（单一事实源）。
      *
-     * 完成重载消歧与 actionId 冲突校验，返回最终生效的命名空间：
-     * - actionId 存在时拼 接 `${actionId}:${namespace}` 或直接 actionId；
-     * - 无 actionId 时返回显式 namespace 或空字符串（包级扁平状态）。
+     * 完成重载消歧后委托 mergeStateScope 计算最终生效的命名空间：
+     * - (actionId, key, options) 形态：位置 actionId 参与冲突校验；
+     * - (key, options) 扁平形态：首参是状态键，options.actionId 属合法显式指定。
      */
     private resolveStateScope;
+    /**
+     * 合并位置 actionId 与 options.actionId 并计算最终命名空间（单一事实源）。
+     *
+     * - positionalActionId 非 undefined：调用形态携带位置 actionId，
+     *   options.actionId 与其冲突时抛出异常（空串同样参与冲突校验）；
+     * - positionalActionId 为 undefined：无位置 actionId 的扁平调用形态，
+     *   options.actionId 属合法显式指定，直接采纳。
+     */
+    private mergeStateScope;
     getState<T extends JsonValue = JsonValue>(key: string, options?: StateScopeOptions): Promise<T | undefined>;
     getState<T extends JsonValue = JsonValue>(actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
     setState<T extends JsonValue = JsonValue>(key: string, value: T, options?: StateScopeOptions): Promise<void>;
@@ -78,11 +93,17 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     listStateKeys(actionId: string, options?: StateScopeOptions): Promise<string[]>;
     clearState(options?: StateScopeOptions): Promise<number>;
     clearState(actionId: string, options?: StateScopeOptions): Promise<number>;
+    listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    clearRuns(options?: {
+        actionId?: string;
+        status?: string;
+    }): Promise<number>;
+    listStateEntries(options?: any): Promise<import("../storage/types.js").StateEntry[]>;
     close(options?: {
         graceMs?: number;
     }): Promise<void>;
 }
 /**
- * 工厂函数：创建并初始化 ActionDockApp 实例。
+ * 工厂函数：创建并初始化 PackageRuntime 实例。
  */
-export declare function createActionDockApp(options?: ActionDockAppOptions): Promise<ActionDockApp>;
+export declare function createPackageRuntime(options?: PackageRuntimeOptions): Promise<PackageRuntime>;