@actiondock/core 2.10.0 → 2.12.0

package/dist/platform/types.d.ts

@@ -1,50 +1,8 @@
 import type { ProcessAPI } from "@actiondock/sdk";
-import type { Clock } from "../runtime/clock.js";
-import type { ModuleLoader } from "../runtime/module-loader.js";
+import type { Clock } from "../storage/clock.js";
+import type { ModuleLoader } from "./module-loader.js";
 import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
-/**
- * 文件元数据信息契约。
- */
-export interface FileStat {
-    /** 是否为目录 */
-    isDirectory(): boolean;
-    /** 是否为普通文件 */
-    isFile(): boolean;
-    /** 文件字节大小 */
-    size: number;
-}
-/**
- * 跨运行时统一文件系统抽象契约。
- */
-export interface FileSystem {
-    /** 读取文件内容 */
-    readFile(path: string, encoding?: string): Promise<string> | string;
-    /** 写入文件内容 */
-    writeFile(path: string, content: string | Uint8Array): Promise<void> | void;
-    /** 读取目录下的所有条目名称 */
-    readdir(dir: string): Promise<string[]> | string[];
-    /** 获取路径对应条目的元数据状态 */
-    stat(path: string): Promise<{
-        isDirectory(): boolean;
-        isFile(): boolean;
-        size: number;
-    }>;
-    /** 检查路径是否存在 */
-    exists(path: string): Promise<boolean> | boolean;
-    /** 创建目录 */
-    mkdir(dir: string, options?: {
-        recursive?: boolean;
-    }): Promise<void> | void;
-    /** 删除文件或目录 */
-    rm(path: string, options?: {
-        recursive?: boolean;
-        force?: boolean;
-    }): Promise<void> | void;
-    /** 拷贝文件或目录 */
-    copy(src: string, dest: string, options?: {
-        recursive?: boolean;
-    }): Promise<void> | void;
-}
+import type { EventSink } from "../runtime/events.js";
 /**
  * 跨运行时持久化存储工厂配置选项。
  */
@@ -93,12 +51,14 @@ export interface RuntimePlatform {
     readonly name: "node" | "test";
     /** 统一时间与时钟驱动 */
     readonly clock: Clock;
-    /** 统一文件系统操作驱动 */
-    readonly files: FileSystem;
     /** 动态源码模块加载驱动 */
     readonly modules: ModuleLoader;
     /** 子进程衍生与执行驱动 */
     readonly process: ProcessAPI;
     /** 持久化数据库存储驱动工厂 */
     readonly storage: StorageFactory;
+    /**
+     * 可选执行事件接收器，宿主可注入，缺省由上层默认构造。
+     */
+    readonly eventSink?: EventSink;
 }

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

@@ -1,15 +1,13 @@
-import type { CallOptions, ControlGrant, OperationReceipt, ProcessAcquireInput, ProcessAPI, ProcessControlInput, ProcessInfo, ProcessListInput, ProcessListResult, ProcessReadInput, ProcessRunInput, ProcessRunResult, ProcessStartInput, ProcessStartResult, ProcessStopInput, ProcessWriteInput, ReadResult } from "@actiondock/sdk";
+import type { CallOptions, OperationReceipt, ProcessAPI, ProcessControlInput, ProcessInfo, ProcessListInput, ProcessListResult, ProcessReadInput, ProcessRunInput, ProcessRunResult, ProcessStartInput, ProcessStartResult, ProcessStopInput, ProcessWriteInput, ReadResult } from "@actiondock/sdk";
 import type { ProcessManager, ProcessOwner } from "./process-manager.js";
 /**
  * 绑定当前 ActionContext 上下文凭据与运行标识的 ProcessAPI 适配器实现。
  *
  * 核心保证：
  * - 自动注入当前运行上下文的归属所有者与运行标识。
- * - 跟踪由当前 Run 申请成功持有的控制权令牌。
- * - 拦截 Run 退出或异常生命周期：若当前 Run 未显式 release 释放控制权，自动撤销 grant 并将目标进程置入隔离状态 quarantined。
+ * - 跟踪 Run 生命周期终结时的资源清理。
  */
 export declare class ContextProcessAPI implements ProcessAPI {
-    private readonly heldProcesses;
     private isDisposed;
     private onAbortHandler?;
     readonly processManager: ProcessManager;
@@ -39,18 +37,6 @@ export declare class ContextProcessAPI implements ProcessAPI {
      * 分页列出当前所有者可见的受管进程列表。
      */
     list(input: ProcessListInput, call?: CallOptions): Promise<ProcessListResult>;
-    /**
-     * 申请指定受管进程的独占控制令牌。
-     */
-    acquire(id: string, input: ProcessAcquireInput, call?: CallOptions): Promise<ControlGrant>;
-    /**
-     * 延长当前有效控制令牌的存活时间。
-     */
-    renew(id: string, token: string, ttlMs: number, call?: CallOptions): Promise<ControlGrant>;
-    /**
-     * 显式释放控制令牌。
-     */
-    release(id: string, token: string, call?: CallOptions): Promise<void>;
     /**
      * 向受管进程输入流写入原始字节数据。
      */
@@ -72,8 +58,7 @@ export declare class ContextProcessAPI implements ProcessAPI {
      */
     stop(id: string, input: ProcessStopInput, call?: CallOptions): Promise<ProcessInfo>;
     /**
-     * 拦截 Action Run 生命周期终结：
-     * 若当前 Run 持有进程控制权且未显式 release，自动撤销 grant 并将目标进程置入隔离状态。
+     * 拦截 Action Run 生命周期终结,执行资源清理。
      */
     dispose(): Promise<void>;
     /**

package/dist/process/context-process.js

@@ -3,11 +3,9 @@
  *
  * 核心保证：
  * - 自动注入当前运行上下文的归属所有者与运行标识。
- * - 跟踪由当前 Run 申请成功持有的控制权令牌。
- * - 拦截 Run 退出或异常生命周期：若当前 Run 未显式 release 释放控制权，自动撤销 grant 并将目标进程置入隔离状态 quarantined。
+ * - 跟踪 Run 生命周期终结时的资源清理。
  */
 export class ContextProcessAPI {
-    heldProcesses = new Map();
     isDisposed = false;
     onAbortHandler;
     processManager;
@@ -64,29 +62,6 @@ export class ContextProcessAPI {
     async list(input, call) {
         return this.processManager.list(this.owner, input, this.mergeCallOptions(call));
     }
-    /**
-     * 申请指定受管进程的独占控制令牌。
-     */
-    async acquire(id, input, call) {
-        const grant = await this.processManager.acquire(this.owner, id, input, this.mergeCallOptions(call), this.runId);
-        this.heldProcesses.set(id, grant.token);
-        return grant;
-    }
-    /**
-     * 延长当前有效控制令牌的存活时间。
-     */
-    async renew(id, token, ttlMs, call) {
-        const renewed = await this.processManager.renew(this.owner, id, token, ttlMs, this.mergeCallOptions(call));
-        this.heldProcesses.set(id, renewed.token);
-        return renewed;
-    }
-    /**
-     * 显式释放控制令牌。
-     */
-    async release(id, token, call) {
-        await this.processManager.release(this.owner, id, token, this.mergeCallOptions(call));
-        this.heldProcesses.delete(id);
-    }
     /**
      * 向受管进程输入流写入原始字节数据。
      */
@@ -115,13 +90,10 @@ export class ContextProcessAPI {
      * 终止指定的受管进程资源。
      */
     async stop(id, input, call) {
-        const info = await this.processManager.stop(this.owner, id, input, this.mergeCallOptions(call));
-        this.heldProcesses.delete(id);
-        return info;
+        return await this.processManager.stop(this.owner, id, input, this.mergeCallOptions(call));
     }
     /**
-     * 拦截 Action Run 生命周期终结：
-     * 若当前 Run 持有进程控制权且未显式 release，自动撤销 grant 并将目标进程置入隔离状态。
+     * 拦截 Action Run 生命周期终结,执行资源清理。
      */
     async dispose() {
         if (this.isDisposed) {
@@ -132,19 +104,6 @@ export class ContextProcessAPI {
             this.signal.removeEventListener("abort", this.onAbortHandler);
             this.onAbortHandler = undefined;
         }
-        if (this.heldProcesses.size === 0) {
-            return;
-        }
-        const pendingEntries = Array.from(this.heldProcesses.entries());
-        this.heldProcesses.clear();
-        for (const [processId, token] of pendingEntries) {
-            try {
-                await this.processManager.quarantineProcess(this.owner, processId, token, "Run terminated without explicitly releasing control");
-            }
-            catch {
-                // 忽略终结清理阶段次级异常
-            }
-        }
     }
     /**
      * 合并上下文取消信号与单次调用选项中的取消信号。

package/dist/process/control.d.ts

@@ -0,0 +1,21 @@
+import type { ManagedProcessRecord, ProcessOwner } from "./managed-record.js";
+export interface ControlManagerOptions {
+    persistState: (processId: string, patch: any) => Promise<void>;
+    takeoverQueue: (proc: ManagedProcessRecord, reason: string) => void;
+}
+/**
+ * 受管进程控制权状态管理器。
+ * 聚焦于 free、quarantined 与 closed 三态流转与输入队列安全接管。
+ */
+export declare class ProcessControlManager {
+    private readonly options;
+    constructor(options: ControlManagerOptions);
+    /**
+     * 将进程控制状态原子收敛为已关闭（终态）。
+     */
+    close(proc: ManagedProcessRecord): Promise<void>;
+    /**
+     * 将进程转入检疫隔离状态，接管待处理输入队列并透传隔离原因。
+     */
+    quarantine(proc: ManagedProcessRecord, owner: ProcessOwner, reason?: string): Promise<void>;
+}

package/dist/process/control.js

@@ -0,0 +1,34 @@
+import { CONTROL_REVOKED } from "../errors.js";
+import { checkOwnerAuthorized } from "./converters.js";
+/**
+ * 受管进程控制权状态管理器。
+ * 聚焦于 free、quarantined 与 closed 三态流转与输入队列安全接管。
+ */
+export class ProcessControlManager {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * 将进程控制状态原子收敛为已关闭（终态）。
+     */
+    async close(proc) {
+        if (proc.info.control === "closed") {
+            return;
+        }
+        proc.info.control = "closed";
+        await this.options.persistState(proc.info.id, { control: "closed", controlState: "closed" });
+    }
+    /**
+     * 将进程转入检疫隔离状态，接管待处理输入队列并透传隔离原因。
+     */
+    async quarantine(proc, owner, reason) {
+        checkOwnerAuthorized(owner, proc.owner);
+        if (proc.info.control === "quarantined" || proc.info.control === "closed") {
+            return;
+        }
+        proc.info.control = "quarantined";
+        this.options.takeoverQueue(proc, reason ?? CONTROL_REVOKED);
+        await this.options.persistState(proc.info.id, { control: "quarantined", controlState: "quarantined" });
+    }
+}

package/dist/process/converters.d.ts

@@ -0,0 +1,23 @@
+import type { ProcessInfo } from "@actiondock/sdk";
+import type { ProcessOwnerFilter, StoredProcessRecord } from "./metadata-store.js";
+import type { ProcessOwner } from "./managed-record.js";
+/**
+ * 格式化生成作用域唯一隔离字符串。
+ */
+export declare function formatProcessScope(owner: ProcessOwner): string;
+/**
+ * 校验调用方所有者凭据与目标记录是否完全匹配。
+ */
+export declare function checkOwnerAuthorized(owner: ProcessOwner, target: ProcessOwnerFilter | StoredProcessRecord): void;
+/**
+ * 计算任意 JSON 负载对象的 SHA-256 哈希值。
+ */
+export declare function hashRequestPayload(payload: unknown): string;
+/**
+ * 将持久化记录转换为 SDK 标准 ProcessInfo 快照。
+ */
+export declare function toSdkProcessInfo(record: StoredProcessRecord): ProcessInfo;
+/**
+ * 将内部模型转换为持久化记录。
+ */
+export declare function toStoredProcessRecord(owner: ProcessOwner, info: ProcessInfo, startRequestId?: string): StoredProcessRecord;

package/dist/process/converters.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { ACCESS_DENIED, ProcessError } from "../errors.js";
+/**
+ * 格式化生成作用域唯一隔离字符串。
+ */
+export function formatProcessScope(owner) {
+    return `${owner.tenantId}:${owner.principalId}:${owner.packageInstanceId}:${owner.generationId}`;
+}
+/**
+ * 校验调用方所有者凭据与目标记录是否完全匹配。
+ */
+export function checkOwnerAuthorized(owner, target) {
+    if (!owner ||
+        !owner.tenantId ||
+        !owner.principalId ||
+        !owner.packageInstanceId ||
+        !owner.generationId) {
+        throw new ProcessError(ACCESS_DENIED, "Missing required owner identity fields");
+    }
+    if (owner.tenantId !== target.tenantId ||
+        owner.principalId !== target.principalId ||
+        owner.packageInstanceId !== target.packageInstanceId ||
+        owner.generationId !== target.generationId) {
+        throw new ProcessError(ACCESS_DENIED, "Access denied: owner identity mismatch");
+    }
+}
+/**
+ * 计算任意 JSON 负载对象的 SHA-256 哈希值。
+ */
+export function hashRequestPayload(payload) {
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+/**
+ * 将持久化记录转换为 SDK 标准 ProcessInfo 快照。
+ */
+export function toSdkProcessInfo(record) {
+    const ctrl = (record.control ?? record.controlState ?? "free");
+    const exitDetails = record.exitCode !== undefined || record.exitSignal !== undefined
+        ? { code: record.exitCode ?? null, signal: record.exitSignal ?? null }
+        : undefined;
+    return {
+        id: record.processId,
+        hostEpoch: record.hostEpoch,
+        state: record.state,
+        control: ctrl,
+        io: (record.ioConfig ?? { mode: "pipe" }),
+        capabilities: (record.capabilities ?? {
+            pty: false,
+            resize: false,
+            inputEOF: false,
+            interruptForeground: false,
+            terminationScope: "process",
+        }),
+        createdAt: record.createdAt ?? new Date().toISOString(),
+        exit: exitDetails,
+        endReason: record.endReason,
+        outputClosed: Boolean(record.outputClosed),
+        outputEndReason: record.outputEndReason,
+        effectiveLimits: (record.effectiveLimits ?? {
+            idleMs: 60000,
+            lifetimeMs: 3600000,
+            outputBufferBytes: 4 * 1024 * 1024,
+        }),
+    };
+}
+/**
+ * 将内部模型转换为持久化记录。
+ */
+export function toStoredProcessRecord(owner, info, startRequestId) {
+    return {
+        processId: info.id,
+        tenantId: owner.tenantId,
+        principalId: owner.principalId,
+        packageInstanceId: owner.packageInstanceId,
+        generationId: owner.generationId,
+        hostEpoch: info.hostEpoch,
+        state: info.state,
+        controlState: info.control,
+        control: info.control,
+        ioConfig: info.io,
+        capabilities: info.capabilities,
+        createdAt: info.createdAt,
+        exitCode: info.exit ? info.exit.code : null,
+        exitSignal: info.exit ? info.exit.signal : null,
+        endReason: info.endReason ?? null,
+        outputClosed: info.outputClosed,
+        outputEndReason: info.outputEndReason ?? null,
+        inputClosed: false,
+        effectiveLimits: info.effectiveLimits,
+        startRequestId,
+    };
+}

package/dist/process/cursor.js

@@ -1,29 +1,9 @@
 import { INVALID_CURSOR, ProcessError } from "../errors.js";
 function toBase64Url(str) {
-    if (typeof Buffer !== "undefined") {
-        return Buffer.from(str, "utf8").toString("base64url");
-    }
-    const bytes = new TextEncoder().encode(str);
-    let binary = "";
-    for (let i = 0; i < bytes.byteLength; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
-    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return Buffer.from(str, "utf8").toString("base64url");
 }
 function fromBase64Url(base64url) {
-    if (typeof Buffer !== "undefined") {
-        return Buffer.from(base64url, "base64url").toString("utf8");
-    }
-    let base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
-    while (base64.length % 4) {
-        base64 += "=";
-    }
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-        bytes[i] = binary.charCodeAt(i);
-    }
-    return new TextDecoder("utf-8").decode(bytes);
+    return Buffer.from(base64url, "base64url").toString("utf8");
 }
 /**
  * 将内部字段编码为外部不透明游标字符串。

package/dist/process/{diagnostics-sink.d.ts → diagnostics.d.ts}

@@ -6,7 +6,6 @@ import type { Logger } from "@actiondock/sdk";
  * 缺失时保留在内存环形缓冲区，避免静默吞没异常。
  */
 export declare class DiagnosticsSink {
-    /** 注入的 logger 缺失时保留最近诊断条目的环形缓冲容量，默认 100 */
     static readonly DEFAULT_BUFFER_LIMIT = 100;
     private readonly logger?;
     private readonly bufferLimit;
@@ -15,12 +14,6 @@ export declare class DiagnosticsSink {
         logger?: Logger;
         bufferLimit?: number;
     });
-    /**
-     * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
-     */
     record(message: string, err?: unknown): void;
-    /**
-     * 获取最近的内部诊断日志快照（最近条目在前）。
-     */
     recent(): string[];
 }

package/dist/process/{diagnostics-sink.js → diagnostics.js}

@@ -5,7 +5,6 @@
  * 缺失时保留在内存环形缓冲区，避免静默吞没异常。
  */
 export class DiagnosticsSink {
-    /** 注入的 logger 缺失时保留最近诊断条目的环形缓冲容量，默认 100 */
     static DEFAULT_BUFFER_LIMIT = 100;
     logger;
     bufferLimit;
@@ -14,9 +13,6 @@ export class DiagnosticsSink {
         this.logger = options?.logger;
         this.bufferLimit = options?.bufferLimit ?? DiagnosticsSink.DEFAULT_BUFFER_LIMIT;
     }
-    /**
-     * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
-     */
     record(message, err) {
         const detail = err instanceof Error ? `${err.name}: ${err.message}` : err !== undefined ? String(err) : "";
         const line = detail ? `${message} (${detail})` : message;
@@ -24,11 +20,13 @@ export class DiagnosticsSink {
         if (this.diagnostics.length > this.bufferLimit) {
             this.diagnostics.shift();
         }
-        this.logger?.warn("[ProcessManager] " + line);
+        try {
+            this.logger?.warn("[ProcessManager] " + line);
+        }
+        catch {
+            // 防御与透明：避免外部 Logger 故障反向干扰核心生命周期流程
+        }
     }
-    /**
-     * 获取最近的内部诊断日志快照（最近条目在前）。
-     */
     recent() {
         return [...this.diagnostics].reverse();
     }

package/dist/process/index.d.ts

@@ -2,14 +2,12 @@ export * from "./cursor.js";
 export * from "./output-log.js";
 export * from "./metadata-store.js";
 export * from "./driver.js";
-export * from "./diagnostics-sink.js";
 export * from "./reservation-table.js";
 export * from "./terminal-output-cache.js";
 export * from "./run-executor.js";
 export * from "./managed-record.js";
-export * from "./control-arbiter.js";
 export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";
 export * from "./process-driver.js";
-export * from "./process-executor.js";
+export * from "./converters.js";

package/dist/process/index.js

@@ -2,14 +2,12 @@ export * from "./cursor.js";
 export * from "./output-log.js";
 export * from "./metadata-store.js";
 export * from "./driver.js";
-export * from "./diagnostics-sink.js";
 export * from "./reservation-table.js";
 export * from "./terminal-output-cache.js";
 export * from "./run-executor.js";
 export * from "./managed-record.js";
-export * from "./control-arbiter.js";
 export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";
 export * from "./process-driver.js";
-export * from "./process-executor.js";
+export * from "./converters.js";

package/dist/process/input-dispatcher.d.ts

@@ -1,6 +1,5 @@
 import type { OperationReceipt } from "@actiondock/sdk";
 import type { ManagedProcessRecord, ProcessOwner, QueuedOperation } from "./managed-record.js";
-import type { ControlArbiter } from "./control-arbiter.js";
 import type { ProcessRequestKey, StoredProcessRecord } from "./metadata-store.js";
 /**
  * 输入调度器宿主协作回调集合。
@@ -12,23 +11,17 @@ export interface InputDispatcherHost {
     persistReceipt(key: ProcessRequestKey, receipt: OperationReceipt, payloadHash?: string): Promise<void>;
     persistState(processId: string, patch: Partial<StoredProcessRecord>): Promise<void>;
     /** 写入不确定失败后的隔离处置 */
-    quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): Promise<void> | unknown;
+    quarantineProcess(owner: ProcessOwner, processId: string, reason?: string): Promise<void> | unknown;
     /** 成功输入后的空闲定时器刷新 */
     refreshIdleTimer(proc: ManagedProcessRecord): void;
     /** 内部诊断记录 */
     recordDiagnostic(message: string, err?: unknown): void;
-    /** 宿主级输入队列待写字节统计 */
-    countHostPendingInputBytes(): number;
-    /** 输入队列容量配额 */
-    readonly maxPendingQueueBytesPerProcess: number;
-    readonly maxPendingQueueBytesPerHost: number;
 }
 /**
  * write 入队请求参数。
  */
 export interface EnqueueWriteInput {
     requestId: string;
-    token: string;
     data: Uint8Array;
     key: ProcessRequestKey;
     payloadHash: string;
@@ -38,7 +31,6 @@ export interface EnqueueWriteInput {
  */
 export interface EnqueueControlInput {
     requestId: string;
-    token: string;
     action: QueuedOperation["action"];
     key: ProcessRequestKey;
     payloadHash: string;
@@ -55,14 +47,13 @@ export interface EnqueueControlInput {
  */
 export declare class InputDispatcher {
     private readonly host;
-    private readonly arbiter;
-    constructor(host: InputDispatcherHost, arbiter: ControlArbiter);
+    constructor(host: InputDispatcherHost);
     /**
-     * 入队写入操作：同步阶段完成授权校验、输入通道校验、队列容量检查与字节预扣；
+     * 入队写入操作：同步阶段完成授权校验与输入通道校验；
      * 异步阶段落盘排队收据并推送队列，随后触发串行调度。
      *
      * 返回的 Promise 在收据成功入队后 resolve（state 为 queued）；
-     * 落盘或推送失败时回滚字节预扣并原样抛出。
+     * 落盘或推送失败时原样抛出。
      */
     enqueueWrite(proc: ManagedProcessRecord, input: EnqueueWriteInput): Promise<OperationReceipt>;
     /**