@actiondock/core 2.20.0 → 2.21.0

package/dist/process/process-driver.js

@@ -1,8 +1,33 @@
 import childProcess from "node:child_process";
 import { createRequire } from "node:module";
-import { ActionDockError, INPUT_CLOSED, PROCESS_NOT_FOUND, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
+import { ActionDockError, INPUT_CLOSED, PROCESS_NOT_FOUND, PROCESS_TIMEOUT, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
 import { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv, } from "./driver.js";
 export { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv };
+/**
+ * 跨平台探测进程组是否在操作系统中仍然存活。
+ *
+ * - 在 POSIX 环境下驱动创建了独立进程组，仅向负数进程标识 (-pid) 发送探测信号 0；
+ *   若返回 EPERM 视为仍存活；若返回 ESRCH 则表示进程组已彻底消亡；其他错误不静默当作消亡；
+ *   绝不对正 pid 探测，杜绝命中操作系统已重用 PID 的其他进程。
+ * - 在 Windows 环境下通过 process.kill(pid, 0) 探测父进程存活性。
+ *
+ * @param pid 目标进程标识
+ */
+export function isProcessGroupAlive(pid) {
+    if (pid <= 0 || !Number.isInteger(pid))
+        return false;
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "EPERM")
+            return true;
+        if (error?.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
 /**
  * 跨平台终止进程组，确保不会遗留孤儿进程。
  *
@@ -149,10 +174,12 @@ function ptySignalToName(signal) {
 export class NodeProcessDriver {
     drainDeadlineMs;
     spawnFn;
+    waitForOutputClose;
     instances = new Map();
     constructor(options = {}) {
         this.drainDeadlineMs = options.drainDeadlineMs ?? 5000;
         this.spawnFn = options.spawnFn ?? childProcess.spawn;
+        this.waitForOutputClose = options.waitForOutputClose ?? false;
     }
     /**
      * 运行时能力集属性访问器。
@@ -235,6 +262,7 @@ export class NodeProcessDriver {
             throw faultError;
         }
         const exitListeners = [];
+        const closedListeners = [];
         const instance = {
             id: handleId,
             pid: ptyProcess.pid,
@@ -245,6 +273,7 @@ export class NodeProcessDriver {
             exited: false,
             outputClosed: false,
             exitListeners,
+            closedListeners,
             onExit(cb) {
                 if (instance.exited) {
                     cb();
@@ -253,19 +282,33 @@ export class NodeProcessDriver {
                     exitListeners.push(cb);
                 }
             },
+            onClosed(cb) {
+                if (instance.outputClosed) {
+                    cb();
+                }
+                else {
+                    closedListeners.push(cb);
+                }
+            },
             cleanup() {
                 if (instance.drainTimer) {
                     clearTimeout(instance.drainTimer);
                     instance.drainTimer = undefined;
                 }
                 exitListeners.length = 0;
+                closedListeners.length = 0;
             },
             selfRelease: () => {
                 // 终态收敛后自移除：按实例身份判断，dispose 先行移除或表内已换新实例时不重复删除
+                // 活跃 terminate 过程中不能因为父 close 提前自移除而绕过清理
+                if (instance.terminationPromise) {
+                    return;
+                }
                 if (this.instances.get(handleId) === instance) {
                     this.instances.delete(handleId);
                 }
             },
+            markOutputClosed: (reason) => markOutputClosed(reason),
         };
         const markExited = (code, signal) => {
             if (!instance.exited) {
@@ -284,12 +327,20 @@ export class NodeProcessDriver {
             }
             if (!instance.outputClosed) {
                 instance.outputClosed = true;
+                instance.outputClosedReason = reason;
                 observer.outputClosed(reason);
+                for (const listener of closedListeners) {
+                    listener();
+                }
+            }
+            if (instance.outputClosedReason === "natural" && !instance.terminationPromise) {
+                instance.selfRelease();
             }
-            instance.selfRelease();
         };
         // 绑定 PTY 数据输出
         ptyProcess.onData((data) => {
+            if (instance.outputClosed)
+                return;
             observer.output("pty", new TextEncoder().encode(data));
         });
         ptyProcess.onExit((e) => {
@@ -324,6 +375,7 @@ export class NodeProcessDriver {
             throw faultError;
         }
         const exitListeners = [];
+        const closedListeners = [];
         const instance = {
             id: handleId,
             pid: child.pid,
@@ -333,6 +385,7 @@ export class NodeProcessDriver {
             exited: false,
             outputClosed: false,
             exitListeners,
+            closedListeners,
             onExit(cb) {
                 if (instance.exited) {
                     cb();
@@ -341,19 +394,33 @@ export class NodeProcessDriver {
                     exitListeners.push(cb);
                 }
             },
+            onClosed(cb) {
+                if (instance.outputClosed) {
+                    cb();
+                }
+                else {
+                    closedListeners.push(cb);
+                }
+            },
             cleanup() {
                 if (instance.drainTimer) {
                     clearTimeout(instance.drainTimer);
                     instance.drainTimer = undefined;
                 }
                 exitListeners.length = 0;
+                closedListeners.length = 0;
             },
             selfRelease: () => {
                 // 终态收敛后自移除：按实例身份判断，dispose 先行移除或表内已换新实例时不重复删除
+                // 活跃 terminate 过程中不能因为父 close 提前自移除而绕过清理
+                if (instance.terminationPromise) {
+                    return;
+                }
                 if (this.instances.get(handleId) === instance) {
                     this.instances.delete(handleId);
                 }
             },
+            markOutputClosed: (reason) => markOutputClosed(reason),
         };
         const markExited = (code, signal) => {
             if (!instance.exited) {
@@ -372,18 +439,42 @@ export class NodeProcessDriver {
             }
             if (!instance.outputClosed) {
                 instance.outputClosed = true;
+                instance.outputClosedReason = reason;
+                if (reason !== "natural") {
+                    try {
+                        child.stdout?.destroy();
+                    }
+                    catch { }
+                    try {
+                        child.stderr?.destroy();
+                    }
+                    catch { }
+                    try {
+                        child.stdin?.destroy();
+                    }
+                    catch { }
+                }
                 observer.outputClosed(reason);
+                for (const listener of closedListeners) {
+                    listener();
+                }
+            }
+            if (instance.outputClosedReason === "natural" && !instance.terminationPromise) {
+                instance.selfRelease();
             }
-            instance.selfRelease();
         };
         // 同步完成 stdout/stderr 监听绑定，防止产生数据丢失竞态
         if (child.stdout) {
             child.stdout.on("data", (chunk) => {
+                if (instance.outputClosed)
+                    return;
                 observer.output("stdout", new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
             });
         }
         if (child.stderr) {
             child.stderr.on("data", (chunk) => {
+                if (instance.outputClosed)
+                    return;
                 observer.output("stderr", new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
             });
         }
@@ -395,7 +486,7 @@ export class NodeProcessDriver {
         }
         child.on("exit", (code, signal) => {
             markExited(code, signal);
-            if (!instance.outputClosed && !instance.drainTimer) {
+            if (!this.waitForOutputClose && !instance.terminationPromise && !instance.outputClosed && !instance.drainTimer) {
                 instance.drainTimer = setTimeout(() => {
                     markOutputClosed("drain-timeout");
                 }, this.drainDeadlineMs);
@@ -551,8 +642,9 @@ export class NodeProcessDriver {
         instance.ptyProcess.resize(cols, rows);
     }
     /**
-     * 优雅终止进程，超时未退出则发送 SIGKILL 强杀兜底。
-     * 终态自清理（selfRelease）或 dispose 先行移除实例时视为已终止，直接无害返回。
+     * 优雅终止进程整棵进程树，超时未退出则发送 SIGKILL 强杀兜底。
+     * 修复父进程先退出导致的短路，确保整组存活成员（包括忽略 SIGTERM 的孙进程及未闭合输出的活实例）被彻底终止，
+     * 并等待父进程与输出收敛。
      */
     async terminate(handle, graceMs) {
         const instance = this.instances.get(handle.id);
@@ -560,72 +652,149 @@ export class NodeProcessDriver {
             return;
         }
         const pid = instance.pid;
-        if (!pid || instance.exited) {
+        if (!pid) {
             return;
         }
-        await killProcessGroup(pid, "SIGTERM", this.spawnFn);
-        if (graceMs <= 0) {
-            if (!instance.exited) {
-                await killProcessGroup(pid, "SIGKILL", this.spawnFn);
-            }
-            return;
+        // 若当前实例已有正在进行的活跃 terminate 流程，直接复用合并，杜绝并发竞争
+        if (instance.terminationPromise) {
+            return instance.terminationPromise;
         }
-        if (instance.exited) {
+        // 若父进程已退出且输出已关闭，且进程树已无存活成员，直接无害返回（防止对历史 PID 发信号导致 PID 重用风险）
+        if (instance.exited && instance.outputClosed && !isProcessGroupAlive(pid)) {
             return;
         }
-        await new Promise((resolve) => {
-            let timer;
-            let settled = false;
-            let exitFinish;
-            const finish = () => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                // 完成后自注销本次注册的 exit 监听器，避免同一实例反复 terminate 时累积监听器
-                if (exitFinish) {
-                    const idx = instance.exitListeners.indexOf(exitFinish);
-                    if (idx >= 0) {
-                        instance.exitListeners.splice(idx, 1);
+        const terminationPromise = Promise.resolve().then(async () => {
+            try {
+                const isSettled = () => instance.exited && instance.outputClosed;
+                await killProcessGroup(pid, "SIGTERM", this.spawnFn);
+                if (graceMs <= 0) {
+                    if (!isSettled() || isProcessGroupAlive(pid)) {
+                        await killProcessGroup(pid, "SIGKILL", this.spawnFn);
                     }
                 }
-                if (timer)
-                    clearTimeout(timer);
-                resolve();
-            };
-            exitFinish = finish;
-            instance.onExit(finish);
-            timer = setTimeout(async () => {
-                if (!instance.exited) {
-                    try {
-                        await killProcessGroup(pid, "SIGKILL", this.spawnFn);
+                else {
+                    if (!isSettled() || isProcessGroupAlive(pid)) {
+                        await new Promise((resolve) => {
+                            let timer;
+                            let pollTimer;
+                            let settled = false;
+                            let exitListener;
+                            let closeListener;
+                            const cleanup = () => {
+                                if (settled) {
+                                    return;
+                                }
+                                settled = true;
+                                if (exitListener) {
+                                    const idx = instance.exitListeners.indexOf(exitListener);
+                                    if (idx >= 0) {
+                                        instance.exitListeners.splice(idx, 1);
+                                    }
+                                }
+                                if (closeListener) {
+                                    const idx = instance.closedListeners.indexOf(closeListener);
+                                    if (idx >= 0) {
+                                        instance.closedListeners.splice(idx, 1);
+                                    }
+                                }
+                                if (timer)
+                                    clearTimeout(timer);
+                                if (pollTimer)
+                                    clearInterval(pollTimer);
+                                resolve();
+                            };
+                            const check = () => {
+                                if (isSettled() && !isProcessGroupAlive(pid)) {
+                                    cleanup();
+                                }
+                            };
+                            exitListener = check;
+                            closeListener = check;
+                            pollTimer = setInterval(check, 20);
+                            timer = setTimeout(cleanup, graceMs);
+                            instance.onExit(exitListener);
+                            instance.onClosed(closeListener);
+                        });
+                        if (!isSettled() || isProcessGroupAlive(pid)) {
+                            await killProcessGroup(pid, "SIGKILL", this.spawnFn);
+                        }
                     }
-                    catch {
-                        // 忽略终止失败异常
+                }
+                // 第二阶段：强杀后等待父进程退出与输出收敛
+                if (!isSettled()) {
+                    if (instance.drainTimer) {
+                        clearTimeout(instance.drainTimer);
+                        instance.drainTimer = undefined;
                     }
+                    await new Promise((resolve, reject) => {
+                        let timer;
+                        let settled = false;
+                        let exitListener;
+                        let closeListener;
+                        const cleanup = () => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            if (exitListener) {
+                                const idx = instance.exitListeners.indexOf(exitListener);
+                                if (idx >= 0) {
+                                    instance.exitListeners.splice(idx, 1);
+                                }
+                            }
+                            if (closeListener) {
+                                const idx = instance.closedListeners.indexOf(closeListener);
+                                if (idx >= 0) {
+                                    instance.closedListeners.splice(idx, 1);
+                                }
+                            }
+                            if (timer)
+                                clearTimeout(timer);
+                        };
+                        const check = () => {
+                            if (isSettled()) {
+                                cleanup();
+                                resolve();
+                            }
+                        };
+                        exitListener = check;
+                        closeListener = check;
+                        instance.onExit(exitListener);
+                        instance.onClosed(closeListener);
+                        timer = setTimeout(() => {
+                            cleanup();
+                            if (!isSettled()) {
+                                if (!instance.outputClosed) {
+                                    instance.markOutputClosed("drain-timeout");
+                                }
+                                reject(new ProcessError(PROCESS_TIMEOUT, `Process failed to exit and close output within ${this.drainDeadlineMs}ms after termination: handle id ${instance.id}`));
+                            }
+                            else {
+                                resolve();
+                            }
+                        }, this.drainDeadlineMs);
+                    });
                 }
-                finish();
-            }, graceMs);
-            timer.unref?.();
+            }
+            finally {
+                instance.terminationPromise = undefined;
+                if (instance.outputClosed) {
+                    instance.selfRelease();
+                }
+            }
         });
+        instance.terminationPromise = terminationPromise;
+        return terminationPromise;
     }
     /**
      * 销毁进程句柄并清理相关资源。
-     * 对仍在运行的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
-     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出实例直接清理。
-     * 终态自清理（selfRelease）与 dispose 可能并发到达，二者均按实例身份判断，
-     * 后到方对已删除条目为无害空操作。
+     * 对仍在运行或进程树存活或输出未闭合的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
+     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出且输出闭合实例直接清理。
      */
     async dispose(handle) {
         const instance = this.instances.get(handle.id);
         if (instance) {
-            if (!instance.exited) {
-                try {
-                    await this.terminate(handle, 0);
-                }
-                catch {
-                    // 兜底终止失败不阻断句柄清理，退出事件仍会经监听链路上报
-                }
+            if (!instance.exited || !instance.outputClosed || isProcessGroupAlive(instance.pid ?? 0)) {
+                await this.terminate(handle, 0);
             }
             instance.cleanup();
             if (this.instances.get(handle.id) === instance) {

package/dist/process/run-executor.js

@@ -1,5 +1,5 @@
 import { encodeBytes, } from "@actiondock/sdk";
-import { PROCESS_CANCELLED, PROCESS_TIMEOUT, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
+import { PROCESS_CANCELLED, PROCESS_TIMEOUT, PROCESS_SPAWN_ERROR, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
 /**
  * 一次性 run 执行器。
  *
@@ -19,6 +19,12 @@ export class RunExecutor {
         if (ioMode !== "pipe") {
             throw new ProcessError(UNSUPPORTED_CAPABILITY, "Run requires IO mode to be 'pipe'");
         }
+        // 对齐 start 防御顺序：派生前检查取消信号，已中止直接抛出取消错误不再派生进程
+        if (call?.signal?.aborted) {
+            throw call.signal.reason instanceof ProcessError
+                ? call.signal.reason
+                : new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
+        }
         const effectiveSpec = {
             ...input.spec,
             io: {
@@ -31,13 +37,27 @@ export class RunExecutor {
         let truncated = false;
         let timedOut = false;
         let cancelled = false;
-        let resolveExit;
-        let rejectError;
-        const exitPromise = new Promise((resolve, reject) => {
-            resolveExit = resolve;
-            rejectError = reject;
-        });
+        let faultError;
+        let exitResult;
         let driverHandle;
+        let terminationOutcomePromise;
+        let requestedGraceMs;
+        // 唤醒统一等待链路的信号
+        let wakeUpWaiters;
+        const wakeUpPromise = new Promise((resolve) => {
+            wakeUpWaiters = resolve;
+        });
+        const triggerTerminate = (graceMs) => {
+            requestedGraceMs = Math.min(requestedGraceMs ?? graceMs, graceMs);
+            // 同步驱动可在 spawn 返回句柄前上报超限或故障，不能缓存一次空的清理结果。
+            if (!driverHandle)
+                return Promise.resolve({ ok: true });
+            if (!terminationOutcomePromise) {
+                const rawPromise = Promise.resolve().then(() => this.driver.terminate(driverHandle, requestedGraceMs));
+                terminationOutcomePromise = rawPromise.then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+            }
+            return terminationOutcomePromise;
+        };
         const observer = {
             output: (stream, data) => {
                 if (truncated)
@@ -47,9 +67,8 @@ export class RunExecutor {
                 const remaining = input.maxOutputBytes - totalBytes;
                 if (remaining <= 0) {
                     truncated = true;
-                    if (driverHandle) {
-                        void this.driver.terminate(driverHandle, 1000);
-                    }
+                    triggerTerminate(1000);
+                    wakeUpWaiters();
                     return;
                 }
                 if (data.byteLength > remaining) {
@@ -60,9 +79,8 @@ export class RunExecutor {
                     });
                     totalBytes += slice.byteLength;
                     truncated = true;
-                    if (driverHandle) {
-                        void this.driver.terminate(driverHandle, 1000);
-                    }
+                    triggerTerminate(1000);
+                    wakeUpWaiters();
                 }
                 else {
                     chunks.push({
@@ -73,82 +91,118 @@ export class RunExecutor {
                 }
             },
             exited: (exit) => {
-                resolveExit(exit);
+                exitResult = exit;
+                wakeUpWaiters();
             },
             outputClosed: () => { },
             fault: (err) => {
-                rejectError(err);
+                faultError = err;
+                triggerTerminate(0);
+                wakeUpWaiters();
             },
         };
-        // 对齐 start 防御顺序：派生前检查取消信号，已中止直接抛出取消错误不再派生进程
+        driverHandle = await this.driver.spawn(effectiveSpec, observer);
+        // 检查派生期间是否已被标记取消
         if (call?.signal?.aborted) {
-            throw call.signal.reason instanceof ProcessError
-                ? call.signal.reason
-                : new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
+            cancelled = true;
+            triggerTerminate(1000);
         }
-        driverHandle = await this.driver.spawn(effectiveSpec, observer);
         let timeoutTimer;
-        if (input.timeoutMs > 0) {
+        if (input.timeoutMs > 0 && !cancelled) {
             timeoutTimer = setTimeout(() => {
                 timedOut = true;
-                if (driverHandle) {
-                    void this.driver.terminate(driverHandle, 1000);
-                }
+                triggerTerminate(1000);
+                wakeUpWaiters();
             }, input.timeoutMs);
             if (typeof timeoutTimer?.unref === "function") {
                 timeoutTimer.unref();
             }
         }
         let onAbort;
-        if (call?.signal) {
-            if (call.signal.aborted) {
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                if (driverHandle)
-                    void this.driver.terminate(driverHandle, 1000);
-                throw call.signal.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-            }
+        if (call?.signal && !cancelled) {
             onAbort = () => {
                 cancelled = true;
                 if (timeoutTimer)
                     clearTimeout(timeoutTimer);
-                if (driverHandle)
-                    void this.driver.terminate(driverHandle, 1000);
+                triggerTerminate(1000);
+                wakeUpWaiters();
             };
             call.signal.addEventListener("abort", onAbort, { once: true });
         }
         try {
-            const exit = await exitPromise;
+            // 统一等待唤醒：exit、fault、timeout、cancel、output-limit 均触发 wakeUpPromise
+            while (!exitResult && !faultError && !timedOut && !cancelled && !truncated) {
+                await wakeUpPromise;
+            }
+            // 等待终结后清理定时器与事件监听
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
             if (call?.signal && onAbort) {
                 call.signal.removeEventListener("abort", onAbort);
             }
+            // 若启动了终止（超时、取消、输出超限、故障），统一等待单次终止排空结果
+            let outcome = { ok: true };
+            if (terminationOutcomePromise || timedOut || cancelled || truncated || faultError) {
+                outcome = await triggerTerminate(1000);
+            }
+            // 统一分类主错误及清理 cause
+            if (faultError) {
+                if (!outcome.ok && !faultError.cause) {
+                    faultError.cause = outcome.error;
+                }
+                throw faultError;
+            }
             if (timedOut) {
-                throw new ProcessError(PROCESS_TIMEOUT, `Process exceeded timeout of ${input.timeoutMs}ms`);
+                const err = new ProcessError(PROCESS_TIMEOUT, `Process exceeded timeout of ${input.timeoutMs}ms`, !outcome.ok ? { cause: outcome.error } : undefined);
+                if (!outcome.ok) {
+                    err.cause = outcome.error;
+                }
+                throw err;
             }
             if (cancelled || call?.signal?.aborted) {
-                throw call?.signal?.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
+                const baseReason = call?.signal?.reason;
+                if (baseReason !== undefined && outcome.ok)
+                    throw baseReason;
+                if (baseReason instanceof Error) {
+                    if (!outcome.ok && !baseReason.cause) {
+                        baseReason.cause = outcome.error;
+                    }
+                    throw baseReason;
+                }
+                const err = new ProcessError(PROCESS_CANCELLED, "Process run was cancelled", !outcome.ok ? { cause: outcome.error, reason: baseReason } : undefined);
+                if (!outcome.ok) {
+                    err.cause = outcome.error;
+                }
+                throw err;
+            }
+            if (truncated) {
+                if (!outcome.ok) {
+                    // 输出限额触发的强杀清理若发生异常，必须抛出清理错误避免静默吞错
+                    throw outcome.error instanceof Error
+                        ? outcome.error
+                        : new ProcessError(PROCESS_TIMEOUT, String(outcome.error));
+                }
+                if (!exitResult) {
+                    throw new ProcessError(PROCESS_SPAWN_ERROR, "Terminated process did not report an exit result");
+                }
+                return {
+                    exit: exitResult,
+                    chunks,
+                    truncated: true,
+                };
             }
             return {
-                exit,
+                exit: exitResult,
                 chunks,
-                truncated,
+                truncated: false,
             };
         }
-        catch (err) {
+        finally {
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
             if (call?.signal && onAbort) {
                 call.signal.removeEventListener("abort", onAbort);
             }
-            if (timedOut) {
-                throw new ProcessError(PROCESS_TIMEOUT, `Process exceeded timeout of ${input.timeoutMs}ms`);
-            }
-            if (cancelled || call?.signal?.aborted) {
-                throw call?.signal?.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
-            }
-            throw err;
         }
     }
 }