@gt-fe/eap-runtime 0.0.8

package/dist/graph/adapters/langgraph-checkpointer.js

@@ -0,0 +1,211 @@
+/**
+ * LangGraphCheckpointer — BaseCheckpointSaver 桥接实现
+ *
+ * 将 LangGraph 的 BaseCheckpointSaver 接口委托到平台的 ICheckpointSaver，
+ * 实现 getTuple / put / putWrites / list 与 CheckpointData 之间的数据映射。
+ *
+ * @see design.md §1.4 Checkpoint 集成
+ * @see tasks.md Task 11.5
+ */
+import { BaseCheckpointSaver, } from '@langchain/langgraph';
+/**
+ * LangGraphCheckpointer — 桥接 LangGraph BaseCheckpointSaver → ICheckpointSaver
+ *
+ * intermediate writes（putWrites）先放进程内；checkpoint 快照仍落 ICheckpointSaver。
+ */
+export class LangGraphCheckpointer extends BaseCheckpointSaver {
+    saver;
+    /** threadId|ns|checkpointId → writes */
+    pendingWrites = new Map();
+    constructor(saver) {
+        super();
+        this.saver = saver;
+    }
+    async getTuple(config) {
+        const threadId = this.extractThreadId(config);
+        if (!threadId) {
+            return undefined;
+        }
+        const checkpointId = config.configurable?.['checkpoint_id'];
+        let data;
+        if (checkpointId) {
+            data = await this.saver.loadByCheckpointId(checkpointId);
+        }
+        else {
+            data = await this.saver.load(threadId);
+        }
+        if (!data) {
+            return undefined;
+        }
+        return this.checkpointDataToTuple(data, config);
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        const threadId = this.extractThreadId(config) ?? `thread-${Date.now()}`;
+        const data = this.checkpointToData(threadId, checkpoint, metadata);
+        await this.saver.save(threadId, data);
+        return {
+            ...config,
+            configurable: {
+                ...config.configurable,
+                thread_id: threadId,
+                checkpoint_id: checkpoint.id,
+            },
+        };
+    }
+    /**
+     * 存储与 checkpoint 关联的 intermediate writes（LangGraph 0.2+ 必需；缺此方法会报 putWrites is not a function）
+     */
+    async putWrites(config, writes, taskId) {
+        const threadId = this.extractThreadId(config);
+        const checkpointNs = String(config.configurable?.['checkpoint_ns'] ?? '');
+        const checkpointId = config.configurable?.['checkpoint_id'];
+        if (!threadId || !checkpointId) {
+            return;
+        }
+        const outerKey = `${threadId}|${checkpointNs}|${checkpointId}`;
+        let bucket = this.pendingWrites.get(outerKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.pendingWrites.set(outerKey, bucket);
+        }
+        writes.forEach(([channel, value], idx) => {
+            const innerKey = `${taskId},${idx}`;
+            bucket.set(innerKey, [taskId, String(channel), value]);
+        });
+    }
+    async *list(config, options) {
+        const threadId = this.extractThreadId(config);
+        if (!threadId) {
+            return;
+        }
+        let checkpoints = await this.saver.list(threadId);
+        checkpoints.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+        if (options?.before) {
+            const beforeId = options.before.configurable?.['checkpoint_id'];
+            if (beforeId) {
+                const idx = checkpoints.findIndex((cp) => cp.checkpointId === beforeId);
+                if (idx >= 0) {
+                    checkpoints = checkpoints.slice(idx + 1);
+                }
+            }
+        }
+        if (options?.limit && options.limit > 0) {
+            checkpoints = checkpoints.slice(0, options.limit);
+        }
+        for (const cp of checkpoints) {
+            yield this.checkpointDataToTuple(cp, config);
+        }
+    }
+    extractThreadId(config) {
+        return config.configurable?.['thread_id'];
+    }
+    checkpointDataToTuple(data, config) {
+        const checkpoint = this.restoreLangGraphCheckpoint(data);
+        const metadata = {
+            source: 'loop',
+            step: data.historyPath.length,
+            writes: null,
+        };
+        const tupleConfig = {
+            ...config,
+            configurable: {
+                ...config.configurable,
+                thread_id: data.threadId,
+                checkpoint_id: data.checkpointId,
+            },
+        };
+        const checkpointNs = String(config.configurable?.['checkpoint_ns'] ?? '');
+        const outerKey = `${data.threadId}|${checkpointNs}|${data.checkpointId}`;
+        const writes = this.pendingWrites.get(outerKey);
+        const pendingWrites = writes
+            ? Array.from(writes.values()).map(([taskId, channel, value]) => [taskId, channel, value])
+            : undefined;
+        return {
+            config: tupleConfig,
+            checkpoint,
+            metadata,
+            ...(pendingWrites ? { pendingWrites } : {}),
+        };
+    }
+    /**
+     * 优先还原 put() 时写入的 engineSnapshot；旧数据兜底补齐 pending_sends=[]。
+     */
+    restoreLangGraphCheckpoint(data) {
+        const snap = data.engineSnapshot;
+        if (snap && typeof snap === 'object') {
+            const channelValues = snap.channel_values && typeof snap.channel_values === 'object'
+                ? snap.channel_values
+                : {};
+            const channelVersions = snap.channel_versions && typeof snap.channel_versions === 'object'
+                ? snap.channel_versions
+                : {};
+            const versionsSeen = snap.versions_seen && typeof snap.versions_seen === 'object'
+                ? snap.versions_seen
+                : {};
+            const restored = {
+                v: typeof snap.v === 'number' ? snap.v : 1,
+                id: typeof snap.id === 'string' && snap.id ? snap.id : data.checkpointId,
+                ts: typeof snap.ts === 'string' && snap.ts ? snap.ts : data.createdAt,
+                channel_values: channelValues,
+                channel_versions: channelVersions,
+                versions_seen: versionsSeen,
+                pending_sends: Array.isArray(snap.pending_sends) ? snap.pending_sends : [],
+            };
+            return restored;
+        }
+        return {
+            v: 1,
+            id: data.checkpointId,
+            ts: data.createdAt,
+            channel_values: {
+                messages: data.state.messages ?? [],
+                currentNode: data.currentNodeId,
+                ...this.extractExtraState(data),
+            },
+            channel_versions: { messages: 1, currentNode: 1 },
+            versions_seen: {},
+            pending_sends: [],
+        };
+    }
+    checkpointToData(threadId, checkpoint, metadata) {
+        const messages = Array.isArray(checkpoint.channel_values['messages'])
+            ? checkpoint.channel_values['messages']
+            : [];
+        const currentNodeId = checkpoint.channel_values['currentNode'] ?? '';
+        const step = Number.isFinite(metadata.step) ? Math.max(0, Math.min(metadata.step, 1000)) : 0;
+        const historyPath = Array.from({ length: step }, () => 'node');
+        const raw = checkpoint;
+        return {
+            checkpointId: checkpoint.id,
+            threadId,
+            currentNodeId,
+            historyPath,
+            state: {
+                messages: messages.map((msg) => ({
+                    role: msg['role'] ?? 'user',
+                    content: msg['content'] ?? '',
+                    toolCalls: msg['tool_calls'],
+                })),
+                userId: checkpoint.channel_values['userId'] ?? '',
+            },
+            engineSnapshot: {
+                v: checkpoint.v,
+                id: checkpoint.id,
+                ts: checkpoint.ts,
+                channel_values: checkpoint.channel_values,
+                channel_versions: checkpoint.channel_versions,
+                versions_seen: checkpoint.versions_seen,
+                pending_sends: Array.isArray(raw.pending_sends) ? raw.pending_sends : [],
+            },
+            createdBy: 'system',
+            createdAt: checkpoint.ts,
+            updatedBy: 'system',
+            updatedAt: checkpoint.ts,
+            isDeleted: false,
+        };
+    }
+    extractExtraState(data) {
+        const { messages: _m, userId: _u, ...rest } = data.state;
+        return rest;
+    }
+}

package/dist/graph/adapters/langgraph.adapter.d.ts

@@ -0,0 +1,190 @@
+/**
+ * LangGraph Adapter — IStateGraphEngine 的 v1 实现
+ *
+ * 将平台 StateGraph Contract 映射到 LangGraph.js API，
+ * 实现 Graph 的构建、流式执行、同步调用、Checkpoint 和恢复。
+ *
+ * @see design.md §1.4 StateGraph Contract 与 LangGraph.js 集成
+ * @see requirements.md Requirement 1 AC5
+ */
+import type { IStateGraphEngine } from '../contracts/state-graph.contract.js';
+import type { ExecutableGraph, GraphDSL, GraphState, RuntimeEvent, CheckpointData, GraphResult } from '../contracts/executable-graph.js';
+import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { HitlHandler } from '../hitl/hitl-handler.js';
+import { type ILLMProvider } from '../nodes/llm-node.js';
+import type { IToolExecutor } from '../../tool/tool-executor.interface.js';
+import type { IGovernanceClient } from '../../governance/governance-client.js';
+import { type ConditionEvaluatorFn } from '../condition-evaluator.js';
+/**
+ * LangGraphAdapter — 基于 @langchain/langgraph 的 IStateGraphEngine 实现
+ *
+ * 职责：
+ * 1. 解析 GraphDSL → 注册节点、添加边/条件路由 → 编译为可执行图
+ * 2. 调用 LangGraph 的 stream/invoke 驱动执行
+ * 3. 提供 Checkpoint 提取与恢复能力
+ */
+export declare class LangGraphAdapter implements IStateGraphEngine {
+    private readonly checkpointer;
+    private readonly subGraphCompiler;
+    private readonly llmProvider;
+    private readonly toolExecutor?;
+    private readonly toolOrchestrator?;
+    private readonly toolResultInjector;
+    private readonly conditionEvaluator;
+    private readonly systemPromptBuilder;
+    private readonly skillAuditRecorder;
+    /** 流式旁路：LLM token / Tool 执行事件在节点执行中实时入队 */
+    private streamSink;
+    private streamEventContext;
+    private streamChunkIndex;
+    private streamIteration;
+    private reasoningStartedThisTurn;
+    private streamedTextThisTurn;
+    /**
+     * @param checkpointSaver - 可选的 ICheckpointSaver
+     * @param llmProvider - LLM 调用提供者，默认 EchoLLMProvider
+     * @param toolExecutor - Tool 执行器（HttpToolExecutor 等）
+     */
+    private readonly governanceClient?;
+    private hitlHandler?;
+    constructor(checkpointSaver?: ICheckpointSaver, llmProvider?: ILLMProvider, toolExecutor?: IToolExecutor, governanceClient?: IGovernanceClient, hitlHandler?: HitlHandler);
+    /**
+     * 注册自定义条件评估函数
+     */
+    registerConditionEvaluator(name: string, fn: ConditionEvaluatorFn): void;
+    /**
+     * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
+     * 无 streamSink 时为空操作（纯 invoke）。
+     */
+    emitStreamEvent(event: RuntimeEvent): void;
+    /**
+     * 子图 LLM 可清零流式标志；结束后保留「已经 stream 过」以免父图 convertUpdates 再发一遍正文。
+     */
+    runIsolatedLlmStreamFlags<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Tool 节点执行旁路：started → tool.called + tool.progress；
+     * completed/error → 对应终态 + tool.progress。同一 toolCallId。
+     */
+    private emitToolExecutionEvents;
+    /**
+     * 解析 GraphDSL 并构建可执行图
+     *
+     * **Request Isolation**: 每次调用都创建全新的 StateGraph 实例并编译，
+     * 确保并发请求之间无共享可变状态。Adapter 自身仅持有 readonly 配置（checkpointer、subGraphCompiler），
+     * 不缓存任何编译产物或运行时状态。
+     *
+     * 流程：
+     * 1. 创建 StateGraph 实例（配置 channels）
+     * 2. 遍历 DSL nodes → addNode 注册节点函数
+     * 3. 遍历 DSL edges → addEdge 添加普通边
+     * 4. 遍历 DSL conditionalEdges → addConditionalEdges 添加条件路由
+     * 5. 设置入口/终止节点
+     * 6. compile() 编译
+     */
+    buildGraph(dsl: GraphDSL): Promise<ExecutableGraph>;
+    /**
+     * 流式驱动图执行，逐步 yield RuntimeEvent
+     *
+     * - LangGraph `streamMode: "updates"`：节点完成后产出 response.chunk / stats 等
+     * - LLM token / Tool 执行事件：经 streamSink 在节点执行中实时旁路入队
+     * （当前 @langchain/langgraph@0.2 无 messages mode，故用 LLMNode.onChunk 模拟）
+     */
+    stream(graph: ExecutableGraph, state: GraphState): AsyncIterableIterator<RuntimeEvent>;
+    /**
+     * 同步调用图执行，返回完整结果
+     */
+    invoke(graph: ExecutableGraph, state: GraphState): Promise<GraphResult>;
+    /**
+     * 从运行中的图提取 Checkpoint
+     *
+     * 提取当前执行状态为可持久化的 CheckpointData。
+     */
+    checkpoint(graph: ExecutableGraph): CheckpointData;
+    /**
+     * 从 CheckpointData 恢复可执行图
+     *
+     * HITL / Fork 续跑请走 `buildGraph(dsl)` + 同一 `thread_id` 的 state。
+     * 本方法无 DSL，无法编译出可用 `_engineInstance`。
+     */
+    restore(checkpointData: CheckpointData): Promise<ExecutableGraph>;
+    /**
+     * 根据节点类型创建对应的执行函数
+     */
+    private createNodeFunction;
+    private createSkillBindNodeFunction;
+    private buildSkillCatalog;
+    private createToolNodeFunction;
+    private createLLMNodeFunction;
+    /**
+     * 子图节点：优先 config.subgraphDsl；否则按 skillId 从 state.skillDefinitions.workflow 解析。
+     * 技能 prompt 由 SubGraphCompiler 写入 activeSkillPrompt，供入口 LLM 拼接。
+     */
+    private createSubGraphNodeFunction;
+    /**
+     * 并行节点：并行执行多个子任务分支
+     *
+     * 支持两种并行模式：
+     * 1. branches 模式：node.branches 列出要并行执行的节点 ID，每个节点的执行函数由 DSL 定义
+     * 2. tasks 模式：node.config.tasks 列出要并行执行的异步任务函数
+     *
+     * 执行结果合并到 state.__parallelResults 中。
+     */
+    private createParallelNodeFunction;
+    /**
+     * 代码执行节点：在受限沙箱中执行用户代码
+     *
+     * 支持两种模式：
+     * 1. inline：node.config.code 为内联 JavaScript/TypeScript 代码字符串
+     * 2. handler：node.config.handler 为外部模块路径 + 函数名
+     *
+     * 安全措施：
+     * - 禁止 require/import 动态加载
+     * - 执行超时控制（默认 5000ms）
+     * - 限制可访问的 state 字段
+     */
+    private createCodeNodeFunction;
+    /**
+     * 受限沙箱执行代码
+     *
+     * 使用 Function 构造器 + 超时控制，禁止动态模块加载。
+     * 注意：这不是完整的安全沙箱，生产环境应使用 vm2/isolated-vm 或容器化方案。
+     */
+    private executeCodeInSandbox;
+    /**
+     * 从 DSL 中提取条件节点关联的分支值
+     */
+    private extractBranchValuesFromDsl;
+    /**
+     * shouldContinue 的 call_tools 只能进 type:tool。
+     * 禁止指向 subgraph / llm / code：那是路由信号，不是 Tool 执行。
+     * 内嵌 subgraphDsl 同样校验。
+     */
+    private assertShouldContinueTargetsTool;
+    /**
+     * 添加条件路由边到 StateGraph
+     *
+     * 使用 ConditionEvaluator 对 DSL 中的 conditionFn 表达式求值，
+     * 支持 stateField 引用、简单表达式和自定义评估函数。
+     */
+    private addConditionalEdge;
+    /**
+     * 获取编译后图的内部引用
+     */
+    private getCompiledRef;
+    /**
+     * 将 GraphState 转换为 LangGraph 输入格式。
+     * 必须原样保留 toolCalls / toolCallId / reasoningContent 等字段，
+     * 否则多轮回放时 DeepSeek thinking 会因缺少 reasoning_content 而 400，
+     * tool 消息也会丢掉 tool_call_id。
+     */
+    private graphStateToLangGraphInput;
+    /**
+     * 将 LangGraph updates 模式输出转为平台 RuntimeEvent 序列
+     *
+     * updates 形态：`{ [nodeId]: partialState }`；partialState.messages 仅为该节点新增消息。
+     */
+    private convertUpdatesToEvents;
+    /** 规范化 updates / values 两种 stream 输出 */
+    private normalizeStreamUpdates;
+    private extractMessagesFromPartial;
+}