@actiondock/core 2.0.12 → 2.2.0

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>;
+}

package/dist/ipc/target.js

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { fork } from "node:child_process";
+import { DiagnosticForwarder } from "./diagnostic.js";
+import { EXECUTION_ABORTED, HOST_PROCESS_EXITED } from "../errors.js";
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
+ *
+ * 职责：
+ * 1. 监督并隔离子进程的生命周期与标准输出，保证父进程标准输入输出通道 100% 纯净。
+ * 2. 将子进程标准输出/错误通过 DiagnosticForwarder 进行受控排空与诊断流限流转发。
+ * 3. 当子进程异常终止时，立即将当前活跃调用转换为结构化 HOST_PROCESS_EXITED 错误，防止调用方死锁。
+ */
+export class IpcActionDockTarget {
+    child;
+    forwarder;
+    pendingCalls = new Map();
+    isClosed = false;
+    exitError;
+    readyPromise;
+    constructor(options) {
+        this.forwarder = new DiagnosticForwarder({
+            maxBytes: options.maxDiagnosticBytes,
+            maxRateBytesPerSec: options.maxDiagnosticRate,
+            target: options.diagnosticTarget,
+        });
+        if (options.childProcess) {
+            this.child = options.childProcess;
+        }
+        else if (options.scriptPath) {
+            this.child = fork(options.scriptPath, options.scriptArgs || [], {
+                cwd: options.cwd || process.cwd(),
+                env: options.env || process.env,
+                stdio: ["pipe", "pipe", "pipe", "ipc"],
+            });
+        }
+        else {
+            throw new Error("IpcActionDockTarget requires either 'childProcess' or 'scriptPath'");
+        }
+        // 绑定子进程输出至受控限流排空器，绝不泄露至 process.stdout
+        if (this.child.stdout) {
+            this.forwarder.attach(this.child.stdout, "stdout");
+        }
+        if (this.child.stderr) {
+            this.forwarder.attach(this.child.stderr, "stderr");
+        }
+        let resolveReady;
+        this.readyPromise = new Promise((r) => {
+            resolveReady = r;
+        });
+        this.child.on("message", (msg) => {
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.type === "ready") {
+                resolveReady();
+            }
+            else if (msg.type === "response") {
+                const resp = msg;
+                const pending = this.pendingCalls.get(resp.id);
+                if (pending) {
+                    this.pendingCalls.delete(resp.id);
+                    if (resp.ok) {
+                        pending.resolve(resp.data);
+                    }
+                    else {
+                        const err = new Error(resp.error?.message || "IPC Target call failed");
+                        if (resp.error?.code)
+                            err.code = resp.error.code;
+                        if (resp.error?.details)
+                            err.details = resp.error.details;
+                        pending.reject(err);
+                    }
+                }
+            }
+        });
+        this.child.on("exit", (code, signal) => {
+            const exitMsg = `Host process exited prematurely with code ${code ?? signal ?? "unknown"}`;
+            const err = new Error(exitMsg);
+            err.code = "HOST_PROCESS_EXITED";
+            this.exitError = err;
+            this.isClosed = true;
+            // 快速失败所有待处理调用
+            for (const pending of this.pendingCalls.values()) {
+                if (pending.method === "runAction") {
+                    pending.resolve({
+                        ok: false,
+                        runId: randomUUID(),
+                        error: {
+                            code: HOST_PROCESS_EXITED,
+                            message: exitMsg,
+                        },
+                    });
+                }
+                else {
+                    pending.reject(err);
+                }
+            }
+            this.pendingCalls.clear();
+            resolveReady(); // 避免就绪死锁
+        });
+        this.child.on("error", (err) => {
+            this.exitError = err;
+        });
+    }
+    /**
+     * 等待宿主子进程初始化就绪。
+     */
+    async waitReady(timeoutMs = 5000) {
+        if (this.exitError)
+            throw this.exitError;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Timeout waiting for host process ready after ${timeoutMs}ms`)), timeoutMs);
+        });
+        try {
+            await Promise.race([this.readyPromise, timeout]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    /**
+     * 获取底层子进程实例。
+     */
+    get process() {
+        return this.child;
+    }
+    async callRemote(method, args) {
+        if (this.isClosed || this.exitError) {
+            if (method === "runAction") {
+                return {
+                    ok: false,
+                    runId: randomUUID(),
+                    error: {
+                        code: HOST_PROCESS_EXITED,
+                        message: this.exitError?.message || "Host process is already closed",
+                    },
+                };
+            }
+            throw this.exitError || new Error("Host process is already closed");
+        }
+        const id = randomUUID();
+        const msg = {
+            id,
+            type: "call",
+            method,
+            args,
+        };
+        return new Promise((resolve, reject) => {
+            this.pendingCalls.set(id, { resolve, reject, method });
+            try {
+                if (this.child.send) {
+                    this.child.send(msg);
+                }
+                else {
+                    this.pendingCalls.delete(id);
+                    reject(new Error("IPC channel unavailable on child process"));
+                }
+            }
+            catch (err) {
+                this.pendingCalls.delete(id);
+                reject(err);
+            }
+        });
+    }
+    async info() {
+        return this.callRemote("info", []);
+    }
+    async listPackages() {
+        return this.callRemote("listPackages", []);
+    }
+    async listActions(options) {
+        return this.callRemote("listActions", [options]);
+    }
+    async describeAction(ref) {
+        return this.callRemote("describeAction", [ref]);
+    }
+    async listPlaybooks(options) {
+        return this.callRemote("listPlaybooks", [options]);
+    }
+    async describePlaybook(id) {
+        return this.callRemote("describePlaybook", [id]);
+    }
+    async runAction(ref, input, options) {
+        const { signal, ...serializableOptions } = options || {};
+        if (signal?.aborted) {
+            return {
+                ok: false,
+                runId: randomUUID(),
+                error: {
+                    code: EXECUTION_ABORTED,
+                    message: "Execution was aborted before starting",
+                },
+            };
+        }
+        return this.callRemote("runAction", [ref, input, serializableOptions]);
+    }
+    async startAction(ref, input, options) {
+        const { signal, ...serializableOptions } = options || {};
+        return this.callRemote("startAction", [ref, input, serializableOptions]);
+    }
+    async getRun(runId) {
+        const res = await this.callRemote("getRun", [runId]);
+        return res ?? undefined;
+    }
+    async cancelRun(runId) {
+        return this.callRemote("cancelRun", [runId]);
+    }
+    async listRuns(options) {
+        return this.callRemote("listRuns", [options]);
+    }
+    async *events(_runId, _options) {
+        // 基础 IPC 通道暂不流式下发历史事件
+    }
+    async listConfig(packageId) {
+        return this.callRemote("listConfig", [packageId]);
+    }
+    async getConfig(packageId, key) {
+        return this.callRemote("getConfig", [packageId, key]);
+    }
+    async setConfig(packageId, key, value) {
+        return this.callRemote("setConfig", [packageId, key, value]);
+    }
+    async deleteConfig(packageId, key) {
+        return this.callRemote("deleteConfig", [packageId, key]);
+    }
+    async getState(packageId, actionId, key, options) {
+        return this.callRemote("getState", [
+            packageId,
+            actionId,
+            key,
+            options,
+        ]);
+    }
+    async setState(packageId, actionId, key, value, options) {
+        return this.callRemote("setState", [packageId, actionId, key, value, options]);
+    }
+    async deleteState(packageId, actionId, key, options) {
+        return this.callRemote("deleteState", [packageId, actionId, key, options]);
+    }
+    async listStateKeys(packageId, actionId, options) {
+        return this.callRemote("listStateKeys", [packageId, actionId, options]);
+    }
+    async clearState(packageId, actionId, options) {
+        return this.callRemote("clearState", [packageId, actionId, options]);
+    }
+    async close() {
+        if (this.isClosed)
+            return;
+        if (this.child.exitCode !== null) {
+            this.forwarder.detachAll();
+            return;
+        }
+        const exitPromise = new Promise((resolve) => {
+            if (this.child.exitCode !== null) {
+                resolve();
+            }
+            else {
+                this.child.once("exit", () => resolve());
+            }
+        });
+        try {
+            if (this.child.connected) {
+                this.child.send({ type: "close" });
+            }
+        }
+        catch {
+            // 忽略发送关闭消息异常
+        }
+        // 若子进程超时未退出，先 SIGTERM 再 SIGKILL
+        const termTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGTERM");
+                }
+                catch { }
+            }
+        }, 1500);
+        const killTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch { }
+            }
+        }, 3000);
+        try {
+            await exitPromise;
+        }
+        finally {
+            clearTimeout(termTimer);
+            clearTimeout(killTimer);
+            this.forwarder.detachAll();
+        }
+    }
+}