@actiondock/core 2.0.11 → 2.2.0

package/dist/runtime/execution-manager.js

@@ -0,0 +1,66 @@
+/**
+ * 内存中活跃执行句柄（In-flight Execution Handles）生命周期管理器。
+ *
+ * 职责：
+ * 1. 集中追踪正在执行的异步 Action 任务句柄。
+ * 2. 任务完成（无论成功或失败）后通过 Promise.finally 自动注销，防止内存泄漏。
+ * 3. 支持依据 runId 查询、遍历或主动发送取消信号（cancel）。
+ */
+export class ExecutionManager {
+    active = new Map();
+    /**
+     * 注册一个活跃的执行句柄。
+     * 当底层 Promise 完成结算（resolve/reject）时，自动从活跃映射表中移除。
+     *
+     * @param handle 执行句柄对象
+     */
+    register(handle) {
+        this.active.set(handle.runId, handle);
+        handle.result.finally(() => {
+            this.active.delete(handle.runId);
+        });
+    }
+    /**
+     * 根据 runId 检索正在执行的任务句柄。
+     *
+     * @param runId 运行 ID
+     * @returns 匹配的 ExecutionHandle 或 undefined
+     */
+    get(runId) {
+        return this.active.get(runId);
+    }
+    /**
+     * 向指定 runId 的在途执行任务发送取消信号。
+     *
+     * @param runId 目标运行 ID
+     * @param reason 取消原因描述
+     * @returns 若句柄存在且成功触发中断返回 true；若任务不存在或已完成返回 false
+     */
+    cancel(runId, reason) {
+        const handle = this.active.get(runId);
+        if (!handle) {
+            return false;
+        }
+        return handle.cancel(reason);
+    }
+    /**
+     * 手动从活跃集合中移除执行句柄。
+     *
+     * @param runId 运行 ID
+     */
+    remove(runId) {
+        this.active.delete(runId);
+    }
+    /**
+     * 获取当前系统中所有正在执行的活跃句柄列表。
+     */
+    list() {
+        return Array.from(this.active.values());
+    }
+    /**
+     * 清空所有活跃执行句柄。
+     */
+    clear() {
+        this.active.clear();
+    }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./context.js";
+export * from "./action-collection.js";
+export * from "./runner.js";
+export * from "./execution-manager.js";
+export * from "./standalone.js";
+export * from "./env.js";
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./events.js";
+export * from "./module-loader.js";

package/dist/runtime/index.js

@@ -0,0 +1,10 @@
+export * from "./context.js";
+export * from "./action-collection.js";
+export * from "./runner.js";
+export * from "./execution-manager.js";
+export * from "./standalone.js";
+export * from "./env.js";
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./events.js";
+export * from "./module-loader.js";

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

@@ -0,0 +1,34 @@
+/**
+ * 统一源码模块加载器接口。
+ * 解耦 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>;
+}
+/**
+ * 基于标准 ECMAScript 动态 import 的默认模块加载器。
+ */
+export declare class DefaultModuleLoader implements ModuleLoader {
+    load<T = any>(specifier: string, _parentPath?: string): Promise<T>;
+    loadDefault<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}

package/dist/runtime/module-loader.js

@@ -0,0 +1,16 @@
+import { pathToFileURL } from "node:url";
+/**
+ * 基于标准 ECMAScript 动态 import 的默认模块加载器。
+ */
+export class DefaultModuleLoader {
+    async load(specifier, _parentPath) {
+        const importSpecifier = specifier.startsWith("file://")
+            ? specifier
+            : pathToFileURL(specifier).href;
+        return (await import(importSpecifier));
+    }
+    async loadDefault(specifier, parentPath) {
+        const mod = await this.load(specifier, parentPath);
+        return (mod?.default !== undefined ? mod.default : mod?.action !== undefined ? mod.action : mod);
+    }
+}

package/dist/runtime/process.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessAPI, ProcessExecOptions, ProcessResult } from "@actiondock/sdk";
+export type ProcessExecutor = ProcessAPI;
+/**
+ * 基于 Node.js 标准 child_process 实现的基础进程执行器。
+ */
+export declare class DefaultProcessExecutor implements ProcessExecutor {
+    exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+    spawn(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+}

package/dist/runtime/process.js

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR } from "../errors.js";
+/**
+ * 基于 Node.js 标准 child_process 实现的基础进程执行器。
+ */
+export class DefaultProcessExecutor {
+    async exec(command, args = [], options = {}) {
+        const startTime = Date.now();
+        const maxOutputBytes = options.maxOutputBytes ?? 10 * 1024 * 1024;
+        return new Promise((resolve, reject) => {
+            let stdoutBuf = "";
+            let stderrBuf = "";
+            let totalBytes = 0;
+            let timedOut = false;
+            let cancelled = false;
+            let error;
+            const cp = spawn(command, args, {
+                cwd: options.cwd,
+                env: options.env ? { ...process.env, ...options.env } : process.env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            if (options.input) {
+                cp.stdin.write(options.input);
+                cp.stdin.end();
+            }
+            else {
+                cp.stdin.end();
+            }
+            let timer;
+            let forceKillTimer;
+            if (options.timeoutMs && options.timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    cp.kill("SIGTERM");
+                    forceKillTimer = setTimeout(() => {
+                        if (!cp.killed)
+                            cp.kill("SIGKILL");
+                    }, 1000);
+                }, options.timeoutMs);
+            }
+            const onAbort = () => {
+                cancelled = true;
+                cp.kill("SIGTERM");
+                forceKillTimer = setTimeout(() => {
+                    if (!cp.killed)
+                        cp.kill("SIGKILL");
+                }, 1000);
+            };
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    onAbort();
+                }
+                else {
+                    options.signal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                if (forceKillTimer) {
+                    clearTimeout(forceKillTimer);
+                    forceKillTimer = undefined;
+                }
+                if (options.signal) {
+                    options.signal.removeEventListener("abort", onAbort);
+                }
+            };
+            cp.stdout?.on("data", (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes > maxOutputBytes) {
+                    error = {
+                        code: PROCESS_OUTPUT_LIMIT,
+                        message: `Process output exceeded limit of ${maxOutputBytes} bytes`,
+                    };
+                    cp.kill("SIGKILL");
+                    return;
+                }
+                stdoutBuf += chunk.toString("utf-8");
+            });
+            cp.stderr?.on("data", (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes > maxOutputBytes) {
+                    error = {
+                        code: PROCESS_OUTPUT_LIMIT,
+                        message: `Process output exceeded limit of ${maxOutputBytes} bytes`,
+                    };
+                    cp.kill("SIGKILL");
+                    return;
+                }
+                stderrBuf += chunk.toString("utf-8");
+            });
+            cp.on("error", (err) => {
+                cleanup();
+                const durationMs = Date.now() - startTime;
+                const res = {
+                    ok: false,
+                    exitCode: null,
+                    stdout: stdoutBuf.trim(),
+                    stderr: stderrBuf.trim() || err.message,
+                    raw: new TextEncoder().encode(stdoutBuf),
+                    timedOut,
+                    cancelled,
+                    durationMs,
+                    error: error || {
+                        code: PROCESS_SPAWN_ERROR,
+                        message: err.message,
+                    },
+                };
+                if (options.throwOnError) {
+                    reject(new Error(err.message));
+                }
+                else {
+                    resolve(res);
+                }
+            });
+            cp.on("close", (exitCode, signal) => {
+                cleanup();
+                const durationMs = Date.now() - startTime;
+                const ok = exitCode === 0 && !timedOut && !cancelled && !error;
+                const res = {
+                    ok,
+                    exitCode,
+                    signal: signal || undefined,
+                    stdout: stdoutBuf.trim(),
+                    stderr: stderrBuf.trim(),
+                    raw: new TextEncoder().encode(stdoutBuf),
+                    timedOut,
+                    cancelled,
+                    durationMs,
+                    error,
+                };
+                if (!ok && options.throwOnError) {
+                    reject(new Error(stderrBuf.trim() || `Process exited with code ${exitCode}`));
+                }
+                else {
+                    resolve(res);
+                }
+            });
+        });
+    }
+    async spawn(command, args = [], options = {}) {
+        return this.exec(command, args, options);
+    }
+}

package/dist/runtime/runner.d.ts

@@ -0,0 +1,293 @@
+import type { ActionDefinition, ActionRef, ExecutionResult, Logger, ProcessAPI, ProgressReporter } from "@actiondock/sdk";
+import type { ProjectConfig } from "../project/types.js";
+import type { RuntimeStorage } from "../storage/types.js";
+import type { Clock } from "./clock.js";
+import type { RuntimePlatform } from "../platform/types.js";
+export { RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, MAX_SUBRUNS_REACHED, ACTION_CALL_CYCLE, ACTION_CYCLE_DETECTED, ACTION_MAX_DEPTH_EXCEEDED, } from "../errors.js";
+/**
+ * 校验值是否为合法的 JSON 兼容结构，严禁 NaN、Infinity、循环引用及不可序列化类型。
+ */
+export declare function validateJsonValue(val: unknown, seen?: WeakSet<object>): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * ActionRunner 初始化配置选项。
+ */
+export interface RunnerOptions {
+    /** 运行所属的 Package ID */
+    packageId: string;
+    /** 持久化运行时存储实例（SQLite） */
+    storage?: RuntimeStorage;
+    /** 全局共享持久化存储实例（SQLite，用于单例池化避免泄漏） */
+    globalStorage?: RuntimeStorage;
+    /** 项目根目录绝对路径 */
+    projectRoot?: string;
+    /** 项目元数据配置 */
+    projectConfig?: ProjectConfig;
+    /** CLI 或上层注入的临时配置覆盖项 */
+    configOverrides?: Record<string, unknown>;
+    /** 预加载的 Action 映射表 */
+    actions?: Map<string, ActionDefinition>;
+    /** 外部注入的进程执行器 */
+    process?: ProcessAPI;
+    /** 可选的时间与时钟源（默认使用存储内嵌时钟或系统时间） */
+    clock?: Clock;
+    /** 可选的底层运行时平台契约 */
+    platform?: RuntimePlatform;
+    /** 动态解析跨包或未注册 Action 的委托函数 */
+    actionResolver?: (ref: ActionRef | string, currentPackageId?: string) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
+    /** 最大调用嵌套深度限制（防死循环/过深调用链，默认 16） */
+    maxCallDepth?: number;
+    /** 最大并发子任务数限制（默认 64） */
+    maxSubRuns?: number;
+    /** 跨包存储工厂 */
+    getStorageForPackage?: (packageId: string, projectRoot?: string) => RuntimeStorage;
+    /** 跨包运行上下文解析委托函数 */
+    packageContextResolver?: (packageId: string) => Promise<{
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined> | {
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined;
+    /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
+    customHome?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
+}
+/** ActionRunnerOptions 别名兼容 */
+export type ActionRunnerOptions = RunnerOptions;
+/**
+ * 启动 Action 执行时的可选控制参数。
+ */
+export interface ExecutionStartOptions {
+    /** 显式指定的运行 ID */
+    runId?: string;
+    /** 根运行 ID */
+    rootRunId?: string;
+    /** 父级运行 ID（嵌套调用场景下建立调用链树） */
+    parentRunId?: string;
+    /** 包物理实例标识 */
+    packageInstanceId?: string;
+    /** 快照代次标识 */
+    generationId?: string;
+    /** 执行所有者标识 */
+    ownerId?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
+    /** 调用栈数组（用于检测 A -> B -> A 环路死锁） */
+    callStack?: string[];
+    /** 外部传入的 AbortSignal 取消信号 */
+    signal?: AbortSignal;
+    /** 最大超时时间（毫秒），超时将自动中止执行并标记为 ACTION_TIMEOUT */
+    timeoutMs?: number;
+    /** 最大调用深度覆盖 */
+    maxCallDepth?: number;
+    /** 外部注入的进程执行器 */
+    process?: ProcessAPI;
+    /** 可选的底层运行时平台契约 */
+    platform?: RuntimePlatform;
+    /** 外部注入的进度报告器 */
+    progress?: ProgressReporter;
+    /** 外部注入的日志记录器 */
+    logger?: Logger;
+    /** 执行级临时配置覆盖项 */
+    configOverrides?: Record<string, unknown>;
+}
+/**
+ * 异步执行句柄，支持获取执行结果 Promise 与主动取消操作。
+ */
+export interface ExecutionHandle {
+    /** 本次执行生成的全局唯一运行 ID */
+    runId: string;
+    /** 最终执行结果信封 Promise */
+    result: Promise<ExecutionResult>;
+    /**
+     * 取消当前正在执行的任务
+     * @param reason 取消原因
+     * @returns 是否成功触发取消
+     */
+    cancel(reason?: string): boolean;
+}
+/**
+ * Action 解析结果判别联合类型。
+ */
+export type ActionResolution = {
+    status: "found";
+    action: ActionDefinition;
+} | {
+    status: "not_found";
+    reason?: string;
+} | {
+    status: "load_failed";
+    error: Error;
+    packageId: string;
+    projectRoot: string;
+};
+/**
+ * ActionDock 核心执行引擎（ActionRunner）。
+ *
+ * 职责：
+ * - 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
+ * - 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
+ * - 嵌套 Action 相互调用的环路检测（Cycle Detection）。
+ * - 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
+ * - 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
+ */
+export declare class ActionRunner {
+    private packageId;
+    private storage;
+    private globalStorage?;
+    private projectRoot?;
+    private projectConfig?;
+    private configOverrides;
+    private actions;
+    private clock?;
+    private process?;
+    private platform?;
+    private maxCallDepth;
+    private maxSubRuns;
+    private activeSubRuns;
+    private packageRunners;
+    private actionResolver?;
+    private getStorageForPackage?;
+    private packageContextResolver?;
+    private customHome?;
+    private hostSessionId?;
+    constructor(options: RunnerOptions);
+    getStorage(): RuntimeStorage;
+    getPackageRunners(): Map<string, ActionRunner>;
+    /**
+     * 注册单个 Action 到当前 Runner。
+     */
+    registerAction(id: string, action: ActionDefinition): void;
+    registerAction(action: ({
+        id: string;
+        action?: ActionDefinition;
+    } & Partial<ActionDefinition>) | ActionDefinition): void;
+    /**
+     * 根据 ID 检索注册的 Action。
+     */
+    getAction(id: string): ActionDefinition | undefined;
+    /**
+     * 动态解析 Action（支持本地注册表、自定义解析器委托与已链接包目录索引检索）。
+     *
+     * @param actionOrRef Action 定义对象、引用或标识符
+     * @returns 解析判别联合结果（found | not_found | load_failed）
+     */
+    resolveAction(actionOrRef: ActionDefinition | ActionRef | string): Promise<ActionResolution>;
+    /**
+     * 获取当前 Runner 已注册的所有 Action 列表。
+     */
+    listActions(): ActionDefinition[];
+    /**
+     * 注入或更新跨包运行上下文解析委托。
+     */
+    setPackageContextResolver(resolver: (packageId: string) => Promise<{
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined> | {
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined): void;
+    /**
+     * 跨包运行时解析与获取（确保跨包执行具备独立的配置、存储、状态与 Action 注册表）。
+     */
+    resolveTargetPackageRunner(targetPackageId: string): Promise<ActionRunner | undefined>;
+    /**
+     * 异步启动 Action 的执行并立即返回 ExecutionHandle 句柄。
+     *
+     * @param actionOrId Action 定义对象、引用或标识符
+     * @param input 传递给 Action 的输入数据
+     * @param options 执行控制选项（超时、取消信号、父运行 ID 等）
+     * @returns 包含 runId、result Promise 和 cancel 方法的执行句柄
+     */
+    start(actionOrId: ActionDefinition | ActionRef | string, input?: unknown, options?: ExecutionStartOptions): ExecutionHandle;
+    /**
+     * 计算根运行标识（优先显式 rootRunId，其次 parentRunId，最后自身 runId）。
+     */
+    private computeRootRunId;
+    /**
+     * 预解析执行目标并装配运行期共享上下文对象（runId、目标标识、时钟源与调用栈快照）。
+     */
+    private prepareRunContext;
+    /**
+     * 为匿名传入的 Action 定义对象解析或分配稳定标识。
+     */
+    private resolveAnonymousActionId;
+    /**
+     * 尝试将 failed 终态初始记录写入存储（非法输入场景，存储异常静默忽略）。
+     */
+    private tryPersistInitialRun;
+    /**
+     * 构建 running 初始记录并强制写入存储（存储不可用时抛出 RUN_REPOSITORY_UNAVAILABLE）。
+     */
+    private persistInitialRun;
+    /**
+     * 依据运行期上下文构造 RunRecord 初始记录。
+     */
+    private buildInitialRunRecord;
+    /**
+     * 创建运行终态收敛器：封装终态去重、超时定时器清理与落库异常捕获。
+     */
+    private createRunFinalizer;
+    /**
+     * 调用嵌套深度限制检测（超限时返回 ACTION_CALL_CYCLE 错误）。
+     */
+    private checkCallDepth;
+    /**
+     * 计算调用键并执行环路死锁检测（命中时返回携带错误的调用键结果）。
+     */
+    private computeCallKey;
+    /**
+     * 输入参数 JSON Schema 校验（若 action 已就绪，返回校验错误或 undefined）。
+     */
+    private checkActionInputSchema;
+    /**
+     * 构建 ActionContext 运行时上下文（内嵌子 Action 调用委托提为私有方法）。
+     */
+    private buildActionContext;
+    /**
+     * 子 Action 调用委托：并发上限守卫、uses 跨包声明校验与子执行派发。
+     */
+    private invokeChildAction;
+    /**
+     * 校验跨包子调用是否已在 uses 声明中授权（未声明时抛出 UNDECLARED_ACTION_DEPENDENCY）。
+     */
+    private assertDeclaredUses;
+    /**
+     * 解析子调用应使用的 Runner（本包或已解析的目标包 Runner）。
+     */
+    private resolveChildRunner;
+    /**
+     * 执行 Action 业务逻辑并与取消/超时信号进行竞态，返回执行结果信封 Promise。
+     */
+    private raceExecutionAndAbort;
+    /**
+     * 输出结果 Schema 校验（返回校验错误或 undefined）。
+     */
+    private checkActionOutputSchema;
+    /**
+     * 异常分类收敛：超时、取消与业务失败分别映射为对应终态与错误码。
+     */
+    private classifyExecutionError;
+    /**
+     * 同步等待方式执行指定 Action，直接返回 ExecutionResult 信封结果。
+     *
+     * @param actionOrId Action 定义对象、引用或标识符
+     * @param input 输入参数
+     * @param options 执行控制选项
+     */
+    execute(actionOrId: ActionDefinition | ActionRef | string, input?: unknown, options?: ExecutionStartOptions): Promise<ExecutionResult>;
+}