@actiondock/core 2.0.1 → 2.0.3

package/src/runtime/clock.ts

@@ -0,0 +1,41 @@
+/**
+ * 统一时间与时钟接口。
+ */
+export interface Clock {
+  /** 获取当前系统墙上时间 */
+  now(): Date;
+  /** 获取单调递增时间戳（单位：毫秒） */
+  monotonic(): number;
+  /** 异步休眠指定毫秒 */
+  sleep(ms: number): Promise<void>;
+}
+
+/**
+ * 生产环境系统时钟实现。
+ */
+export class SystemClock implements Clock {
+  now(): Date {
+    return new Date();
+  }
+
+  monotonic(): number {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+      return performance.now();
+    }
+    return Date.now();
+  }
+
+  sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+let defaultClock: Clock = new SystemClock();
+
+export function getSystemClock(): Clock {
+  return defaultClock;
+}
+
+export function setSystemClock(clock: Clock): void {
+  defaultClock = clock;
+}

package/src/runtime/context.ts

@@ -1,15 +1,19 @@
+import { randomUUID } from "node:crypto";
 import type {
   ActionContext,
   ActionDefinition,
   ActionInvoker,
   Config,
   Logger,
+  ProcessAPI,
+  ProgressReporter,
   StateStore,
 } from "@actiondock/sdk";
 import type { ProjectConfig } from "../project/types";
 import { createGlobalStorage } from "../storage";
 import type { RuntimeStorage } from "../storage/types";
 import { resolveEnvValue } from "./env";
+import { getProcessExecutor } from "./process";
 
 /**
  * 生产级配置解析器实现。
@@ -184,8 +188,12 @@ export interface ContextOptions {
   overrides?: Record<string, unknown>;
   projectConfig?: ProjectConfig;
   parentRunId?: string;
+  runId?: string;
+  rootRunId?: string;
   callStack?: string[];
   signal?: AbortSignal;
+  process?: ProcessAPI;
+  progress?: ProgressReporter;
   onActionInvoke?: (
     action: ActionDefinition,
     input: unknown,
@@ -196,7 +204,7 @@ export interface ContextOptions {
 /**
  * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。
  * 
- * @param options 上下文构建参数（包含存储连接、配置覆盖、项目元数据、取消信号与互调委托）
+ * @param options 上下文构建参数
  * @returns 组装完毕的 ActionContext 实例
  */
 export function createActionContext(options: ContextOptions): ActionContext {
@@ -208,6 +216,8 @@ export function createActionContext(options: ContextOptions): ActionContext {
   const state = new RuntimeStateStore(options.storage);
   const log = new StderrLogger();
   const signal = options.signal ?? new AbortController().signal;
+  const currentRunId = options.runId || randomUUID();
+  const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
 
   const invoker: ActionInvoker = {
     async invoke<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O> {
@@ -215,18 +225,30 @@ export function createActionContext(options: ContextOptions): ActionContext {
         return (await options.onActionInvoke(
           action as any,
           input,
-          options.parentRunId
+          currentRunId
         )) as O;
       }
       throw new Error("ActionInvoker not configured with an invocation delegate");
     },
   };
 
+  const processApi = options.process || getProcessExecutor();
+  const progressApi: ProgressReporter = options.progress || {
+    report() {},
+  };
+
   return {
     config,
     state,
     actions: invoker,
+    process: processApi,
     log,
+    progress: progressApi,
     signal,
+    run: {
+      id: currentRunId,
+      rootId: currentRootRunId,
+      parentId: options.parentRunId,
+    },
   };
 }

package/src/runtime/events.ts

@@ -0,0 +1,142 @@
+import type { ExecutionEvent } from "@actiondock/sdk";
+
+export interface EventSink {
+  emit(event: ExecutionEvent): void;
+  subscribe(
+    runId: string,
+    options?: { after?: number; signal?: AbortSignal }
+  ): AsyncIterable<ExecutionEvent>;
+  clear(runId: string): void;
+}
+
+/**
+ * 进程内有界事件缓冲区实现。
+ * 遵循设计文档：每个运行最多保留 1024 条或 1MB 事件，支持单调序号。
+ */
+export class InMemoryEventSink implements EventSink {
+  private eventsByRun = new Map<string, ExecutionEvent[]>();
+  private listeners = new Map<string, Set<(event: ExecutionEvent) => void>>();
+  private maxEventsPerRun = 1024;
+
+  emit(event: ExecutionEvent): void {
+    let list = this.eventsByRun.get(event.runId);
+    if (!list) {
+      list = [];
+      this.eventsByRun.set(event.runId, list);
+    }
+
+    if (list.length >= this.maxEventsPerRun) {
+      // 淘汰旧日志和进度事件，保留状态和结果
+      const nonEssentialIndex = list.findIndex((e) => e.type === "log" || e.type === "progress");
+      if (nonEssentialIndex >= 0) {
+        list.splice(nonEssentialIndex, 1);
+      } else {
+        list.shift();
+      }
+    }
+    list.push(event);
+
+    const subs = this.listeners.get(event.runId);
+    if (subs) {
+      for (const listener of subs) {
+        try {
+          listener(event);
+        } catch {
+          // 忽略单个监听器内部异常
+        }
+      }
+    }
+  }
+
+  async *subscribe(
+    runId: string,
+    options: { after?: number; signal?: AbortSignal } = {}
+  ): AsyncIterable<ExecutionEvent> {
+    const after = options.after ?? -1;
+    const history = this.eventsByRun.get(runId) || [];
+
+    for (const evt of history) {
+      if (evt.sequence > after) {
+        yield evt;
+      }
+    }
+
+    const lastEvt = history[history.length - 1];
+    if (lastEvt && (lastEvt.type === "finish" || lastEvt.type === "status" && lastEvt.status !== "running")) {
+      return;
+    }
+
+    const queue: ExecutionEvent[] = [];
+    let notify: (() => void) | null = null;
+    let done = false;
+
+    const listener = (evt: ExecutionEvent) => {
+      if (evt.sequence > after) {
+        queue.push(evt);
+        if (notify) {
+          notify();
+          notify = null;
+        }
+        if (evt.type === "finish") {
+          done = true;
+        }
+      }
+    };
+
+    let subs = this.listeners.get(runId);
+    if (!subs) {
+      subs = new Set();
+      this.listeners.set(runId, subs);
+    }
+    subs.add(listener);
+
+    const cleanup = () => {
+      subs?.delete(listener);
+      if (subs && subs.size === 0) {
+        this.listeners.delete(runId);
+      }
+    };
+
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => {
+        done = true;
+        if (notify) {
+          notify();
+          notify = null;
+        }
+      }, { once: true });
+    }
+
+    try {
+      while (!done && !options.signal?.aborted) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else {
+          await new Promise<void>((resolve) => {
+            notify = resolve;
+          });
+        }
+      }
+      while (queue.length > 0) {
+        yield queue.shift()!;
+      }
+    } finally {
+      cleanup();
+    }
+  }
+
+  clear(runId: string): void {
+    this.eventsByRun.delete(runId);
+    this.listeners.delete(runId);
+  }
+}
+
+let defaultEventSink: EventSink = new InMemoryEventSink();
+
+export function getDefaultEventSink(): EventSink {
+  return defaultEventSink;
+}
+
+export function setDefaultEventSink(sink: EventSink): void {
+  defaultEventSink = sink;
+}

package/src/runtime/index.ts

@@ -3,3 +3,7 @@ export * from "./runner";
 export * from "./execution-manager";
 export * from "./standalone";
 export * from "./env";
+export * from "./clock";
+export * from "./process";
+export * from "./events";
+

package/src/runtime/process.ts

@@ -0,0 +1,244 @@
+import { spawn } from "node:child_process";
+import type {
+  DetachedProcessOptions,
+  DetachedProcessResult,
+  ProcessAPI,
+  ProcessExecOptions,
+  ProcessResult,
+  RuntimeError,
+} from "@actiondock/sdk";
+
+export type ProcessExecutor = ProcessAPI;
+
+let globalProcessExecutor: ProcessExecutor | undefined;
+
+export function setProcessExecutor(executor: ProcessExecutor): void {
+  globalProcessExecutor = executor;
+}
+
+export function getProcessExecutor(): ProcessExecutor {
+  if (!globalProcessExecutor) {
+    globalProcessExecutor = new DefaultProcessExecutor();
+  }
+  return globalProcessExecutor;
+}
+
+/**
+ * 基于 Node.js 标准 child_process 实现的基础进程执行器。
+ */
+export class DefaultProcessExecutor implements ProcessExecutor {
+  async exec(
+    command: string,
+    args: string[] = [],
+    options: ProcessExecOptions = {}
+  ): Promise<ProcessResult> {
+    const startTime = Date.now();
+    const maxOutputBytes = options.maxOutputBytes ?? 10 * 1024 * 1024;
+
+    return new Promise<ProcessResult>((resolve, reject) => {
+      let stdoutBuf = "";
+      let stderrBuf = "";
+      let totalBytes = 0;
+      let timedOut = false;
+      let cancelled = false;
+      let error: RuntimeError | undefined;
+
+      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: ReturnType<typeof setTimeout> | undefined;
+      if (options.timeoutMs && options.timeoutMs > 0) {
+        timer = setTimeout(() => {
+          timedOut = true;
+          cp.kill("SIGTERM");
+          setTimeout(() => {
+            if (!cp.killed) cp.kill("SIGKILL");
+          }, 1000);
+        }, options.timeoutMs);
+      }
+
+      const onAbort = () => {
+        cancelled = true;
+        cp.kill("SIGTERM");
+        setTimeout(() => {
+          if (!cp.killed) cp.kill("SIGKILL");
+        }, 1000);
+      };
+
+      if (options.signal) {
+        if (options.signal.aborted) {
+          onAbort();
+        } else {
+          options.signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+
+      cp.stdout?.on("data", (chunk: Buffer) => {
+        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: Buffer) => {
+        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) => {
+        if (timer) clearTimeout(timer);
+        const durationMs = Date.now() - startTime;
+        const res: ProcessResult = {
+          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) => {
+        if (timer) clearTimeout(timer);
+        const durationMs = Date.now() - startTime;
+        const ok = exitCode === 0 && !timedOut && !cancelled && !error;
+
+        const res: ProcessResult = {
+          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 spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult> {
+    const startTime = Date.now();
+    try {
+      const child = spawn(options.command, options.args || [], {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        detached: true,
+        stdio: "ignore",
+      });
+
+      child.unref();
+
+      if (!options.probe) {
+        return {
+          ok: true,
+          pid: child.pid,
+          ready: true,
+          durationMs: Date.now() - startTime,
+        };
+      }
+
+      const probeInterval = options.probeIntervalMs ?? 200;
+      const probeTimeout = options.probeTimeoutMs ?? 5000;
+      const deadline = Date.now() + probeTimeout;
+
+      while (Date.now() < deadline) {
+        if (options.signal?.aborted) {
+          return {
+            ok: false,
+            pid: child.pid,
+            ready: false,
+            durationMs: Date.now() - startTime,
+            error: {
+              code: "PROCESS_CANCELLED",
+              message: "Probe was cancelled by AbortSignal",
+            },
+          };
+        }
+
+        try {
+          const checkRes = await this.exec(options.command, ["--version"], {
+            timeoutMs: 1000,
+          });
+          const isReady = await options.probe(checkRes);
+          if (isReady) {
+            return {
+              ok: true,
+              pid: child.pid,
+              ready: true,
+              durationMs: Date.now() - startTime,
+            };
+          }
+        } catch {
+          // 探测失败继续轮询
+        }
+
+        await new Promise((r) => setTimeout(r, probeInterval));
+      }
+
+      return {
+        ok: false,
+        pid: child.pid,
+        ready: false,
+        durationMs: Date.now() - startTime,
+        error: {
+          code: "PROCESS_PROBE_TIMEOUT",
+          message: `Process probe timed out after ${probeTimeout}ms`,
+        },
+      };
+    } catch (err: any) {
+      return {
+        ok: false,
+        ready: false,
+        durationMs: Date.now() - startTime,
+        error: {
+          code: "PROCESS_DETACHED_FAILED",
+          message: err.message,
+        },
+      };
+    }
+  }
+}

package/src/runtime/runner.ts

@@ -3,6 +3,9 @@ import type {
   ActionContext,
   ActionDefinition,
   ExecutionResult,
+  JsonValue,
+  ProcessAPI,
+  ProgressReporter,
   RuntimeError,
   RunRecord,
 } from "@actiondock/sdk";
@@ -10,6 +13,7 @@ import type { ProjectConfig } from "../project/types";
 import { validateSchema } from "../schema/validator";
 import type { RuntimeStorage, TerminalRunStatus } from "../storage/types";
 import { RuntimeConfig, RuntimeStateStore, StderrLogger } from "./context";
+import { getProcessExecutor } from "./process";
 
 /**
  * ActionRunner 初始化配置选项。
@@ -25,20 +29,34 @@ export interface RunnerOptions {
   configOverrides?: Record<string, unknown>;
   /** 预加载的 Action 映射表 */
   actions?: Map<string, ActionDefinition>;
+  /** 外部注入的进程执行器 */
+  process?: ProcessAPI;
 }
 
 /**
  * 启动 Action 执行时的可选控制参数。
  */
 export interface ExecutionStartOptions {
+  /** 根运行 ID */
+  rootRunId?: string;
   /** 父级运行 ID（嵌套调用场景下建立调用链树） */
   parentRunId?: string;
+  /** 包物理实例标识 */
+  packageInstanceId?: string;
+  /** 快照代次标识 */
+  generationId?: string;
+  /** 执行所有者标识 */
+  ownerId?: string;
   /** 调用栈数组（用于检测 A -> B -> A 环路死锁） */
   callStack?: string[];
   /** 外部传入的 AbortSignal 取消信号 */
   signal?: AbortSignal;
   /** 最大超时时间（毫秒），超时将自动中止执行并标记为 ACTION_TIMEOUT */
   timeoutMs?: number;
+  /** 外部注入的进程执行器 */
+  process?: ProcessAPI;
+  /** 外部注入的进度报告器 */
+  progress?: ProgressReporter;
 }
 
 /**
@@ -173,11 +191,15 @@ export class ActionRunner {
     // 3. 插入初始运行记录 (状态: running)
     const initialRun: RunRecord = {
       id: runId,
+      rootRunId: options.rootRunId || options.parentRunId || runId,
+      parentRunId: options.parentRunId,
       packageId: this.packageId,
+      packageInstanceId: options.packageInstanceId || this.packageId,
       actionId: action.id,
-      parentRunId: options.parentRunId,
+      generationId: options.generationId || "1",
+      ownerId: options.ownerId || "local",
       status: "running",
-      input,
+      input: input as JsonValue | undefined,
       startedAt,
     };
     this.storage.createRun(initialRun);
@@ -235,9 +257,12 @@ export class ActionRunner {
         childInput: I
       ): Promise<O> => {
         const childResult = await this.execute(childAction, childInput, {
+          rootRunId: initialRun.rootRunId,
           parentRunId: runId,
           callStack,
           signal: controller.signal,
+          process: options.process,
+          progress: options.progress,
         });
         if (!childResult.ok) {
           const err = new Error(childResult.error.message);
@@ -253,8 +278,17 @@ export class ActionRunner {
       config,
       state,
       actions: invoker,
+      process: options.process || getProcessExecutor(),
       log,
+      progress: options.progress || {
+        report() {},
+      },
       signal: controller.signal,
+      run: {
+        id: runId,
+        rootId: initialRun.rootRunId,
+        parentId: options.parentRunId,
+      },
     };
 
     // 6. 执行 Action 业务逻辑并与取消/超时信号进行竞态
@@ -295,7 +329,7 @@ export class ActionRunner {
         return {
           ok: true,
           runId,
-          data: rawOutput,
+          data: rawOutput as JsonValue,
         };
       } catch (err: any) {
         if (isTimeout) {

package/src/server/runtime-registry.ts

@@ -12,12 +12,47 @@ import type { RuntimeStorage } from "../storage/types";
  */
 export class ServerRuntimeRegistry {
   private storages = new Map<string, RuntimeStorage>();
+  private listeners = new Map<string, Set<(event: { type: string; data: any }) => void>>();
   public executionManager: ExecutionManager;
 
   constructor() {
     this.executionManager = new ExecutionManager();
   }
 
+  /**
+   * 订阅指定 runId 的事件（用于 SSE 流式推送）。
+   */
+  public subscribe(runId: string, listener: (event: { type: string; data: any }) => void): () => void {
+    let set = this.listeners.get(runId);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(runId, set);
+    }
+    set.add(listener);
+    return () => {
+      set?.delete(listener);
+      if (set && set.size === 0) {
+        this.listeners.delete(runId);
+      }
+    };
+  }
+
+  /**
+   * 向指定 runId 的订阅者广播事件。
+   */
+  public emit(runId: string, event: { type: string; data: any }): void {
+    const set = this.listeners.get(runId);
+    if (set) {
+      for (const listener of set) {
+        try {
+          listener(event);
+        } catch {
+          // 忽略单个监听器错误
+        }
+      }
+    }
+  }
+
   /**
    * 获取或懒加载指定 Package 和 projectRoot 的缓存 RuntimeStorage 实例。
    *