@gt-fe/eap-runtime 0.0.8

package/dist/session/session-context.service.d.ts

@@ -0,0 +1,49 @@
+/**
+ * SessionContextService — 会话上下文解析服务
+ *
+ * Agent Invoke API 调用入口的编排逻辑：
+ * - sessionId 已存在且 Runtime 有壳 → 加载 Session + 历史消息
+ * - sessionId 由上游分配但 Runtime 无壳 → 采纳该 ID 建壳，并仍按 sessionId 加载 Message
+ * - sessionId 为空 → 创建新 Session，返回空历史
+ *
+ * @see requirements.md Requirement 11 AC9, AC10
+ */
+import type { SessionRecord, MessageRecord } from './session.service.js';
+import { SessionService } from './session.service.js';
+import { MessageService } from './message.service.js';
+/**
+ * 解析会话上下文的输入参数
+ */
+export interface ResolveSessionParams {
+    /** 会话 ID（可选，不传则创建新会话） */
+    sessionId?: string;
+    /** 用户 ID */
+    userId: string;
+    /** Agent ID */
+    agentId: string;
+    /** 预装版本，写入 session.metadata.agentVersion（续聊回退） */
+    agentVersion?: string;
+}
+/**
+ * 解析后的会话上下文
+ */
+export interface SessionContext {
+    /** Session 记录 */
+    session: SessionRecord;
+    /** 历史消息列表（新会话为空数组） */
+    messages: MessageRecord[];
+    /** 是否为新创建的会话 */
+    isNew: boolean;
+}
+export declare class SessionContextService {
+    private readonly sessionService;
+    private readonly messageService;
+    constructor(sessionService: SessionService, messageService: MessageService);
+    /**
+     * 解析会话上下文
+     *
+     * - sessionId 存在：加载 Session 及其历史消息
+     * - sessionId 为空：创建新 Session，返回空消息列表
+     */
+    resolveSessionContext(params: ResolveSessionParams): Promise<SessionContext>;
+}

package/dist/session/session-context.service.js

@@ -0,0 +1,66 @@
+/**
+ * SessionContextService — 会话上下文解析服务
+ *
+ * Agent Invoke API 调用入口的编排逻辑：
+ * - sessionId 已存在且 Runtime 有壳 → 加载 Session + 历史消息
+ * - sessionId 由上游分配但 Runtime 无壳 → 采纳该 ID 建壳，并仍按 sessionId 加载 Message
+ * - sessionId 为空 → 创建新 Session，返回空历史
+ *
+ * @see requirements.md Requirement 11 AC9, AC10
+ */
+// ─────────────────────────────────────────────
+// SessionContextService Implementation
+// ─────────────────────────────────────────────
+export class SessionContextService {
+    sessionService;
+    messageService;
+    constructor(sessionService, messageService) {
+        this.sessionService = sessionService;
+        this.messageService = messageService;
+    }
+    /**
+     * 解析会话上下文
+     *
+     * - sessionId 存在：加载 Session 及其历史消息
+     * - sessionId 为空：创建新 Session，返回空消息列表
+     */
+    async resolveSessionContext(params) {
+        if (params.sessionId) {
+            const existing = await this.sessionService.findSession(params.sessionId);
+            if (existing) {
+                const messages = await this.messageService.getMessages(params.sessionId);
+                return {
+                    session: existing,
+                    messages,
+                    isNew: false,
+                };
+            }
+            // Hosting 等上游已分配 sessionId，Runtime 侧尚未落库时采纳该 ID。
+            // Message 权威可能已在 File/PG：必须加载，禁止因壳缺失而清空历史。
+            const session = await this.sessionService.createSession({
+                id: params.sessionId,
+                userId: params.userId,
+                agentId: params.agentId,
+                metadata: params.agentVersion ? { agentVersion: params.agentVersion } : undefined,
+            });
+            const messages = await this.messageService.getMessages(params.sessionId);
+            return {
+                session,
+                messages,
+                // 有历史则不当作新会话（避免重启后误发 session.created）
+                isNew: messages.length === 0,
+            };
+        }
+        // 创建新 Session
+        const session = await this.sessionService.createSession({
+            userId: params.userId,
+            agentId: params.agentId,
+            metadata: params.agentVersion ? { agentVersion: params.agentVersion } : undefined,
+        });
+        return {
+            session,
+            messages: [],
+            isNew: true,
+        };
+    }
+}

package/dist/session/session.service.d.ts

@@ -0,0 +1,194 @@
+/**
+ * SessionService — 会话管理服务
+ *
+ * 管理 Session 生命周期：创建、查询、归档、加载历史消息。
+ * v1 使用 InMemorySessionRepository 存储，生产由 PostgresSessionRepository 替换。
+ *
+ * @see requirements.md Requirement 10 AC1-AC4
+ */
+import type { ExecutionSessionBindingStatus } from '../common/types.js';
+/**
+ * Session 记录（对应 sessions 表）
+ */
+export interface SessionRecord {
+    /** 会话唯一 ID */
+    id: string;
+    /** 所属用户 ID */
+    userId: string;
+    /** 关联 Agent（值为 agentCode；字段名保留 agentId 对齐存储列 agent_id） */
+    agentId: string;
+    /** 会话标题（可选） */
+    title: string | null;
+    /** 会话状态：active | archived */
+    status: ExecutionSessionBindingStatus;
+    /** 扩展元数据 */
+    metadata: Record<string, unknown>;
+    /** 创建人 */
+    createdBy: string;
+    /** 创建时间 (ISO 8601) */
+    createdAt: string;
+    /** 最后更新人 */
+    updatedBy: string;
+    /** 最后更新时间 (ISO 8601) */
+    updatedAt: string;
+    /** 是否删除（软删除标记） */
+    isDeleted: boolean;
+    /** 删除人 */
+    deletedBy?: string | null;
+    /** 删除时间 (ISO 8601) */
+    deletedAt?: string | null;
+}
+/**
+ * 创建 Session 参数
+ */
+export interface CreateSessionParams {
+    /** 会话 ID（可选；Hosting 下发时用于采纳外部 ID） */
+    id?: string;
+    /** 用户 ID */
+    userId: string;
+    /** Agent（值为 agentCode；字段名保留 agentId 对齐存储列 agent_id） */
+    agentId: string;
+    /** 会话标题（可选） */
+    title?: string;
+    /** 扩展元数据（可选） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 加载历史消息的分页选项
+ */
+export interface LoadHistoryOptions {
+    /** 返回条数上限 */
+    limit?: number;
+    /** 偏移量 */
+    offset?: number;
+}
+/**
+ * 消息记录（对应 messages 表）
+ *
+ * 完整实现在 message.service.ts (Task 4.3)；
+ * 此处仅定义接口类型供 loadHistory 返回值使用。
+ */
+export interface MessageRecord {
+    id: string;
+    sessionId: string;
+    taskId: string | null;
+    correlationId: string | null;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    toolCalls: unknown[] | null;
+    tokenCount: number;
+    /** 可选：模型 reasoning / 思考过程 */
+    reasoning?: unknown | null;
+    /** 可选：生成或工具耗时（毫秒） */
+    durationMs?: number | null;
+    /** 元数据（扩展字段） */
+    metadata?: Record<string, unknown>;
+    createdBy: string;
+    createdAt: string;
+    updatedBy: string;
+    updatedAt: string;
+    isDeleted: boolean;
+    deletedBy?: string | null;
+    deletedAt?: string | null;
+}
+/**
+ * ISessionRepository — Session 持久化接口
+ *
+ * SessionService 通过此接口访问存储层，默认使用 InMemorySessionRepository。
+ * Task 4.2 将提供 MySQL 实现。
+ */
+export interface ISessionRepository {
+    save(session: SessionRecord): Promise<void>;
+    findById(id: string): Promise<SessionRecord | null>;
+    findByUserId(userId: string, limit?: number, offset?: number): Promise<SessionRecord[]>;
+    update(session: SessionRecord): Promise<void>;
+}
+/**
+ * IMessageRepository — Message 查询接口（最小定义）
+ *
+ * SessionService.loadHistory 委托此接口查询消息。
+ * 完整实现由 Task 4.3/4.4 提供。
+ */
+export interface IMessageRepository {
+    findBySessionId(sessionId: string, limit?: number, offset?: number): Promise<MessageRecord[]>;
+    /**
+     * 保存单条消息
+     *
+     * @param message - 消息记录
+     */
+    save(message: MessageRecord): Promise<void>;
+    /**
+     * 批量保存消息
+     *
+     * @param messages - 消息记录列表
+     */
+    saveMany(messages: MessageRecord[]): Promise<void>;
+    /**
+     * 标记消息为已压缩
+     *
+     * @param messageIds - 消息 ID 列表
+     * @param compressedBy - 操作人
+     * @param compressedAt - 压缩时间
+     */
+    markAsCompressed(messageIds: string[], compressedBy: string, compressedAt: string): Promise<void>;
+}
+/**
+ * InMemorySessionRepository — 内存存储实现
+ *
+ * 用于开发/测试阶段，后续替换为 MySQL 实现。
+ */
+export declare class InMemorySessionRepository implements ISessionRepository {
+    private readonly store;
+    save(session: SessionRecord): Promise<void>;
+    findById(id: string): Promise<SessionRecord | null>;
+    findByUserId(userId: string, limit?: number, offset?: number): Promise<SessionRecord[]>;
+    update(session: SessionRecord): Promise<void>;
+}
+/**
+ * InMemoryMessageRepository — 内存 Message 存储（stub）
+ *
+ * 供 SessionService 开发/测试使用，Task 4.3/4.4 将提供完整实现。
+ */
+export declare class InMemoryMessageRepository implements IMessageRepository {
+    private readonly store;
+    findBySessionId(sessionId: string, limit?: number, offset?: number): Promise<MessageRecord[]>;
+    save(message: MessageRecord): Promise<void>;
+    saveMany(messages: MessageRecord[]): Promise<void>;
+    markAsCompressed(messageIds: string[], compressedBy: string, compressedAt: string): Promise<void>;
+    /** 辅助方法：添加消息（测试用） */
+    addMessage(message: MessageRecord): Promise<void>;
+}
+export declare class SessionService {
+    private readonly sessionRepository;
+    private readonly messageRepository;
+    constructor(sessionRepository?: ISessionRepository, messageRepository?: IMessageRepository);
+    /**
+     * 创建新 Session，初始状态为 active
+     */
+    createSession(params: CreateSessionParams): Promise<SessionRecord>;
+    /**
+     * 按 ID 查找 Session（不存在返回 null）
+     */
+    findSession(sessionId: string): Promise<SessionRecord | null>;
+    /**
+     * 按 ID 获取 Session（不存在则抛错）
+     */
+    getSession(sessionId: string): Promise<SessionRecord>;
+    /**
+     * 列出用户的 Session
+     */
+    listSessions(userId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SessionRecord[]>;
+    /**
+     * 归档 Session（标记为 archived）
+     */
+    archiveSession(sessionId: string): Promise<void>;
+    /**
+     * 加载 Session 的消息历史（分页）
+     *
+     * 委托 IMessageRepository 查询，返回按时间排序的消息列表。
+     */
+    loadHistory(sessionId: string, options?: LoadHistoryOptions): Promise<MessageRecord[]>;
+}

package/dist/session/session.service.js

@@ -0,0 +1,166 @@
+/**
+ * SessionService — 会话管理服务
+ *
+ * 管理 Session 生命周期：创建、查询、归档、加载历史消息。
+ * v1 使用 InMemorySessionRepository 存储，生产由 PostgresSessionRepository 替换。
+ *
+ * @see requirements.md Requirement 10 AC1-AC4
+ */
+import { randomUUID } from 'node:crypto';
+// ─────────────────────────────────────────────
+// In-Memory Repository (Default)
+// ─────────────────────────────────────────────
+/**
+ * InMemorySessionRepository — 内存存储实现
+ *
+ * 用于开发/测试阶段，后续替换为 MySQL 实现。
+ */
+export class InMemorySessionRepository {
+    store = new Map();
+    async save(session) {
+        this.store.set(session.id, { ...session });
+    }
+    async findById(id) {
+        const record = this.store.get(id);
+        return record ? { ...record } : null;
+    }
+    async findByUserId(userId, limit, offset) {
+        const filtered = Array.from(this.store.values())
+            .filter((s) => s.userId === userId && !s.isDeleted)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        const start = offset ?? 0;
+        const end = limit !== undefined ? start + limit : undefined;
+        return filtered.slice(start, end);
+    }
+    async update(session) {
+        this.store.set(session.id, { ...session });
+    }
+}
+/**
+ * InMemoryMessageRepository — 内存 Message 存储（stub）
+ *
+ * 供 SessionService 开发/测试使用，Task 4.3/4.4 将提供完整实现。
+ */
+export class InMemoryMessageRepository {
+    store = [];
+    async findBySessionId(sessionId, limit, offset) {
+        const filtered = this.store.filter((m) => m.sessionId === sessionId);
+        const start = offset ?? 0;
+        const end = limit !== undefined ? start + limit : undefined;
+        return filtered.slice(start, end);
+    }
+    async save(message) {
+        // 检查是否已存在，存在则更新，不存在则添加
+        const existingIndex = this.store.findIndex((m) => m.id === message.id);
+        if (existingIndex >= 0) {
+            this.store[existingIndex] = { ...message };
+        }
+        else {
+            this.store.push({ ...message });
+        }
+    }
+    async saveMany(messages) {
+        for (const message of messages) {
+            await this.save(message);
+        }
+    }
+    async markAsCompressed(messageIds, compressedBy, compressedAt) {
+        for (const id of messageIds) {
+            const message = this.store.find((m) => m.id === id);
+            if (message) {
+                // 在 metadata 中添加压缩标记
+                if (!message.metadata) {
+                    message.metadata = {};
+                }
+                message.metadata.compressed = true;
+                message.metadata.compressedBy = compressedBy;
+                message.metadata.compressedAt = compressedAt;
+                message.updatedBy = compressedBy;
+                message.updatedAt = compressedAt;
+            }
+        }
+    }
+    /** 辅助方法：添加消息（测试用） */
+    async addMessage(message) {
+        this.store.push({ ...message });
+    }
+}
+// ─────────────────────────────────────────────
+// SessionService Implementation
+// ─────────────────────────────────────────────
+export class SessionService {
+    sessionRepository;
+    messageRepository;
+    constructor(sessionRepository, messageRepository) {
+        this.sessionRepository = sessionRepository ?? new InMemorySessionRepository();
+        this.messageRepository = messageRepository ?? new InMemoryMessageRepository();
+    }
+    /**
+     * 创建新 Session，初始状态为 active
+     */
+    async createSession(params) {
+        const now = new Date().toISOString();
+        const session = {
+            id: params.id ?? randomUUID(),
+            userId: params.userId,
+            agentId: params.agentId,
+            title: params.title ?? null,
+            status: 'active',
+            metadata: params.metadata ?? {},
+            createdBy: params.userId,
+            createdAt: now,
+            updatedBy: params.userId,
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.sessionRepository.save(session);
+        return session;
+    }
+    /**
+     * 按 ID 查找 Session（不存在返回 null）
+     */
+    async findSession(sessionId) {
+        return this.sessionRepository.findById(sessionId);
+    }
+    /**
+     * 按 ID 获取 Session（不存在则抛错）
+     */
+    async getSession(sessionId) {
+        const session = await this.sessionRepository.findById(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: '${sessionId}'`);
+        }
+        return session;
+    }
+    /**
+     * 列出用户的 Session
+     */
+    async listSessions(userId, options) {
+        return this.sessionRepository.findByUserId(userId, options?.limit, options?.offset);
+    }
+    /**
+     * 归档 Session（标记为 archived）
+     */
+    async archiveSession(sessionId) {
+        const session = await this.sessionRepository.findById(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: '${sessionId}'`);
+        }
+        if (session.status === 'archived') {
+            return; // 幂等：已归档则无操作
+        }
+        session.status = 'archived';
+        session.updatedAt = new Date().toISOString();
+        await this.sessionRepository.update(session);
+    }
+    /**
+     * 加载 Session 的消息历史（分页）
+     *
+     * 委托 IMessageRepository 查询，返回按时间排序的消息列表。
+     */
+    async loadHistory(sessionId, options) {
+        // 先验证 Session 存在
+        await this.getSession(sessionId);
+        return this.messageRepository.findBySessionId(sessionId, options?.limit, options?.offset);
+    }
+}

package/dist/sse/connection-event-logger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SSE 连接异常状态记录 — A3
+ */
+import type { ILogger } from '../common/logger.js';
+export type DisconnectReason = 'network_error' | 'client_close' | 'server_timeout' | 'unknown';
+export interface ConnectionEvent {
+    taskId: string;
+    sessionId: string;
+    reason: DisconnectReason;
+    timestamp: string;
+    lastEventId?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class ConnectionEventLogger {
+    private readonly logger;
+    private readonly history;
+    constructor(logger: ILogger);
+    logDisconnect(event: ConnectionEvent): void;
+    logReconnect(taskId: string, sessionId: string, lastEventId?: string): void;
+    getHistory(taskId: string): ConnectionEvent[];
+}

package/dist/sse/connection-event-logger.js

@@ -0,0 +1,33 @@
+/**
+ * SSE 连接异常状态记录 — A3
+ */
+export class ConnectionEventLogger {
+    logger;
+    history = new Map();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    logDisconnect(event) {
+        this.logger.warn('SSE disconnected', { taskId: event.taskId, reason: event.reason, sessionId: event.sessionId });
+        const list = this.history.get(event.taskId) ?? [];
+        list.push(event);
+        this.history.set(event.taskId, list);
+    }
+    logReconnect(taskId, sessionId, lastEventId) {
+        this.logger.info('SSE reconnected', { taskId, sessionId, lastEventId });
+        const event = {
+            taskId,
+            sessionId,
+            reason: 'unknown', // reconnect 不是 disconnect，reason 不适用
+            timestamp: new Date().toISOString(),
+            lastEventId,
+            metadata: { type: 'reconnect' },
+        };
+        const list = this.history.get(taskId) ?? [];
+        list.push(event);
+        this.history.set(taskId, list);
+    }
+    getHistory(taskId) {
+        return this.history.get(taskId) ?? [];
+    }
+}

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

@@ -0,0 +1 @@
+export * from './sse-emitter.contract.js';

package/dist/sse/contracts/index.js

@@ -0,0 +1 @@
+export * from './sse-emitter.contract.js';

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

@@ -0,0 +1,74 @@
+/**
+ * SSE Emitter Contract — 服务端推送事件发射器接口
+ *
+ * 定义 SSE 连接生命周期管理和事件发射能力。
+ * 将 RuntimeEvent 包装为 SSE 协议格式推送给客户端。
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ * @see requirements.md Requirement 5 AC1-AC5
+ * @see requirements.md Requirement 9 AC1-AC4
+ */
+/**
+ * SSEEvent — 面向 SSE 协议的事件封装
+ *
+ * 将 RuntimeEvent 包装为 SSE 传输格式：
+ * ```
+ * event: {type}
+ * data: {"correlationId":"xxx", "taskId":"xxx", "timestamp":"xxx", ...payload}
+ * ```
+ */
+export interface SSEEvent {
+    /** 事件类型名称（如 response.chunk, tool.called 等） */
+    type: string;
+    /** JSON 序列化后的事件数据负载 */
+    data: Record<string, unknown>;
+    /** 请求关联 ID */
+    correlationId: string;
+    /** 关联的 Task ID */
+    taskId: string;
+    /** 事件时间戳 (ISO 8601) */
+    timestamp: string;
+}
+/**
+ * SSEConnectionState — SSE 连接生命周期状态
+ */
+export type SSEConnectionState = 'connected' | 'disconnected' | 'reconnecting';
+/**
+ * ISSEEmitter — SSE 事件发射器接口
+ *
+ * 负责将 Graph 执行产生的 RuntimeEvent 转换为 SSE 格式推送给客户端。
+ * 管理连接生命周期，支持心跳保活。
+ *
+ * 使用方式：
+ * 1. 创建 Emitter 实例绑定到 HTTP Response
+ * 2. Graph.stream() 每产出一个 RuntimeEvent → 调用 emit() 推送
+ * 3. 定时调用 heartbeat() 保活连接（默认 30s 间隔）
+ * 4. Task 完成或异常时调用 close() 关闭连接
+ */
+export interface ISSEEmitter {
+    /**
+     * 发射单个 SSE 事件到客户端
+     *
+     * 将 SSEEvent 序列化为 SSE 协议格式：
+     * ```
+     * event: {event.type}
+     * data: {"correlationId":"...", "taskId":"...", "timestamp":"...", ...data}
+     * ```
+     *
+     * @param event - 要发送的 SSE 事件
+     */
+    emit(event: SSEEvent): void;
+    /**
+     * 关闭 SSE 连接
+     *
+     * 终止事件流，释放底层资源。调用后不可再 emit。
+     */
+    close(): void;
+    /**
+     * 发送心跳事件保持连接活跃
+     *
+     * 推送 `connection.heartbeat` 事件，防止代理/LB 因空闲超时断开连接。
+     * 默认心跳间隔 30s，可通过配置调整。
+     */
+    heartbeat(): void;
+}

package/dist/sse/contracts/sse-emitter.contract.js

@@ -0,0 +1,11 @@
+/**
+ * SSE Emitter Contract — 服务端推送事件发射器接口
+ *
+ * 定义 SSE 连接生命周期管理和事件发射能力。
+ * 将 RuntimeEvent 包装为 SSE 协议格式推送给客户端。
+ *
+ * @see design.md §1.6 SSE事件协议定义
+ * @see requirements.md Requirement 5 AC1-AC5
+ * @see requirements.md Requirement 9 AC1-AC4
+ */
+export {};

package/dist/sse/event-buffer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SSEEventBuffer — 环形缓冲区，支持断线重连事件回放
+ */
+import type { SSEEvent } from './contracts/index.js';
+export declare class SSEEventBuffer {
+    private readonly maxSize;
+    private readonly buffer;
+    private head;
+    private count;
+    private seq;
+    constructor(maxSize?: number);
+    /** 缓存事件，eventId 由外部传入 */
+    push(event: SSEEvent, eventId: string): void;
+    /** 获取 lastEventId 之后的所有事件 */
+    getEventsSince(lastEventId: string): SSEEvent[];
+    /** 生成自增事件 ID */
+    generateId(): string;
+    /** 按时间顺序返回所有有效 entries */
+    private entries;
+}

package/dist/sse/event-buffer.js

@@ -0,0 +1,45 @@
+/**
+ * SSEEventBuffer — 环形缓冲区，支持断线重连事件回放
+ */
+export class SSEEventBuffer {
+    maxSize;
+    buffer;
+    head = 0;
+    count = 0;
+    seq = 0;
+    constructor(maxSize = 100) {
+        this.maxSize = maxSize;
+        this.buffer = new Array(maxSize);
+    }
+    /** 缓存事件，eventId 由外部传入 */
+    push(event, eventId) {
+        this.buffer[this.head] = { event, eventId };
+        this.head = (this.head + 1) % this.maxSize;
+        if (this.count < this.maxSize)
+            this.count++;
+    }
+    /** 获取 lastEventId 之后的所有事件 */
+    getEventsSince(lastEventId) {
+        const entries = this.entries();
+        const idx = entries.findIndex(e => e.eventId === lastEventId);
+        if (idx === -1)
+            return entries.map(e => e.event); // 找不到，返回全部缓冲
+        return entries.slice(idx + 1).map(e => e.event);
+    }
+    /** 生成自增事件 ID */
+    generateId() {
+        return `evt-${++this.seq}`;
+    }
+    /** 按时间顺序返回所有有效 entries */
+    entries() {
+        const result = [];
+        const start = this.count < this.maxSize ? 0 : this.head;
+        for (let i = 0; i < this.count; i++) {
+            const idx = (start + i) % this.maxSize;
+            const entry = this.buffer[idx];
+            if (entry)
+                result.push(entry);
+        }
+        return result;
+    }
+}