@actiondock/core 2.9.1 → 2.11.0

package/dist/errors.js

@@ -75,8 +75,6 @@ export const STORAGE_BUSY = "STORAGE_BUSY";
 export const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
 export const PROJECT_RECOVERY_REQUIRED = "PROJECT_RECOVERY_REQUIRED";
-/** SQLite 工作线程已退出 */
-export const STORAGE_WORKER_EXITED = "STORAGE_WORKER_EXITED";
 /** 事件订阅队列积压超过背压上限 */
 export const EVENT_BACKPRESSURE_LIMIT = "EVENT_BACKPRESSURE_LIMIT";
 export const EVENT_CURSOR_EXPIRED = "EVENT_CURSOR_EXPIRED";
@@ -178,7 +176,7 @@ export function describeActionLoadFailure(err, context) {
     const rootCause = err instanceof Error ? err.message : String(err ?? "");
     const isMissingModule = isMissingModuleError(rootCause);
     const hint = isMissingModule
-        ? `依赖未安装，在 '${context.projectRoot}' 执行 npm install 或先执行 'ad run ${context.packageId}/${context.actionId}'`
+        ? `Project dependencies are missing. Run 'npm install --omit=dev' in '${context.projectRoot}' and try again.`
         : undefined;
     return {
         code: ACTION_LOAD_FAILED,
@@ -255,6 +253,58 @@ export const AMBIGUOUS_STATE_KEY = "AMBIGUOUS_STATE_KEY";
 export const RUN_NOT_FOUND = "RUN_NOT_FOUND";
 /** 目标运行已进入终态不可操作 */
 export const RUN_ALREADY_FINISHED = "RUN_ALREADY_FINISHED";
+/** 目标环境配置 Profile 未找到 */
+export const PROFILE_NOT_FOUND = "PROFILE_NOT_FOUND";
+/** 锁文件读取失败 */
+export const LOCKFILE_READ_FAILED = "LOCKFILE_READ_FAILED";
+/** 锁文件内容损坏或存在重复键 */
+export const LOCKFILE_CORRUPTED = "LOCKFILE_CORRUPTED";
+/** 锁文件结构或格式非法 */
+export const LOCKFILE_INVALID = "LOCKFILE_INVALID";
+/** 不受支持的锁文件版本 */
+export const UNSUPPORTED_LOCKFILE_VERSION = "UNSUPPORTED_LOCKFILE_VERSION";
+/** 项目清单读取失败 */
+export const MANIFEST_READ_FAILED = "MANIFEST_READ_FAILED";
+/** 项目清单 JSON 解析失败或内容损坏 */
+export const MANIFEST_CORRUPTED = "MANIFEST_CORRUPTED";
+/** 项目清单结构或格式非法 */
+export const MANIFEST_INVALID = "MANIFEST_INVALID";
+/** 不受支持的项目清单 Schema 版本 */
+export const UNSUPPORTED_MANIFEST_SCHEMA = "UNSUPPORTED_MANIFEST_SCHEMA";
+/** 项目清单文件 actiondock.json 未找到 */
+export const MANIFEST_NOT_FOUND = "MANIFEST_NOT_FOUND";
+/** 清单确定性摘要与锁文件记录不一致 */
+export const MANIFEST_DIGEST_MISMATCH = "MANIFEST_DIGEST_MISMATCH";
+/** 全局注册表文件损坏或格式非法 */
+export const REGISTRY_CORRUPTED = "REGISTRY_CORRUPTED";
+/** 底层 SQLite 存储不支持异步事务 */
+export const ASYNC_TRANSACTION_UNSUPPORTED = "ASYNC_TRANSACTION_UNSUPPORTED";
+/** 底层存储或数据库连接已关闭 */
+export const STORAGE_CLOSED = "STORAGE_CLOSED";
+/** 多个不同物理路径声明了相同的包标识冲突 */
+export const PACKAGE_ID_CONFLICT = "PACKAGE_ID_CONFLICT";
+/** 路径参数非法（含空字节或非字符串） */
+export const INVALID_PATH = "INVALID_PATH";
+/** 存储数据目录初始化失败 */
+export const STORAGE_INIT_FAILED = "STORAGE_INIT_FAILED";
+/** 对象处于非法状态或缺少必要内部资源 */
+export const INVALID_STATE = "INVALID_STATE";
+/** 目标进程未找到或不存在 */
+export const PROCESS_NOT_FOUND = "PROCESS_NOT_FOUND";
+/** 模块标识符解析失败 */
+export const MODULE_RESOLVE_FAILED = "MODULE_RESOLVE_FAILED";
+/** 执行并发达到上限 */
+export const EXECUTION_CONCURRENCY_LIMIT = "EXECUTION_CONCURRENCY_LIMIT";
+/** 项目配置文件 actiondock.json 未找到 */
+export const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
+/** 项目清单加载失败 */
+export const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
+/** 动作标识符不符合命名规范 */
+export const INVALID_ACTION_ID = "INVALID_ACTION_ID";
+/** 规程标识符不符合命名规范 */
+export const INVALID_PLAYBOOK_ID = "INVALID_PLAYBOOK_ID";
+/** 项目根目录未找到或不是合法的 ActionDock 包 */
+export const PROJECT_ROOT_NOT_FOUND = "PROJECT_ROOT_NOT_FOUND";
 /**
  * ActionDock 统一基础结构化异常类。
  * 全仓各领域异常与跨层透传异常的统一事实源基类。
@@ -263,15 +313,75 @@ export class ActionDockError extends Error {
     code;
     details;
     status;
-    constructor(code, message, details, status) {
+    hint;
+    constructor(code, message, details, status, hint) {
         super(message);
         this.name = "ActionDockError";
         this.code = code;
         this.details = details;
         this.status = status;
+        this.hint =
+            hint ??
+                (details && typeof details === "object" && typeof details.hint === "string"
+                    ? details.hint
+                    : undefined);
         Object.setPrototypeOf(this, ActionDockError.prototype);
     }
 }
+/**
+ * 统一构造机器错误信封。
+ */
+export function createErrorEnvelope(code, message, details, meta, hint) {
+    const effectiveHint = hint ??
+        (details && typeof details === "object" && typeof details.hint === "string"
+            ? details.hint
+            : undefined);
+    const result = {
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+    };
+    if (effectiveHint !== undefined) {
+        result.hint = effectiveHint;
+    }
+    if (meta && Object.keys(meta).length > 0) {
+        result.meta = meta;
+    }
+    return result;
+}
+/**
+ * 根据 Action 执行失败错误解析自愈指引提示文案。
+ *
+ * 作为 CLI 与独立分发器（StandaloneDispatcher）执行失败时提示解析的单一事实源。
+ *
+ * @param targetRef 目标 Action 引用标识（如 "greet" 或 "pkg/greet"）
+ * @param error 执行失败错误对象
+ */
+export function resolveExecutionHint(targetRef, error) {
+    if (!error)
+        return undefined;
+    if (error.code === INPUT_VALIDATION_FAILED) {
+        return `Tip: Run 'ad describe ${targetRef}' to inspect schema and syntax examples.`;
+    }
+    if (error.code === ACTION_NOT_FOUND) {
+        return "Tip: Run 'ad list' to discover available actions, or 'ad info' to inspect packages.";
+    }
+    if (error.code === ACTION_TIMEOUT) {
+        return "Tip: Increase timeout via '--timeout <duration>', or run in background via '--async' and track with 'ad runs show <runId>'.";
+    }
+    if (error.hint && typeof error.hint === "string") {
+        return error.hint;
+    }
+    if (error.details &&
+        typeof error.details === "object" &&
+        typeof error.details.hint === "string") {
+        return error.details.hint;
+    }
+    return undefined;
+}
 /**
  * 进程领域结构化异常类。
  */

package/dist/execution/service.d.ts

@@ -1,36 +1,56 @@
-import type { ActionDefinition, ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionDefinition, ActionRef, ExecutionEvent, ExecutionResult, RunRecord } from "@actiondock/sdk";
 import { type EventSink } from "../runtime/events.js";
-import { type ExecutionHandle } from "../runtime/runner.js";
+import { type RuntimeStorage } from "../storage/types.js";
 import { type PackageIdentity } from "../runtime/identity.js";
-import type { ActionInvoker, CancelResult, ExecutionService, ExecutionServiceOptions, ExecutionTicket, InvocationContext } from "./types.js";
+import type { ActionInvoker, CancelResult, ExecutionHandle, ExecutionService, ExecutionServiceOptions, ExecutionTicket } from "./types.js";
+import { type InvocationContext, type RunOptions } from "../invocation/types.js";
 export type { ExecutionServiceOptions };
 /**
- * 统一执行协调服务实现。
+ * 在途运行心跳刷新间隔（毫秒）。
+ *
+ * 必须显著小于存活判定的宽限期（见 run-liveness 的 RUN_LIVENESS_GRACE_MS），
+ * 保证心跳正常的宿主绝不被误判过期；间隔内崩溃由进程探测兜底，
+ * 心跳只服务无进程标识的遗留记录收敛判定。
+ */
+export declare const RUN_HEARTBEAT_INTERVAL_MS = 30000;
+/**
+ * 统一执行引擎（融合原协调服务与运行器）。
+ * 消除双层 AbortController 与重复参数透传，收敛唯一生命周期与存储落库。
  */
 export declare class DefaultExecutionService implements ExecutionService {
     readonly identity: PackageIdentity;
     readonly packageId: string;
+    readonly packageInstanceId: string;
+    readonly generationId: string;
+    hostSessionId?: string;
+    /** 宿主进程标识：落库到运行记录供跨进程存活判定（并发打开同一数据目录时不误收割） */
+    readonly hostPid: number;
+    readonly eventSink: EventSink;
     private storage;
+    private globalStorage?;
     private projectConfig?;
     private projectRoot?;
+    private configOverrides;
     private moduleLoader?;
-    readonly eventSink: EventSink;
-    readonly packageInstanceId: string;
-    readonly generationId: string;
     private maxActiveRuns;
     private ownerId;
-    hostSessionId?: string;
-    private _runner;
+    private actionResolver?;
     private logger?;
-    private clock?;
+    private clock;
     private process?;
-    private actionResolver?;
-    private activeRuns;
-    private globalStorage?;
     private actionInvoker?;
+    private registry;
+    private activeRuns;
+    /** 在途运行心跳定时器：周期性刷新心跳时间戳，支撑无进程标识判定路径的兜底收敛 */
+    private heartbeatTimer?;
     private isClosing;
     private reservedSlots;
     constructor(options: ExecutionServiceOptions);
+    /** 获取运行底层存储实例 */
+    getStorage(): RuntimeStorage;
+    /** 兼容性引用，执行引擎即执行器自身 */
+    get _runner(): this;
+    get activeRunsCount(): number;
     setActionInvoker(invoker?: ActionInvoker): void;
     registerAction(id: string, action: ActionDefinition): void;
     registerAction(action: ({
@@ -40,35 +60,21 @@ export declare class DefaultExecutionService implements ExecutionService {
     getAction(id: string): ActionDefinition | undefined;
     listActions(): ActionDefinition[];
     getActiveHandle(runId: string): ExecutionHandle | undefined;
-    execute(ref: ActionRef | string, input: JsonValue, context: InvocationContext): Promise<ExecutionResult>;
-    run(ref: ActionRef | string, input: JsonValue, context: InvocationContext): Promise<ExecutionResult>;
-    get activeRunsCount(): number;
-    start(ref: ActionRef | string, input: JsonValue, context: InvocationContext): Promise<ExecutionTicket>;
-    /**
-     * 幂等门检查：digest 计算与冲突/重复分流（重复命中时直接返回已有票据）。
-     */
+    execute(ref: ActionDefinition | ActionRef | string, input?: unknown, contextOrOptions?: InvocationContext | RunOptions | Record<string, unknown>): Promise<ExecutionResult>;
+    run(ref: ActionDefinition | ActionRef | string, input?: unknown, contextOrOptions?: InvocationContext | RunOptions | Record<string, unknown>): Promise<ExecutionResult>;
+    start(ref: ActionDefinition | ActionRef | string, input?: unknown, contextOrOptions?: InvocationContext | RunOptions | Record<string, unknown>): Promise<ExecutionTicket & ExecutionHandle>;
+    private normalizeContext;
+    private raceExecution;
+    private classifyExecutionError;
+    private invokeChildAction;
     private checkIdempotencyGate;
-    /**
-     * 解析执行目标：确定目标 Action 定义。
-     * 铁律 4：Runner 不找 Package，ExecutionService 仅执行本 Package 的 Action。
-     */
     private resolveExecutionTarget;
-    /**
-     * 解析指定 Action 定义（供 PackageRuntime 或内部使用）。
-     */
     resolveAction(ref: ActionRef | string): Promise<ActionDefinition | undefined>;
-    /**
-     * 目标 Action 缺失时的失败票据：落库 failed 记录并补发 status 与 finish 事件。
-     */
     private failTicketForMissingAction;
-    /**
-     * 创建执行事件桥：事件序列号分配、进度报告器与双写日志适配器。
-     */
+    private buildPersistenceInput;
+    private checkActionInputSchema;
+    private checkActionOutputSchema;
     private createEventBridge;
-    /**
-     * 监听执行句柄终态：映射终态状态、补发 status 与 finish 事件并注销活跃运行。
-     */
-    private watchHandleCompletion;
     get(runId: string): Promise<RunRecord | undefined>;
     cancel(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
@@ -76,8 +82,20 @@ export declare class DefaultExecutionService implements ExecutionService {
         signal?: AbortSignal;
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
+    /**
+     * 确保在途运行心跳定时器存在。
+     *
+     * 存活判定的第一依据是进程探测（运行记录已落库宿主进程标识），
+     * 心跳是对遗留记录（无进程标识）与其他协作场景的兜底信号：
+     * 持有进程周期性刷新在途记录的心跳时间戳，收割方仅对心跳过期的
+     * 遗留记录做宽限期判定，正常运行中的记录绝不会被误判过期。
+     * 定时器不阻塞进程退出（unref），无在途运行时不产生任何调度。
+     */
+    private ensureHeartbeatTimer;
     close(options?: {
         graceMs?: number;
     }): Promise<void>;
+    dispose(): Promise<void>;
 }
 export { DefaultExecutionService as ExecutionService };
+export { DefaultExecutionService as ActionRunner };