@gt-fe/eap-runtime 0.0.8

package/dist/sse/sse-emitter.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { SSEHeartbeat } from './sse-heartbeat.js';
+/** SSEEmitterOptions 默认值 */
+const DEFAULT_OPTIONS = {
+    heartbeatInterval: 30000,
+    setHeaders: true,
+};
+// ─────────────────────────────────────────────
+// SSEEmitter 实现
+// ─────────────────────────────────────────────
+/**
+ * SSEEmitter — ISSEEmitter 实现类
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new SSEEmitter(res, { heartbeatInterval: 30000 });
+ * emitter.emit({ type: 'task.started', data: {...}, correlationId, taskId, timestamp });
+ * emitter.heartbeat();
+ * emitter.close();
+ * ```
+ */
+export class SSEEmitter {
+    stream;
+    state = 'connected';
+    options;
+    heartbeatScheduler = null;
+    /** 最后发送的事件 ID */
+    lastEventId = null;
+    constructor(stream, options) {
+        this.stream = stream;
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        };
+        // 设置 SSE HTTP 响应头
+        if (this.options.setHeaders && this.isServerResponse(stream)) {
+            this.setSSEHeaders(stream);
+        }
+        // 监听流关闭/错误事件以更新连接状态
+        this.stream.on('close', () => {
+            this.stopHeartbeat();
+            this.state = 'disconnected';
+        });
+        this.stream.on('error', () => {
+            this.stopHeartbeat();
+            this.state = 'disconnected';
+        });
+    }
+    /**
+     * 发射单个 SSE 事件到客户端
+     *
+     * 格式（含 id 行）：
+     * ```
+     * id: {eventId}
+     * event: {type}
+     * data: {"correlationId":"...", "taskId":"...", "timestamp":"...", ...data}
+     * ```
+     */
+    emit(event, eventId) {
+        if (this.state !== 'connected') {
+            return;
+        }
+        if (eventId) {
+            this.lastEventId = eventId;
+        }
+        const payload = this.formatEvent(event, eventId ?? this.lastEventId);
+        this.write(payload);
+    }
+    /**
+     * 重连时回放断开期间的事件
+     */
+    replayFrom(lastEventId, buffer) {
+        const events = buffer.getEventsSince(lastEventId);
+        for (const event of events) {
+            this.emit(event);
+        }
+    }
+    /**
+     * 关闭 SSE 连接
+     *
+     * 终止事件流并标记为断开。自动停止心跳定时器。调用后不可再 emit。
+     */
+    close() {
+        if (this.state === 'disconnected') {
+            return;
+        }
+        this.stopHeartbeat();
+        this.state = 'disconnected';
+        if (!this.stream.destroyed) {
+            this.stream.end();
+        }
+    }
+    /**
+     * 发送心跳事件保持连接活跃
+     *
+     * 推送 `connection.heartbeat` 事件，防止代理/LB 因空闲超时断开连接。
+     */
+    heartbeat() {
+        if (this.state !== 'connected') {
+            return;
+        }
+        const heartbeatEvent = {
+            type: 'connection.heartbeat',
+            data: { timestamp: new Date().toISOString() },
+            correlationId: this.options.correlationId ?? '',
+            taskId: this.options.taskId ?? '',
+            timestamp: new Date().toISOString(),
+        };
+        this.emit(heartbeatEvent);
+    }
+    /**
+     * 启动自动周期心跳
+     *
+     * 按配置的 heartbeatInterval（默认 30s）定时发送心跳事件。
+     * 重复调用不会创建多个定时器。
+     */
+    startHeartbeat() {
+        if (this.heartbeatScheduler !== null) {
+            return;
+        }
+        this.heartbeatScheduler = new SSEHeartbeat(this, {
+            interval: this.options.heartbeatInterval,
+        });
+        this.heartbeatScheduler.start();
+    }
+    /**
+     * 停止自动周期心跳
+     *
+     * 清除心跳定时器。close() 时自动调用。
+     */
+    stopHeartbeat() {
+        if (this.heartbeatScheduler !== null) {
+            this.heartbeatScheduler.stop();
+            this.heartbeatScheduler = null;
+        }
+    }
+    // ─────────────────────────────────────────────
+    // Public Accessors
+    // ─────────────────────────────────────────────
+    /** 获取当前连接状态 */
+    get connectionState() {
+        return this.state;
+    }
+    /** 是否处于连接状态 */
+    get isConnected() {
+        return this.state === 'connected';
+    }
+    // ─────────────────────────────────────────────
+    // Private Methods
+    // ─────────────────────────────────────────────
+    /**
+     * 将 SSEEvent 格式化为 SSE 协议字符串（含 id 行）
+     */
+    formatEvent(event, eventId) {
+        const dataPayload = {
+            correlationId: event.correlationId,
+            taskId: event.taskId,
+            timestamp: event.timestamp,
+            ...event.data,
+        };
+        const dataLine = JSON.stringify(dataPayload);
+        const idLine = eventId ? `id: ${eventId}\n` : '';
+        return `${idLine}event: ${event.type}\ndata: ${dataLine}\n\n`;
+    }
+    /**
+     * 写入底层流，处理写入错误
+     */
+    write(payload) {
+        try {
+            const canWrite = this.stream.write(payload);
+            if (!canWrite) {
+                // 背压：流缓冲区满，但不断开连接，等待 drain
+                // 对 SSE 场景，通常不需要特别处理背压
+            }
+        }
+        catch {
+            // 写入异常，标记为断开
+            this.state = 'disconnected';
+        }
+    }
+    /**
+     * 设置 SSE 特定的 HTTP 响应头
+     */
+    setSSEHeaders(res) {
+        if (!res.headersSent) {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'X-Accel-Buffering': 'no', // 禁用 Nginx 缓冲
+            });
+        }
+    }
+    /**
+     * 类型守卫：判断是否为 ServerResponse
+     */
+    isServerResponse(stream) {
+        return 'writeHead' in stream && typeof stream.writeHead === 'function';
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * SSEHeartbeat — 自动周期心跳调度器
+ *
+ * 管理 SSE 连接的定时心跳发送，防止代理/负载均衡器因空闲超时断开连接。
+ * 使用 setInterval 定时调用 emitter.heartbeat()，支持可配置间隔。
+ *
+ * @see design.md §1.6 connection.heartbeat 事件
+ * @see requirements.md Requirement 5 AC5
+ */
+import type { ISSEEmitter } from './contracts/index.js';
+/**
+ * SSEHeartbeatOptions — 心跳调度器配置
+ */
+export interface SSEHeartbeatOptions {
+    /** 心跳间隔（毫秒），默认 30000 (30s) */
+    interval?: number;
+}
+/**
+ * SSEHeartbeat — 周期心跳调度器
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new SSEEmitter(res);
+ * const heartbeat = new SSEHeartbeat(emitter, { interval: 30000 });
+ * heartbeat.start();
+ * // ... 业务逻辑 ...
+ * heartbeat.stop(); // 或 emitter.close() 时自动停止
+ * ```
+ */
+export declare class SSEHeartbeat {
+    private readonly emitter;
+    private readonly interval;
+    private timer;
+    constructor(emitter: ISSEEmitter, options?: SSEHeartbeatOptions);
+    /**
+     * 启动周期心跳
+     *
+     * 使用 setInterval 定时调用 emitter.heartbeat()。
+     * timer.unref() 防止心跳定时器阻塞进程退出。
+     * 重复调用 start() 不会创建多个定时器。
+     */
+    start(): void;
+    /**
+     * 停止周期心跳
+     *
+     * 清除 setInterval 定时器，释放资源。
+     * 重复调用 stop() 是安全的（幂等操作）。
+     */
+    stop(): void;
+    /**
+     * 是否正在运行
+     */
+    get isRunning(): boolean;
+    /**
+     * 获取配置的心跳间隔（毫秒）
+     */
+    get heartbeatInterval(): number;
+}

package/dist/sse/sse-heartbeat.js

@@ -0,0 +1,76 @@
+/**
+ * SSEHeartbeat — 自动周期心跳调度器
+ *
+ * 管理 SSE 连接的定时心跳发送，防止代理/负载均衡器因空闲超时断开连接。
+ * 使用 setInterval 定时调用 emitter.heartbeat()，支持可配置间隔。
+ *
+ * @see design.md §1.6 connection.heartbeat 事件
+ * @see requirements.md Requirement 5 AC5
+ */
+/** 默认心跳间隔：30 秒 */
+const DEFAULT_HEARTBEAT_INTERVAL = 30000;
+// ─────────────────────────────────────────────
+// SSEHeartbeat 实现
+// ─────────────────────────────────────────────
+/**
+ * SSEHeartbeat — 周期心跳调度器
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new SSEEmitter(res);
+ * const heartbeat = new SSEHeartbeat(emitter, { interval: 30000 });
+ * heartbeat.start();
+ * // ... 业务逻辑 ...
+ * heartbeat.stop(); // 或 emitter.close() 时自动停止
+ * ```
+ */
+export class SSEHeartbeat {
+    emitter;
+    interval;
+    timer = null;
+    constructor(emitter, options) {
+        this.emitter = emitter;
+        this.interval = options?.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
+    }
+    /**
+     * 启动周期心跳
+     *
+     * 使用 setInterval 定时调用 emitter.heartbeat()。
+     * timer.unref() 防止心跳定时器阻塞进程退出。
+     * 重复调用 start() 不会创建多个定时器。
+     */
+    start() {
+        if (this.timer !== null) {
+            return; // 已在运行，防止重复启动
+        }
+        this.timer = setInterval(() => {
+            this.emitter.heartbeat();
+        }, this.interval);
+        // unref 使定时器不会阻塞 Node.js 进程退出
+        this.timer.unref();
+    }
+    /**
+     * 停止周期心跳
+     *
+     * 清除 setInterval 定时器，释放资源。
+     * 重复调用 stop() 是安全的（幂等操作）。
+     */
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * 是否正在运行
+     */
+    get isRunning() {
+        return this.timer !== null;
+    }
+    /**
+     * 获取配置的心跳间隔（毫秒）
+     */
+    get heartbeatInterval() {
+        return this.interval;
+    }
+}

package/dist/sse/trace-collector.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TraceCollector — SSE 侧 Trace 采集实现
+ *
+ * 类型定义统一使用 contracts/trace-collector；本模块仅提供内存实现与 SSE 桥接。
+ *
+ * @see contracts/trace-collector.ts
+ * @see sse/sse-emitter.ts
+ */
+import type { ExecutionFlowEvent, ExecutionNodeEvent, ITraceCollector, TraceEvent, TraceLinkEvent, TraceLinkNodeEvent, TraceSession } from '../contracts/trace-collector.js';
+/**
+ * InMemoryTraceCollector — 内存 Trace 采集器（测试用）
+ */
+export declare class InMemoryTraceCollector implements ITraceCollector {
+    private readonly sessions;
+    collect(event: TraceEvent): Promise<void>;
+    startSession(sessionId: string, taskId: string): Promise<void>;
+    endSession(sessionId: string, status: 'completed' | 'failed'): Promise<void>;
+    getSession(sessionId: string): Promise<TraceSession | null>;
+    createFlow(_event: ExecutionFlowEvent): Promise<string>;
+    createNode(_event: ExecutionNodeEvent): Promise<string>;
+    completeNode(_nodeId: string, _params: {
+        status: 'completed' | 'failed';
+        output?: unknown;
+        error?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    }): Promise<void>;
+    createLink(_event: TraceLinkEvent): Promise<string>;
+    createLinkNode(_event: TraceLinkNodeEvent): Promise<string>;
+    completeLinkNode(_nodeId: string, _params: {
+        status: 'completed' | 'failed';
+        error?: string;
+    }): Promise<void>;
+    /** 获取所有会话（调试用） */
+    getAllSessions(): TraceSession[];
+}
+/**
+ * SSE 事件转 Trace 事件
+ */
+export declare function sseEventToTraceEvent(sseEvent: {
+    type: string;
+    data: Record<string, unknown>;
+}, correlationId: string, taskId: string, sessionId: string): TraceEvent;
+/**
+ * Trace 采集中间件
+ *
+ * 包装 SSE Emitter，在推送 SSE 事件的同时收集 Trace 事件。
+ */
+export declare class TraceCollectorMiddleware {
+    private readonly collector;
+    constructor(collector: ITraceCollector);
+    wrapEmit(emitFn: (type: string, data: Record<string, unknown>) => void, context: {
+        correlationId: string;
+        taskId: string;
+        sessionId: string;
+    }): (type: string, data: Record<string, unknown>) => void;
+    startSession(sessionId: string, taskId: string): Promise<void>;
+    endSession(sessionId: string, status: 'completed' | 'failed'): Promise<void>;
+}

package/dist/sse/trace-collector.js

@@ -0,0 +1,107 @@
+/**
+ * TraceCollector — SSE 侧 Trace 采集实现
+ *
+ * 类型定义统一使用 contracts/trace-collector；本模块仅提供内存实现与 SSE 桥接。
+ *
+ * @see contracts/trace-collector.ts
+ * @see sse/sse-emitter.ts
+ */
+import { randomUUID } from 'node:crypto';
+// ─────────────────────────────────────────────
+// Trace 采集器实现
+// ─────────────────────────────────────────────
+/**
+ * InMemoryTraceCollector — 内存 Trace 采集器（测试用）
+ */
+export class InMemoryTraceCollector {
+    sessions = new Map();
+    async collect(event) {
+        const session = this.sessions.get(event.sessionId);
+        if (session) {
+            session.events.push(event);
+        }
+    }
+    async startSession(sessionId, taskId) {
+        this.sessions.set(sessionId, {
+            sessionId,
+            taskId,
+            startTime: new Date().toISOString(),
+            events: [],
+            status: 'running',
+        });
+    }
+    async endSession(sessionId, status) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.endTime = new Date().toISOString();
+            session.status = status;
+        }
+    }
+    async getSession(sessionId) {
+        return this.sessions.get(sessionId) ?? null;
+    }
+    async createFlow(_event) {
+        return `flow-${randomUUID()}`;
+    }
+    async createNode(_event) {
+        return `node-${randomUUID()}`;
+    }
+    async completeNode(_nodeId, _params) { }
+    async createLink(_event) {
+        return `link-${randomUUID()}`;
+    }
+    async createLinkNode(_event) {
+        return `link-node-${randomUUID()}`;
+    }
+    async completeLinkNode(_nodeId, _params) { }
+    /** 获取所有会话（调试用） */
+    getAllSessions() {
+        return Array.from(this.sessions.values());
+    }
+}
+// ─────────────────────────────────────────────
+// SSE 事件转 Trace 事件
+// ─────────────────────────────────────────────
+/**
+ * SSE 事件转 Trace 事件
+ */
+export function sseEventToTraceEvent(sseEvent, correlationId, taskId, sessionId) {
+    return {
+        id: `trace-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
+        type: sseEvent.type,
+        correlationId,
+        taskId,
+        sessionId,
+        timestamp: new Date().toISOString(),
+        payload: sseEvent.data,
+    };
+}
+// ─────────────────────────────────────────────
+// Trace 采集中间件
+// ─────────────────────────────────────────────
+/**
+ * Trace 采集中间件
+ *
+ * 包装 SSE Emitter，在推送 SSE 事件的同时收集 Trace 事件。
+ */
+export class TraceCollectorMiddleware {
+    collector;
+    constructor(collector) {
+        this.collector = collector;
+    }
+    wrapEmit(emitFn, context) {
+        return (type, data) => {
+            emitFn(type, data);
+            const traceEvent = sseEventToTraceEvent({ type, data }, context.correlationId, context.taskId, context.sessionId);
+            this.collector.collect(traceEvent).catch((err) => {
+                console.error('[TraceCollectorMiddleware] Failed to collect trace event:', err);
+            });
+        };
+    }
+    async startSession(sessionId, taskId) {
+        await this.collector.startSession(sessionId, taskId);
+    }
+    async endSession(sessionId, status) {
+        await this.collector.endSession(sessionId, status);
+    }
+}

package/dist/task/contracts/index.d.ts

@@ -0,0 +1,2 @@
+export type { ITaskManager, CreateTaskParams, TaskRecord, TaskStatusInfo, TokenUsageRecord, } from './task-manager.contract.js';
+export type { TaskStatus } from '../../common/types.js';

package/dist/task/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/task/contracts/task-manager.contract.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Task Manager Contract — 任务生命周期管理接口
+ *
+ * 定义 Task 的创建、状态流转、查询、Token 消耗记录等核心操作。
+ * 状态流转：pending → running → success/failed/timeout/token_exhausted
+ *
+ * @see design.md §1.3 数据模型 — tasks 表
+ * @see requirements.md Requirement 7 AC1-AC5
+ */
+import type { TaskStatus } from '../../common/types.js';
+/**
+ * CreateTaskParams — 创建 Task 所需参数
+ */
+export interface CreateTaskParams {
+    /**
+     * 上游发号的 Task ID（如 Hosting `task.id`）。
+     * 有则 Runtime 复用；无则自行生成。
+     */
+    id?: string;
+    /** Agent 对外主键（值为 agentCode；字段名保留 agentId 对齐存储列 agent_id） */
+    agentId: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 用户 ID */
+    userId: string;
+    /** 请求关联 ID（用于链路追踪） */
+    correlationId: string;
+    /** 用户输入 */
+    input: unknown;
+    /** 超时时间（毫秒） */
+    timeout: number;
+}
+/**
+ * TaskRecord — Task 完整记录（对应 tasks 表）
+ */
+export interface TaskRecord {
+    /** Task 唯一 ID */
+    id: string;
+    /** Agent 对外主键（值为 agentCode；字段名保留 agentId 对齐存储列 agent_id） */
+    agentId: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 用户 ID */
+    userId: string;
+    /** 请求关联 ID */
+    correlationId: string;
+    /** 用户输入 */
+    input: unknown;
+    /** 执行输出 */
+    output: unknown | null;
+    /** 当前状态 */
+    status: TaskStatus;
+    /** Trace ID（链路追踪） */
+    traceId: string | null;
+    /** Token 消耗汇总 */
+    tokenUsage: TokenUsageRecord[];
+    /** 累计成本 */
+    cost: number;
+    /** 开始执行时间 (ISO 8601) */
+    startedAt: string | null;
+    /** 完成时间 (ISO 8601) */
+    completedAt: string | null;
+    /** 创建人 */
+    createdBy: string;
+    /** 创建时间 (ISO 8601) */
+    createdAt: string;
+    /** 最后更新人 */
+    updatedBy: string;
+    /** 最后更新时间 (ISO 8601) */
+    updatedAt: string;
+    /** 是否删除（软删除标记） */
+    isDeleted: boolean;
+    /** 删除人 */
+    deletedBy?: string | null;
+    /** 删除时间 (ISO 8601) */
+    deletedAt?: string | null;
+}
+/**
+ * TaskStatusInfo — 轮询接口返回的任务状态信息
+ *
+ * 用于 GET /tasks/{taskId}/status，客户端轮询长任务进度。
+ */
+export interface TaskStatusInfo {
+    /** 当前状态 */
+    status: TaskStatus;
+    /** 执行进度（0-100） */
+    progress: number;
+    /** 开始执行时间 (ISO 8601) */
+    startedAt: string | null;
+    /** 已运行时长（毫秒） */
+    duration: number;
+}
+/**
+ * TokenUsageRecord — 单次 Token 消耗记录
+ *
+ * 每次 LLM 调用产生一条，关联到具体节点和模型。
+ */
+export interface TokenUsageRecord {
+    /** 产生消耗的节点 ID */
+    nodeId: string;
+    /** 使用的模型标识 */
+    model: string;
+    /** 输入 Token 数 */
+    inputTokens: number;
+    /** 输出 Token 数 */
+    outputTokens: number;
+    /** 预估成本（美元） */
+    costEstimate: number;
+}
+/**
+ * ITaskManager — 任务管理器接口
+ *
+ * 负责 Task 的创建、状态流转、状态查询和 Token 消耗记录。
+ * 由 TaskService 实现，提供 Task 生命周期的完整管理能力。
+ */
+export interface ITaskManager {
+    /**
+     * 创建新 Task（初始状态为 pending）
+     *
+     * @param params - 创建参数
+     * @returns 创建后的完整 TaskRecord
+     */
+    create(params: CreateTaskParams): Promise<TaskRecord>;
+    /**
+     * 更新 Task 状态
+     *
+     * 合法流转：pending→running, running→success/failed/timeout/token_exhausted
+     *
+     * @param taskId - Task ID
+     * @param status - 目标状态
+     * @param output - 执行输出（success 时设置）
+     */
+    updateStatus(taskId: string, status: TaskStatus, output?: unknown): Promise<void>;
+    /**
+     * 获取 Task 当前状态（供轮询使用）
+     *
+     * @param taskId - Task ID
+     * @returns 状态信息（包含进度百分比和运行时长）
+     */
+    getStatus(taskId: string): Promise<TaskStatusInfo>;
+    /**
+     * 记录一次 Token 消耗
+     *
+     * 每次 LLM 调用后调用此方法，累计 Token 消耗。
+     *
+     * @param taskId - Task ID
+     * @param usage - Token 消耗记录
+     */
+    recordTokenUsage(taskId: string, usage: TokenUsageRecord): Promise<void>;
+    /**
+     * 更新 Task 的执行进度（用于长任务）
+     *
+     * 显式设置进度百分比，供 getStatus() 返回细粒度进度。
+     * 适用于分钟级/小时级长任务，客户端通过轮询获取实时进度。
+     *
+     * @param taskId - Task ID
+     * @param progress - 进度百分比 (0-100)
+     */
+    updateProgress(taskId: string, progress: number): Promise<void>;
+}

package/dist/task/contracts/task-manager.contract.js

@@ -0,0 +1,10 @@
+/**
+ * Task Manager Contract — 任务生命周期管理接口
+ *
+ * 定义 Task 的创建、状态流转、查询、Token 消耗记录等核心操作。
+ * 状态流转：pending → running → success/failed/timeout/token_exhausted
+ *
+ * @see design.md §1.3 数据模型 — tasks 表
+ * @see requirements.md Requirement 7 AC1-AC5
+ */
+export {};

package/dist/task/index.d.ts

@@ -0,0 +1,7 @@
+export * from './contracts/index.js';
+export { TaskService, InMemoryTaskRepository } from './task.service.js';
+export type { ITaskRepository } from './task.service.js';
+export { TaskTimeoutManager } from './task-timeout.js';
+export type { TaskTimeoutManagerOptions } from './task-timeout.js';
+export { TaskProgressTracker } from './task-progress-tracker.js';
+export type { TaskProgressInfo } from './task-progress-tracker.js';