@actiondock/core 2.0.12 → 2.2.0

package/dist/runtime/events.js

@@ -0,0 +1,604 @@
+import { EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED } from "../errors.js";
+/**
+ * 订阅者通道：封装实时事件队列、监听器与终止状态。
+ * 职责：
+ * - 接收实时推送事件并入队（超出背压上限时推送终止事件并切断通道）。
+ * - 维护 done 终止标记与唤醒回调，供生成器编排消费。
+ * - 暴露 inactive 注销钩子，供外部在通道切断时注销监听器。
+ */
+class SubscriberChannel {
+    /** 实时事件队列（含背压终止事件） */
+    liveQueue = [];
+    /** 是否已收到终止信号（finish、淘汰、中断或唤醒） */
+    done = false;
+    /** 实时监听器（入队与背压终止逻辑入口） */
+    listener;
+    /** 通道被切断或订阅退出时的注销回调（由订阅方注入） */
+    onInactive = null;
+    /** 等待挂起期间的唤醒回调（由等待方注入） */
+    notify = null;
+    runId;
+    maxQueueSize;
+    cursor;
+    allocateEventId;
+    backpressureTerminated = false;
+    constructor(options) {
+        this.runId = options.runId;
+        this.maxQueueSize = options.maxQueueSize;
+        this.cursor = options.cursor;
+        this.allocateEventId = options.allocateEventId;
+        this.listener = (evt) => this.receive(evt);
+    }
+    /**
+     * 接收单条实时事件：队列满时推送背压终止事件并切断通道。
+     */
+    receive(evt) {
+        if (this.backpressureTerminated || this.done) {
+            return;
+        }
+        if (this.liveQueue.length >= this.maxQueueSize) {
+            // 慢订阅者导致队列溢出：向该慢订阅者推送终止事件并切断通道，主运行不受反向阻塞
+            this.backpressureTerminated = true;
+            this.onInactive?.();
+            const termEvt = {
+                runId: this.runId,
+                rootRunId: evt.rootRunId || this.runId,
+                sequence: evt.sequence + 1,
+                eventId: this.allocateEventId(),
+                timestamp: new Date().toISOString(),
+                type: "error",
+                error: {
+                    code: EVENT_BACKPRESSURE_LIMIT,
+                    message: `Event subscription queue exceeded limit of ${this.maxQueueSize} items due to slow subscriber`,
+                    details: {
+                        lastConfirmedCursor: this.cursor.lastConfirmedEventId ??
+                            (this.cursor.lastConfirmedSequence >= 0 ? String(this.cursor.lastConfirmedSequence) : "0"),
+                        lastConfirmedEventId: this.cursor.lastConfirmedEventId,
+                        lastConfirmedSequence: this.cursor.lastConfirmedSequence,
+                    },
+                },
+            };
+            this.liveQueue.length = 0;
+            this.liveQueue.push(termEvt);
+            if (this.notify) {
+                this.notify();
+                this.notify = null;
+            }
+            return;
+        }
+        this.liveQueue.push(evt);
+        if (this.notify) {
+            this.notify();
+            this.notify = null;
+        }
+        if (evt.type === "finish") {
+            this.done = true;
+        }
+    }
+    /**
+     * 标记通道终止并唤醒挂起的等待方。
+     */
+    terminate() {
+        this.done = true;
+        if (this.notify) {
+            this.notify();
+            this.notify = null;
+        }
+    }
+}
+/**
+ * 计算单个事件的 UTF-8 JSON 字节长度。
+ */
+function estimateEventBytes(event) {
+    try {
+        return Buffer.byteLength(JSON.stringify(event), "utf8");
+    }
+    catch {
+        return 256;
+    }
+}
+/**
+ * 进程内有界事件缓冲区实现。
+ * 遵循设计规范：
+ * - 单运行双配额保护：上限 1024 条事件或 1MiB 字节数，优先淘汰日志与进度，保护终态。
+ * - 全局有界回收：限制最大运行数（默认 500），溢出时优先淘汰已完成运行。
+ * - 原子订阅衔接：先注册实时队列再回放历史快照，去重并杜绝并发丢事件窗口。
+ * - 严格生命周期清理：迭代退出或中断时彻底注销监听器与 AbortSignal 事件。
+ * - 慢订阅者背压保护：队列超出上限时推送终止事件并切断通道，主运行不受阻。
+ * - 游标断点续传：支持全局持久化 eventId 与序列号，过期游标返回 EVENT_CURSOR_EXPIRED。
+ */
+export class InMemoryEventSink {
+    runs = new Map();
+    listeners = new Map();
+    wakeups = new Map();
+    evictions = new Map();
+    evictedRuns = new Set();
+    globalEventSeq = 0;
+    maxEventsPerRun;
+    maxBytesPerRun;
+    maxRuns;
+    maxSubscriberQueueSize;
+    constructor(options = {}) {
+        this.maxEventsPerRun = options.maxEventsPerRun ?? 1024;
+        this.maxBytesPerRun = options.maxBytesPerRun ?? 1024 * 1024; // 1 MiB
+        this.maxRuns = options.maxRuns ?? 500;
+        this.maxSubscriberQueueSize = options.maxSubscriberQueueSize ?? 1024;
+    }
+    emit(event) {
+        const runId = event.runId;
+        const now = Date.now();
+        let run = this.runs.get(runId);
+        let processedEvent = event;
+        if (!processedEvent.eventId) {
+            processedEvent = {
+                ...processedEvent,
+                eventId: String(++this.globalEventSeq),
+            };
+        }
+        if (!run) {
+            // 全局有界淘汰
+            if (this.runs.size >= this.maxRuns) {
+                this.evictOldestRun();
+            }
+            run = {
+                entries: [],
+                totalBytes: 0,
+                lastAccessedAt: now,
+                isTerminal: false,
+                earliestRetainedSequence: processedEvent.sequence,
+                earliestRetainedEventId: processedEvent.eventId,
+            };
+            this.runs.set(runId, run);
+            this.evictedRuns.delete(runId);
+        }
+        else {
+            run.lastAccessedAt = now;
+            if (run.earliestRetainedSequence === undefined) {
+                run.earliestRetainedSequence = processedEvent.sequence;
+                run.earliestRetainedEventId = processedEvent.eventId;
+            }
+        }
+        let eventBytes = estimateEventBytes(processedEvent);
+        // 如果单条事件本身超过单运行最大字节限制，尝试截断 log / finish 数据
+        if (eventBytes > this.maxBytesPerRun) {
+            if (processedEvent.type === "log" && typeof processedEvent.message === "string") {
+                const keepChars = Math.max(0, Math.floor(this.maxBytesPerRun / 2));
+                processedEvent = {
+                    ...processedEvent,
+                    message: `${processedEvent.message.slice(0, keepChars)}... [TRUNCATED]`,
+                    data: undefined,
+                };
+                eventBytes = estimateEventBytes(processedEvent);
+            }
+            else if (processedEvent.type === "finish" && processedEvent.result) {
+                if (processedEvent.result.ok) {
+                    processedEvent = {
+                        ...processedEvent,
+                        result: {
+                            ok: true,
+                            runId: processedEvent.result.runId,
+                            data: { _truncated: true, message: "Output exceeded maximum quota" },
+                        },
+                    };
+                }
+                else {
+                    const err = processedEvent.result.error;
+                    const keepChars = Math.max(0, Math.min(200, Math.floor(this.maxBytesPerRun / 2)));
+                    const truncatedMsg = typeof err?.message === "string"
+                        ? `${err.message.slice(0, keepChars)}... [TRUNCATED]`
+                        : "Error exceeded maximum quota";
+                    processedEvent = {
+                        ...processedEvent,
+                        result: {
+                            ok: false,
+                            runId: processedEvent.result.runId,
+                            error: {
+                                code: err?.code || "EXECUTION_ERROR",
+                                message: truncatedMsg,
+                            },
+                        },
+                    };
+                }
+                eventBytes = estimateEventBytes(processedEvent);
+            }
+        }
+        // 严格限制单运行缓存字节配额，超标事件不可入队，杜绝突破 maxBytesPerRun
+        if (eventBytes <= this.maxBytesPerRun) {
+            // 检查是否超出单运行条数或字节配额，按优先级淘汰
+            while (run.entries.length > 0 &&
+                (run.entries.length >= this.maxEventsPerRun ||
+                    run.totalBytes + eventBytes > this.maxBytesPerRun)) {
+                // 优先淘汰非核心事件：log 或 progress
+                const nonEssentialIndex = run.entries.findIndex((e) => e.event.type === "log" || e.event.type === "progress");
+                if (nonEssentialIndex >= 0) {
+                    const removed = run.entries.splice(nonEssentialIndex, 1)[0];
+                    run.totalBytes -= removed.bytes;
+                }
+                else {
+                    // 无非核心事件时，淘汰最早的非 finish 事件
+                    const nonTerminalIndex = run.entries.findIndex((e) => e.event.type !== "finish");
+                    if (nonTerminalIndex >= 0) {
+                        const removed = run.entries.splice(nonTerminalIndex, 1)[0];
+                        run.totalBytes -= removed.bytes;
+                    }
+                    else {
+                        const removed = run.entries.shift();
+                        run.totalBytes -= removed.bytes;
+                    }
+                }
+            }
+            if (run.entries.length > 0) {
+                run.earliestRetainedSequence = run.entries[0].event.sequence;
+                run.earliestRetainedEventId = run.entries[0].event.eventId;
+            }
+            if (run.totalBytes + eventBytes <= this.maxBytesPerRun) {
+                run.entries.push({ event: processedEvent, bytes: eventBytes });
+                run.totalBytes += eventBytes;
+            }
+        }
+        // 仅在接收到 finish 事件时才标记已终态，防止在终态 status 与 finish 之间的窗口内订阅过早结束
+        if (processedEvent.type === "finish") {
+            run.isTerminal = true;
+        }
+        // 广播至当前活跃监听器
+        const subs = this.listeners.get(runId);
+        if (subs && subs.size > 0) {
+            for (const listener of subs) {
+                try {
+                    listener(processedEvent);
+                }
+                catch {
+                    // 忽略单个监听器内部异常
+                }
+            }
+        }
+    }
+    async *subscribe(runId, options = {}) {
+        let afterSequence;
+        let afterEventId;
+        if (options.after !== undefined) {
+            if (typeof options.after === "number") {
+                afterSequence = options.after;
+            }
+            else {
+                const trimmed = String(options.after).trim();
+                if (/^-?\d+$/.test(trimmed)) {
+                    afterSequence = parseInt(trimmed, 10);
+                }
+                afterEventId = trimmed;
+            }
+        }
+        const effectiveAfter = afterSequence ?? -1;
+        const cursor = {
+            lastYieldedSequence: effectiveAfter,
+            lastConfirmedEventId: afterEventId,
+            lastConfirmedSequence: effectiveAfter,
+        };
+        if (options.signal?.aborted || this.evictedRuns.has(runId)) {
+            return;
+        }
+        // 检查游标是否在请求前已过期被清理
+        const run = this.runs.get(runId);
+        if (run && options.after !== undefined) {
+            this.assertCursorRetained(run, options.after, afterSequence);
+        }
+        const channel = new SubscriberChannel({
+            runId,
+            maxQueueSize: options.maxQueueSize ?? this.maxSubscriberQueueSize,
+            cursor,
+            allocateEventId: () => String(++this.globalEventSeq),
+        });
+        let subs = this.listeners.get(runId);
+        if (!subs) {
+            subs = new Set();
+            this.listeners.set(runId, subs);
+        }
+        const cleanupListener = () => {
+            subs?.delete(channel.listener);
+            if (subs && subs.size === 0) {
+                this.listeners.delete(runId);
+            }
+        };
+        channel.onInactive = cleanupListener;
+        let evictSet = this.evictions.get(runId);
+        if (!evictSet) {
+            evictSet = new Set();
+            this.evictions.set(runId, evictSet);
+        }
+        const onEvict = () => channel.terminate();
+        const onAbort = () => channel.terminate();
+        let currentWakeupCleanup = null;
+        // 先挂载实时监听器，防止历史回放与监听注册之间的竞态丢事件
+        subs.add(channel.listener);
+        evictSet.add(onEvict);
+        if (options.signal) {
+            options.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        const cleanup = () => {
+            if (currentWakeupCleanup) {
+                currentWakeupCleanup();
+                currentWakeupCleanup = null;
+            }
+            cleanupListener();
+            evictSet?.delete(onEvict);
+            if (evictSet && evictSet.size === 0) {
+                this.evictions.delete(runId);
+            }
+            if (options.signal) {
+                options.signal.removeEventListener("abort", onAbort);
+            }
+        };
+        try {
+            // 回放历史快照
+            if (run) {
+                run.lastAccessedAt = Date.now();
+                const historySnapshot = run.entries.map((e) => e.event);
+                for (const evt of historySnapshot) {
+                    if (options.signal?.aborted)
+                        return;
+                    if (evt.sequence > cursor.lastYieldedSequence) {
+                        this.trackDeliveredEvent(cursor, evt);
+                        yield evt;
+                        if (this.isTerminalDelivery(evt)) {
+                            channel.done = true;
+                            return;
+                        }
+                    }
+                }
+                // 若该运行已终态且历史中已无 finish 事件，先排空实时队列已到达的事件
+                if (run.isTerminal) {
+                    while (channel.liveQueue.length > 0) {
+                        const evt = this.takeNextDeliverable(channel, cursor);
+                        if (evt) {
+                            yield evt;
+                            if (this.isTerminalDelivery(evt)) {
+                                channel.done = true;
+                                return;
+                            }
+                        }
+                    }
+                    channel.done = true;
+                    return;
+                }
+            }
+            // 无缝衔接消费实时队列中的事件
+            while ((channel.liveQueue.length > 0 || !channel.done) && !options.signal?.aborted) {
+                if (this.evictedRuns.has(runId)) {
+                    channel.done = true;
+                    break;
+                }
+                if (channel.liveQueue.length > 0) {
+                    const evt = this.takeNextDeliverable(channel, cursor);
+                    if (evt) {
+                        yield evt;
+                        if (this.isTerminalDelivery(evt)) {
+                            channel.done = true;
+                            return;
+                        }
+                    }
+                }
+                else {
+                    if (this.evictedRuns.has(runId)) {
+                        channel.done = true;
+                        break;
+                    }
+                    await this.waitForNextEvent(runId, channel, (cleanupFn) => {
+                        currentWakeupCleanup = cleanupFn;
+                    });
+                }
+            }
+            // 消费中止或完成瞬间积压在 liveQueue 中的剩余事件
+            while (channel.liveQueue.length > 0) {
+                const evt = this.takeNextDeliverable(channel, cursor);
+                if (evt) {
+                    yield evt;
+                    if (this.isTerminalDelivery(evt)) {
+                        return;
+                    }
+                }
+            }
+        }
+        finally {
+            cleanup();
+        }
+    }
+    /**
+     * 断言请求游标仍处于保留窗口内（过期则抛出 EVENT_CURSOR_EXPIRED 错误）。
+     */
+    assertCursorRetained(run, after, afterSequence) {
+        const earliestSeq = run.earliestRetainedSequence ?? 0;
+        if (afterSequence !== undefined && afterSequence >= 0 && afterSequence < earliestSeq - 1) {
+            const earliestCursor = run.earliestRetainedEventId ?? String(earliestSeq);
+            const expiredErr = new Error(`Event cursor '${after}' has expired; earliest available cursor is '${earliestCursor}'`);
+            expiredErr.code = EVENT_CURSOR_EXPIRED;
+            expiredErr.details = {
+                cursor: after,
+                earliestCursor,
+                earliestRetainedCursor: earliestCursor,
+                earliestSequence: earliestSeq,
+                earliestEventId: run.earliestRetainedEventId,
+            };
+            throw expiredErr;
+        }
+    }
+    /**
+     * 记录已交付事件并推进游标（已交付序号与最后确认游标）。
+     */
+    trackDeliveredEvent(cursor, evt) {
+        cursor.lastYieldedSequence = evt.sequence;
+        cursor.lastConfirmedSequence = evt.sequence;
+        if (evt.eventId)
+            cursor.lastConfirmedEventId = evt.eventId;
+    }
+    /**
+     * 终止谓词：finish 事件或背压终止事件交付后订阅应立即结束。
+     */
+    isTerminalDelivery(evt) {
+        return (evt.type === "finish" ||
+            (evt.type === "error" && evt.error?.code === EVENT_BACKPRESSURE_LIMIT));
+    }
+    /**
+     * 从实时队列取出下一条应交付的事件（跳过已交付序号），并同步推进游标。
+     */
+    takeNextDeliverable(channel, cursor) {
+        const evt = channel.liveQueue.shift();
+        if (!evt)
+            return undefined;
+        if (evt.sequence > cursor.lastYieldedSequence || evt.type === "error") {
+            this.trackDeliveredEvent(cursor, evt);
+            return evt;
+        }
+        return undefined;
+    }
+    /**
+     * 挂起等待下一条实时事件、通道终止或运行淘汰唤醒（严格注销监听避免泄漏）。
+     */
+    async waitForNextEvent(runId, channel, registerCleanup) {
+        await new Promise((resolve) => {
+            let runWakeups = this.wakeups.get(runId);
+            if (!runWakeups) {
+                runWakeups = new Set();
+                this.wakeups.set(runId, runWakeups);
+            }
+            const unregister = () => {
+                runWakeups?.delete(onWakeup);
+                if (runWakeups && runWakeups.size === 0) {
+                    this.wakeups.delete(runId);
+                }
+                registerCleanup(null);
+            };
+            const onWakeup = () => {
+                channel.done = true;
+                unregister();
+                resolve();
+            };
+            runWakeups.add(onWakeup);
+            registerCleanup(unregister);
+            channel.notify = () => {
+                unregister();
+                resolve();
+            };
+        });
+    }
+    /**
+     * 手动修剪已终态运行中早于指定序列号的历史事件（用于模拟过期清理）。
+     */
+    pruneEvents(runId, upToSequence) {
+        const run = this.runs.get(runId);
+        if (!run)
+            return;
+        const idx = run.entries.findIndex((e) => e.event.sequence > upToSequence);
+        if (idx > 0) {
+            const removed = run.entries.splice(0, idx);
+            for (const r of removed) {
+                run.totalBytes -= r.bytes;
+            }
+        }
+        else if (idx === -1 && run.entries.length > 0) {
+            run.entries = [];
+            run.totalBytes = 0;
+        }
+        if (run.entries.length > 0) {
+            run.earliestRetainedSequence = run.entries[0].event.sequence;
+            run.earliestRetainedEventId = run.entries[0].event.eventId;
+        }
+        else {
+            run.earliestRetainedSequence = upToSequence + 1;
+            run.earliestRetainedEventId = undefined;
+        }
+    }
+    clear(runId) {
+        this.evictedRuns.add(runId);
+        if (this.evictedRuns.size > 2000) {
+            const first = this.evictedRuns.values().next().value;
+            if (first) {
+                this.evictedRuns.delete(first);
+            }
+        }
+        this.runs.delete(runId);
+        this.listeners.delete(runId);
+        const evictCbs = this.evictions.get(runId);
+        if (evictCbs) {
+            this.evictions.delete(runId);
+            for (const cb of Array.from(evictCbs)) {
+                try {
+                    cb();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        const waiting = this.wakeups.get(runId);
+        if (waiting) {
+            const cbs = Array.from(waiting);
+            this.wakeups.delete(runId);
+            for (const wake of cbs) {
+                try {
+                    wake();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    /**
+     * 获取指定运行的事件统计信息（调试与测试用）。
+     */
+    getRunStats(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            return undefined;
+        return {
+            count: run.entries.length,
+            bytes: run.totalBytes,
+            isTerminal: run.isTerminal,
+        };
+    }
+    /**
+     * 获取全局缓存的运行数。
+     */
+    getRunCount() {
+        return this.runs.size;
+    }
+    /**
+     * 淘汰最久未活跃的运行记录。
+     * 优先淘汰已终态运行；若无终态运行则淘汰最旧活动运行，严格保证 runs.size <= maxRuns。
+     */
+    evictOldestRun() {
+        let candidateRunId = null;
+        let candidateAccess = Infinity;
+        for (const [id, buffer] of this.runs.entries()) {
+            if (buffer.isTerminal) {
+                if (buffer.lastAccessedAt < candidateAccess) {
+                    candidateAccess = buffer.lastAccessedAt;
+                    candidateRunId = id;
+                }
+            }
+        }
+        if (!candidateRunId) {
+            for (const [id, buffer] of this.runs.entries()) {
+                if (buffer.lastAccessedAt < candidateAccess) {
+                    candidateAccess = buffer.lastAccessedAt;
+                    candidateRunId = id;
+                }
+            }
+        }
+        if (candidateRunId) {
+            this.clear(candidateRunId);
+        }
+    }
+    /**
+     * 关闭事件接收器并唤醒所有活跃订阅者退出。
+     */
+    close() {
+        for (const wakeups of this.wakeups.values()) {
+            for (const onWakeup of wakeups) {
+                onWakeup();
+            }
+        }
+        this.wakeups.clear();
+        this.listeners.clear();
+    }
+}

package/dist/runtime/execution-manager.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionHandle } from "./runner";
+import type { ExecutionHandle } from "./runner.js";
 /**
  * 内存中活跃执行句柄（In-flight Execution Handles）生命周期管理器。
  *

package/dist/runtime/execution-manager.js

@@ -0,0 +1,66 @@
+/**
+ * 内存中活跃执行句柄（In-flight Execution Handles）生命周期管理器。
+ *
+ * 职责：
+ * 1. 集中追踪正在执行的异步 Action 任务句柄。
+ * 2. 任务完成（无论成功或失败）后通过 Promise.finally 自动注销，防止内存泄漏。
+ * 3. 支持依据 runId 查询、遍历或主动发送取消信号（cancel）。
+ */
+export class ExecutionManager {
+    active = new Map();
+    /**
+     * 注册一个活跃的执行句柄。
+     * 当底层 Promise 完成结算（resolve/reject）时，自动从活跃映射表中移除。
+     *
+     * @param handle 执行句柄对象
+     */
+    register(handle) {
+        this.active.set(handle.runId, handle);
+        handle.result.finally(() => {
+            this.active.delete(handle.runId);
+        });
+    }
+    /**
+     * 根据 runId 检索正在执行的任务句柄。
+     *
+     * @param runId 运行 ID
+     * @returns 匹配的 ExecutionHandle 或 undefined
+     */
+    get(runId) {
+        return this.active.get(runId);
+    }
+    /**
+     * 向指定 runId 的在途执行任务发送取消信号。
+     *
+     * @param runId 目标运行 ID
+     * @param reason 取消原因描述
+     * @returns 若句柄存在且成功触发中断返回 true；若任务不存在或已完成返回 false
+     */
+    cancel(runId, reason) {
+        const handle = this.active.get(runId);
+        if (!handle) {
+            return false;
+        }
+        return handle.cancel(reason);
+    }
+    /**
+     * 手动从活跃集合中移除执行句柄。
+     *
+     * @param runId 运行 ID
+     */
+    remove(runId) {
+        this.active.delete(runId);
+    }
+    /**
+     * 获取当前系统中所有正在执行的活跃句柄列表。
+     */
+    list() {
+        return Array.from(this.active.values());
+    }
+    /**
+     * 清空所有活跃执行句柄。
+     */
+    clear() {
+        this.active.clear();
+    }
+}

package/dist/runtime/index.d.ts

@@ -1,9 +1,10 @@
-export * from "./context";
-export * from "./runner";
-export * from "./execution-manager";
-export * from "./standalone";
-export * from "./env";
-export * from "./clock";
-export * from "./process";
-export * from "./events";
-export * from "./module-loader";
+export * from "./context.js";
+export * from "./action-collection.js";
+export * from "./runner.js";
+export * from "./execution-manager.js";
+export * from "./standalone.js";
+export * from "./env.js";
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./events.js";
+export * from "./module-loader.js";