@actiondock/core 2.5.1 → 2.7.0

package/dist/process/reservation-table.d.ts

@@ -0,0 +1,39 @@
+import type { ProcessRequestKey } from "./metadata-store.js";
+/**
+ * 同步幂等预占条目：在异步落盘窗口内锁定同作用域、进程、操作类型与请求标识的并发请求。
+ */
+export interface RequestReservation {
+    payloadHash: string;
+    operation: string;
+    promise: Promise<unknown>;
+    resolve: (value: unknown) => void;
+    reject: (err: unknown) => void;
+}
+/**
+ * 同步幂等预占表。
+ *
+ * 以复合键在异步落盘窗口内锁定并发重复请求，独立持有全部预占条目：
+ * commit 与 reject 均为「查表、删除、resolve/reject」同步原子序列。
+ */
+export declare class ReservationTable {
+    private readonly reservations;
+    /**
+     * 同步预占幂等请求：跨 await 的检查与落盘窗口内锁定同复合键并发调用。
+     * 返回 undefined 表示预占成功，调用方继续异步路径并在完成时调用 commit/reject。
+     * 返回 RequestReservation 表示已有同请求进行中，调用方可等待其结果。
+     * 若已有请求负载或操作类型不同，立即抛出 REQUEST_CONFLICT 杜绝混用结果。
+     */
+    reserve(key: ProcessRequestKey, payloadHash: string, operation: string): RequestReservation | undefined;
+    /**
+     * 结算预占：同步完成查表、删除与 resolve 的原子序列。
+     */
+    commit(key: ProcessRequestKey, operation: string, value: unknown): void;
+    /**
+     * 拒绝预占：同步完成查表、删除与 reject 的原子序列。
+     */
+    reject(key: ProcessRequestKey, operation: string, err: unknown): void;
+    /**
+     * 逐条拒绝并删除全部残余预占，供宿主关闭时唤醒全部等待方。
+     */
+    rejectAll(err: unknown): void;
+}

package/dist/process/reservation-table.js

@@ -0,0 +1,80 @@
+import { REQUEST_CONFLICT, ProcessError, } from "../errors.js";
+/**
+ * 格式化同步幂等预占键。
+ */
+function formatReservationKey(key, operation) {
+    return `${key.hostEpoch}:${key.scope}:${key.processId ?? ""}:${operation}:${key.requestId}`;
+}
+/**
+ * 同步幂等预占表。
+ *
+ * 以复合键在异步落盘窗口内锁定并发重复请求，独立持有全部预占条目：
+ * commit 与 reject 均为「查表、删除、resolve/reject」同步原子序列。
+ */
+export class ReservationTable {
+    reservations = new Map();
+    /**
+     * 同步预占幂等请求：跨 await 的检查与落盘窗口内锁定同复合键并发调用。
+     * 返回 undefined 表示预占成功，调用方继续异步路径并在完成时调用 commit/reject。
+     * 返回 RequestReservation 表示已有同请求进行中，调用方可等待其结果。
+     * 若已有请求负载或操作类型不同，立即抛出 REQUEST_CONFLICT 杜绝混用结果。
+     */
+    reserve(key, payloadHash, operation) {
+        const reservationKey = formatReservationKey(key, operation);
+        const existing = this.reservations.get(reservationKey);
+        if (existing) {
+            if (existing.payloadHash !== payloadHash || existing.operation !== operation) {
+                throw new ProcessError(REQUEST_CONFLICT, "Request conflict: identical requestId with different payload", { requestId: key.requestId });
+            }
+            return existing;
+        }
+        let resolveFn = () => { };
+        let rejectFn = () => { };
+        const promise = new Promise((res, rej) => {
+            resolveFn = res;
+            rejectFn = rej;
+        });
+        // 预占 promise 可能永远无人等待：预先挂接空捕获，避免拒绝时触发 unhandledRejection
+        promise.catch(() => { });
+        const reservation = {
+            payloadHash,
+            operation,
+            promise,
+            resolve: resolveFn,
+            reject: rejectFn,
+        };
+        this.reservations.set(reservationKey, reservation);
+        return undefined;
+    }
+    /**
+     * 结算预占：同步完成查表、删除与 resolve 的原子序列。
+     */
+    commit(key, operation, value) {
+        const reservationKey = formatReservationKey(key, operation);
+        const reservation = this.reservations.get(reservationKey);
+        if (reservation) {
+            this.reservations.delete(reservationKey);
+            reservation.resolve(value);
+        }
+    }
+    /**
+     * 拒绝预占：同步完成查表、删除与 reject 的原子序列。
+     */
+    reject(key, operation, err) {
+        const reservationKey = formatReservationKey(key, operation);
+        const reservation = this.reservations.get(reservationKey);
+        if (reservation) {
+            this.reservations.delete(reservationKey);
+            reservation.reject(err);
+        }
+    }
+    /**
+     * 逐条拒绝并删除全部残余预占，供宿主关闭时唤醒全部等待方。
+     */
+    rejectAll(err) {
+        for (const [reservationKey, res] of Array.from(this.reservations.entries())) {
+            this.reservations.delete(reservationKey);
+            res.reject(err);
+        }
+    }
+}

package/dist/process/run-executor.d.ts

@@ -0,0 +1,16 @@
+import { type CallOptions, type ProcessRunInput, type ProcessRunResult } from "@actiondock/sdk";
+import type { ProcessDriver } from "./driver.js";
+/**
+ * 一次性 run 执行器。
+ *
+ * 仅依赖底层驱动、错误映射与输入校验，不触碰进程注册表：
+ * 派生独立 run 进程、收集有限输出并支持协作式取消与超时回收。
+ */
+export declare class RunExecutor {
+    private readonly driver;
+    constructor(driver: ProcessDriver);
+    /**
+     * 执行一次性外部命令运行。
+     */
+    execute(input: ProcessRunInput, call?: CallOptions): Promise<ProcessRunResult>;
+}

package/dist/process/run-executor.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { encodeBytes, } from "@actiondock/sdk";
+import { PROCESS_CANCELLED, PROCESS_TIMEOUT, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
+/**
+ * 一次性 run 执行器。
+ *
+ * 仅依赖底层驱动、错误映射与输入校验，不触碰进程注册表：
+ * 派生独立 run 进程、收集有限输出并支持协作式取消与超时回收。
+ */
+export class RunExecutor {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /**
+     * 执行一次性外部命令运行。
+     */
+    async execute(input, call) {
+        const ioMode = input.spec.io?.mode ?? "pipe";
+        if (ioMode !== "pipe") {
+            throw new ProcessError(UNSUPPORTED_CAPABILITY, "Run requires IO mode to be 'pipe'");
+        }
+        const effectiveSpec = {
+            ...input.spec,
+            io: {
+                ...input.spec.io,
+                mode: "pipe",
+            },
+        };
+        const runProcessId = `run-${randomUUID()}`;
+        const chunks = [];
+        let totalBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        let resolveExit;
+        let rejectError;
+        const exitPromise = new Promise((resolve, reject) => {
+            resolveExit = resolve;
+            rejectError = reject;
+        });
+        let driverHandle;
+        const callbacks = {
+            onOutput: (stream, data) => {
+                if (truncated)
+                    return;
+                if (stream !== "stdout" && stream !== "stderr")
+                    return;
+                const remaining = input.maxOutputBytes - totalBytes;
+                if (remaining <= 0) {
+                    truncated = true;
+                    if (driverHandle) {
+                        void driverHandle.terminate(1000);
+                    }
+                    return;
+                }
+                if (data.byteLength > remaining) {
+                    const slice = data.subarray(0, remaining);
+                    chunks.push({
+                        stream,
+                        data: encodeBytes(slice),
+                    });
+                    totalBytes += slice.byteLength;
+                    truncated = true;
+                    if (driverHandle) {
+                        void driverHandle.terminate(1000);
+                    }
+                }
+                else {
+                    chunks.push({
+                        stream,
+                        data: encodeBytes(data),
+                    });
+                    totalBytes += data.byteLength;
+                }
+            },
+            onExit: (exit) => {
+                resolveExit(exit);
+            },
+            onError: (err) => {
+                rejectError(err);
+            },
+        };
+        // 对齐 start 防御顺序：派生前检查取消信号，已中止直接抛出取消错误不再派生进程
+        if (call?.signal?.aborted) {
+            throw call.signal.reason instanceof ProcessError
+                ? call.signal.reason
+                : new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
+        }
+        driverHandle = await this.driver.spawn(runProcessId, effectiveSpec, callbacks);
+        let timeoutTimer;
+        if (input.timeoutMs > 0) {
+            timeoutTimer = setTimeout(() => {
+                timedOut = true;
+                if (driverHandle) {
+                    void driverHandle.terminate(1000);
+                }
+            }, 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 driverHandle.terminate(1000);
+                throw call.signal.reason ?? new ProcessError(PROCESS_CANCELLED, "Process run was cancelled");
+            }
+            onAbort = () => {
+                cancelled = true;
+                if (timeoutTimer)
+                    clearTimeout(timeoutTimer);
+                if (driverHandle)
+                    void driverHandle.terminate(1000);
+            };
+            call.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        try {
+            const exit = await exitPromise;
+            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");
+            }
+            return {
+                exit,
+                chunks,
+                truncated,
+            };
+        }
+        catch (err) {
+            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;
+        }
+    }
+}

package/dist/process/terminal-output-cache.d.ts

@@ -0,0 +1,66 @@
+import type { ProcessOutputLog } from "./output-log.js";
+/**
+ * 已淘汰输出日志的墓碑信息。
+ */
+export interface EvictedOutputTombstone {
+    tailCursor: string;
+    earliestCursor: string;
+    evictedAt: number;
+}
+/**
+ * 终态输出日志保留缓存。
+ *
+ * 独立持有已驱逐进程的输出日志缓存与墓碑登记：内存输出无法从持久层恢复，
+ * 保留缓存支撑后续游标读取；TTL 过期转墓碑与 LRU 淘汰均保持同步原子。
+ */
+export declare class TerminalOutputCache {
+    /** 保留日志最大条目数上限（默认） */
+    static readonly DEFAULT_MAX_ENTRIES = 512;
+    /** 墓碑最大登记条数上限（默认） */
+    static readonly DEFAULT_MAX_TOMBSTONES = 2048;
+    private readonly entries;
+    private readonly tombstones;
+    private readonly retentionMs;
+    private readonly maxHostBufferBytes;
+    private readonly maxEntries;
+    private readonly maxTombstones;
+    constructor(options: {
+        /** 保留时长（毫秒） */
+        retentionMs: number;
+        /** 宿主输出缓冲区字节总配额 */
+        maxHostBufferBytes: number;
+        /** 保留日志最大条目数，默认 512 */
+        maxEntries?: number;
+        /** 墓碑最大登记条数，默认 2048 */
+        maxTombstones?: number;
+    });
+    /**
+     * 记录已淘汰输出日志的墓碑信息（超出容量时淘汰最旧登记，防止内存无限积压）。
+     */
+    private recordTombstone;
+    /**
+     * 清理已过期的终态输出日志条目并转为墓碑。
+     */
+    private cleanExpired;
+    /**
+     * 获取指定进程的墓碑登记信息。
+     */
+    getTombstone(processId: string): EvictedOutputTombstone | undefined;
+    /**
+     * 统计终态保留日志当前在内存中实际占用的输出缓冲字节总数（附带过期清理）。
+     */
+    retainedBytes(): number;
+    /**
+     * 将终态输出日志存入保留缓存，并根据宿主配额执行 LRU 与 TTL 淘汰。
+     */
+    retain(processId: string, log: ProcessOutputLog): void;
+    /**
+     * 获取终态保留日志（附带过期清理与 LRU 触达更新）。
+     */
+    get(processId: string): ProcessOutputLog | undefined;
+    /**
+     * 按 LRU 顺序逐条淘汰最旧保留日志并转为墓碑，直至剩余保留字节数不超过给定的可容纳上限。
+     * 返回被淘汰条目释放的字节总数，供宿主输出缓冲预算扣减复用。
+     */
+    evictLRUUntil(fits: number): number;
+}

package/dist/process/terminal-output-cache.js

@@ -0,0 +1,132 @@
+/**
+ * 终态输出日志保留缓存。
+ *
+ * 独立持有已驱逐进程的输出日志缓存与墓碑登记：内存输出无法从持久层恢复，
+ * 保留缓存支撑后续游标读取；TTL 过期转墓碑与 LRU 淘汰均保持同步原子。
+ */
+export class TerminalOutputCache {
+    /** 保留日志最大条目数上限（默认） */
+    static DEFAULT_MAX_ENTRIES = 512;
+    /** 墓碑最大登记条数上限（默认） */
+    static DEFAULT_MAX_TOMBSTONES = 2048;
+    entries = new Map();
+    tombstones = new Map();
+    retentionMs;
+    maxHostBufferBytes;
+    maxEntries;
+    maxTombstones;
+    constructor(options) {
+        this.retentionMs = options.retentionMs;
+        this.maxHostBufferBytes = options.maxHostBufferBytes;
+        this.maxEntries = options.maxEntries ?? TerminalOutputCache.DEFAULT_MAX_ENTRIES;
+        this.maxTombstones = options.maxTombstones ?? TerminalOutputCache.DEFAULT_MAX_TOMBSTONES;
+    }
+    /**
+     * 记录已淘汰输出日志的墓碑信息（超出容量时淘汰最旧登记，防止内存无限积压）。
+     */
+    recordTombstone(processId, tombstone) {
+        if (this.tombstones.size >= this.maxTombstones) {
+            const oldestKey = this.tombstones.keys().next().value;
+            if (oldestKey) {
+                this.tombstones.delete(oldestKey);
+            }
+        }
+        this.tombstones.set(processId, tombstone);
+    }
+    /**
+     * 清理已过期的终态输出日志条目并转为墓碑。
+     */
+    cleanExpired() {
+        const now = Date.now();
+        for (const [id, entry] of this.entries.entries()) {
+            if (now - entry.evictedAt > this.retentionMs) {
+                this.recordTombstone(id, {
+                    tailCursor: entry.log.tailCursor,
+                    earliestCursor: entry.log.earliestCursor,
+                    evictedAt: now,
+                });
+                this.entries.delete(id);
+            }
+        }
+    }
+    /**
+     * 获取指定进程的墓碑登记信息。
+     */
+    getTombstone(processId) {
+        return this.tombstones.get(processId);
+    }
+    /**
+     * 统计终态保留日志当前在内存中实际占用的输出缓冲字节总数（附带过期清理）。
+     */
+    retainedBytes() {
+        this.cleanExpired();
+        let bytes = 0;
+        for (const entry of this.entries.values()) {
+            bytes += entry.log.currentBytes;
+        }
+        return bytes;
+    }
+    /**
+     * 将终态输出日志存入保留缓存，并根据宿主配额执行 LRU 与 TTL 淘汰。
+     */
+    retain(processId, log) {
+        this.cleanExpired();
+        // 若新加入条目会导致总输出配额超限或数量超限，按 LRU 顺序淘汰最旧条目
+        while ((this.retainedBytes() + log.currentBytes > this.maxHostBufferBytes ||
+            this.entries.size >= this.maxEntries) &&
+            this.entries.size > 0) {
+            const oldestKey = this.entries.keys().next().value;
+            if (!oldestKey)
+                break;
+            const oldestEntry = this.entries.get(oldestKey);
+            if (oldestEntry) {
+                this.recordTombstone(oldestKey, {
+                    tailCursor: oldestEntry.log.tailCursor,
+                    earliestCursor: oldestEntry.log.earliestCursor,
+                    evictedAt: Date.now(),
+                });
+            }
+            this.entries.delete(oldestKey);
+        }
+        this.entries.set(processId, {
+            log,
+            evictedAt: Date.now(),
+        });
+    }
+    /**
+     * 获取终态保留日志（附带过期清理与 LRU 触达更新）。
+     */
+    get(processId) {
+        this.cleanExpired();
+        const entry = this.entries.get(processId);
+        if (!entry)
+            return undefined;
+        // 触达刷新 LRU 顺序
+        this.entries.delete(processId);
+        this.entries.set(processId, entry);
+        return entry.log;
+    }
+    /**
+     * 按 LRU 顺序逐条淘汰最旧保留日志并转为墓碑，直至剩余保留字节数不超过给定的可容纳上限。
+     * 返回被淘汰条目释放的字节总数，供宿主输出缓冲预算扣减复用。
+     */
+    evictLRUUntil(fits) {
+        let evictedBytes = 0;
+        while (this.entries.size > 0 && this.retainedBytes() > fits) {
+            const oldestKey = this.entries.keys().next().value;
+            if (!oldestKey)
+                break;
+            const oldest = this.entries.get(oldestKey);
+            if (oldest) {
+                this.recordTombstone(oldestKey, {
+                    tailCursor: oldest.log.tailCursor,
+                    earliestCursor: oldest.log.earliestCursor,
+                    evictedAt: Date.now(),
+                });
+                evictedBytes += oldest.log.currentBytes;
+            }
+            this.entries.delete(oldestKey);
+        }
+        return evictedBytes;
+    }
+}

package/dist/profile/client-actions.d.ts

@@ -0,0 +1,56 @@
+import type { ExecutionResult } from "@actiondock/sdk";
+import { type RemoteClientRequestOptions } from "./client-transport.js";
+/**
+ * 远端 Action 执行与查询域端点。
+ */
+/**
+ * 调用远端 ActionDock 服务端执行 Action 时的选项参数。
+ */
+export interface RemoteExecuteOptions extends RemoteClientRequestOptions {
+    /** 动态配置覆盖 */
+    configOverrides?: Record<string, unknown>;
+    /** 鉴权 Bearer Token */
+    token?: string;
+    /** 超时毫秒数 */
+    timeoutMs?: number;
+    /** 中断信号 */
+    signal?: AbortSignal;
+    /** 幂等请求去重标识 */
+    requestId?: string;
+    /** 是否异步触发（202 Accepted 立即返回 runId） */
+    async?: boolean;
+}
+/**
+ * 远端 Action 执行结果信封对象。
+ */
+export type RemoteExecutionResult<T = unknown> = ExecutionResult<T> & {
+    status?: string;
+};
+/**
+ * 执行远端 Action：支持幂等标识、异步触发、外部取消信号与本地超时守卫组合。
+ */
+export declare function executeRemoteAction<T = unknown>(serverUrl: string, actionId: string, input?: unknown, configOverridesOrOptions?: Record<string, unknown> | RemoteExecuteOptions, tokenArg?: string): Promise<RemoteExecutionResult<T>>;
+/**
+ * 拉取远端 Action 列表（可按意图过滤）。
+ */
+export declare function fetchRemoteActions(serverUrl: string, token?: string, intent?: string, options?: RemoteClientRequestOptions): Promise<Array<{
+    id: string;
+    description: string;
+    packageId?: string;
+}>>;
+/**
+ * 拉取单个远端 Action 的详细契约描述。
+ */
+export declare function fetchRemoteActionShow(serverUrl: string, actionId: string, token?: string, options?: RemoteClientRequestOptions): Promise<any>;
+/**
+ * 拉取远端服务信息总览（可按意图、包名过滤并附目录树）。
+ */
+export declare function fetchRemoteInfo(serverUrl: string, token?: string, options?: {
+    intent?: string;
+    package?: string;
+    tree?: boolean;
+} & RemoteClientRequestOptions): Promise<any>;
+/**
+ * 拉取远端环境体检报告（可定向指定包）。
+ */
+export declare function fetchRemoteDoctor(serverUrl: string, token?: string, targetPackage?: string, options?: RemoteClientRequestOptions): Promise<any>;