@gt-fe/eap-runtime 0.0.8

package/dist/session/persist-turn-messages.js

@@ -0,0 +1,325 @@
+/**
+ * 多轮对话 Message 写回辅助
+ *
+ * invoke / stream 主路径在执行前后调用，保证 Session 短期记忆可被下一轮加载。
+ */
+export async function persistUserTurnMessage(messageService, params) {
+    if (!messageService || !params.content)
+        return;
+    await messageService.addMessage({
+        sessionId: params.sessionId,
+        taskId: params.taskId,
+        correlationId: params.correlationId,
+        role: 'user',
+        content: params.content,
+        tokenCount: 0,
+    });
+}
+export async function persistAssistantTurnMessage(messageService, params) {
+    if (!messageService)
+        return;
+    const content = params.content?.trim() ?? '';
+    if (!content && !(params.toolCalls && params.toolCalls.length > 0))
+        return;
+    await messageService.addMessage({
+        sessionId: params.sessionId,
+        taskId: params.taskId,
+        correlationId: params.correlationId,
+        role: 'assistant',
+        content: content || '(tool_calls)',
+        toolCalls: params.toolCalls,
+        tokenCount: params.tokenCount ?? 0,
+        reasoning: params.reasoningContent
+            ? { reasoningContent: params.reasoningContent }
+            : null,
+    });
+}
+/**
+ * HITL 等待态占位消息：避免早退时本轮只有 user、历史偏薄
+ *
+ * 以 assistant 写入确认问题；metadata.hitlWaiting=true 供后续过滤/展示。
+ */
+export async function persistHitlWaitingPlaceholder(messageService, params) {
+    if (!messageService)
+        return;
+    const question = params.question?.trim() || '等待人工确认';
+    await messageService.addMessage({
+        sessionId: params.sessionId,
+        taskId: params.taskId,
+        correlationId: params.correlationId,
+        role: 'assistant',
+        content: question,
+        tokenCount: 0,
+        metadata: {
+            hitlWaiting: true,
+            hitlOptions: params.options,
+            hitlThreadId: params.threadId,
+        },
+    });
+}
+export async function persistToolTurnMessage(messageService, params) {
+    if (!messageService)
+        return;
+    const content = typeof params.content === 'string'
+        ? params.content
+        : JSON.stringify(params.content ?? null);
+    await messageService.addMessage({
+        sessionId: params.sessionId,
+        taskId: params.taskId,
+        correlationId: params.correlationId,
+        role: 'tool',
+        content,
+        toolCalls: [
+            {
+                id: params.toolCallId,
+                name: params.toolName,
+                success: params.success,
+            },
+        ],
+        tokenCount: 0,
+    });
+}
+/** 从流式 RuntimeEvent payload 抽取文本增量 */
+export function extractStreamTextDelta(eventType, payload) {
+    if (eventType !== 'response.chunk' &&
+        eventType !== 'response.delta' &&
+        eventType !== 'response.final') {
+        return '';
+    }
+    if (!payload || typeof payload !== 'object')
+        return '';
+    const p = payload;
+    const text = p.chunk ?? p.delta ?? p.content;
+    return typeof text === 'string' ? text : '';
+}
+/**
+ * 从流式事件抽取 assistant reasoning。
+ * 子图在 skill.completed 上回传（父图不再为 subgraph 节点发空 response.chunk）。
+ */
+export function extractStreamReasoning(eventType, payload) {
+    if (eventType !== 'response.chunk' &&
+        eventType !== 'response.delta' &&
+        eventType !== 'response.final' &&
+        eventType !== 'skill.completed') {
+        return undefined;
+    }
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const value = payload.reasoningContent;
+    return typeof value === 'string' && value ? value : undefined;
+}
+/** 历史 MessageRecord → GraphMessage（保留 tool 元数据与 reasoning） */
+export function messageRecordsToGraphMessages(records) {
+    return records.map((m) => {
+        const base = {
+            role: m.role,
+            content: m.content,
+        };
+        if (m.toolCalls && m.toolCalls.length > 0) {
+            base.toolCalls = m.toolCalls;
+            const first = m.toolCalls[0];
+            if (m.role === 'tool') {
+                if (first?.id)
+                    base.toolCallId = first.id;
+                if (first?.name)
+                    base.toolName = first.name;
+                if (typeof first?.success === 'boolean')
+                    base.success = first.success;
+            }
+        }
+        const reasoningContent = extractReasoningContent(m.reasoning);
+        if (reasoningContent)
+            base.reasoningContent = reasoningContent;
+        return base;
+    });
+}
+function extractReasoningContent(reasoning) {
+    if (typeof reasoning === 'string' && reasoning) {
+        const trimmed = reasoning.trim();
+        if (trimmed.startsWith('{')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed.reasoningContent === 'string' && parsed.reasoningContent) {
+                    return parsed.reasoningContent;
+                }
+                if (typeof parsed.content === 'string' && parsed.content) {
+                    return parsed.content;
+                }
+            }
+            catch {
+                // 非 JSON 字符串，按原文回传
+            }
+        }
+        return reasoning;
+    }
+    if (!reasoning || typeof reasoning !== 'object')
+        return undefined;
+    const r = reasoning;
+    if (typeof r.reasoningContent === 'string' && r.reasoningContent)
+        return r.reasoningContent;
+    if (typeof r.content === 'string' && r.content)
+        return r.content;
+    return undefined;
+}
+/**
+ * 组装本轮送入 Graph 的 messages。
+ *
+ * 契约：
+ * - Session 消息是产品侧短期记忆（展示/落库）
+ * - Session 级 Checkpoint 持有图内 messages（含 reasoning）
+ * - 当 Checkpoint 已有历史时，只追加本轮 user，避免双重 append
+ * - Checkpoint 缺失/无 messages 时，回退 Session 全量历史
+ */
+export async function buildTurnGraphMessages(params) {
+    const newUser = { role: 'user', content: params.input };
+    const history = params.history;
+    if (!params.checkpointSaver || !params.threadId || history.length === 0) {
+        return [...history, newUser];
+    }
+    const cp = await params.checkpointSaver.load(params.threadId);
+    if (checkpointHasMessages(cp)) {
+        return [newUser];
+    }
+    return [...history, newUser];
+}
+function checkpointHasMessages(cp) {
+    if (!cp)
+        return false;
+    if (Array.isArray(cp.state?.messages) && cp.state.messages.length > 0)
+        return true;
+    const channelValues = cp.engineSnapshot?.['channel_values'];
+    if (channelValues && typeof channelValues === 'object') {
+        const messages = channelValues['messages'];
+        if (Array.isArray(messages) && messages.length > 0)
+            return true;
+    }
+    return false;
+}
+export function buildHitlWaitingTaskOutput(params) {
+    return {
+        hitlWaiting: true,
+        hitlThreadId: params.threadId,
+        question: params.question?.trim() || '等待人工确认',
+        options: params.options,
+    };
+}
+/** 从 Task.output 解析 Checkpoint thread_id（含嵌套 hitl.threadId） */
+export function extractHitlThreadId(output) {
+    if (!output || typeof output !== 'object')
+        return undefined;
+    const o = output;
+    if (typeof o.hitlThreadId === 'string' && o.hitlThreadId.trim()) {
+        return o.hitlThreadId.trim();
+    }
+    const hitl = o.hitl;
+    if (hitl && typeof hitl === 'object') {
+        const threadId = hitl.threadId;
+        if (typeof threadId === 'string' && threadId.trim())
+            return threadId.trim();
+    }
+    return undefined;
+}
+/**
+ * Checkpoint thread_id 契约：HITL/多轮优先且应唯一等于 sessionId；
+ * 无 session 时退到 `task-${taskId}`。勿用 correlationId 作为 Checkpoint key。
+ *
+ * 注意：session 级 thread + 全量 Session 历史同时注入会导致 messages 双重 append。
+ * 组装本轮 Graph 输入请用 {@link buildTurnGraphMessages}（有 Checkpoint 历史则只追加 user）。
+ */
+export function resolveCheckpointThreadId(params) {
+    if (params.sessionId)
+        return params.sessionId;
+    if (params.taskId)
+        return `task-${params.taskId}`;
+    if (params.graphId)
+        return `thread-${params.graphId}`;
+    return `thread-${Date.now()}`;
+}
+/**
+ * 将 stream 侧累加的 tool 事件规范为与 invoke GraphState 增量同序的 messages：
+ * assistant(tool_calls) → tool* → assistant(text)
+ */
+export function buildTurnTranscriptFromStreamEvents(params) {
+    const out = [];
+    const pending = params.pendingToolCalls ?? [];
+    const results = params.toolResults ?? [];
+    const text = params.assistantText ?? '';
+    if (pending.length > 0) {
+        out.push({
+            role: 'assistant',
+            content: '',
+            toolCalls: pending.map((tc) => ({
+                id: tc.id,
+                name: tc.name,
+                arguments: tc.arguments,
+            })),
+            ...(params.toolCallReasoningContent
+                ? { reasoningContent: params.toolCallReasoningContent }
+                : {}),
+        });
+    }
+    for (const tr of results) {
+        out.push({
+            role: 'tool',
+            content: typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content ?? null),
+            toolCallId: tr.toolCallId,
+            toolName: tr.toolName,
+            success: tr.success,
+        });
+    }
+    if (text.trim() || (params.persistEmptyAssistant && out.length === 0)) {
+        out.push({
+            role: 'assistant',
+            content: text,
+            ...(params.assistantReasoningContent
+                ? { reasoningContent: params.assistantReasoningContent }
+                : {}),
+        });
+    }
+    return out;
+}
+/**
+ * 统一落库本轮 transcript（invoke / stream / AgentRuntime.stream 共用）
+ */
+export async function persistTurnTranscript(messageService, params) {
+    if (!messageService)
+        return;
+    let hasAssistantText = false;
+    for (const m of params.messages) {
+        if (m.role === 'assistant') {
+            const isToolCallOnly = Boolean(m.toolCalls?.length) && !(m.content?.trim());
+            if (!isToolCallOnly && (m.content?.trim() ?? '')) {
+                hasAssistantText = true;
+            }
+            await persistAssistantTurnMessage(messageService, {
+                sessionId: params.sessionId,
+                taskId: params.taskId,
+                correlationId: params.correlationId,
+                content: m.content ?? '',
+                toolCalls: m.toolCalls,
+                tokenCount: isToolCallOnly ? 0 : params.assistantTokenCount,
+                reasoningContent: m.reasoningContent,
+            });
+        }
+        else if (m.role === 'tool') {
+            await persistToolTurnMessage(messageService, {
+                sessionId: params.sessionId,
+                taskId: params.taskId,
+                correlationId: params.correlationId,
+                toolCallId: m.toolCallId ?? 'unknown',
+                toolName: m.toolName ?? 'unknown',
+                content: m.content,
+                success: m.success !== false,
+            });
+        }
+    }
+    if (!hasAssistantText && params.fallbackAssistantContent != null) {
+        await persistAssistantTurnMessage(messageService, {
+            sessionId: params.sessionId,
+            taskId: params.taskId,
+            correlationId: params.correlationId,
+            content: params.fallbackAssistantContent,
+            tokenCount: params.assistantTokenCount,
+        });
+    }
+}

package/dist/session/pg-message.repository.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PostgresMessageRepository — Message 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 IFullMessageRepository 接口。
+ * JSON 字段（tool_calls / reasoning / metadata）使用 JSONB 类型存储。
+ *
+ * @see design.md §1.3 数据模型 — messages 表
+ * @see message.service.ts IFullMessageRepository 接口定义
+ */
+import type { MessageRecord } from './session.service.js';
+import type { IFullMessageRepository } from './message.service.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export declare class PostgresMessageRepository implements IFullMessageRepository {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    /**
+     * INSERT message record with audit fields
+     */
+    save(message: MessageRecord): Promise<void>;
+    /**
+     * SELECT messages by session_id, ORDER BY created_at ASC, 支持分页
+     * Excludes soft-deleted records
+     */
+    findBySessionId(sessionId: string, limit?: number, offset?: number): Promise<MessageRecord[]>;
+    /**
+     * SELECT messages by task_id, ORDER BY created_at ASC
+     * Excludes soft-deleted records
+     */
+    findByTaskId(taskId: string): Promise<MessageRecord[]>;
+    /**
+     * Soft delete message
+     */
+    saveMany(messages: MessageRecord[]): Promise<void>;
+    markAsCompressed(messageIds: string[], compressedBy: string, compressedAt: string): Promise<void>;
+    softDelete(id: string, deletedBy: string): Promise<void>;
+    /**
+     * 将 PostgreSQL 行数据转换为 MessageRecord
+     */
+    private rowToRecord;
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    private parseJson;
+}

package/dist/session/pg-message.repository.js

@@ -0,0 +1,149 @@
+/**
+ * PostgresMessageRepository — Message 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 IFullMessageRepository 接口。
+ * JSON 字段（tool_calls / reasoning / metadata）使用 JSONB 类型存储。
+ *
+ * @see design.md §1.3 数据模型 — messages 表
+ * @see message.service.ts IFullMessageRepository 接口定义
+ */
+// ─────────────────────────────────────────────
+// PostgresMessageRepository
+// ─────────────────────────────────────────────
+export class PostgresMessageRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * INSERT message record with audit fields
+     */
+    async save(message) {
+        const sql = `
+      INSERT INTO messages (
+        id, session_id, task_id, correlation_id, role, content, tool_calls,
+        reasoning, metadata, token_count, duration_ms,
+        created_by, created_at, updated_by, updated_at
+      )
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
+    `;
+        await this.pool.query(sql, [
+            message.id,
+            message.sessionId,
+            message.taskId,
+            message.correlationId,
+            message.role,
+            message.content,
+            message.toolCalls != null ? JSON.stringify(message.toolCalls) : null,
+            message.reasoning != null ? JSON.stringify(message.reasoning) : null,
+            JSON.stringify(message.metadata ?? {}),
+            message.tokenCount,
+            message.durationMs ?? null,
+            message.createdBy || 'system',
+            message.createdAt,
+            message.updatedBy || 'system',
+            message.updatedAt,
+        ]);
+    }
+    /**
+     * SELECT messages by session_id, ORDER BY created_at ASC, 支持分页
+     * Excludes soft-deleted records
+     */
+    async findBySessionId(sessionId, limit, offset) {
+        let sql = `SELECT * FROM messages WHERE session_id = $1 AND is_deleted = FALSE ORDER BY created_at ASC`;
+        const params = [sessionId];
+        if (limit !== undefined) {
+            sql += ` LIMIT $${params.length + 1}`;
+            params.push(limit);
+        }
+        if (offset !== undefined) {
+            sql += ` OFFSET $${params.length + 1}`;
+            params.push(offset);
+        }
+        const { rows } = await this.pool.query(sql, params);
+        return rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * SELECT messages by task_id, ORDER BY created_at ASC
+     * Excludes soft-deleted records
+     */
+    async findByTaskId(taskId) {
+        const sql = `SELECT * FROM messages WHERE task_id = $1 AND is_deleted = FALSE ORDER BY created_at ASC`;
+        const { rows } = await this.pool.query(sql, [taskId]);
+        return rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Soft delete message
+     */
+    async saveMany(messages) {
+        for (const message of messages) {
+            await this.save(message);
+        }
+    }
+    async markAsCompressed(messageIds, compressedBy, compressedAt) {
+        if (messageIds.length === 0)
+            return;
+        const placeholders = messageIds.map((_, i) => `$${i + 4}`).join(',');
+        const patch = JSON.stringify({
+            compressed: true,
+            compressedBy,
+            compressedAt,
+        });
+        const sql = `
+      UPDATE messages
+      SET metadata = COALESCE(metadata, '{}'::jsonb) || $1::jsonb,
+          updated_by = $2,
+          updated_at = $3
+      WHERE id IN (${placeholders}) AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [patch, compressedBy, compressedAt, ...messageIds]);
+    }
+    async softDelete(id, deletedBy) {
+        const sql = `
+      UPDATE messages
+      SET is_deleted = TRUE, deleted_by = $1, deleted_at = NOW()
+      WHERE id = $2 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [deletedBy, id]);
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 PostgreSQL 行数据转换为 MessageRecord
+     */
+    rowToRecord(row) {
+        const metadataRaw = row.metadata != null ? this.parseJson(row.metadata) : {};
+        return {
+            id: row.id,
+            sessionId: row.session_id,
+            taskId: row.task_id,
+            correlationId: row.correlation_id,
+            role: row.role,
+            content: row.content,
+            toolCalls: row.tool_calls != null ? this.parseJson(row.tool_calls) : null,
+            reasoning: row.reasoning != null ? this.parseJson(row.reasoning) : null,
+            metadata: metadataRaw && typeof metadataRaw === 'object' && !Array.isArray(metadataRaw)
+                ? metadataRaw
+                : {},
+            tokenCount: row.token_count,
+            durationMs: row.duration_ms,
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+            updatedBy: row.updated_by,
+            updatedAt: row.updated_at.toISOString(),
+            isDeleted: row.is_deleted,
+            deletedBy: row.deleted_by,
+            deletedAt: row.deleted_at?.toISOString(),
+        };
+    }
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    parseJson(value) {
+        if (typeof value === 'string') {
+            return JSON.parse(value);
+        }
+        return value;
+    }
+}

package/dist/session/pg-session.repository.d.ts

@@ -0,0 +1,46 @@
+/**
+ * PostgresSessionRepository — Session 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 ISessionRepository 接口。
+ * JSON 字段（metadata）使用 JSONB 类型存储。
+ *
+ * @see design.md §1.3 数据模型 — sessions 表
+ * @see session.service.ts ISessionRepository 接口定义
+ */
+import type { SessionRecord, ISessionRepository } from './session.service.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export declare class PostgresSessionRepository implements ISessionRepository {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    /**
+     * INSERT session record with all fields including audit fields
+     */
+    save(session: SessionRecord): Promise<void>;
+    /**
+     * SELECT session by id, deserialize JSON fields
+     * Excludes soft-deleted records
+     */
+    findById(id: string): Promise<SessionRecord | null>;
+    /**
+     * UPDATE all mutable fields by id
+     */
+    findByUserId(userId: string, limit?: number, offset?: number): Promise<SessionRecord[]>;
+    update(session: SessionRecord): Promise<void>;
+    /**
+     * Soft delete session
+     */
+    softDelete(id: string, deletedBy: string): Promise<void>;
+    /**
+     * 将 PostgreSQL 行数据转换为 SessionRecord
+     */
+    private rowToRecord;
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    private parseJson;
+}

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

@@ -0,0 +1,117 @@
+/**
+ * PostgresSessionRepository — Session 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 ISessionRepository 接口。
+ * JSON 字段（metadata）使用 JSONB 类型存储。
+ *
+ * @see design.md §1.3 数据模型 — sessions 表
+ * @see session.service.ts ISessionRepository 接口定义
+ */
+// ─────────────────────────────────────────────
+// PostgresSessionRepository
+// ─────────────────────────────────────────────
+export class PostgresSessionRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * INSERT session record with all fields including audit fields
+     */
+    async save(session) {
+        const sql = `
+      INSERT INTO sessions (id, user_id, agent_id, title, status, metadata, created_by, created_at, updated_by, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+    `;
+        await this.pool.query(sql, [
+            session.id,
+            session.userId,
+            session.agentId,
+            session.title,
+            session.status,
+            JSON.stringify(session.metadata),
+            session.createdBy || 'system',
+            session.createdAt,
+            session.updatedBy || 'system',
+            session.updatedAt,
+        ]);
+    }
+    /**
+     * SELECT session by id, deserialize JSON fields
+     * Excludes soft-deleted records
+     */
+    async findById(id) {
+        const sql = `SELECT * FROM sessions WHERE id = $1 AND is_deleted = FALSE`;
+        const { rows } = await this.pool.query(sql, [id]);
+        if (rows.length === 0) {
+            return null;
+        }
+        return this.rowToRecord(rows[0]);
+    }
+    /**
+     * UPDATE all mutable fields by id
+     */
+    async findByUserId(userId, limit, offset) {
+        const sql = `SELECT * FROM sessions WHERE user_id = $1 AND is_deleted = false ORDER BY created_at DESC LIMIT $2 OFFSET $3`;
+        const result = await this.pool.query(sql, [userId, limit ?? 100, offset ?? 0]);
+        return result.rows.map((row) => this.rowToRecord(row));
+    }
+    async update(session) {
+        const sql = `
+      UPDATE sessions
+      SET title = $1, status = $2, metadata = $3, updated_by = $4, updated_at = $5
+      WHERE id = $6 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [
+            session.title,
+            session.status,
+            JSON.stringify(session.metadata),
+            session.updatedBy || 'system',
+            session.updatedAt,
+            session.id,
+        ]);
+    }
+    /**
+     * Soft delete session
+     */
+    async softDelete(id, deletedBy) {
+        const sql = `
+      UPDATE sessions
+      SET is_deleted = TRUE, deleted_by = $1, deleted_at = NOW()
+      WHERE id = $2 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [deletedBy, id]);
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 PostgreSQL 行数据转换为 SessionRecord
+     */
+    rowToRecord(row) {
+        return {
+            id: row.id,
+            userId: row.user_id,
+            agentId: row.agent_id,
+            title: row.title,
+            status: row.status,
+            metadata: this.parseJson(row.metadata),
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+            updatedBy: row.updated_by,
+            updatedAt: row.updated_at.toISOString(),
+            isDeleted: row.is_deleted,
+            deletedBy: row.deleted_by,
+            deletedAt: row.deleted_at?.toISOString(),
+        };
+    }
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    parseJson(value) {
+        if (typeof value === 'string') {
+            return JSON.parse(value);
+        }
+        return value;
+    }
+}