@actiondock/core 2.7.0 → 2.8.0

package/dist/process/process-driver.d.ts

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+import type { Capabilities, LaunchSpec } from "@actiondock/sdk";
+import { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv, type ProcessDriver, type ProcessDriverCallbacks, type ProcessDriverHandle, type ProcessHandle, type ProcessObserver } from "./driver.js";
+export { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv };
+export type { ProcessDriver, ProcessObserver, ProcessHandle, ProcessDriverCallbacks, ProcessDriverHandle };
+/**
+ * 跨平台终止进程组，确保不会遗留孤儿进程。
+ *
+ * - 在 POSIX 环境下通过负数进程标识终止整个进程组
+ * - 在 Windows 环境下优先通过 taskkill 递归终止整棵进程树，等待其完成后将 process.kill 作为失败或超时 fallback
+ *
+ * @param pid 目标子进程标识
+ * @param signal 发送的系统信号
+ * @param spawnFn 进程启动函数，默认为 childProcess.spawn
+ */
+export declare function killProcessGroup(pid: number, signal?: "SIGTERM" | "SIGKILL", spawnFn?: typeof spawn): Promise<void>;
+/**
+ * NodeProcessDriver 初始化选项。
+ */
+export interface NodeProcessDriverOptions {
+    /** 进程 exit 后 stdio 未 close 的最长等待排空时限（毫秒），默认为 5000 */
+    drainDeadlineMs?: number;
+    /** 进程派生函数，默认为 childProcess.spawn */
+    spawnFn?: typeof spawn;
+}
+/**
+ * 基于 Node.js 标准子进程实现的平台驱动。
+ * 遵循《ActionDock Managed Process 设计 v2》规范：
+ * - pipe 模式采用 child_process.spawn，支持进程组隔离与跨平台 killProcessGroup
+ * - 输出与生命周期监听在 spawn 返回前完成绑定，杜绝竞态丢失
+ * - 环境变量按 allowlisted 白名单与 none 策略严格继承，叠加 set 与 unset 变更
+ * - 写入支持背压流控与管道提早关闭异常捕获
+ * - 输入流支持 inputEOF 干净终止
+ * - 支持 5s 优雅输出排空 deadline 与 outputClosed 状态上报
+ * - PTY 模式在无 node-pty 环境明确拒绝并报告 UNSUPPORTED_CAPABILITY
+ */
+export declare class NodeProcessDriver implements ProcessDriver {
+    private readonly drainDeadlineMs;
+    readonly spawnFn: typeof spawn;
+    private readonly instances;
+    constructor(options?: NodeProcessDriverOptions);
+    /**
+     * 运行时能力集属性访问器。
+     */
+    get capabilities(): Capabilities;
+    /**
+     * 获取驱动支持的运行时能力集。
+     */
+    getCapabilities(): Capabilities;
+    /**
+     * 依据《Managed Process 设计 v2》标准契约启动受管进程。
+     */
+    spawn(spec: LaunchSpec, observer: ProcessObserver): Promise<ProcessHandle>;
+    /**
+     * 标准接口派生受管进程实现。
+     */
+    private spawnStandard;
+    /**
+     * PTY 模式派生：检查运行环境能力，若缺失 node-pty 则明确抛出异常。
+     */
+    private spawnPty;
+    /**
+     * pipe 模式派生：使用 child_process.spawn，同步完成监听绑定杜绝竞态。
+     */
+    private spawnPipe;
+    /**
+     * 构造对齐驱动操作的 ProcessHandle 对象。
+     */
+    private createHandleObject;
+    /**
+     * 向受管进程输入流写入字节数据，支持背压与管道提早关闭错误捕获。
+     * 终态自清理（selfRelease）或 dispose 先行移除实例时，进程已退出且输入管道必然关闭，
+     * 按已关闭语义抛出 INPUT_CLOSED 而非笼统异常。
+     */
+    write(handle: ProcessHandle, data: Uint8Array): Promise<void>;
+    /**
+     * 结束输入流写入，发送 EOF。
+     */
+    inputEOF(handle: ProcessHandle): Promise<void>;
+    /**
+     * 中断前台作业组。
+     */
+    interruptForeground(handle: ProcessHandle): Promise<void>;
+    /**
+     * 动态调整终端尺寸，仅 PTY 模式生效。
+     */
+    resize(handle: ProcessHandle, cols: number, rows: number): Promise<void>;
+    /**
+     * 优雅终止进程，超时未退出则发送 SIGKILL 强杀兜底。
+     * 终态自清理（selfRelease）或 dispose 先行移除实例时视为已终止，直接无害返回。
+     */
+    terminate(handle: ProcessHandle, graceMs: number): Promise<void>;
+    /**
+     * 销毁进程句柄并清理相关资源。
+     * 对仍在运行的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
+     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出实例直接清理。
+     * 终态自清理（selfRelease）与 dispose 可能并发到达，二者均按实例身份判断，
+     * 后到方对已删除条目为无害空操作。
+     */
+    dispose(handle: ProcessHandle): Promise<void>;
+    /**
+     * 解析查找内部受管进程实例。
+     */
+    private resolveInstance;
+}
+/**
+ * 兼容原有命名导出。
+ */
+export { NodeProcessDriver as ProcessDriverImpl };