@gt-fe/eap-runtime 0.0.8

package/dist/session/file-session.repository.js

@@ -0,0 +1,212 @@
+/**
+ * FileSessionRepository — Session 持久化文件存储实现
+ *
+ * 基于本地 JSON 文件实现 ISessionRepository 接口。
+ * 适用于生产环境中的会话信息存储，支持审计字段和软删除。
+ *
+ * 文件结构：
+ * - 每个 Session 存储为独立的 JSON 文件
+ * - 文件路径：{baseDir}/{sessionId}.json
+ * - 支持索引文件用于快速查询
+ *
+ * @see design.md §1.3 数据模型 — sessions 表
+ * @see session.service.ts ISessionRepository 接口定义
+ */
+import { join } from 'node:path';
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+// ─────────────────────────────────────────────
+// FileSessionRepository
+// ─────────────────────────────────────────────
+export class FileSessionRepository {
+    baseDir;
+    enableIndex;
+    fileExtension;
+    indexFile;
+    constructor(options) {
+        this.baseDir = options.baseDir;
+        this.enableIndex = options.enableIndex ?? true;
+        this.fileExtension = options.fileExtension ?? '.json';
+        this.indexFile = join(this.baseDir, '_index.json');
+    }
+    /**
+     * 保存 Session 到 JSON 文件
+     */
+    async save(session) {
+        const filePath = this.getFilePath(session.id);
+        const content = JSON.stringify(session, null, 2);
+        // 确保目录存在
+        await this.ensureDir(this.baseDir);
+        // 写入文件
+        await writeFile(filePath, content, 'utf-8');
+        // 更新索引
+        if (this.enableIndex) {
+            await this.updateIndex(session);
+        }
+    }
+    /**
+     * 从 JSON 文件加载 Session
+     * Excludes soft-deleted records
+     */
+    async findById(id) {
+        const filePath = this.getFilePath(id);
+        try {
+            // 检查文件是否存在
+            await access(filePath);
+            // 读取文件
+            const content = await readFile(filePath, 'utf-8');
+            const session = JSON.parse(content);
+            // 检查是否已软删除
+            if (session.isDeleted) {
+                return null;
+            }
+            return session;
+        }
+        catch (error) {
+            // 文件不存在或解析错误
+            return null;
+        }
+    }
+    /**
+     * 更新 Session 文件
+     */
+    async update(session) {
+        const filePath = this.getFilePath(session.id);
+        // 检查文件是否存在
+        try {
+            await access(filePath);
+        }
+        catch {
+            throw new Error(`Session file not found: ${session.id}`);
+        }
+        // 更新文件
+        const content = JSON.stringify(session, null, 2);
+        await writeFile(filePath, content, 'utf-8');
+        // 更新索引
+        if (this.enableIndex) {
+            await this.updateIndex(session);
+        }
+    }
+    /**
+     * 软删除 Session
+     */
+    async softDelete(id, deletedBy) {
+        const session = await this.findById(id);
+        if (!session) {
+            throw new Error(`Session not found: ${id}`);
+        }
+        session.isDeleted = true;
+        session.deletedBy = deletedBy;
+        session.deletedAt = new Date().toISOString();
+        session.updatedBy = deletedBy;
+        session.updatedAt = new Date().toISOString();
+        await this.update(session);
+    }
+    /**
+     * 列出所有 Session（从索引文件）
+     * Excludes soft-deleted records
+     */
+    async listAll() {
+        if (!this.enableIndex) {
+            throw new Error('Index is disabled. Use findById for individual queries.');
+        }
+        try {
+            // 检查索引文件是否存在
+            await access(this.indexFile);
+            // 读取索引文件
+            const content = await readFile(this.indexFile, 'utf-8');
+            const index = JSON.parse(content);
+            // 加载完整的 Session 记录
+            const sessions = [];
+            for (const entry of index) {
+                const session = await this.findById(entry.id);
+                if (session) {
+                    sessions.push(session);
+                }
+            }
+            return sessions;
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    /**
+     * 按 userId 查询 Session
+     * Excludes soft-deleted records
+     */
+    async findByUserId(userId) {
+        if (!this.enableIndex) {
+            throw new Error('Index is disabled. Use findById for individual queries.');
+        }
+        try {
+            // 检查索引文件是否存在
+            await access(this.indexFile);
+            // 读取索引文件
+            const content = await readFile(this.indexFile, 'utf-8');
+            const index = JSON.parse(content);
+            // 过滤指定用户的 Session
+            const userEntries = index.filter(entry => entry.userId === userId);
+            // 加载完整的 Session 记录
+            const sessions = [];
+            for (const entry of userEntries) {
+                const session = await this.findById(entry.id);
+                if (session) {
+                    sessions.push(session);
+                }
+            }
+            return sessions;
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 获取 Session 文件路径
+     */
+    getFilePath(sessionId) {
+        return join(this.baseDir, `${sessionId}${this.fileExtension}`);
+    }
+    /**
+     * 确保目录存在
+     */
+    async ensureDir(dir) {
+        await mkdir(dir, { recursive: true });
+    }
+    /**
+     * 更新索引文件
+     */
+    async updateIndex(session) {
+        let index = [];
+        try {
+            // 检查索引文件是否存在
+            await access(this.indexFile);
+            // 读取索引文件
+            const content = await readFile(this.indexFile, 'utf-8');
+            index = JSON.parse(content);
+        }
+        catch (error) {
+            // 索引文件不存在或解析错误，使用空数组
+        }
+        // 查找并更新或添加条目
+        const existingIndex = index.findIndex(entry => entry.id === session.id);
+        const entry = {
+            id: session.id,
+            userId: session.userId,
+            agentId: session.agentId,
+            status: session.status,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+        };
+        if (existingIndex >= 0) {
+            index[existingIndex] = entry;
+        }
+        else {
+            index.push(entry);
+        }
+        // 写入索引文件
+        const content = JSON.stringify(index, null, 2);
+        await writeFile(this.indexFile, content, 'utf-8');
+    }
+}

package/dist/session/index.d.ts

@@ -0,0 +1,13 @@
+export { SessionService, InMemorySessionRepository, InMemoryMessageRepository, } from './session.service.js';
+export type { SessionRecord, CreateSessionParams, LoadHistoryOptions, MessageRecord, ISessionRepository, IMessageRepository, } from './session.service.js';
+export { PostgresSessionRepository } from './pg-session.repository.js';
+export { FileSessionRepository } from './file-session.repository.js';
+export { MessageService, InMemoryFullMessageRepository, } from './message.service.js';
+export type { AddMessageParams, PaginationOptions, IFullMessageRepository, } from './message.service.js';
+export { PostgresMessageRepository } from './pg-message.repository.js';
+export { FileMessageRepository } from './file-message.repository.js';
+export type { FileMessageRepositoryOptions } from './file-message.repository.js';
+export { SessionContextService } from './session-context.service.js';
+export type { ResolveSessionParams, SessionContext, } from './session-context.service.js';
+export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';
+export type { CompressionMiddlewareConfig } from './compression-middleware.js';

package/dist/session/index.js

@@ -0,0 +1,12 @@
+// Session Module — 会话管理
+export { SessionService, InMemorySessionRepository, InMemoryMessageRepository, } from './session.service.js';
+export { PostgresSessionRepository } from './pg-session.repository.js';
+export { FileSessionRepository } from './file-session.repository.js';
+// Message Module — 消息管理
+export { MessageService, InMemoryFullMessageRepository, } from './message.service.js';
+export { PostgresMessageRepository } from './pg-message.repository.js';
+export { FileMessageRepository } from './file-message.repository.js';
+// Session Context — 会话上下文解析
+export { SessionContextService } from './session-context.service.js';
+// 压缩中间件
+export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';

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

@@ -0,0 +1,80 @@
+/**
+ * Message Service — 消息持久化服务
+ *
+ * 提供消息的 CRUD 操作，支持分页查询。
+ */
+import type { MessageRecord } from './session.service.js';
+export type { MessageRecord };
+export interface AddMessageParams {
+    sessionId: string;
+    taskId?: string;
+    correlationId?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: unknown[];
+    tokenCount: number;
+    reasoning?: unknown | null;
+    durationMs?: number | null;
+    metadata?: Record<string, unknown>;
+}
+export interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * IFullMessageRepository — 完整的 Message 持久化接口
+ *
+ * 扩展 IMessageRepository，增加 save 和 findByTaskId 方法。
+ * MessageService 通过此接口访问存储层。
+ */
+export interface IFullMessageRepository {
+    /** 按 sessionId 查询消息 */
+    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>;
+    /** 按 taskId 查询关联消息 */
+    findByTaskId(taskId: string): Promise<MessageRecord[]>;
+}
+/**
+ * InMemoryFullMessageRepository — 内存完整 Message 存储
+ *
+ * 实现 IFullMessageRepository，用于开发/测试阶段。
+ */
+export declare class InMemoryFullMessageRepository implements IFullMessageRepository {
+    private readonly store;
+    save(message: MessageRecord): Promise<void>;
+    saveMany(messages: MessageRecord[]): Promise<void>;
+    markAsCompressed(messageIds: string[], compressedBy: string, compressedAt: string): Promise<void>;
+    findBySessionId(sessionId: string, limit?: number, offset?: number): Promise<MessageRecord[]>;
+    findByTaskId(taskId: string): Promise<MessageRecord[]>;
+}
+export declare class MessageService {
+    private readonly repository;
+    constructor(repository?: IFullMessageRepository);
+    /**
+     * 添加消息到 Session
+     *
+     * 生成唯一 ID 和时间戳，持久化后返回完整 MessageRecord。
+     */
+    addMessage(params: AddMessageParams): Promise<MessageRecord>;
+    /**
+     * 批量添加消息
+     */
+    addMessages(params: AddMessageParams[]): Promise<MessageRecord[]>;
+    /**
+     * 获取 Session 的消息列表（按 createdAt 排序，支持分页）
+     */
+    getMessages(sessionId: string, options?: PaginationOptions): Promise<MessageRecord[]>;
+    /**
+     * 获取与指定 Task 关联的所有消息
+     */
+    getMessagesByTask(taskId: string): Promise<MessageRecord[]>;
+    /**
+     * 标记消息为已压缩
+     */
+    markAsCompressed(messageIds: string[], compressedBy: string): Promise<void>;
+}

package/dist/session/message.service.js

@@ -0,0 +1,128 @@
+/**
+ * Message Service — 消息持久化服务
+ *
+ * 提供消息的 CRUD 操作，支持分页查询。
+ */
+import { randomUUID } from 'crypto';
+// ─────────────────────────────────────────────
+// In-Memory Full Message Repository
+// ─────────────────────────────────────────────
+/**
+ * InMemoryFullMessageRepository — 内存完整 Message 存储
+ *
+ * 实现 IFullMessageRepository，用于开发/测试阶段。
+ */
+export class InMemoryFullMessageRepository {
+    store = [];
+    async save(message) {
+        this.store.push({ ...message });
+    }
+    async saveMany(messages) {
+        for (const message of messages) {
+            this.store.push({ ...message });
+        }
+    }
+    async markAsCompressed(messageIds, compressedBy, compressedAt) {
+        for (const message of this.store) {
+            if (messageIds.includes(message.id)) {
+                message.updatedBy = compressedBy;
+                message.updatedAt = compressedAt;
+            }
+        }
+    }
+    async findBySessionId(sessionId, limit, offset) {
+        const filtered = this.store
+            .filter((m) => m.sessionId === sessionId && !m.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 findByTaskId(taskId) {
+        return this.store
+            .filter((m) => m.taskId === taskId && !m.isDeleted)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+}
+// ─────────────────────────────────────────────
+// MessageService Implementation
+// ─────────────────────────────────────────────
+export class MessageService {
+    repository;
+    constructor(repository) {
+        this.repository = repository ?? new InMemoryFullMessageRepository();
+    }
+    /**
+     * 添加消息到 Session
+     *
+     * 生成唯一 ID 和时间戳，持久化后返回完整 MessageRecord。
+     */
+    async addMessage(params) {
+        const now = new Date().toISOString();
+        const message = {
+            id: randomUUID(),
+            sessionId: params.sessionId,
+            taskId: params.taskId ?? null,
+            correlationId: params.correlationId ?? null,
+            role: params.role,
+            content: params.content,
+            toolCalls: params.toolCalls ?? null,
+            tokenCount: params.tokenCount,
+            reasoning: params.reasoning ?? null,
+            durationMs: params.durationMs ?? null,
+            metadata: params.metadata ?? {},
+            createdBy: 'system',
+            createdAt: now,
+            updatedBy: 'system',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.repository.save(message);
+        return message;
+    }
+    /**
+     * 批量添加消息
+     */
+    async addMessages(params) {
+        const now = new Date().toISOString();
+        const messages = params.map((p) => ({
+            id: randomUUID(),
+            sessionId: p.sessionId,
+            taskId: p.taskId ?? null,
+            correlationId: p.correlationId ?? null,
+            role: p.role,
+            content: p.content,
+            toolCalls: p.toolCalls ?? null,
+            tokenCount: p.tokenCount,
+            reasoning: p.reasoning ?? null,
+            durationMs: p.durationMs ?? null,
+            metadata: p.metadata ?? {},
+            createdBy: 'system',
+            createdAt: now,
+            updatedBy: 'system',
+            updatedAt: now,
+            isDeleted: false,
+        }));
+        await this.repository.saveMany(messages);
+        return messages;
+    }
+    /**
+     * 获取 Session 的消息列表（按 createdAt 排序，支持分页）
+     */
+    async getMessages(sessionId, options) {
+        return this.repository.findBySessionId(sessionId, options?.limit, options?.offset);
+    }
+    /**
+     * 获取与指定 Task 关联的所有消息
+     */
+    async getMessagesByTask(taskId) {
+        return this.repository.findByTaskId(taskId);
+    }
+    /**
+     * 标记消息为已压缩
+     */
+    async markAsCompressed(messageIds, compressedBy) {
+        const now = new Date().toISOString();
+        await this.repository.markAsCompressed(messageIds, compressedBy, now);
+    }
+}

package/dist/session/persist-turn-messages.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 多轮对话 Message 写回辅助
+ *
+ * invoke / stream 主路径在执行前后调用，保证 Session 短期记忆可被下一轮加载。
+ */
+import type { MessageService } from './message.service.js';
+import type { MessageRecord } from './session.service.js';
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+export declare function persistUserTurnMessage(messageService: MessageService | undefined, params: {
+    sessionId: string;
+    taskId: string;
+    correlationId?: string;
+    content: string;
+}): Promise<void>;
+export declare function persistAssistantTurnMessage(messageService: MessageService | undefined, params: {
+    sessionId: string;
+    taskId: string;
+    correlationId?: string;
+    content: string;
+    tokenCount?: number;
+    toolCalls?: unknown[];
+    /** DeepSeek thinking：多轮回传用 */
+    reasoningContent?: string;
+}): Promise<void>;
+/**
+ * HITL 等待态占位消息：避免早退时本轮只有 user、历史偏薄
+ *
+ * 以 assistant 写入确认问题；metadata.hitlWaiting=true 供后续过滤/展示。
+ */
+export declare function persistHitlWaitingPlaceholder(messageService: MessageService | undefined, params: {
+    sessionId: string;
+    taskId: string;
+    correlationId?: string;
+    question: string;
+    options: string[];
+    threadId: string;
+}): Promise<void>;
+export declare function persistToolTurnMessage(messageService: MessageService | undefined, params: {
+    sessionId: string;
+    taskId: string;
+    correlationId?: string;
+    toolCallId: string;
+    toolName: string;
+    content: unknown;
+    success: boolean;
+}): Promise<void>;
+/** 从流式 RuntimeEvent payload 抽取文本增量 */
+export declare function extractStreamTextDelta(eventType: string, payload: unknown): string;
+/**
+ * 从流式事件抽取 assistant reasoning。
+ * 子图在 skill.completed 上回传（父图不再为 subgraph 节点发空 response.chunk）。
+ */
+export declare function extractStreamReasoning(eventType: string, payload: unknown): string | undefined;
+/** 历史 MessageRecord → GraphMessage（保留 tool 元数据与 reasoning） */
+export declare function messageRecordsToGraphMessages(records: MessageRecord[]): GraphMessage[];
+/**
+ * 组装本轮送入 Graph 的 messages。
+ *
+ * 契约：
+ * - Session 消息是产品侧短期记忆（展示/落库）
+ * - Session 级 Checkpoint 持有图内 messages（含 reasoning）
+ * - 当 Checkpoint 已有历史时，只追加本轮 user，避免双重 append
+ * - Checkpoint 缺失/无 messages 时，回退 Session 全量历史
+ */
+export declare function buildTurnGraphMessages(params: {
+    history: GraphMessage[];
+    input: string;
+    checkpointSaver?: {
+        load(threadId: string): Promise<{
+            state?: {
+                messages?: unknown;
+            };
+            engineSnapshot?: Record<string, unknown>;
+        } | null>;
+    } | null;
+    /** 与 LangGraph configurable.thread_id 一致（通常为 sessionId） */
+    threadId?: string;
+}): Promise<GraphMessage[]>;
+/**
+ * HITL 等待态写入 Task.output 的结构化载荷。
+ * 冷恢复时优先读 `hitlThreadId`，避免误用 correlationId。
+ */
+export interface HitlWaitingTaskOutput {
+    hitlWaiting: true;
+    hitlThreadId: string;
+    question: string;
+    options: string[];
+}
+export declare function buildHitlWaitingTaskOutput(params: {
+    threadId: string;
+    question: string;
+    options: string[];
+}): HitlWaitingTaskOutput;
+/** 从 Task.output 解析 Checkpoint thread_id（含嵌套 hitl.threadId） */
+export declare function extractHitlThreadId(output: unknown): string | undefined;
+/**
+ * Checkpoint thread_id 契约：HITL/多轮优先且应唯一等于 sessionId；
+ * 无 session 时退到 `task-${taskId}`。勿用 correlationId 作为 Checkpoint key。
+ *
+ * 注意：session 级 thread + 全量 Session 历史同时注入会导致 messages 双重 append。
+ * 组装本轮 Graph 输入请用 {@link buildTurnGraphMessages}（有 Checkpoint 历史则只追加 user）。
+ */
+export declare function resolveCheckpointThreadId(params: {
+    sessionId?: string;
+    taskId?: string;
+    graphId?: string;
+}): string;
+export type StreamToolCall = {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export type StreamToolResult = {
+    toolCallId: string;
+    toolName: string;
+    content: unknown;
+    success: boolean;
+};
+/**
+ * 将 stream 侧累加的 tool 事件规范为与 invoke GraphState 增量同序的 messages：
+ * assistant(tool_calls) → tool* → assistant(text)
+ */
+export declare function buildTurnTranscriptFromStreamEvents(params: {
+    pendingToolCalls?: StreamToolCall[];
+    toolResults?: StreamToolResult[];
+    assistantText?: string;
+    /** 带 tool_calls 的那条 assistant 的 reasoning（thinking 回传） */
+    toolCallReasoningContent?: string;
+    /** 最终文本 assistant 的 reasoning */
+    assistantReasoningContent?: string;
+    /** 无 tool、也无文本时是否仍写一条空 assistant（默认否） */
+    persistEmptyAssistant?: boolean;
+}): GraphMessage[];
+/**
+ * 统一落库本轮 transcript（invoke / stream / AgentRuntime.stream 共用）
+ */
+export declare function persistTurnTranscript(messageService: MessageService | undefined, params: {
+    sessionId: string;
+    taskId: string;
+    correlationId?: string;
+    messages: GraphMessage[];
+    /** 无 assistant 文本消息时的兜底（invoke 的 graphResult.output） */
+    fallbackAssistantContent?: string;
+    assistantTokenCount?: number;
+}): Promise<void>;