@actiondock/core 2.5.1 → 2.6.0

package/dist/runtime/run-persistence.d.ts

@@ -0,0 +1,85 @@
+import type { RuntimeError, RunRecord } from "@actiondock/sdk";
+import type { RuntimeStorage, TerminalRunStatus } from "../storage/types.js";
+/**
+ * 运行记录落库参数（RunRecord 构造与写入的领域入参）。
+ *
+ * 由 Runner 编排层在执行启动时装配，落库模块仅依赖该纯数据契约，不感知执行编排
+ * 与上下文构建细节。
+ */
+export interface InitialRunRecordInput {
+    /** 本次执行生成的全局唯一运行 ID */
+    runId: string;
+    /** 根运行 ID */
+    rootRunId: string;
+    /** 父级运行 ID（嵌套调用场景下建立调用链树） */
+    parentRunId?: string;
+    /** 执行归属所有者标识 */
+    ownerId?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
+    /** 包物理实例标识 */
+    packageInstanceId?: string;
+    /** 快照代次标识 */
+    generationId?: string;
+    /** 目标 Package 标识 */
+    targetPackageId: string;
+    /** 目标 Action 标识 */
+    targetActionId: string;
+    /** 执行开始时间戳 */
+    startedAt: string;
+    /** 原始输入数据 */
+    input: unknown;
+    /** 宿主 Runner 的 Package 标识 */
+    runnerPackageId: string;
+    /** 宿主 Runner 的包物理实例标识 */
+    runnerPackageInstanceId: string;
+    /** 宿主 Runner 的快照代次标识 */
+    runnerGenerationId: string;
+    /** Runner 构造注入的执行宿主会话标识 */
+    runnerHostSessionId?: string;
+}
+/**
+ * 运行终态收敛器（收敛原 finalized、persistError、isTimeout、timeoutTimer 闭包状态）。
+ */
+export interface RunFinalizer {
+    /** 是否已写入终态 */
+    finalized: boolean;
+    /** 是否命中超时 */
+    isTimeout: boolean;
+    /** 落库异常错误信息 */
+    persistError: RuntimeError | undefined;
+    /** 超时定时器句柄 */
+    timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+    /** 超时守卫绑定的取消控制器 */
+    controller: AbortController | undefined;
+    /** 外部中止信号对象 */
+    signal?: AbortSignal;
+    /** 外部中止信号监听句柄 */
+    onAbort?: () => void;
+    /** 竞态监听句柄注销函数列表（finalize 时统一清理，覆盖成功路径） */
+    raceListenerRemovers: Array<() => void>;
+    /** 绑定取消控制器并启动超时定时器 */
+    startTimeout(controller: AbortController, timeoutMs: number): void;
+    /** 写入终态（幂等，自动清理超时定时器与全部监听句柄） */
+    finalize(status: TerminalRunStatus, output?: unknown, error?: RuntimeError): void;
+}
+/**
+ * 构建运行初始记录（RunRecord 组装单一事实源）。
+ */
+export declare function buildInitialRunRecord(params: InitialRunRecordInput, status: "running" | "failed", error?: RuntimeError): RunRecord;
+/**
+ * 尝试将初始记录写入存储（存储异常静默忽略，用于非法输入等弱依赖场景）。
+ */
+export declare function tryCreateRun(storage: RuntimeStorage, record: RunRecord): void;
+/**
+ * 强制将初始记录写入存储（存储不可用时抛出 RUN_REPOSITORY_UNAVAILABLE）。
+ */
+export declare function createRunOrThrow(storage: RuntimeStorage, record: RunRecord): void;
+/**
+ * 更新运行终态并捕获落库异常（异常转译为 RUN_PERSISTENCE_FAILED 错误对象返回）。
+ */
+export declare function updateRunStatus(storage: RuntimeStorage, runId: string, status: TerminalRunStatus, output?: unknown, error?: RuntimeError): RuntimeError | undefined;
+/**
+ * 创建运行终态收敛器：封装终态去重、超时定时器清理与落库异常捕获。
+ */
+export declare function createRunFinalizer(storage: RuntimeStorage, runId: string): RunFinalizer;

package/dist/runtime/run-persistence.js

@@ -0,0 +1,111 @@
+import { RUN_PERSISTENCE_FAILED, RUN_REPOSITORY_UNAVAILABLE } from "../errors.js";
+/**
+ * 构建运行初始记录（RunRecord 组装单一事实源）。
+ */
+export function buildInitialRunRecord(params, status, error) {
+    const { runId, rootRunId, parentRunId, ownerId, hostSessionId, packageInstanceId, generationId, targetPackageId, targetActionId, startedAt, input, runnerPackageId, runnerPackageInstanceId, runnerGenerationId, runnerHostSessionId, } = params;
+    const record = {
+        id: runId,
+        rootRunId,
+        parentRunId,
+        packageId: targetPackageId,
+        packageInstanceId: packageInstanceId || (runnerPackageId === targetPackageId ? runnerPackageInstanceId : targetPackageId),
+        actionId: targetActionId,
+        generationId: generationId || (runnerPackageId === targetPackageId ? runnerGenerationId : "1"),
+        ownerId: ownerId || "local",
+        hostSessionId: hostSessionId || runnerHostSessionId,
+        status,
+        error,
+        startedAt,
+    };
+    if (status === "running") {
+        record.input = input;
+    }
+    else {
+        record.finishedAt = startedAt;
+    }
+    return record;
+}
+/**
+ * 尝试将初始记录写入存储（存储异常静默忽略，用于非法输入等弱依赖场景）。
+ */
+export function tryCreateRun(storage, record) {
+    try {
+        storage.createRun(record);
+    }
+    catch { }
+}
+/**
+ * 强制将初始记录写入存储（存储不可用时抛出 RUN_REPOSITORY_UNAVAILABLE）。
+ */
+export function createRunOrThrow(storage, record) {
+    try {
+        storage.createRun(record);
+    }
+    catch (err) {
+        const error = new Error(`RUN_REPOSITORY_UNAVAILABLE: Failed to initialize run record in repository: ${err?.message || String(err)}`);
+        error.code = RUN_REPOSITORY_UNAVAILABLE;
+        error.details = { originalError: err?.message };
+        throw error;
+    }
+}
+/**
+ * 更新运行终态并捕获落库异常（异常转译为 RUN_PERSISTENCE_FAILED 错误对象返回）。
+ */
+export function updateRunStatus(storage, runId, status, output, error) {
+    try {
+        storage.updateRun(runId, status, output, error);
+        return undefined;
+    }
+    catch (persistErr) {
+        return {
+            code: RUN_PERSISTENCE_FAILED,
+            message: `RUN_PERSISTENCE_FAILED: Failed to persist run state: ${persistErr?.message || String(persistErr)}`,
+            details: { originalError: persistErr?.message },
+        };
+    }
+}
+/**
+ * 创建运行终态收敛器：封装终态去重、超时定时器清理与落库异常捕获。
+ */
+export function createRunFinalizer(storage, runId) {
+    const finalizer = {
+        finalized: false,
+        isTimeout: false,
+        persistError: undefined,
+        timeoutTimer: undefined,
+        controller: undefined,
+        signal: undefined,
+        onAbort: undefined,
+        raceListenerRemovers: [],
+        startTimeout: (controller, timeoutMs) => {
+            finalizer.controller = controller;
+            finalizer.timeoutTimer = setTimeout(() => {
+                finalizer.isTimeout = true;
+                finalizer.controller?.abort(new Error(`Action exceeded timeout of ${timeoutMs}ms`));
+            }, timeoutMs);
+        },
+        finalize: (status, output, error) => {
+            if (finalizer.timeoutTimer) {
+                clearTimeout(finalizer.timeoutTimer);
+                finalizer.timeoutTimer = undefined;
+            }
+            if (finalizer.signal && finalizer.onAbort) {
+                finalizer.signal.removeEventListener("abort", finalizer.onAbort);
+                finalizer.onAbort = undefined;
+            }
+            // 成功路径同样注销竞态监听句柄，避免信号对象残留引用
+            for (const remove of finalizer.raceListenerRemovers.splice(0)) {
+                try {
+                    remove();
+                }
+                catch { }
+            }
+            if (finalizer.finalized)
+                return;
+            finalizer.finalized = true;
+            finalizer.persistError = updateRunStatus(storage, runId, status, output, error);
+        },
+    };
+    return finalizer;
+}

package/dist/runtime/runner.d.ts

@@ -153,12 +153,15 @@ export type ActionResolution = {
 /**
  * ActionDock 核心执行引擎（ActionRunner）。
  *
- * 职责：
- * - 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
- * - 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
- * - 嵌套 Action 相互调用的环路检测（Cycle Detection）。
- * - 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
- * - 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
+ * 本类为执行编排壳：负责 Action 执行的全生命周期编排（校验、深度与环路检测、
+ * 超时与取消竞态、子调用 uses 授权与错误分类），并将单一职责域委托至独立模块：
+ * - Action 注册与检索委托 `ActionRegistry`（action-registry.ts）
+ * - RunRecord 构造与落库委托 run-persistence.ts
+ * - 跨包 Runner 构建与缓存委托 `PackageRunnerFactory`（package-runner-factory.ts）
+ *
+ * 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验、嵌套 Action
+ * 相互调用的环路检测（Cycle Detection）、超时 (Timeout) 与中断信号 (AbortSignal)
+ * 竞态控制与运行记录持久化编排仍由本类承担。
  */
 export declare class ActionRunner {
     readonly packageId: string;
@@ -169,22 +172,21 @@ export declare class ActionRunner {
     private projectRoot?;
     private projectConfig?;
     private configOverrides;
-    private actions;
+    private registry;
     private clock?;
     private process?;
     private platform?;
     private maxCallDepth;
     private maxSubRuns;
     private activeSubRuns;
-    private packageRunners;
-    /** 跨包 Runner 构建中的 in-flight Promise：并发调用 await 同一构建任务，消除 check-then-act 竞态 */
-    private pendingPackageRunners;
+    private packageFactory;
     private actionResolver?;
     private getStorageForPackage?;
-    private packageContextResolver?;
     private customHome?;
     private hostSessionId?;
     constructor(options: RunnerOptions);
+    /** 本地 Action 注册表底层映射（仅内部与跨包工厂委托使用） */
+    private get actions();
     getStorage(): RuntimeStorage;
     getPackageRunners(): Map<string, ActionRunner>;
     /**
@@ -222,10 +224,6 @@ export declare class ActionRunner {
      * 并发方 await 同一构建任务，构建失败时移除该 Promise 以便后续重试。
      */
     resolveTargetPackageRunner(targetPackageId: string): Promise<ActionRunner | undefined>;
-    /**
-     * 实际构建跨包 Runner（仅由 resolveTargetPackageRunner 串行调度）。
-     */
-    private buildTargetPackageRunner;
     /**
      * 异步启动 Action 的执行并立即返回 ExecutionHandle 句柄。
      *
@@ -244,25 +242,9 @@ export declare class ActionRunner {
      */
     private prepareRunContext;
     /**
-     * 为匿名传入的 Action 定义对象解析或分配稳定标识。
-     */
-    private resolveAnonymousActionId;
-    /**
-     * 尝试将 failed 终态初始记录写入存储（非法输入场景，存储异常静默忽略）。
-     */
-    private tryPersistInitialRun;
-    /**
-     * 构建 running 初始记录并强制写入存储（存储不可用时抛出 RUN_REPOSITORY_UNAVAILABLE）。
+     * 依据运行期上下文装配落库模块入参（RunRecord 构造领域契约）。
      */
-    private persistInitialRun;
-    /**
-     * 依据运行期上下文构造 RunRecord 初始记录。
-     */
-    private buildInitialRunRecord;
-    /**
-     * 创建运行终态收敛器：封装终态去重、超时定时器清理与落库异常捕获。
-     */
-    private createRunFinalizer;
+    private buildRunPersistenceInput;
     /**
      * 调用嵌套深度限制检测（超限时返回 ACTION_CALL_CYCLE 错误）。
      */
@@ -303,6 +285,14 @@ export declare class ActionRunner {
      * 异常分类收敛：超时、取消与业务失败分别映射为对应终态与错误码。
      */
     private classifyExecutionError;
+    /**
+     * 释放 Runner 持有的跨包资源：遍历关闭全部子包 Runner 及其独立创建的存储连接。
+     *
+     * 幂等且并发安全：重复调用直接复用首次 Promise；子包存储异常不阻断其余释放；
+     * 仅关闭由本 Runner 构建子包 Runner 时独立创建的存储，外部注入的存储（如经
+     * packageContextResolver 传入的目标包自身存储）生命周期归所有者管理，不在此误关。
+     */
+    dispose(): Promise<void>;
     /**
      * 同步等待方式执行指定 Action，直接返回 ExecutionResult 信封结果。
      *