@actiondock/sdk 2.0.2 → 2.0.3

package/README.md

@@ -1,121 +1,107 @@
 # @actiondock/sdk
 
-The lightweight, zero-dependency SDK for defining, orchestrating, and testing AI Agent Actions and Skills in ActionDock 2.0.
+ActionDock 2.0 纯净核心开发者接口契约包。
 
-[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.2-black?logo=bun)](https://bun.sh/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-> **Runtime requirement**: [Bun](https://bun.sh/) >= 1.2.0 is required.
+`@actiondock/sdk` 为开发者编写原子 Action 提供零外部依赖的纯净类型定义与核心契约。
 
 ---
 
-## Installation
+## 安装方式
+
+使用标准包管理器添加依赖：
 
 ```bash
-bun add @actiondock/sdk
+npm install @actiondock/sdk
 ```
 
 ---
 
-## Quick Example
+## 核心契约与函数
+
+### defineAction 函数
 
-### 1. Define an Action (`actions/greet.ts`)
+用于声明并严格校验单个 Action 的静态属性与执行函数：
 
 ```ts
 import { defineAction } from "@actiondock/sdk";
 
 export default defineAction({
-  id: "sample.greet",
-  description: "Greet a user and track greeting count in persistent state",
+  id: "calculator.add",
+  description: "计算两个数值之和",
 
   inputSchema: {
     type: "object",
     properties: {
-      name: { type: "string", minLength: 1 },
+      a: { type: "number", description: "第一个加数" },
+      b: { type: "number", description: "第二个加数" },
     },
-    required: ["name"],
+    required: ["a", "b"],
   },
 
-  async run(input: { name: string }, ctx) {
-    const greeting = ctx.config.get("GREETING_PREFIX", "Hello");
-    const count = ((await ctx.state.get<number>(`greet:${input.name}`)) || 0) + 1;
-    await ctx.state.set(`greet:${input.name}`, count);
-    ctx.log.info(`Greeted ${input.name} ${count} time(s)`);
+  outputSchema: {
+    type: "object",
+    properties: {
+      result: { type: "number", description: "计算结果" },
+    },
+    required: ["result"],
+  },
 
+  async run(input, ctx) {
+    ctx.log.info(`计算加法: ${input.a} + ${input.b}`);
     return {
-      message: `${greeting}, ${input.name}!`,
-      count,
+      result: input.a + input.b,
     };
   },
 });
 ```
 
-### 2. Test in Milliseconds (`tests/greet.test.ts`)
+`defineAction` 支持的完整契约字段：
 
-```ts
-import { describe, expect, it } from "bun:test";
-import { createTestRuntime } from "@actiondock/sdk";
-import greetAction from "../actions/greet";
-
-describe("sample.greet Action", () => {
-  it("greets user and updates state counter", async () => {
-    const runtime = createTestRuntime({
-      config: { GREETING_PREFIX: "Welcome" },
-      state: { "greet:Alice": 2 },
-    });
-
-    const result = await runtime.run(greetAction, { name: "Alice" });
-    expect(result.message).toBe("Welcome, Alice!");
-    expect(result.count).toBe(3);
-    expect(await runtime.state.get("greet:Alice")).toBe(3);
-  });
-});
-```
+- `id`：动作唯一标识符，格式通常为领域或命名空间前缀拼接名称。
+- `description`：动作功能的人类可读说明。
+- `inputSchema`：入参模式规范，采用标准 JSON Schema 格式。
+- `outputSchema`：出参模式规范，采用标准 JSON Schema 格式。
+- `uses`：静态声明当前 Action 所依赖的其他 Action 标识列表。
+- `tags`：用于分类与检索的标签数组。
+- `annotations`：面向协议适配器的扩展注解字典。
+- `run`：业务执行入口函数，接收已通过校验的入参数据和运行时上下文对象。
 
 ---
 
-## Core Capabilities
+## ActionContext 运行时上下文
 
-- `ActionContext`:
-  - `ctx.config`: 5-tier configuration resolution (`override > sqlite > env > default > fallback`)
-  - `ctx.state`: Embedded SQLite state store with namespace and TTL support
-  - `ctx.actions`: Inter-action invocation with cycle detection
-  - `ctx.log`: Isolated logging directed to `stderr`
-  - `ctx.signal`: Cooperative cancellation via `AbortSignal`
-- `execCli`: Deadlock-safe, cross-platform synchronous CLI executor with Windows `.cmd` resolution, stdin streaming, timeout, and signal support.
-- `spawnDetached`: Safe asynchronous launcher for daemon-spawning CLI tools (e.g., `agent-browser open`), preventing pipe EOF hangs via fire-and-forget stdio decoupling and polling probe.
-- `createTestRuntime`: Fast, zero-dependency in-memory test harness for unit tests.
-
----
+在 Action 执行时，宿主环境注入标准化上下文对象 `ActionContext`，提供受控的系统交互能力：
 
-## API Summary
-
-| Export | Type | Description |
-|---|---|---|
-| `defineAction(def)` | Function | Defines and defensively validates an Action |
-| `createTestRuntime(opts)` | Function | Creates an in-memory test runner (`config`, `state`, `logger`, `run()`) |
-| `execCli(cmd, args, opts)` | Function | Synchronous, deadlock-safe CLI execution utility |
-| `spawnDetached(opts)` | Function | Safe asynchronous launcher & readiness prober for daemon-spawning CLI tools |
-| `MemoryConfig` | Class | In-memory `Config` provider for unit tests |
-| `MemoryStateStore` | Class | In-memory `StateStore` with TTL and namespace support |
-| `MemoryLogger` | Class | In-memory `Logger` collecting log entries for test assertions |
-| `ActionContext` | Interface | Runtime context provided to `action.run(input, ctx)` |
-| `ActionDefinition` | Interface | Schema and execution contract for an Action |
-| `ExecutionResult` | Type | Standard JSON envelope (`ok: true, data` or `ok: false, error`) |
+- `ctx.process`：进程执行接口，提供 `exec` 与 `spawnDetached`，安全调用系统外部命令或启动后台守护进程，支持超时与输出截断保护。
+- `ctx.log`：结构化日志输出接口，提供 `debug`、`info`、`warn`、`error` 级别日志。日志严格输出至标准错误流，彻底隔离标准输出流，杜绝污染协议报文。
+- `ctx.progress`：进度报告器，支持在长时间运行的任务中通过 `report(current, total, message)` 上报当前阶段。
+- `ctx.signal`：协作式取消信号，类型为标准 `AbortSignal`。当任务被外部客户端取消或超时时自动触发中止，业务逻辑需主动监听并响应。
+- `ctx.run`：当前执行实例元数据，包含 `id`（本次运行标识）、`rootId`（根调用标识）和 `parentId`（父级调用标识），便于全链路追踪。
+- `ctx.config`：分层配置读取接口，提供 `get` 与 `has` 方法，支持优先级回退与类型强转。
+- `ctx.state`：持久化状态接口，提供基于当前 Package 命名空间隔离的键值存储与存活时间控制。
+- `ctx.actions`：动作相互调用接口，支持调用包内其他 Action，并内置调用栈环路死锁检测。
 
 ---
 
-## 📖 Documentation
+## 快速单元测试
 
-For detailed guides, design principles, and exhaustive API references, see the [ActionDock Documentation Center](../../docs/README.md):
+结合 `@actiondock/testing` 或 SDK 内置的测试辅助方法，可以在纯内存环境下毫秒级验证 Action：
 
-- [Action SDK API Reference](../../docs/reference/action-api.md)
-- [ActionContext Concept](../../docs/concepts/action-context.md)
-- [Testing & Verification Guide](../../docs/developer/testing.md)
+```ts
+import { createTestRuntime } from "@actiondock/sdk";
+import addAction from "../actions/add";
+
+const runtime = createTestRuntime();
+const result = await runtime.run(addAction, { a: 10, b: 20 });
+console.log(result.result); // 输出 30
+```
 
 ---
 
-## License
+## 开源协议
 
-[Apache-2.0](../../LICENSE) © team4u
+本项目采用 Apache-2.0 开源协议。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/sdk",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "ActionDock SDK for defining and testing standalone AI Agent Actions",
   "type": "module",
   "main": "./src/index.ts",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "engines": {
-    "bun": ">=1.2.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/cli.ts

@@ -77,6 +77,48 @@ export interface ExecCliResult {
  * @param options 运行选项（工作目录、环境变量、取消信号、超时、stdin、字符编码、抛错开关）
  * @returns ExecCliResult 执行结果结构体
  */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/**
+ * 跨运行时安全查找可执行文件绝对物理路径。
+ */
+function findExecutable(command: string): string | null {
+  if (typeof (globalThis as any).Bun !== "undefined" && typeof (globalThis as any).Bun.which === "function") {
+    try {
+      const bPath = (globalThis as any).Bun.which(command);
+      if (bPath) return bPath;
+    } catch {
+      // 忽略 Bun.which 异常，进入通用解析
+    }
+  }
+
+  const hasPathSep = command.includes("/") || command.includes("\\");
+  if (hasPathSep) {
+    return existsSync(command) ? command : null;
+  }
+
+  const pathEnv = process.env.PATH || "";
+  const dirs = pathEnv.split(delimiter);
+  const isWindows = process.platform === "win32";
+  const pathext = isWindows
+    ? (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";")
+    : [""];
+
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of pathext) {
+      const candidate = join(dir, isWindows && !command.includes(".") ? command + ext : command);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
 export function execCli(
   command: string,
   args: string[] = [],
@@ -100,11 +142,11 @@ export function execCli(
     return errRes;
   }
 
-  // 2. 跨平台绝对路径解析（解决 Windows 下 npm 全局 .cmd shim 识别问题）
+  // 2. 跨平台绝对路径解析
   const hasPathSep = command.includes("/") || command.includes("\\");
-  const binPath = hasPathSep ? command : (Bun.which(command) || command);
+  const binPath = hasPathSep ? (existsSync(command) ? command : null) : findExecutable(command);
 
-  if (!hasPathSep && !Bun.which(command)) {
+  if (!binPath) {
     const errRes: ExecCliResult = {
       ok: false,
       exitCode: -1,
@@ -120,27 +162,26 @@ export function execCli(
   }
 
   // 3. 处理标准输入数据
-  let stdinOption: Uint8Array | "ignore" | undefined = "ignore";
+  let stdinInput: Buffer | undefined;
   if (options.input !== undefined) {
     if (typeof options.input === "string") {
-      stdinOption = new TextEncoder().encode(options.input);
+      stdinInput = Buffer.from(options.input);
     } else if (options.input instanceof Uint8Array) {
-      stdinOption = options.input;
+      stdinInput = Buffer.from(options.input);
     }
   }
 
   try {
-    const proc = Bun.spawnSync([binPath, ...args], {
+    const proc = spawnSync(binPath, args, {
       cwd: options.cwd || process.cwd(),
       env: options.env ? { ...process.env, ...options.env } : process.env,
-      stdin: stdinOption,
-      stdout: "pipe",
-      stderr: "pipe",
+      input: stdinInput,
+      stdio: [stdinInput ? "pipe" : "ignore", "pipe", "pipe"],
       timeout: options.timeout,
     });
 
     const durationMs = Math.round(performance.now() - startTime);
-    const timedOut = Boolean((proc as any).exitedDueToTimeout);
+    const timedOut = Boolean(proc.error && (proc.error as any).code === "ETIMEDOUT");
 
     // 4. 自定义字符集解码
     const decoder = new TextDecoder(options.encoding || "utf-8");
@@ -154,7 +195,7 @@ export function execCli(
       stderr = `Command '${command}' timed out after ${options.timeout}ms`;
     }
 
-    const exitCode = timedOut ? -1 : (proc.exitCode ?? (proc.success ? 0 : -1));
+    const exitCode = timedOut ? -1 : (proc.status ?? (proc.error ? -1 : 0));
     const ok = !timedOut && exitCode === 0;
 
     const result: ExecCliResult = {
@@ -255,28 +296,36 @@ export async function spawnDetached(options: SpawnDetachedOptions): Promise<bool
     throw new Error("Command aborted before execution by signal");
   }
 
-  // 2. 跨平台绝对路径解析（解决 Windows 下 npm 全局 .cmd shim 识别问题）
+  // 2. 跨平台绝对路径解析
   const hasPathSep = command.includes("/") || command.includes("\\");
-  const binPath = hasPathSep ? command : (Bun.which(command) || command);
+  const binPath = hasPathSep ? (existsSync(command) ? command : null) : findExecutable(command);
 
-  if (!hasPathSep && !Bun.which(command)) {
+  if (!binPath) {
     throw new Error(`Command '${command}' not found in PATH.`);
   }
 
   // 3. fire-and-forget：ignore 所有 stdio，unref 防止阻塞事件循环
-  const child = Bun.spawn([binPath, ...args], {
+  const child = spawn(binPath, args, {
     cwd: cwd || process.cwd(),
     env: env ? { ...process.env, ...env } : process.env,
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
+    stdio: "ignore",
+    detached: true,
     signal,
   });
   child.unref();
 
-  // 4. 等待 CLI 前端进程自身退出（错开冷启动窗口，避免 probe 并发拉起两个 daemon）
+  // 4. 等待 CLI 前端进程自身退出
   try {
-    await child.exited;
+    await new Promise<void>((resolveChild, rejectChild) => {
+      child.on("exit", () => resolveChild());
+      child.on("error", (err) => {
+        if (signal?.aborted) {
+          rejectChild(new Error("aborted"));
+        } else {
+          rejectChild(err);
+        }
+      });
+    });
   } catch (err) {
     if (signal?.aborted) {
       throw new Error("aborted");

package/src/index.ts

@@ -1,11 +1,4 @@
 export { defineAction } from "./action";
-export {
-  execCli,
-  spawnDetached,
-  type ExecCliOptions,
-  type ExecCliResult,
-  type SpawnDetachedOptions,
-} from "./cli";
 export {
   createTestRuntime,
   MemoryConfig,
@@ -16,16 +9,25 @@ export {
 } from "./test-runtime";
 export type {
   ActionContext,
+  ActionContract,
   ActionDefinition,
   ActionInvoker,
+  ActionRef,
   Config,
+  DetachedProcessOptions,
+  DetachedProcessResult,
+  ExecutionEvent,
   ExecutionResult,
   JsonSchema,
+  JsonValue,
   Logger,
+  ProcessAPI,
+  ProcessExecOptions,
+  ProcessResult,
+  ProgressReporter,
+  ResolvedActionRef,
   RuntimeError,
   RunRecord,
   RunStatus,
   StateStore,
 } from "./types";
-
-

package/src/test-runtime.ts

@@ -1,9 +1,11 @@
+import { execCli, spawnDetached } from "./cli";
 import type {
   ActionContext,
   ActionDefinition,
   ActionInvoker,
   Config,
   Logger,
+  ProcessResult,
   StateStore,
 } from "./types";
 
@@ -248,12 +250,76 @@ export function createTestRuntime(options: TestRuntimeOptions = {}): TestRuntime
       }
       callStack.push(action.id);
       try {
+        const runId = "test-" + Math.random().toString(36).slice(2, 10);
         const ctx: ActionContext = {
           config,
           state,
           actions: invoker,
+          process: {
+            async exec(command, args, options) {
+              const res = await execCli(command, args, {
+                cwd: options?.cwd,
+                env: options?.env,
+                input: options?.input,
+                timeout: options?.timeoutMs,
+                throwOnError: options?.throwOnError,
+                signal: options?.signal,
+              });
+              return {
+                ok: res.ok,
+                exitCode: res.exitCode,
+                stdout: res.stdout,
+                stderr: res.stderr,
+                raw: res.raw,
+                timedOut: res.timedOut ?? false,
+                cancelled: Boolean(options?.signal?.aborted),
+                durationMs: res.durationMs,
+              };
+            },
+            async spawnDetached(options) {
+              const probeFn = options.probe
+                ? async () => {
+                    const fakeRes: ProcessResult = {
+                      ok: true,
+                      exitCode: 0,
+                      stdout: "",
+                      stderr: "",
+                      raw: new Uint8Array(),
+                      timedOut: false,
+                      cancelled: false,
+                      durationMs: 0,
+                    };
+                    return options.probe!(fakeRes);
+                  }
+                : () => true;
+
+              const ready = await spawnDetached({
+                command: options.command,
+                args: options.args,
+                cwd: options.cwd,
+                env: options.env,
+                timeoutMs: options.timeoutMs ?? options.probeTimeoutMs,
+                intervalMs: options.probeIntervalMs,
+                signal: options.signal,
+                probe: probeFn,
+              });
+
+              return {
+                ok: ready,
+                ready,
+                durationMs: 0,
+              };
+            },
+          },
           log: logger,
+          progress: {
+            report() {},
+          },
           signal,
+          run: {
+            id: runId,
+            rootId: runId,
+          },
         };
         return await action.run(input, ctx);
       } finally {

package/src/types.ts

@@ -1,6 +1,17 @@
+/**
+ * 标准 JSON 数据域。
+ */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
 /**
  * 标准 JSON Schema 结构定义。
- * 支持对象模式（Object Schema）或布尔模式（Boolean Schema）。
+ * 支持对象模式或布尔模式。
  */
 export type JsonSchema = Record<string, unknown> | boolean;
 
@@ -8,25 +19,24 @@ export type JsonSchema = Record<string, unknown> | boolean;
  * ActionDock 标准运行时错误对象。
  */
 export interface RuntimeError {
-  /** 机器可读的唯一错误码，例如 ACTION_NOT_FOUND, INPUT_VALIDATION_FAILED, ACTION_TIMEOUT 等 */
+  /** 机器可读的唯一错误码 */
   code: string;
   /** 人类可读的错误描述信息 */
   message: string;
-  /** 结构化的附加错误详情（如 JSON Schema 校验失败的具体字段列表） */
+  /** 结构化的附加错误详情 */
   details?: unknown;
   /** 导致此错误的底层原始异常或原因 */
   cause?: unknown;
 }
 
 /**
- * 标准执行结果信封（JSON Envelope）。
- * ActionDock 在 CLI、独立二进制、HTTP Runner 和 MCP 等所有场景中均输出该格式。
+ * 标准执行结果信封。
  */
-export type ExecutionResult<T = unknown> =
+export type ExecutionResult<T = JsonValue> =
   | {
       /** 执行是否成功 */
       ok: true;
-      /** 本次执行的全局唯一运行 ID（UUIDv4） */
+      /** 本次执行的全局唯一运行标识 */
       runId: string;
       /** Action 执行返回的业务数据 */
       data: T;
@@ -34,15 +44,58 @@ export type ExecutionResult<T = unknown> =
   | {
       /** 执行是否失败 */
       ok: false;
-      /** 本次执行的全局唯一运行 ID（UUIDv4） */
+      /** 本次执行的全局唯一运行标识 */
       runId: string;
       /** 运行时错误详情 */
       error: RuntimeError;
     };
 
 /**
- * 配置提供器接口（只读查询）。
- * 遵循 5 层优先级链：CLI 参数 > 本地 SQLite > 全局 SQLite > 环境变量 > 项目默认值 > 回退默认值。
+ * Action 逻辑引用。
+ */
+export interface ActionRef {
+  /** 所属包标识 */
+  packageId?: string;
+  /** Action 动作标识 */
+  actionId: string;
+}
+
+/**
+ * 运行时完整解析后的 Action 引用。
+ */
+export interface ResolvedActionRef {
+  /** 包逻辑标识 */
+  packageId: string;
+  /** 包物理实例标识 */
+  packageInstanceId: string;
+  /** Action 动作标识 */
+  actionId: string;
+  /** 运行时代码快照代次标识 */
+  generationId: string;
+}
+
+/**
+ * Action 声明契约。
+ */
+export interface ActionContract {
+  /** Action 唯一标识 */
+  id: string;
+  /** Action 功能描述 */
+  description?: string;
+  /** 输入参数模式规范 */
+  inputSchema?: JsonSchema;
+  /** 输出结果模式规范 */
+  outputSchema?: JsonSchema;
+  /** 静态 Action 依赖列表 */
+  uses?: string[];
+  /** 检索与分类标签 */
+  tags?: string[];
+  /** 协议注解元数据 */
+  annotations?: Record<string, JsonValue>;
+}
+
+/**
+ * 配置提供器接口。
  */
 export interface Config {
   /**
@@ -57,7 +110,7 @@ export interface Config {
    */
   get<T = unknown>(key: string, defaultValue: T): T;
   /**
-   * 检查指定键是否存在配置值（无论来源于哪一层优先级）
+   * 检查指定键是否存在配置值
    * @param key 配置键名
    */
   has(key: string): boolean;
@@ -65,7 +118,6 @@ export interface Config {
 
 /**
  * 共享状态持久化存储接口。
- * 提供跨 Action 调用的数据共享与持久化存储能力，支持命名空间与基于秒的 TTL 自动过期机制。
  */
 export interface StateStore {
   /**
@@ -74,31 +126,29 @@ export interface StateStore {
    */
   get<T = unknown>(key: string): Promise<T | undefined>;
   /**
-   * 设置状态键值对，可选指定过期存活时间（TTL）
+   * 设置状态键值对，可选指定过期存活时间
    * @param key 状态键名
-   * @param value 要存储的数据值（会自动进行深拷贝/序列化）
-   * @param ttl 存活时间（单位：秒）。不传或 <= 0 表示永久有效
+   * @param value 要存储的数据值
+   * @param ttl 存活时间（单位：秒）。不传或小于等于 0 表示永久有效
    */
   set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
   /**
-   * 删除指定键的状态数据。
+   * 删除指定键的状态数据
    * @param key 状态键名
-   * @returns 是否实际删除了数据（true: 存在并删除，false: 不存在）
    */
   delete(key: string): Promise<boolean>;
   /**
-   * 清空当前命名空间（或指定前缀）下的所有状态数据
+   * 清空当前命名空间下的所有状态数据
    * @param prefix 可选的键名前缀过滤条件
-   * @returns 实际清除的条目数量
    */
   clear(prefix?: string): Promise<number>;
   /**
-   * 列出当前命名空间下所有匹配前缀的状态键名（已自动过滤已过期的键）
+   * 列出当前命名空间下所有匹配前缀的状态键名
    * @param prefix 键名前缀过滤条件
    */
   keys(prefix?: string): Promise<string[]>;
   /**
-   * 创建一个具有独立命名空间隔离的子 StateStore 实例
+   * 创建具有独立命名空间隔离的子 StateStore 实例
    * @param namespace 命名空间标识
    */
   scope(namespace: string): StateStore;
@@ -106,7 +156,6 @@ export interface StateStore {
 
 /**
  * 结构化日志记录器接口。
- * 所有日志输出均定向到 stderr，确保不污染 stdout 中的 JSON 信封。
  */
 export interface Logger {
   /** 记录调试级别日志 */
@@ -119,86 +168,196 @@ export interface Logger {
   error(message: string, data?: unknown): void;
 }
 
+/**
+ * 执行进度报告器接口。
+ */
+export interface ProgressReporter {
+  /**
+   * 报告当前任务执行进度
+   * @param current 当前完成量
+   * @param total 任务总量
+   * @param message 当前进度说明
+   */
+  report(current: number, total?: number, message?: string): void;
+}
+
+/**
+ * 进程执行参数。
+ */
+export interface ProcessExecOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  input?: string | Uint8Array;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  encoding?: string;
+  throwOnError?: boolean;
+  maxOutputBytes?: number;
+}
+
+/**
+ * 进程执行结果。
+ */
+export interface ProcessResult {
+  ok: boolean;
+  exitCode: number | null;
+  signal?: string;
+  stdout: string;
+  stderr: string;
+  raw: Uint8Array;
+  timedOut: boolean;
+  cancelled: boolean;
+  durationMs: number;
+  error?: RuntimeError;
+}
+
+/**
+ * 后台守护进程启动选项。
+ */
+export interface DetachedProcessOptions {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  probeIntervalMs?: number;
+  probeTimeoutMs?: number;
+  probe?: (result: ProcessResult) => boolean | Promise<boolean>;
+}
+
+/**
+ * 后台守护进程启动结果。
+ */
+export interface DetachedProcessResult {
+  ok: boolean;
+  pid?: number;
+  ready: boolean;
+  durationMs: number;
+  error?: RuntimeError;
+}
+
+/**
+ * 统一进程操作接口。
+ */
+export interface ProcessAPI {
+  /** 执行外部命令 */
+  exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+  /** 启动脱离父进程的后台进程并探测就绪状态 */
+  spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult>;
+}
+
 /**
  * Action 间相互调用的执行器接口。
- * 支持在 Action 内部安全调用同 Package 或其他 Action，内置调用栈防死循环环路检测。
  */
 export interface ActionInvoker {
   /**
    * 调用指定的 Action 并传入参数，返回其执行结果
-   * @param action 目标 Action 定义对象
+   * @param action 目标 Action 定义对象、引用或标识符
    * @param input 传递给目标 Action 的输入参数
    */
-  invoke<I, O>(
-    action: ActionDefinition<I, O>,
-    input: I
+  invoke<I = unknown, O = unknown>(
+    action: ActionDefinition<I, O> | ActionRef | string,
+    input?: I
   ): Promise<O>;
 }
 
 /**
- * 传递给 Action `run` 处理函数的运行时上下文对象。
+ * 传递给 Action 业务函数的运行时上下文对象。
  */
 export interface ActionContext {
-  /** 配置读取接口，自动按多层优先级解析配置 */
+  /** 配置读取接口 */
   config: Config;
-  /** 状态持久化存储接口，提供跨 Action 调用的数据存取与 TTL */
+  /** 状态持久化存储接口 */
   state: StateStore;
-  /** Action 相互调用接口，支持模块化组合与复用 */
+  /** Action 相互调用接口 */
   actions: ActionInvoker;
-  /** 结构化日志接口，输出定向至 stderr */
+  /** 进程执行接口 */
+  process: ProcessAPI;
+  /** 结构化日志接口 */
   log: Logger;
-  /** 取消信号，用于感知客户端中断、超时或 SIGINT */
+  /** 进度报告接口 */
+  progress: ProgressReporter;
+  /** 取消信号 */
   signal: AbortSignal;
+  /** 当前执行信息 */
+  run: {
+    id: string;
+    rootId: string;
+    parentId?: string;
+  };
 }
 
 /**
  * Action 动作定义契约。
- * 通过 `defineAction({...})` 声明。
  */
-export interface ActionDefinition<I = unknown, O = unknown> {
-  /** Action 唯一标识符（例如: "github.get-pr" 或 "sample.greet"） */
-  id: string;
-  /** Action 功能描述，用于 CLI 帮助文档、Agent 发现以及 MCP Tool 描述 */
-  description?: string;
-  /** 输入参数的 JSON Schema 校验规范 */
-  inputSchema?: JsonSchema;
-  /** 输出结果的 JSON Schema 校验规范 */
-  outputSchema?: JsonSchema;
+export interface ActionDefinition<I = unknown, O = unknown> extends ActionContract {
   /**
    * Action 的核心业务执行函数
    * @param input 符合 inputSchema 契约的输入数据
-   * @param ctx 运行时上下文对象（包含 config, state, actions, log, signal）
+   * @param ctx 运行时上下文对象
    */
   run(input: I, ctx: ActionContext): Promise<O> | O;
 }
 
 /**
- * 运行记录状态枚举。
+ * 运行记录状态。
  */
-export type RunStatus = "running" | "success" | "failed" | "cancelled";
+export type RunStatus =
+  | "running"
+  | "success"
+  | "failed"
+  | "cancelled"
+  | "timed_out"
+  | "interrupted";
 
 /**
  * Action 执行运行历史记录。
  */
 export interface RunRecord {
-  /** 全局唯一运行 ID (UUIDv4) */
+  /** 全局唯一运行标识 */
   id: string;
-  /** 所属 Action Package 的唯一 ID */
+  /** 根调用运行标识 */
+  rootRunId: string;
+  /** 父级调用的运行标识 */
+  parentRunId?: string;
+  /** 所属 Action Package 的逻辑标识 */
   packageId: string;
-  /** 所执行的 Action ID */
+  /** 包物理实例标识 */
+  packageInstanceId: string;
+  /** 所执行的 Action 标识 */
   actionId: string;
-  /** 父级调用的运行 ID（若由其他 Action 嵌套调用触发） */
-  parentRunId?: string;
+  /** 运行时代码快照代次标识 */
+  generationId: string;
+  /** 执行宿主所有者标识 */
+  ownerId: string;
   /** 运行生命周期状态 */
   status: RunStatus;
   /** 输入参数快照 */
-  input: unknown;
-  /** 执行成功时的输出结果 */
-  output?: unknown;
+  input?: JsonValue;
+  /** 执行成功时的输出结果快照 */
+  output?: JsonValue;
   /** 执行失败时的错误信息 */
   error?: RuntimeError;
-  /** 开始执行时间（ISO 8601 格式） */
+  /** 开始执行时间（UTC ISO 8601 格式） */
   startedAt: string;
-  /** 结束执行时间（ISO 8601 格式，进行中时为 undefined） */
+  /** 结束执行时间（UTC ISO 8601 格式） */
   finishedAt?: string;
+  /** 运行耗时（单位：毫秒） */
+  durationMs?: number;
 }
+
+/**
+ * 执行生命周期事件。
+ */
+export type ExecutionEvent = {
+  runId: string;
+  rootRunId: string;
+  sequence: number;
+  timestamp: string;
+} & (
+  | { type: "log"; level: "debug" | "info" | "warn" | "error"; message: string; data?: JsonValue }
+  | { type: "progress"; current?: number; total?: number; message?: string }
+  | { type: "status"; status: RunStatus }
+  | { type: "finish"; result: ExecutionResult }
+);