@actiondock/core 2.6.0 → 2.8.0

package/dist/invocation/types.d.ts

@@ -0,0 +1,172 @@
+import type { ActionDefinition, ActionRef, Logger, ProcessAPI, ProgressReporter } from "@actiondock/sdk";
+import type { ProcessOwner } from "../process/index.js";
+import { createPackageIdentity, type PackageIdentity } from "../runtime/identity.js";
+export { createPackageIdentity };
+export type { PackageIdentity };
+export type { RunOptions } from "../service/types.js";
+/**
+ * 构造默认进程归属所有者（ProcessOwner）的单一事实源工厂。
+ *
+ * 兜底语义：租户与主体标识缺失时回退 "default"，包实例与代次标识缺失时回退
+ * 调用方提供的兜底值；全部五处默认 Owner 构造点（invocation、runner、runtime
+ * 上下文与进程执行器）必须统一经由本工厂，禁止散落字面量拷贝。
+ */
+export declare function createDefaultProcessOwner(options?: {
+    /** 租户标识，缺省回退 "default" */
+    tenantId?: string;
+    /** 主体标识，缺省回退 "default" */
+    principalId?: string;
+    /** 包物理实例标识兜底值，缺省回退 "default" */
+    packageInstanceId?: string;
+    /** 快照代次标识兜底值，缺省回退 "default" */
+    generationId?: string;
+}): ProcessOwner;
+/**
+ * 内部调用方身份凭证（InvocationCaller）。
+ */
+export interface InvocationCaller {
+    /** 调用方所在包标识 */
+    readonly packageId: string;
+    /** 调用方 Action 标识 */
+    readonly actionId: string;
+    /** 调用方运行 ID */
+    readonly runId?: string;
+    /** 调用方声明的 uses 列表 */
+    readonly declaredUses?: string[];
+}
+/**
+ * 内部调用上下文（InvocationContext）。
+ * 贯穿 Host -> Resolution -> PackageRuntime -> ExecutionService 的内部调用链路上下文。
+ */
+export interface InvocationContext {
+    /** 本次执行的全局唯一运行标识 */
+    readonly runId: string;
+    /** 根运行标识（调用链起点） */
+    readonly rootRunId: string;
+    /** 直接父运行标识（嵌套子调用时关联） */
+    readonly parentRunId?: string;
+    /** 调用方上下文（若为嵌套/跨包调用） */
+    readonly caller?: InvocationCaller;
+    /** 调用栈数组快照（用于环路检测与调用深度限制） */
+    readonly callStack: readonly string[];
+    /** 目标包物理与快照身份标识 */
+    readonly package: PackageIdentity;
+    /** 取消信号 */
+    readonly signal: AbortSignal;
+    /** 超时毫秒数 */
+    readonly timeoutMs?: number;
+    /** 配置覆盖项 */
+    readonly config?: Record<string, unknown>;
+    /** 幂等请求标识 */
+    readonly requestId?: string;
+    /** 租户标识 */
+    readonly tenantId?: string;
+    /** 主体标识 */
+    readonly principalId?: string;
+    /** 执行宿主会话标识 */
+    readonly hostSessionId?: string;
+    /** 最大调用深度覆盖 */
+    readonly maxCallDepth?: number;
+    /** 日志记录器 */
+    readonly logger?: Logger;
+    /** 进度报告器 */
+    readonly progress?: ProgressReporter;
+    /** 进程执行器 */
+    readonly process?: ProcessAPI;
+    /** 进程属主身份 */
+    readonly owner?: ProcessOwner;
+}
+/**
+ * 内部调用上下文选项契约。
+ * 强制要求提供确定的 PackageIdentity，禁止隐式兜底 mock 默认包。
+ */
+export interface CreateInvocationContextOptions extends Omit<Partial<InvocationContext>, "package"> {
+    /** 目标包物理与快照身份标识（必填单一事实源） */
+    package: PackageIdentity;
+}
+/**
+ * 构造合法的内部调用上下文（InvocationContext）。
+ * 供测试或内部直接调用执行服务时便捷装配上下文凭据。
+ */
+export declare function createInvocationContext(options: CreateInvocationContextOptions): InvocationContext;
+/**
+ * 构造受信任的根调用上下文选项。
+ */
+export interface CreateRootInvocationContextOptions {
+    /** 目标包物理与快照身份标识（必填单一事实源） */
+    targetPackage: PackageIdentity;
+    /** 可选的初始调用栈（根调用通常为 [rootKey]） */
+    callStack?: readonly string[];
+    /** 外部传入的 AbortSignal 取消信号 */
+    signal?: AbortSignal;
+    /** 最大超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 执行级临时配置覆盖字典 */
+    config?: Record<string, unknown>;
+    /** 幂等请求标识 */
+    requestId?: string;
+    /** 执行宿主会话标识 */
+    hostSessionId?: string;
+    /** 最大调用嵌套深度限制 */
+    maxCallDepth?: number;
+    /** 外部进程执行器注入 */
+    process?: ProcessAPI;
+    /** 租户标识 */
+    tenantId?: string;
+    /** 主体标识 */
+    principalId?: string;
+    /** 日志记录器 */
+    logger?: Logger;
+    /** 进度报告器 */
+    progress?: ProgressReporter;
+    /** 显式执行归属所有者契约 */
+    owner?: ProcessOwner;
+}
+/**
+ * 构造合法的受信任根调用上下文（Root InvocationContext）。
+ * 在 Host 服务边界装配，严格保证无父级调用血缘（parentRunId 为 undefined），
+ * 根运行 ID 等同于自身运行 ID，且仅透传受信任参数。
+ *
+ * 实现委托 createInvocationContext 单一事实源：不传入 runId/rootRunId/parentRunId/caller，
+ * 由公共构造逻辑兜底生成 runId 并令 rootRunId 收敛为自身 runId；随后显式覆写
+ * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
+ */
+export declare function createRootInvocationContext(options: CreateRootInvocationContextOptions): InvocationContext;
+/**
+ * Action 执行上下文（ActionExecutionContext）。
+ * ActionRunner 启动单次 Action 执行时内部装配的完整上下文状态。
+ */
+export interface ActionExecutionContext {
+    /** 运行 ID */
+    readonly runId: string;
+    /** 根运行 ID */
+    readonly rootRunId: string;
+    /** 父运行 ID */
+    readonly parentRunId?: string;
+    /** 当前执行所属包标识 */
+    readonly packageIdentity: PackageIdentity;
+    /** 目标 Action 标识 */
+    readonly targetActionId: string;
+    /** 输入数据 */
+    readonly input: unknown;
+    /** 目标 Action 定义（若已解析就绪） */
+    readonly action?: ActionDefinition;
+    /** 调用栈数组快照 */
+    readonly callStack: readonly string[];
+    /** 取消中断控制器 */
+    readonly controller: AbortController;
+    /** 执行开始时间戳 */
+    readonly startedAt: string;
+    /** 生效的进程执行器 */
+    readonly effectiveProcess?: ProcessAPI;
+    /** 进程属主信息 */
+    readonly owner: ProcessOwner;
+    /** 日志记录器 */
+    readonly logger?: Logger;
+    /** 进度报告器 */
+    readonly progress?: ProgressReporter;
+    /** 配置覆盖项 */
+    readonly configOverrides?: Record<string, unknown>;
+    /** 嵌套子调用委托函数 */
+    readonly actionInvoker?: (childAction: ActionRef | string, childInput: unknown, callerRunId?: string) => Promise<unknown>;
+}

package/dist/invocation/types.js

@@ -0,0 +1,97 @@
+import { createPackageIdentity } from "../runtime/identity.js";
+export { createPackageIdentity };
+/**
+ * 构造默认进程归属所有者（ProcessOwner）的单一事实源工厂。
+ *
+ * 兜底语义：租户与主体标识缺失时回退 "default"，包实例与代次标识缺失时回退
+ * 调用方提供的兜底值；全部五处默认 Owner 构造点（invocation、runner、runtime
+ * 上下文与进程执行器）必须统一经由本工厂，禁止散落字面量拷贝。
+ */
+export function createDefaultProcessOwner(options) {
+    return {
+        tenantId: options?.tenantId || "default",
+        principalId: options?.principalId || "default",
+        packageInstanceId: options?.packageInstanceId || "default",
+        generationId: options?.generationId || "default",
+    };
+}
+/**
+ * 构造合法的内部调用上下文（InvocationContext）。
+ * 供测试或内部直接调用执行服务时便捷装配上下文凭据。
+ */
+export function createInvocationContext(options) {
+    const runId = options.runId ?? crypto.randomUUID();
+    const rootRunId = options.rootRunId ?? runId;
+    const pkg = options.package;
+    return {
+        runId,
+        rootRunId,
+        parentRunId: options.parentRunId,
+        caller: options.caller,
+        callStack: options.callStack ? [...options.callStack] : [],
+        package: pkg,
+        signal: options.signal ?? new AbortController().signal,
+        timeoutMs: options.timeoutMs,
+        config: options.config,
+        requestId: options.requestId,
+        tenantId: options.tenantId,
+        principalId: options.principalId,
+        hostSessionId: options.hostSessionId,
+        maxCallDepth: options.maxCallDepth,
+        logger: options.logger,
+        progress: options.progress,
+        process: options.process,
+        owner: options.owner ??
+            createDefaultProcessOwner({
+                tenantId: options.tenantId,
+                principalId: options.principalId,
+                packageInstanceId: pkg.instanceId,
+                generationId: pkg.generation,
+            }),
+    };
+}
+/**
+ * 构造合法的受信任根调用上下文（Root InvocationContext）。
+ * 在 Host 服务边界装配，严格保证无父级调用血缘（parentRunId 为 undefined），
+ * 根运行 ID 等同于自身运行 ID，且仅透传受信任参数。
+ *
+ * 实现委托 createInvocationContext 单一事实源：不传入 runId/rootRunId/parentRunId/caller，
+ * 由公共构造逻辑兜底生成 runId 并令 rootRunId 收敛为自身 runId；随后显式覆写
+ * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
+ */
+export function createRootInvocationContext(options) {
+    const base = createInvocationContext({
+        package: options.targetPackage,
+        callStack: options.callStack,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+        config: options.config,
+        requestId: options.requestId,
+        hostSessionId: options.hostSessionId,
+        maxCallDepth: options.maxCallDepth,
+        logger: options.logger,
+        progress: options.progress,
+        process: options.process,
+        owner: options.owner,
+        tenantId: options.tenantId,
+        principalId: options.principalId,
+    });
+    return {
+        runId: base.runId,
+        rootRunId: base.rootRunId,
+        parentRunId: undefined,
+        caller: undefined,
+        callStack: base.callStack,
+        package: base.package,
+        signal: base.signal,
+        timeoutMs: base.timeoutMs,
+        config: base.config,
+        requestId: base.requestId,
+        hostSessionId: base.hostSessionId,
+        maxCallDepth: base.maxCallDepth,
+        logger: base.logger,
+        progress: base.progress,
+        process: base.process,
+        owner: base.owner,
+    };
+}

package/dist/ipc/diagnostic.d.ts

@@ -35,14 +35,6 @@ export declare class DiagnosticForwarder {
     private truncated;
     private attachedStreams;
     constructor(options?: DiagnosticForwarderOptions);
-    /**
-     * 是否已达到上限并处于截断状态。
-     */
-    get isTruncated(): boolean;
-    /**
-     * 已成功转发的累计字节数。
-     */
-    get bytesEmitted(): number;
     /**
      * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
      *
@@ -58,8 +50,4 @@ export declare class DiagnosticForwarder {
      * 解绑所有已连接的流。
      */
     detachAll(): void;
-    /**
-     * 重置计数器与截断标志。
-     */
-    reset(): void;
 }

package/dist/ipc/diagnostic.js

@@ -25,18 +25,6 @@ export class DiagnosticForwarder {
         this.prefix = options.prefix ?? "";
         this.onTruncated = options.onTruncated;
     }
-    /**
-     * 是否已达到上限并处于截断状态。
-     */
-    get isTruncated() {
-        return this.truncated;
-    }
-    /**
-     * 已成功转发的累计字节数。
-     */
-    get bytesEmitted() {
-        return this.totalBytesEmitted;
-    }
     /**
      * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
      *
@@ -117,13 +105,4 @@ export class DiagnosticForwarder {
         }
         this.attachedStreams.clear();
     }
-    /**
-     * 重置计数器与截断标志。
-     */
-    reset() {
-        this.totalBytesEmitted = 0;
-        this.bytesInCurrentWindow = 0;
-        this.windowStartMs = Date.now();
-        this.truncated = false;
-    }
 }

package/dist/ipc/host.d.ts

@@ -1,12 +1,12 @@
-import type { ActionDockTarget } from "../target/types.js";
+import type { ActionDockService } from "../service/types.js";
 /**
- * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockService 门面能力。
  *
  * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
  * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
  * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
  * 调用完成后清理映射，确保取消信号全链路透传。
  *
- * @param target 已构造好的 ActionDockTarget 实例
+ * @param service 已构造好的 ActionDockService 实例
  */
-export declare function serveParentIpc(target: ActionDockTarget): Promise<void>;
+export declare function serveParentIpc(service: ActionDockService): Promise<void>;

package/dist/ipc/host.js

@@ -1,47 +1,49 @@
-import { TARGET_CAPABILITY_UNAVAILABLE } from "../target/types.js";
-import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./target.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, SERVICE_ERROR } from "../errors.js";
+import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./service.js";
 /**
- * IPC 通道允许反射调用的目标方法白名单。
+ * IPC 通道方法分发表：方法名到目标调用的唯一事实源。
  *
- * 严格对齐 ActionDockTarget 公共接口方法名集合：白名单之外的方法一律拒绝，
- * 防止 IPC 消息通道触达任意内部属性或危险方法（如 close 之外的私有能力）。
+ * 严格对齐 ActionDockService 公共方法集合：表之外的方法一律拒绝，
+ * 防止 IPC 消息通道触达任意内部属性或危险方法。
+ * 白名单即分发表的键集合，杜绝两份清单重复维护漂移。
  */
-const IPC_ALLOWED_METHODS = new Set([
-    "info",
-    "listPackages",
-    "listActions",
-    "describeAction",
-    "listPlaybooks",
-    "describePlaybook",
-    "runAction",
-    "startAction",
-    "listRuns",
-    "getRun",
-    "cancelRun",
-    "clearRuns",
-    "events",
-    "getConfig",
-    "setConfig",
-    "deleteConfig",
-    "listConfig",
-    "getState",
-    "setState",
-    "deleteState",
-    "listStateKeys",
-    "clearState",
-    "listStateEntries",
-]);
+const IPC_METHOD_HANDLERS = {
+    info: async (service) => service.info(),
+    listPackages: async (service) => service.discovery.listPackages(),
+    listActions: async (service, a) => service.discovery.listActions(a[0]),
+    describeAction: async (service, a) => service.discovery.describeAction(a[0]),
+    listPlaybooks: async (service, a) => service.discovery.listPlaybooks(a[0]),
+    describePlaybook: async (service, a) => service.discovery.describePlaybook(a[0]),
+    runAction: async (service, a) => service.execution.run(a[0], a[1], a[2]),
+    startAction: async (service, a) => service.execution.start(a[0], a[1], a[2]),
+    listRuns: async (service, a) => service.runs.list(a[0]),
+    getRun: async (service, a) => service.runs.get(a[0]),
+    cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
+    clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
+    getConfig: async (service, a) => service.management?.config.get(a[0], a[1]),
+    setConfig: async (service, a) => service.management?.config.set(a[0], a[1], a[2]),
+    deleteConfig: async (service, a) => service.management?.config.delete(a[0], a[1]),
+    listConfig: async (service, a) => service.management?.config.list(a[0]),
+    getState: async (service, a) => service.management?.state.get(a[0], a[1], a[2], a[3]),
+    setState: async (service, a) => service.management?.state.set(a[0], a[1], a[2], a[3], a[4]),
+    deleteState: async (service, a) => service.management?.state.delete(a[0], a[1], a[2], a[3]),
+    listStateKeys: async (service, a) => service.management?.state.list(a[0], a[1], a[2]),
+    clearState: async (service, a) => service.management?.state.clear(a[0], a[1], a[2]),
+    listStateEntries: async (service, a) => service.management?.state.listEntries
+        ? await service.management.state.listEntries(a[0], a[1])
+        : [],
+};
 /**
- * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockService 门面能力。
  *
  * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
  * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
  * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
  * 调用完成后清理映射，确保取消信号全链路透传。
  *
- * @param target 已构造好的 ActionDockTarget 实例
+ * @param service 已构造好的 ActionDockService 实例
  */
-export async function serveParentIpc(target) {
+export async function serveParentIpc(service) {
     if (!process.send) {
         // 若当前未以 IPC 模式运行，直接退出
         return;
@@ -52,7 +54,7 @@ export async function serveParentIpc(target) {
             return;
         isClosing = true;
         try {
-            await target.close();
+            await service.close();
         }
         catch {
             // 忽略关闭异常
@@ -97,19 +99,14 @@ export async function serveParentIpc(target) {
             const callMsg = msg;
             const { id, method, args } = callMsg;
             try {
-                // 白名单校验：仅允许 ActionDockTarget 公共接口方法，阻止任意方法反射调用
-                if (typeof method !== "string" || !IPC_ALLOWED_METHODS.has(method)) {
-                    const err = new Error(`Target method '${method}' is not allowed over IPC (not in ActionDockTarget public interface)`);
-                    err.code = TARGET_CAPABILITY_UNAVAILABLE;
-                    throw err;
-                }
-                const fn = target[method];
-                if (typeof fn !== "function") {
-                    throw new Error(`Target method '${method}' not found`);
+                // 白名单校验：仅允许分发表内方法，阻止任意方法反射调用
+                const handler = typeof method === "string" ? IPC_METHOD_HANDLERS[method] : undefined;
+                if (!handler) {
+                    throw new ActionDockError(CAPABILITY_UNAVAILABLE, `Target method '${method}' is not allowed over IPC`);
                 }
                 // 反序列化执行选项：识别取消信号占位标记并重建控制器接入取消链路
-                const revivedArgs = (args || []).map((arg) => reviveIpcSignal(id, arg));
-                const result = await fn.apply(target, revivedArgs);
+                const a = (args || []).map((arg) => reviveIpcSignal(id, arg));
+                const result = await handler(service, a);
                 const response = {
                     id,
                     type: "response",
@@ -126,7 +123,7 @@ export async function serveParentIpc(target) {
                     type: "response",
                     ok: false,
                     error: {
-                        code: err?.code || "TARGET_ERROR",
+                        code: err?.code || SERVICE_ERROR,
                         message: err?.message || String(err),
                         stack: err?.stack,
                         details: err?.details,
@@ -162,7 +159,7 @@ export async function serveParentIpc(target) {
             }
         }
         else {
-            // 向后兼容：旧版本对端可能推送未知消息类型，防御性忽略并记录诊断，不中断通道
+            // 防御性忽略未知消息类型并记录诊断，不中断通道
             process.stderr.write(`[IPC Host] Ignoring unknown IPC message type: ${JSON.stringify(msg.type)}\n`);
         }
     });

package/dist/ipc/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types.js";
 export * from "./diagnostic.js";
 export * from "./host.js";
-export * from "./target.js";
+export * from "./service.js";

package/dist/ipc/index.js

@@ -1,4 +1,4 @@
 export * from "./types.js";
 export * from "./diagnostic.js";
 export * from "./host.js";
-export * from "./target.js";
+export * from "./service.js";

package/dist/ipc/service.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from "node:child_process";
+import type { PackageInfo } from "../package/types.js";
+import type { ActionDockService, ConfigPort, DiscoveryPort, ExecutionPort, RunsPort, StatePort } from "../service/types.js";
+import type { IpcServiceOptions } from "./types.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export declare const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ */
+export declare function hasIpcSignalMarker(value: unknown): value is Record<string, unknown>;
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
+ * 遵循标准 Service Ports 体系，隔离子进程生命周期并暴露结构化服务端口。
+ */
+export declare class IpcActionDockService implements ActionDockService {
+    private child;
+    private forwarder;
+    private pendingCalls;
+    private isClosed;
+    private exitError?;
+    private readyPromise;
+    readonly discovery: DiscoveryPort;
+    readonly execution: ExecutionPort;
+    readonly runs: RunsPort;
+    readonly management?: {
+        config: ConfigPort;
+        state: StatePort;
+    };
+    constructor(options: IpcServiceOptions);
+    private callRemote;
+    private sendAbort;
+    info(): Promise<PackageInfo[]>;
+    get process(): ChildProcess;
+    waitReady(): Promise<void>;
+    close(): Promise<void>;
+}