@actiondock/core 2.0.11 → 2.2.0

package/dist/host/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./host.js";

package/dist/host/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./host.js";

package/dist/host/types.d.ts

@@ -0,0 +1,81 @@
+import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord } from "@actiondock/sdk";
+import type { ActionDockApp, ActionDockAppOptions, ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
+import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
+import type { Clock } from "../runtime/clock.js";
+import type { EventSink } from "../runtime/events.js";
+import type { RuntimePlatform } from "../platform/types.js";
+/**
+ * ActionDock 宿主容器初始化配置选项。
+ */
+export interface ActionDockHostOptions {
+    /** 显式预注册的包列表（现成 ActionDockApp 实例或 ActionDockAppOptions 配置）。外部传入的 App 属于借用（borrowed），生命周期完全由调用方负责管理，Host 关闭或初始化失败时仅解绑引用并清理自身内部实例，严禁关闭外部借用的 App 实例。 */
+    packages?: Array<ActionDockApp | ActionDockAppOptions>;
+    /** 当前工程根目录绝对物理路径 */
+    projectRoot?: string;
+    /** 是否自动加载当前工程（默认为 true） */
+    autoLoadCurrentProject?: boolean;
+    /** 是否扫描已软链接的外部包（通过 listLinkedPackages，默认为 false） */
+    scanLinkedPackages?: boolean;
+    /** 显式注入的运行时平台适配 */
+    platform?: RuntimePlatform;
+    /** 全局最大并发活跃运行数 */
+    maxActiveRuns?: number;
+    /** 全局调用嵌套深度限制（默认 16） */
+    maxCallDepth?: number;
+    /** 全局子任务数限制（默认 64） */
+    maxSubRuns?: number;
+    /** 日志记录器 */
+    logger?: Logger;
+    /** 时钟源 */
+    clock?: Clock;
+    /** 进程执行器 */
+    process?: ProcessAPI;
+    /** 数据持久化存储目录 */
+    dataDir?: string;
+    /** 自定义 ActionDock 家目录 */
+    customHome?: string;
+    /** 是否采用纯内存运行模式 */
+    inMemory?: boolean;
+    /** 事件接收器 */
+    eventSink?: EventSink;
+}
+/**
+ * ActionDock 多包宿主容器领域契约。
+ * 作为多包环境下的全局协调中枢，负责多包生命周期、完全限定引用路由、依赖校验与配额管理。
+ */
+export interface ActionDockHost {
+    /** 获取所有已注册包的元数据信息列表 */
+    info(): Promise<PackageInfo[]>;
+    /** 静态列出所有已注册包中可用的 Action 摘要 */
+    listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;
+    /** 静态查询并返回指定 Action 的规范结构与模式定义 */
+    describeAction(ref: ActionRef | string): Promise<ActionSpec>;
+    /** 静态列出所有已注册包中可用的 Playbook 规程摘要 */
+    listPlaybooks(): Promise<PlaybookSummary[]>;
+    /** 静态查询并返回指定 Playbook 的规范内容与操作指南 */
+    describePlaybook(id: string): Promise<PlaybookSpec>;
+    /** 同步执行指定 Action 并等待终态结果 */
+    runAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
+    /** 异步启动指定 Action 并立即返回任务执行票据 */
+    startAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    /** 查询指定运行标识的记录详情 */
+    getRun(runId: string): Promise<RunRecord | undefined>;
+    /** 取消指定在运行的任务 */
+    cancelRun(runId: string, reason?: string): Promise<CancelResult>;
+    /** 订阅指定运行的事件流 */
+    events(runId: string, options?: {
+        after?: number | string;
+        signal?: AbortSignal;
+        maxQueueSize?: number;
+    }): AsyncIterable<ExecutionEvent>;
+    /** 根据包唯一标识获取指定 App 实例 */
+    getApp(packageId: string): ActionDockApp | undefined;
+    /** 获取所有当前已注册的 App 实例列表 */
+    listApps(): ActionDockApp[];
+    /** 注册新的 App 实例至当前宿主容器 */
+    registerApp(app: ActionDockApp): void;
+    /** 优雅关闭宿主容器。仅对内部创建的 App 实例执行 close 并安全释放底层资源；外部传入借用的 App 实例生命周期完全由调用方负责管理，Host 关闭时仅解绑引用并清理自身内部实例。 */
+    close(options?: {
+        graceMs?: number;
+    }): Promise<void>;
+}

package/dist/host/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./catalog/index.js";
+export * from "./doctor/index.js";
+export * from "./errors.js";
+export * from "./execution/index.js";
+export * from "./export/index.js";
+export * from "./filter/index.js";
+export * from "./platform/index.js";
+export * from "./profile/index.js";
+export * from "./project/index.js";
+export * from "./registry/index.js";
+export * from "./runtime/index.js";
+export * from "./schema/validator.js";
+export * from "./server/index.js";
+export * from "./storage/index.js";
+export * from "./utils/index.js";
+export * from "./version.js";
+export * from "./app/index.js";
+export * from "./host/index.js";
+export * from "./target/index.js";
+export * from "./ipc/index.js";
+export type { ModuleLoader } from "./runtime/index.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+export * from "./catalog/index.js";
+export * from "./doctor/index.js";
+export * from "./errors.js";
+export * from "./execution/index.js";
+export * from "./export/index.js";
+export * from "./filter/index.js";
+export * from "./platform/index.js";
+export * from "./profile/index.js";
+export * from "./project/index.js";
+export * from "./registry/index.js";
+export * from "./runtime/index.js";
+export * from "./schema/validator.js";
+export * from "./server/index.js";
+export * from "./storage/index.js";
+export * from "./utils/index.js";
+export * from "./version.js";
+export * from "./app/index.js";
+export * from "./host/index.js";
+export * from "./target/index.js";
+export * from "./ipc/index.js";

package/dist/ipc/diagnostic.d.ts

@@ -0,0 +1,65 @@
+import type { Readable, Writable } from "node:stream";
+/**
+ * 诊断日志限流排空转发器配置选项。
+ */
+export interface DiagnosticForwarderOptions {
+    /** 允许转发的累计最大字节数（默认 512 KB） */
+    maxBytes?: number;
+    /** 每秒允许转发的最大字节速率（默认 64 KB/秒） */
+    maxRateBytesPerSec?: number;
+    /** 目标输出流（默认 process.stderr） */
+    target?: Writable;
+    /** 诊断流标识前缀 */
+    prefix?: string;
+    /** 触发超限截断时的回调通知 */
+    onTruncated?: (reason: "size_limit" | "rate_limit") => void;
+}
+/**
+ * 诊断流受控转发与限流排空器（DiagnosticForwarder）。
+ *
+ * 职责：
+ * 1. 独占捕获子进程的标准输出与标准错误流，杜绝第三方代码污染父进程标准协议通道。
+ * 2. 实时监测字节总量与秒级传输速率上限。
+ * 3. 达到阈值后立即停止对外转发、向诊断通道记录截断事件。
+ * 4. 持续以非阻塞方式静默排空后续数据流，避免子进程因管道背压堆积死锁。
+ */
+export declare class DiagnosticForwarder {
+    private readonly maxBytes;
+    private readonly maxRateBytesPerSec;
+    private readonly target;
+    private readonly prefix;
+    private readonly onTruncated?;
+    private totalBytesEmitted;
+    private windowStartMs;
+    private bytesInCurrentWindow;
+    private truncated;
+    private attachedStreams;
+    constructor(options?: DiagnosticForwarderOptions);
+    /**
+     * 是否已达到上限并处于截断状态。
+     */
+    get isTruncated(): boolean;
+    /**
+     * 已成功转发的累计字节数。
+     */
+    get bytesEmitted(): number;
+    /**
+     * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
+     *
+     * @param stream 待转发的可读流
+     * @param label 流标识（如 "stdout" 或 "stderr"）
+     */
+    attach(stream: Readable, label?: string): void;
+    /**
+     * 解绑指定的流监听。
+     */
+    detach(stream: Readable): void;
+    /**
+     * 解绑所有已连接的流。
+     */
+    detachAll(): void;
+    /**
+     * 重置计数器与截断标志。
+     */
+    reset(): void;
+}

package/dist/ipc/diagnostic.js

@@ -0,0 +1,129 @@
+/**
+ * 诊断流受控转发与限流排空器（DiagnosticForwarder）。
+ *
+ * 职责：
+ * 1. 独占捕获子进程的标准输出与标准错误流，杜绝第三方代码污染父进程标准协议通道。
+ * 2. 实时监测字节总量与秒级传输速率上限。
+ * 3. 达到阈值后立即停止对外转发、向诊断通道记录截断事件。
+ * 4. 持续以非阻塞方式静默排空后续数据流，避免子进程因管道背压堆积死锁。
+ */
+export class DiagnosticForwarder {
+    maxBytes;
+    maxRateBytesPerSec;
+    target;
+    prefix;
+    onTruncated;
+    totalBytesEmitted = 0;
+    windowStartMs = Date.now();
+    bytesInCurrentWindow = 0;
+    truncated = false;
+    attachedStreams = new Map();
+    constructor(options = {}) {
+        this.maxBytes = options.maxBytes ?? 512 * 1024;
+        this.maxRateBytesPerSec = options.maxRateBytesPerSec ?? 64 * 1024;
+        this.target = options.target ?? process.stderr;
+        this.prefix = options.prefix ?? "";
+        this.onTruncated = options.onTruncated;
+    }
+    /**
+     * 是否已达到上限并处于截断状态。
+     */
+    get isTruncated() {
+        return this.truncated;
+    }
+    /**
+     * 已成功转发的累计字节数。
+     */
+    get bytesEmitted() {
+        return this.totalBytesEmitted;
+    }
+    /**
+     * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
+     *
+     * @param stream 待转发的可读流
+     * @param label 流标识（如 "stdout" 或 "stderr"）
+     */
+    attach(stream, label) {
+        if (this.attachedStreams.has(stream))
+            return;
+        const handler = (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk;
+            const len = buf.length;
+            // 刷新秒级速率统计窗口
+            const now = Date.now();
+            if (now - this.windowStartMs >= 1000) {
+                this.windowStartMs = now;
+                this.bytesInCurrentWindow = 0;
+            }
+            if (this.truncated) {
+                // 已截断：仅排空丢弃数据，不转发，保持流处于读取排空状态
+                return;
+            }
+            // 检查容量与速率上限
+            let exceedReason = null;
+            if (this.totalBytesEmitted + len > this.maxBytes) {
+                exceedReason = "size_limit";
+            }
+            else if (this.bytesInCurrentWindow + len > this.maxRateBytesPerSec) {
+                exceedReason = "rate_limit";
+            }
+            if (exceedReason) {
+                this.truncated = true;
+                const tag = label ? `[${label}] ` : "";
+                const notice = `\n[Supervisor] ${tag}Diagnostic output exceeded ${exceedReason === "size_limit" ? `size limit (${this.maxBytes} bytes)` : `rate limit (${this.maxRateBytesPerSec} B/s)`}. Forwarding suspended; draining stream.\n`;
+                try {
+                    this.target.write(notice);
+                }
+                catch {
+                    // 忽略写入失败
+                }
+                this.onTruncated?.(exceedReason);
+                return;
+            }
+            // 正常转发
+            this.totalBytesEmitted += len;
+            this.bytesInCurrentWindow += len;
+            try {
+                if (this.prefix) {
+                    this.target.write(`${this.prefix}${buf.toString("utf-8")}`);
+                }
+                else {
+                    this.target.write(buf);
+                }
+            }
+            catch {
+                // 忽略目标写入异常
+            }
+        };
+        stream.on("data", handler);
+        this.attachedStreams.set(stream, handler);
+    }
+    /**
+     * 解绑指定的流监听。
+     */
+    detach(stream) {
+        const handler = this.attachedStreams.get(stream);
+        if (handler) {
+            stream.removeListener("data", handler);
+            this.attachedStreams.delete(stream);
+        }
+    }
+    /**
+     * 解绑所有已连接的流。
+     */
+    detachAll() {
+        for (const [stream, handler] of this.attachedStreams.entries()) {
+            stream.removeListener("data", handler);
+        }
+        this.attachedStreams.clear();
+    }
+    /**
+     * 重置计数器与截断标志。
+     */
+    reset() {
+        this.totalBytesEmitted = 0;
+        this.bytesInCurrentWindow = 0;
+        this.windowStartMs = Date.now();
+        this.truncated = false;
+    }
+}

package/dist/ipc/host.d.ts

@@ -0,0 +1,7 @@
+import type { ActionDockTarget } from "../target/types.js";
+/**
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ *
+ * @param target 已构造好的 ActionDockTarget 实例
+ */
+export declare function serveParentIpc(target: ActionDockTarget): Promise<void>;

package/dist/ipc/host.js

@@ -0,0 +1,93 @@
+/**
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ *
+ * @param target 已构造好的 ActionDockTarget 实例
+ */
+export async function serveParentIpc(target) {
+    if (!process.send) {
+        // 若当前未以 IPC 模式运行，直接退出
+        return;
+    }
+    let isClosing = false;
+    const safeClose = async () => {
+        if (isClosing)
+            return;
+        isClosing = true;
+        try {
+            await target.close();
+        }
+        catch {
+            // 忽略关闭异常
+        }
+    };
+    // 监听父进程断连或退出信号
+    process.once("disconnect", async () => {
+        await safeClose();
+        process.exit(0);
+    });
+    process.once("SIGINT", async () => {
+        await safeClose();
+        process.exit(130);
+    });
+    process.once("SIGTERM", async () => {
+        await safeClose();
+        process.exit(143);
+    });
+    // 处理父进程 IPC 调用请求
+    process.on("message", async (msg) => {
+        if (!msg || typeof msg !== "object")
+            return;
+        if (msg.type === "call") {
+            const callMsg = msg;
+            const { id, method, args } = callMsg;
+            try {
+                const fn = target[method];
+                if (typeof fn !== "function") {
+                    throw new Error(`Target method '${method}' not found`);
+                }
+                const result = await fn.apply(target, args || []);
+                const response = {
+                    id,
+                    type: "response",
+                    ok: true,
+                    data: result,
+                };
+                if (process.send) {
+                    process.send(response);
+                }
+            }
+            catch (err) {
+                const response = {
+                    id,
+                    type: "response",
+                    ok: false,
+                    error: {
+                        code: err?.code || "TARGET_ERROR",
+                        message: err?.message || String(err),
+                        stack: err?.stack,
+                        details: err?.details,
+                    },
+                };
+                if (process.send) {
+                    process.send(response);
+                }
+            }
+        }
+        else if (msg.type === "close") {
+            await safeClose();
+            if (process.send) {
+                process.send({ id: msg.id, type: "response", ok: true });
+            }
+            process.exit(0);
+        }
+        else if (msg.type === "ping") {
+            if (process.send) {
+                process.send({ type: "pong" });
+            }
+        }
+    });
+    // 通知监督父进程：Host 已就绪
+    if (process.send) {
+        process.send({ type: "ready" });
+    }
+}

package/dist/ipc/index.d.ts

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

package/dist/ipc/index.js

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

package/dist/ipc/target.d.ts

@@ -0,0 +1,56 @@
+import { type ChildProcess } from "node:child_process";
+import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
+import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
+import type { ActionDockTarget, ConfigValueView, IpcTargetOptions, StateScopeOptions, TargetInfo } from "../target/types.js";
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
+ *
+ * 职责：
+ * 1. 监督并隔离子进程的生命周期与标准输出，保证父进程标准输入输出通道 100% 纯净。
+ * 2. 将子进程标准输出/错误通过 DiagnosticForwarder 进行受控排空与诊断流限流转发。
+ * 3. 当子进程异常终止时，立即将当前活跃调用转换为结构化 HOST_PROCESS_EXITED 错误，防止调用方死锁。
+ */
+export declare class IpcActionDockTarget implements ActionDockTarget {
+    private child;
+    private forwarder;
+    private pendingCalls;
+    private isClosed;
+    private exitError?;
+    private readyPromise;
+    constructor(options: IpcTargetOptions);
+    /**
+     * 等待宿主子进程初始化就绪。
+     */
+    waitReady(timeoutMs?: number): Promise<void>;
+    /**
+     * 获取底层子进程实例。
+     */
+    get process(): ChildProcess;
+    private callRemote;
+    info(): Promise<TargetInfo>;
+    listPackages(): Promise<PackageInfo[]>;
+    listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;
+    describeAction(ref: ActionRef | string): Promise<ActionSpec>;
+    listPlaybooks(options?: {
+        intent?: string;
+        package?: string;
+    }): Promise<PlaybookSummary[]>;
+    describePlaybook(id: string): Promise<PlaybookSpec>;
+    runAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
+    startAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    getRun(runId: string): Promise<RunRecord | undefined>;
+    cancelRun(runId: string): Promise<CancelResult>;
+    listRuns(options?: any): Promise<RunRecord[]>;
+    events(_runId: string, _options?: any): AsyncIterable<ExecutionEvent>;
+    listConfig(packageId: string): Promise<ConfigValueView[]>;
+    getConfig(packageId: string, key: string): Promise<ConfigValueView>;
+    setConfig(packageId: string, key: string, value: JsonValue): Promise<void>;
+    deleteConfig(packageId: string, key: string): Promise<boolean>;
+    getState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
+    setState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
+    deleteState(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
+    listStateKeys(packageId: string, actionId?: string, options?: StateScopeOptions): Promise<string[]>;
+    clearState(packageId: string, actionId: string, options?: StateScopeOptions): Promise<number>;
+    close(): Promise<void>;
+}