@gt-fe/eap-runtime 0.0.8

package/dist/sse/events/stats-events.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 统计事件 Payload 定义
+ *
+ * 核心事件：
+ * - stats.token_usage
+ *
+ * 可选事件：
+ * - stats.node_token_usage
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ */
+/** Token 消耗统计（按维度分组） */
+export interface TokenUsageBreakdown {
+    /** 输入 token 数 */
+    input: number;
+    /** 输出 token 数 */
+    output: number;
+}
+/** Task 结束时 Token 消耗汇总 */
+export interface StatsTokenUsagePayload {
+    /** 总 token 消耗 */
+    total: TokenUsageBreakdown;
+    /** 按节点分组的 token 消耗 */
+    byNode: Record<string, TokenUsageBreakdown>;
+    /** 按模型分组的 token 消耗 */
+    byModel: Record<string, TokenUsageBreakdown>;
+    /** 预估费用（美元） */
+    costEstimate: number;
+}
+/** 单节点 Token 消耗 */
+export interface StatsNodeTokenUsagePayload {
+    /** 节点 ID */
+    nodeId: string;
+    /** 使用的模型名称 */
+    model: string;
+    /** 输入 token 数 */
+    inputTokens: number;
+    /** 输出 token 数 */
+    outputTokens: number;
+    /** 预估费用（美元） */
+    costEstimate: number;
+    /** 该节点本次调用耗时（毫秒），可选 */
+    durationMs?: number;
+}

package/dist/sse/events/stats-events.js

@@ -0,0 +1,12 @@
+/**
+ * 统计事件 Payload 定义
+ *
+ * 核心事件：
+ * - stats.token_usage
+ *
+ * 可选事件：
+ * - stats.node_token_usage
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ */
+export {};

package/dist/sse/events/tool-events.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 工具执行事件 Payload 定义
+ *
+ * 核心事件：
+ * - tool.called
+ * - tool.result
+ * - tool.error
+ *
+ * 可选事件：
+ * - tool.progress
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ */
+/** 工具被调用 */
+export interface ToolCalledPayload {
+    /** 工具调用 ID */
+    toolCallId: string;
+    /** 工具名称 */
+    toolName: string;
+    /** 调用参数 */
+    arguments: Record<string, unknown>;
+}
+/** 工具执行结果 */
+export interface ToolResultPayload {
+    /** 工具调用 ID */
+    toolCallId: string;
+    /** 工具名称 */
+    toolName: string;
+    /** 返回内容 */
+    content: unknown;
+    /** 是否执行成功 */
+    success: boolean;
+}
+/** 工具执行进度 */
+export type ToolProgressStatus = 'started' | 'completed' | 'error' | (string & {});
+export interface ToolProgressPayload {
+    /** 工具调用 ID */
+    toolCallId: string;
+    /** 工具名称 */
+    toolName: string;
+    /**
+     * 进度状态：
+     * - started / completed / error（与 agent-with-mcp tool.progress 对齐）
+     * - 或其它描述性字符串
+     */
+    status: ToolProgressStatus;
+    /** 进度百分比 (0-100)，可选；started/completed 场景可不传 */
+    progress?: number;
+    /** status=started 时可选：调用参数 */
+    arguments?: Record<string, unknown>;
+    /** status=completed 时可选：工具返回摘要/内容 */
+    content?: unknown;
+    /** status=error 时可选：错误信息 */
+    error?: string;
+    /** 执行耗时（毫秒），status=completed|error 时可选 */
+    executionTime?: number;
+}
+/** 工具执行失败 */
+export interface ToolErrorPayload {
+    /** 工具调用 ID */
+    toolCallId: string;
+    /** 工具名称 */
+    toolName: string;
+    /** 错误信息 */
+    error: string;
+    /** 是否会自动重试 */
+    willRetry: boolean;
+}

package/dist/sse/events/tool-events.js

@@ -0,0 +1,14 @@
+/**
+ * 工具执行事件 Payload 定义
+ *
+ * 核心事件：
+ * - tool.called
+ * - tool.result
+ * - tool.error
+ *
+ * 可选事件：
+ * - tool.progress
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ */
+export {};

package/dist/sse/index.d.ts

@@ -0,0 +1,8 @@
+export * from './contracts/index.js';
+export * from './events/index.js';
+export * from './sse-emitter.js';
+export * from './sse-heartbeat.js';
+export * from './sse-connection-manager.js';
+export * from './event-buffer.js';
+export * from './connection-event-logger.js';
+export * from './trace-collector.js';

package/dist/sse/index.js

@@ -0,0 +1,8 @@
+export * from './contracts/index.js';
+export * from './events/index.js';
+export * from './sse-emitter.js';
+export * from './sse-heartbeat.js';
+export * from './sse-connection-manager.js';
+export * from './event-buffer.js';
+export * from './connection-event-logger.js';
+export * from './trace-collector.js';

package/dist/sse/sse-connection-manager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * SSEConnectionManager — SSE 多连接管理器
+ *
+ * 管理多个并发 SSE 连接，按 taskId 注册/查找/注销。
+ * 支持客户端断线检测（自动注销）和断线重连（替换 emitter）。
+ *
+ * @see design.md §1.1 连接管理：SSE心跳、断线重连支持
+ * @see requirements.md Requirement 9 AC3: 断线重连+Checkpoint恢复
+ * @see requirements.md Requirement 5 AC5: heartbeat保持连接
+ */
+import type { SSEEmitter } from './sse-emitter.js';
+/**
+ * 单个连接的注册选项
+ */
+export interface SSEConnectionOptions {
+    /** 连接断开时的回调 */
+    onDisconnect?: (taskId: string) => void;
+}
+/**
+ * SSEConnectionManager — 多 SSE 连接注册表
+ *
+ * 用法：
+ * ```ts
+ * const manager = new SSEConnectionManager();
+ * manager.register(taskId, emitter, { onDisconnect: (id) => console.log(`${id} disconnected`) });
+ * manager.getEmitter(taskId)?.emit(event);
+ * manager.closeAll(); // graceful shutdown
+ * ```
+ */
+export declare class SSEConnectionManager {
+    private readonly connections;
+    private pollingTimer;
+    private readonly pollInterval;
+    /**
+     * @param pollInterval 断线检测轮询间隔（毫秒），默认 5000
+     */
+    constructor(pollInterval?: number);
+    /**
+     * 注册一个新的 SSE 连接
+     *
+     * 如果同一 taskId 已存在连接，先关闭旧连接再注册新连接。
+     *
+     * @param taskId - 任务 ID（连接唯一标识）
+     * @param emitter - SSE 事件发射器实例
+     * @param options - 可选的连接配置（如 onDisconnect 回调）
+     */
+    register(taskId: string, emitter: SSEEmitter, options?: SSEConnectionOptions): void;
+    /**
+     * 注销指定 taskId 的连接
+     *
+     * 从注册表中移除（不主动 close emitter，调用方负责生命周期管理）。
+     *
+     * @param taskId - 要注销的任务 ID
+     */
+    unregister(taskId: string): void;
+    /**
+     * 获取指定 taskId 的 SSEEmitter
+     *
+     * @param taskId - 任务 ID
+     * @returns SSEEmitter 实例，不存在时返回 undefined
+     */
+    getEmitter(taskId: string): SSEEmitter | undefined;
+    /**
+     * 获取当前活跃连接数
+     */
+    getActiveConnections(): number;
+    /**
+     * 检查指定 taskId 是否有活跃的 SSE 连接
+     *
+     * @param taskId - 任务 ID
+     * @returns true 表示有活跃连接
+     */
+    isConnected(taskId: string): boolean;
+    /**
+     * 断线重连：用新 emitter 替换旧连接
+     *
+     * 客户端断线后重连时调用。关闭旧 emitter（如果还存活），注册新 emitter。
+     * 配合 Checkpoint 机制，客户端可恢复接收后续事件。
+     *
+     * @param taskId - 任务 ID
+     * @param newEmitter - 新的 SSE 事件发射器实例
+     * @param options - 可选的新连接配置
+     */
+    reconnect(taskId: string, newEmitter: SSEEmitter, options?: SSEConnectionOptions): void;
+    /**
+     * 关闭所有连接（优雅停机）
+     *
+     * 遍历所有注册的连接并关闭，清空注册表，停止轮询。
+     */
+    closeAll(): void;
+    /**
+     * 销毁管理器，释放资源
+     *
+     * 停止轮询定时器。不关闭已注册的连接（调用方负责）。
+     */
+    destroy(): void;
+    /**
+     * 启动断线检测轮询
+     *
+     * 定期检查所有已注册 emitter 的连接状态，
+     * 自动注销已断开的连接并触发 onDisconnect 回调。
+     */
+    private startPolling;
+    /**
+     * 停止断线检测轮询
+     */
+    private stopPolling;
+    /**
+     * 检测并处理断开的连接
+     *
+     * 遍历注册表，对已断开的 emitter 执行：
+     * 1. 触发 onDisconnect 回调
+     * 2. 从注册表中移除
+     */
+    private detectDisconnections;
+}

package/dist/sse/sse-connection-manager.js

@@ -0,0 +1,185 @@
+/**
+ * SSEConnectionManager — SSE 多连接管理器
+ *
+ * 管理多个并发 SSE 连接，按 taskId 注册/查找/注销。
+ * 支持客户端断线检测（自动注销）和断线重连（替换 emitter）。
+ *
+ * @see design.md §1.1 连接管理：SSE心跳、断线重连支持
+ * @see requirements.md Requirement 9 AC3: 断线重连+Checkpoint恢复
+ * @see requirements.md Requirement 5 AC5: heartbeat保持连接
+ */
+// ─────────────────────────────────────────────
+// SSEConnectionManager
+// ─────────────────────────────────────────────
+/**
+ * SSEConnectionManager — 多 SSE 连接注册表
+ *
+ * 用法：
+ * ```ts
+ * const manager = new SSEConnectionManager();
+ * manager.register(taskId, emitter, { onDisconnect: (id) => console.log(`${id} disconnected`) });
+ * manager.getEmitter(taskId)?.emit(event);
+ * manager.closeAll(); // graceful shutdown
+ * ```
+ */
+export class SSEConnectionManager {
+    connections = new Map();
+    pollingTimer = null;
+    pollInterval;
+    /**
+     * @param pollInterval 断线检测轮询间隔（毫秒），默认 5000
+     */
+    constructor(pollInterval = 5000) {
+        this.pollInterval = pollInterval;
+        this.startPolling();
+    }
+    // ─────────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────────
+    /**
+     * 注册一个新的 SSE 连接
+     *
+     * 如果同一 taskId 已存在连接，先关闭旧连接再注册新连接。
+     *
+     * @param taskId - 任务 ID（连接唯一标识）
+     * @param emitter - SSE 事件发射器实例
+     * @param options - 可选的连接配置（如 onDisconnect 回调）
+     */
+    register(taskId, emitter, options = {}) {
+        // 如果已有连接，先清理旧连接
+        const existing = this.connections.get(taskId);
+        if (existing) {
+            existing.emitter.close();
+        }
+        this.connections.set(taskId, { emitter, options });
+    }
+    /**
+     * 注销指定 taskId 的连接
+     *
+     * 从注册表中移除（不主动 close emitter，调用方负责生命周期管理）。
+     *
+     * @param taskId - 要注销的任务 ID
+     */
+    unregister(taskId) {
+        this.connections.delete(taskId);
+    }
+    /**
+     * 获取指定 taskId 的 SSEEmitter
+     *
+     * @param taskId - 任务 ID
+     * @returns SSEEmitter 实例，不存在时返回 undefined
+     */
+    getEmitter(taskId) {
+        return this.connections.get(taskId)?.emitter;
+    }
+    /**
+     * 获取当前活跃连接数
+     */
+    getActiveConnections() {
+        return this.connections.size;
+    }
+    /**
+     * 检查指定 taskId 是否有活跃的 SSE 连接
+     *
+     * @param taskId - 任务 ID
+     * @returns true 表示有活跃连接
+     */
+    isConnected(taskId) {
+        const entry = this.connections.get(taskId);
+        if (!entry) {
+            return false;
+        }
+        return entry.emitter.isConnected;
+    }
+    /**
+     * 断线重连：用新 emitter 替换旧连接
+     *
+     * 客户端断线后重连时调用。关闭旧 emitter（如果还存活），注册新 emitter。
+     * 配合 Checkpoint 机制，客户端可恢复接收后续事件。
+     *
+     * @param taskId - 任务 ID
+     * @param newEmitter - 新的 SSE 事件发射器实例
+     * @param options - 可选的新连接配置
+     */
+    reconnect(taskId, newEmitter, options) {
+        const existing = this.connections.get(taskId);
+        const mergedOptions = options ?? existing?.options ?? {};
+        // 关闭旧连接（如果还未断开）
+        if (existing && existing.emitter.isConnected) {
+            existing.emitter.close();
+        }
+        this.connections.set(taskId, { emitter: newEmitter, options: mergedOptions });
+    }
+    /**
+     * 关闭所有连接（优雅停机）
+     *
+     * 遍历所有注册的连接并关闭，清空注册表，停止轮询。
+     */
+    closeAll() {
+        for (const [taskId, entry] of this.connections) {
+            entry.emitter.close();
+            // 触发 onDisconnect 回调
+            entry.options.onDisconnect?.(taskId);
+        }
+        this.connections.clear();
+        this.stopPolling();
+    }
+    /**
+     * 销毁管理器，释放资源
+     *
+     * 停止轮询定时器。不关闭已注册的连接（调用方负责）。
+     */
+    destroy() {
+        this.stopPolling();
+    }
+    // ─────────────────────────────────────────────
+    // Private — 断线检测
+    // ─────────────────────────────────────────────
+    /**
+     * 启动断线检测轮询
+     *
+     * 定期检查所有已注册 emitter 的连接状态，
+     * 自动注销已断开的连接并触发 onDisconnect 回调。
+     */
+    startPolling() {
+        if (this.pollingTimer !== null) {
+            return;
+        }
+        this.pollingTimer = setInterval(() => {
+            this.detectDisconnections();
+        }, this.pollInterval);
+        // 不阻塞进程退出
+        this.pollingTimer.unref();
+    }
+    /**
+     * 停止断线检测轮询
+     */
+    stopPolling() {
+        if (this.pollingTimer !== null) {
+            clearInterval(this.pollingTimer);
+            this.pollingTimer = null;
+        }
+    }
+    /**
+     * 检测并处理断开的连接
+     *
+     * 遍历注册表，对已断开的 emitter 执行：
+     * 1. 触发 onDisconnect 回调
+     * 2. 从注册表中移除
+     */
+    detectDisconnections() {
+        const disconnected = [];
+        for (const [taskId, entry] of this.connections) {
+            if (!entry.emitter.isConnected) {
+                disconnected.push(taskId);
+            }
+        }
+        for (const taskId of disconnected) {
+            const entry = this.connections.get(taskId);
+            if (entry) {
+                entry.options.onDisconnect?.(taskId);
+                this.connections.delete(taskId);
+            }
+        }
+    }
+}

package/dist/sse/sse-emitter.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SSEEmitter — SSE 事件发射器实现
+ *
+ * 将 SSEEvent 格式化为 SSE 协议并推送到客户端 HTTP 响应流。
+ * 管理连接生命周期（connected → emit → close），支持心跳保活。
+ *
+ * @see contracts/sse-emitter.contract.ts ISSEEmitter 接口
+ * @see design.md §1.6 SSE事件协议定义
+ * @see requirements.md Requirement 5 AC1-AC5
+ * @see requirements.md Requirement 9 AC1-AC4
+ */
+import type { Writable } from 'node:stream';
+import type { ServerResponse } from 'node:http';
+import type { ISSEEmitter, SSEEvent, SSEConnectionState } from './contracts/index.js';
+import type { SSEEventBuffer } from './event-buffer.js';
+/**
+ * SSEEmitterOptions — SSE 发射器配置选项
+ */
+export interface SSEEmitterOptions {
+    /** 心跳间隔（毫秒），默认 30000 */
+    heartbeatInterval?: number;
+    /** 是否自动设置 SSE HTTP 响应头，默认 true */
+    setHeaders?: boolean;
+    /** 关联的 correlationId（用于心跳事件） */
+    correlationId?: string;
+    /** 关联的 taskId（用于心跳事件） */
+    taskId?: string;
+}
+/**
+ * SSEEmitter — ISSEEmitter 实现类
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new SSEEmitter(res, { heartbeatInterval: 30000 });
+ * emitter.emit({ type: 'task.started', data: {...}, correlationId, taskId, timestamp });
+ * emitter.heartbeat();
+ * emitter.close();
+ * ```
+ */
+export declare class SSEEmitter implements ISSEEmitter {
+    private readonly stream;
+    private state;
+    private readonly options;
+    private heartbeatScheduler;
+    /** 最后发送的事件 ID */
+    lastEventId: string | null;
+    constructor(stream: Writable | ServerResponse, options?: SSEEmitterOptions);
+    /**
+     * 发射单个 SSE 事件到客户端
+     *
+     * 格式（含 id 行）：
+     * ```
+     * id: {eventId}
+     * event: {type}
+     * data: {"correlationId":"...", "taskId":"...", "timestamp":"...", ...data}
+     * ```
+     */
+    emit(event: SSEEvent, eventId?: string): void;
+    /**
+     * 重连时回放断开期间的事件
+     */
+    replayFrom(lastEventId: string, buffer: SSEEventBuffer): void;
+    /**
+     * 关闭 SSE 连接
+     *
+     * 终止事件流并标记为断开。自动停止心跳定时器。调用后不可再 emit。
+     */
+    close(): void;
+    /**
+     * 发送心跳事件保持连接活跃
+     *
+     * 推送 `connection.heartbeat` 事件，防止代理/LB 因空闲超时断开连接。
+     */
+    heartbeat(): void;
+    /**
+     * 启动自动周期心跳
+     *
+     * 按配置的 heartbeatInterval（默认 30s）定时发送心跳事件。
+     * 重复调用不会创建多个定时器。
+     */
+    startHeartbeat(): void;
+    /**
+     * 停止自动周期心跳
+     *
+     * 清除心跳定时器。close() 时自动调用。
+     */
+    stopHeartbeat(): void;
+    /** 获取当前连接状态 */
+    get connectionState(): SSEConnectionState;
+    /** 是否处于连接状态 */
+    get isConnected(): boolean;
+    /**
+     * 将 SSEEvent 格式化为 SSE 协议字符串（含 id 行）
+     */
+    private formatEvent;
+    /**
+     * 写入底层流，处理写入错误
+     */
+    private write;
+    /**
+     * 设置 SSE 特定的 HTTP 响应头
+     */
+    private setSSEHeaders;
+    /**
+     * 类型守卫：判断是否为 ServerResponse
+     */
+    private isServerResponse;
+}