@actiondock/core 2.0.12 → 2.2.0

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

@@ -32,11 +32,3 @@ export declare class DefaultModuleLoader implements ModuleLoader {
     load<T = any>(specifier: string, _parentPath?: string): Promise<T>;
     loadDefault<T = any>(specifier: string, parentPath?: string): Promise<T>;
 }
-/**
- * 注册全局模块加载器实现。
- */
-export declare function setModuleLoader(loader: ModuleLoader): void;
-/**
- * 获取当前全局模块加载器，若未显式注册则回退使用 DefaultModuleLoader。
- */
-export declare function getModuleLoader(): ModuleLoader;

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

@@ -1,11 +1,9 @@
-import type { DetachedProcessOptions, DetachedProcessResult, ProcessAPI, ProcessExecOptions, ProcessResult } from "@actiondock/sdk";
+import type { ProcessAPI, ProcessExecOptions, ProcessResult } from "@actiondock/sdk";
 export type ProcessExecutor = ProcessAPI;
-export declare function setProcessExecutor(executor: ProcessExecutor): void;
-export declare function getProcessExecutor(): ProcessExecutor;
 /**
  * 基于 Node.js 标准 child_process 实现的基础进程执行器。
  */
 export declare class DefaultProcessExecutor implements ProcessExecutor {
     exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
-    spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult>;
+    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

@@ -1,7 +1,18 @@
 import type { ActionDefinition, ActionRef, ExecutionResult, Logger, ProcessAPI, ProgressReporter } from "@actiondock/sdk";
-import type { ProjectConfig } from "../project/types";
-import type { RuntimeStorage } from "../storage/types";
-import type { Clock } from "./clock";
+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 初始化配置选项。
  */
@@ -9,7 +20,7 @@ export interface RunnerOptions {
     /** 运行所属的 Package ID */
     packageId: string;
     /** 持久化运行时存储实例（SQLite） */
-    storage: RuntimeStorage;
+    storage?: RuntimeStorage;
     /** 全局共享持久化存储实例（SQLite，用于单例池化避免泄漏） */
     globalStorage?: RuntimeStorage;
     /** 项目根目录绝对路径 */
@@ -24,6 +35,8 @@ export interface RunnerOptions {
     process?: ProcessAPI;
     /** 可选的时间与时钟源（默认使用存储内嵌时钟或系统时间） */
     clock?: Clock;
+    /** 可选的底层运行时平台契约 */
+    platform?: RuntimePlatform;
     /** 动态解析跨包或未注册 Action 的委托函数 */
     actionResolver?: (ref: ActionRef | string, currentPackageId?: string) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
     /** 最大调用嵌套深度限制（防死循环/过深调用链，默认 16） */
@@ -46,6 +59,8 @@ export interface RunnerOptions {
     } | undefined;
     /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
     customHome?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
 }
 /** ActionRunnerOptions 别名兼容 */
 export type ActionRunnerOptions = RunnerOptions;
@@ -65,6 +80,8 @@ export interface ExecutionStartOptions {
     generationId?: string;
     /** 执行所有者标识 */
     ownerId?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
     /** 调用栈数组（用于检测 A -> B -> A 环路死锁） */
     callStack?: string[];
     /** 外部传入的 AbortSignal 取消信号 */
@@ -75,6 +92,8 @@ export interface ExecutionStartOptions {
     maxCallDepth?: number;
     /** 外部注入的进程执行器 */
     process?: ProcessAPI;
+    /** 可选的底层运行时平台契约 */
+    platform?: RuntimePlatform;
     /** 外部注入的进度报告器 */
     progress?: ProgressReporter;
     /** 外部注入的日志记录器 */
@@ -116,11 +135,11 @@ export type ActionResolution = {
  * ActionDock 核心执行引擎（ActionRunner）。
  *
  * 职责：
- * 1. 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
- * 2. 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
- * 3. 嵌套 Action 相互调用的环路检测（Cycle Detection）。
- * 4. 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
- * 5. 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
+ * - 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
+ * - 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
+ * - 嵌套 Action 相互调用的环路检测（Cycle Detection）。
+ * - 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
+ * - 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
  */
 export declare class ActionRunner {
     private packageId;
@@ -132,6 +151,7 @@ export declare class ActionRunner {
     private actions;
     private clock?;
     private process?;
+    private platform?;
     private maxCallDepth;
     private maxSubRuns;
     private activeSubRuns;
@@ -140,13 +160,18 @@ export declare class ActionRunner {
     private getStorageForPackage?;
     private packageContextResolver?;
     private customHome?;
+    private hostSessionId?;
     constructor(options: RunnerOptions);
     getStorage(): RuntimeStorage;
     getPackageRunners(): Map<string, ActionRunner>;
     /**
      * 注册单个 Action 到当前 Runner。
      */
-    registerAction(action: ActionDefinition): void;
+    registerAction(id: string, action: ActionDefinition): void;
+    registerAction(action: ({
+        id: string;
+        action?: ActionDefinition;
+    } & Partial<ActionDefinition>) | ActionDefinition): void;
     /**
      * 根据 ID 检索注册的 Action。
      */
@@ -162,6 +187,20 @@ export declare class ActionRunner {
      * 获取当前 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 注册表）。
      */
@@ -175,6 +214,74 @@ export declare class ActionRunner {
      * @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 信封结果。
      *