@gt-fe/eap-runtime 0.0.8

package/dist/graph/adapters/langgraph.adapter.js

@@ -0,0 +1,1303 @@
+/**
+ * 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 { StateGraph, START, END, } from '@langchain/langgraph';
+import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
+import { LangGraphCheckpointer } from './langgraph-checkpointer.js';
+import { SubGraphCompiler } from './subgraph-compiler.js';
+import { LLMNode } from '../nodes/llm-node.js';
+import { ToolNode } from '../nodes/tool-node.js';
+import { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
+import { ToolResultInjector } from '../../tool/tool-result-injector.js';
+import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
+import { EchoLLMProvider } from '../../providers/echo-llm-provider.js';
+import { ConditionEvaluator } from '../condition-evaluator.js';
+import { SystemPromptBuilder, loadedToolsToApiTools, filterLoadedToolsForSkill } from '../../tool/system-prompt-builder.js';
+import { bindSelectedSkill } from '../nodes/skill-bind-node.js';
+import { resolveGraphPrompt } from '../resolve-graph-prompt.js';
+import { SkillAuditRecorder } from '../skill-audit-recorder.js';
+import { preloadSkillNotFound } from '../../registry/preload-errors.js';
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
+// ─────────────────────────────────────────────
+// LangGraphAdapter
+// ─────────────────────────────────────────────
+/**
+ * LangGraphAdapter — 基于 @langchain/langgraph 的 IStateGraphEngine 实现
+ *
+ * 职责：
+ * 1. 解析 GraphDSL → 注册节点、添加边/条件路由 → 编译为可执行图
+ * 2. 调用 LangGraph 的 stream/invoke 驱动执行
+ * 3. 提供 Checkpoint 提取与恢复能力
+ */
+export class LangGraphAdapter {
+    checkpointer;
+    subGraphCompiler;
+    llmProvider;
+    toolExecutor;
+    toolOrchestrator;
+    toolResultInjector;
+    conditionEvaluator;
+    systemPromptBuilder;
+    skillAuditRecorder;
+    /** 流式旁路：LLM token / Tool 执行事件在节点执行中实时入队 */
+    streamSink = null;
+    streamEventContext = {};
+    streamChunkIndex = 0;
+    streamIteration = 0;
+    reasoningStartedThisTurn = false;
+    streamedTextThisTurn = false;
+    /**
+     * @param checkpointSaver - 可选的 ICheckpointSaver
+     * @param llmProvider - LLM 调用提供者，默认 EchoLLMProvider
+     * @param toolExecutor - Tool 执行器（HttpToolExecutor 等）
+     */
+    governanceClient;
+    hitlHandler;
+    constructor(checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler) {
+        this.governanceClient = governanceClient;
+        this.hitlHandler = hitlHandler;
+        this.checkpointer = checkpointSaver
+            ? new LangGraphCheckpointer(checkpointSaver)
+            : undefined;
+        this.llmProvider = llmProvider ?? new EchoLLMProvider();
+        this.toolExecutor = toolExecutor;
+        this.toolOrchestrator = toolExecutor
+            ? new ToolOrchestrator(toolExecutor, governanceClient)
+            : undefined;
+        this.toolResultInjector = new ToolResultInjector();
+        this.conditionEvaluator = new ConditionEvaluator();
+        this.systemPromptBuilder = new SystemPromptBuilder();
+        this.skillAuditRecorder = new SkillAuditRecorder();
+        // ── 内置 ReAct 标准条件函数（shouldContinue）────────────────────────
+        // 判断最后一条 assistant 消息是否有 tool_calls：
+        //   有 → "call_tools"（进 tools 节点执行）
+        //   无 → "finish"（进 __end__，对话结束）
+        // 该函数会被所有 dsl 中 conditionFn="shouldContinue" 的 conditionalEdge 使用。
+        this.conditionEvaluator.register('shouldContinue', (state) => {
+            const messages = state['messages'];
+            if (!Array.isArray(messages) || messages.length === 0)
+                return 'finish';
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const msg = messages[i];
+                if (!msg || msg.role !== 'assistant')
+                    continue;
+                const toolCalls = (msg.toolCalls ?? msg.tool_calls);
+                if (Array.isArray(toolCalls) && toolCalls.length > 0)
+                    return 'call_tools';
+                return 'finish';
+            }
+            return 'finish';
+        });
+        this.conditionEvaluator.register('afterSkillRoute', (state) => {
+            const route = state['skillRoute'];
+            if (route === 'clarify')
+                return 'clarify';
+            if (route === 'skill') {
+                const skillId = state['activatedSkill'];
+                if (typeof skillId === 'string' && skillId.trim())
+                    return skillId.trim();
+                return 'skill';
+            }
+            return 'none';
+        });
+        // 必须在其他依赖初始化后再创建 SubGraphCompiler（它持有 adapter 引用）
+        this.subGraphCompiler = new SubGraphCompiler(this, governanceClient, this.skillAuditRecorder);
+    }
+    /**
+     * 注册自定义条件评估函数
+     */
+    registerConditionEvaluator(name, fn) {
+        this.conditionEvaluator.register(name, fn);
+    }
+    /**
+     * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
+     * 无 streamSink 时为空操作（纯 invoke）。
+     */
+    emitStreamEvent(event) {
+        if (!this.streamSink)
+            return;
+        this.streamSink({
+            ...event,
+            taskId: event.taskId ?? this.streamEventContext.taskId,
+            correlationId: event.correlationId ?? this.streamEventContext.correlationId,
+        });
+    }
+    /**
+     * 子图 LLM 可清零流式标志；结束后保留「已经 stream 过」以免父图 convertUpdates 再发一遍正文。
+     */
+    async runIsolatedLlmStreamFlags(work) {
+        const savedStreamed = this.streamedTextThisTurn;
+        const savedReasoning = this.reasoningStartedThisTurn;
+        this.reasoningStartedThisTurn = false;
+        this.streamedTextThisTurn = false;
+        try {
+            return await work();
+        }
+        finally {
+            this.streamedTextThisTurn = savedStreamed || this.streamedTextThisTurn;
+            this.reasoningStartedThisTurn = savedReasoning || this.reasoningStartedThisTurn;
+        }
+    }
+    /**
+     * Tool 节点执行旁路：started → tool.called + tool.progress；
+     * completed/error → 对应终态 + tool.progress。同一 toolCallId。
+     */
+    emitToolExecutionEvents(progress) {
+        if (!this.streamSink)
+            return;
+        const timestamp = new Date().toISOString();
+        const { taskId, correlationId } = this.streamEventContext;
+        const loc = {
+            ...(progress.node ? { node: progress.node } : {}),
+            ...(progress.skillId ? { skillId: progress.skillId } : {}),
+        };
+        if (progress.status === 'started') {
+            this.streamSink({
+                type: 'tool.called',
+                taskId,
+                correlationId,
+                timestamp,
+                payload: {
+                    toolCallId: progress.toolCallId,
+                    toolName: progress.toolName,
+                    arguments: progress.arguments ?? {},
+                    ...loc,
+                },
+            });
+        }
+        this.streamSink({
+            type: 'tool.progress',
+            taskId,
+            correlationId,
+            timestamp,
+            payload: { ...progress },
+        });
+        if (progress.status === 'completed') {
+            this.streamSink({
+                type: 'tool.result',
+                taskId,
+                correlationId,
+                timestamp,
+                payload: {
+                    toolCallId: progress.toolCallId,
+                    toolName: progress.toolName,
+                    content: progress.content,
+                    success: true,
+                    ...loc,
+                },
+            });
+        }
+        else if (progress.status === 'error') {
+            this.streamSink({
+                type: 'tool.error',
+                taskId,
+                correlationId,
+                timestamp,
+                payload: {
+                    toolCallId: progress.toolCallId,
+                    toolName: progress.toolName,
+                    error: progress.error ?? 'Unknown error',
+                    willRetry: false,
+                    ...loc,
+                },
+            });
+        }
+    }
+    /**
+     * 解析 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() 编译
+     */
+    async buildGraph(dsl) {
+        this.assertShouldContinueTargetsTool(dsl);
+        const silentNodeIds = new Set(dsl.nodes
+            .filter((node) => node.type === 'llm' && node.config?.['silent'] === true)
+            .map((node) => node.id));
+        const subgraphNodeIds = new Set(dsl.nodes.filter((node) => node.type === 'subgraph').map((node) => node.id));
+        // 创建 StateGraph，使用简单的 messages channel
+        // 辅助 channel 采用 ephemeral 语义（value=最后写入者胜出），保证 loadedTools/executionContext
+        // 等运行期上下文在节点间透传，不会被 LangGraph 按 schema 过滤掉。
+        const ephemeral = (defaultValue) => ({
+            value: (_current, update) => (update === undefined ? _current : update),
+            default: () => defaultValue,
+        });
+        const stateGraph = new StateGraph({
+            channels: {
+                messages: {
+                    value: (current, update) => {
+                        if (update && typeof update === 'object' && !Array.isArray(update)) {
+                            const replace = update.__set;
+                            if (Array.isArray(replace))
+                                return replace;
+                        }
+                        return Array.isArray(current) && Array.isArray(update)
+                            ? [...current, ...update]
+                            : update ?? current;
+                    },
+                    default: () => [],
+                },
+                currentNode: {
+                    value: (_current, update) => update,
+                    default: () => '',
+                },
+                // ── 运行期上下文（ephemeral）：由 invoke/stream 入口注入，节点只读 ──
+                userId: ephemeral(''),
+                // agentId 已废弃：channel 保留仅为旧 Checkpoint 反序列化兼容，新代码只写 agentCode
+                agentId: ephemeral(''),
+                agentCode: ephemeral(''),
+                agentVersion: ephemeral(undefined),
+                delegationToken: ephemeral(''),
+                correlationId: ephemeral(''),
+                taskId: ephemeral(''),
+                sessionId: ephemeral(''),
+                loadedTools: ephemeral(undefined),
+                loadedSkills: ephemeral(undefined),
+                skillDefinitions: ephemeral(undefined),
+                skillInput: ephemeral(undefined),
+                activeSkillPrompt: ephemeral(undefined),
+                activatedSkill: ephemeral(undefined),
+                skillRoute: ephemeral(undefined),
+                skillSelectRaw: ephemeral(undefined),
+                silentOutput: ephemeral(undefined),
+                promptRoots: ephemeral(undefined),
+                executionContext: ephemeral(undefined),
+                forceToolServer: ephemeral(undefined),
+                traceCollector: ephemeral(undefined),
+                traceId: ephemeral(undefined),
+                skillSpanId: ephemeral(undefined),
+                hitlChoice: ephemeral(undefined),
+                // ── LLM Token 使用量：数组累加器 reducer，每次 LLM 节点追加一条使用明细
+                __llmTokenUsage: {
+                    value: (current, update) => {
+                        const cur = Array.isArray(current) ? current : [];
+                        const upd = Array.isArray(update) ? update : [];
+                        return [...cur, ...upd];
+                    },
+                    default: () => [],
+                },
+                __parallelResults: ephemeral(undefined),
+                __codeResult: ephemeral(undefined),
+                __codeError: ephemeral(undefined),
+                __conditionResult: ephemeral(undefined),
+            },
+        });
+        // 注册节点
+        for (const node of dsl.nodes) {
+            const nodeFn = this.createNodeFunction(node);
+            stateGraph.addNode(node.id, nodeFn);
+        }
+        // 入口：优先 edges 里的 __start__；若同时配置了 entryPoint，只保留一种，避免 LangGraph
+        // “EphemeralValue can only receive one value per step”（__start__ 被加两次）
+        const entryPoint = dsl.entryPoint ?? dsl.nodes[0]?.id;
+        const hasStartEdge = dsl.edges.some((e) => e.from === '__start__');
+        // 添加普通边
+        for (const edge of dsl.edges) {
+            if (edge.from === '__start__' && entryPoint && entryPoint !== '__start__' && hasStartEdge) {
+                // 用 setEntryPoint(entryPoint) 统一入口，跳过显式 __start__ 边
+                continue;
+            }
+            const from = edge.from === '__start__' ? START : edge.from;
+            const to = edge.to === '__end__' ? END : edge.to;
+            stateGraph.addEdge(from, to);
+        }
+        // 添加条件路由边
+        if (dsl.conditionalEdges) {
+            for (const condEdge of dsl.conditionalEdges) {
+                this.addConditionalEdge(stateGraph, condEdge);
+            }
+        }
+        // 设置入口节点（仅当 edges 未声明 __start__ 时）
+        if (entryPoint && entryPoint !== '__start__') {
+            stateGraph.setEntryPoint(entryPoint);
+        }
+        // 设置终止节点
+        if (dsl.finishPoints) {
+            for (const fp of dsl.finishPoints) {
+                if (fp !== '__end__') {
+                    stateGraph.setFinishPoint(fp);
+                }
+            }
+        }
+        // 编译（若有 checkpointer 则注入，启用 Checkpoint 持久化）
+        const compileOptions = {};
+        if (this.checkpointer) {
+            compileOptions.checkpointer = this.checkpointer;
+        }
+        const compiled = stateGraph.compile(compileOptions);
+        // 构造 ExecutableGraph
+        const executableGraph = {
+            id: `graph-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            name: dsl.name ?? 'unnamed',
+            status: 'idle',
+            nodeIds: dsl.nodes.map((n) => n.id),
+            entryPoint: entryPoint ?? '__start__',
+            finishPoints: dsl.finishPoints ?? ['__end__'],
+            dslVersion: dsl.version ?? '0.0.0',
+            compiledAt: new Date().toISOString(),
+            _engineInstance: { compiled, dsl, silentNodeIds, subgraphNodeIds },
+        };
+        return executableGraph;
+    }
+    /**
+     * 流式驱动图执行，逐步 yield RuntimeEvent
+     *
+     * - LangGraph `streamMode: "updates"`：节点完成后产出 response.chunk / stats 等
+     * - LLM token / Tool 执行事件：经 streamSink 在节点执行中实时旁路入队
+     * （当前 @langchain/langgraph@0.2 无 messages mode，故用 LLMNode.onChunk 模拟）
+     */
+    async *stream(graph, state) {
+        const ref = this.getCompiledRef(graph);
+        const input = this.graphStateToLangGraphInput(state);
+        const queue = [];
+        const waiter = { fn: null };
+        let finished = false;
+        let failure = null;
+        const signal = () => {
+            const fn = waiter.fn;
+            waiter.fn = null;
+            if (fn)
+                fn();
+        };
+        const enqueue = (event) => {
+            queue.push({
+                ...event,
+                taskId: event.taskId ?? state.taskId,
+                correlationId: event.correlationId ?? state.correlationId,
+            });
+            signal();
+        };
+        this.streamSink = enqueue;
+        this.streamEventContext = { taskId: state.taskId, correlationId: state.correlationId };
+        this.streamChunkIndex = 0;
+        this.streamIteration = 0;
+        this.reasoningStartedThisTurn = false;
+        this.streamedTextThisTurn = false;
+        const producer = (async () => {
+            try {
+                const streamIterator = await ref.compiled.stream(input, {
+                    configurable: {
+                        thread_id: resolveCheckpointThreadId({
+                            sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
+                            taskId: state.taskId,
+                            graphId: graph.id,
+                        }),
+                    },
+                    streamMode: 'updates',
+                });
+                for await (const update of streamIterator) {
+                    for (const event of this.convertUpdatesToEvents(update, graph.id, () => this.streamChunkIndex++, ref.silentNodeIds, ref.subgraphNodeIds)) {
+                        enqueue(event);
+                    }
+                }
+            }
+            catch (err) {
+                failure = err;
+            }
+            finally {
+                finished = true;
+                this.streamSink = null;
+                this.streamEventContext = {};
+                signal();
+            }
+        })();
+        while (!finished || queue.length > 0) {
+            if (queue.length === 0) {
+                await new Promise((resolve) => {
+                    waiter.fn = resolve;
+                });
+                continue;
+            }
+            yield queue.shift();
+        }
+        await producer;
+        if (failure)
+            throw failure;
+    }
+    /**
+     * 同步调用图执行，返回完整结果
+     */
+    async invoke(graph, state) {
+        const ref = this.getCompiledRef(graph);
+        const input = this.graphStateToLangGraphInput(state);
+        const startTime = Date.now();
+        const result = await ref.compiled.invoke(input, {
+            configurable: {
+                thread_id: resolveCheckpointThreadId({
+                    sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
+                    taskId: state.taskId,
+                    graphId: graph.id,
+                }),
+            },
+        });
+        const duration = Date.now() - startTime;
+        const messages = Array.isArray(result['messages']) ? result['messages'] : [];
+        const lastMessage = messages[messages.length - 1];
+        const output = typeof lastMessage === 'object' && lastMessage !== null && 'content' in lastMessage
+            ? String(lastMessage.content)
+            : '';
+        // ── Token 累计：从 __llmTokenUsage 数组累加器读取每轮 LLM 明细 + 汇总
+        //    数组由 channel reducer 自动累加（每次 LLM 节点追加一条）。
+        const llmUsageArray = Array.isArray(result['__llmTokenUsage'])
+            ? result['__llmTokenUsage']
+            : [];
+        const perNode = llmUsageArray.map((u) => ({
+            nodeId: u.nodeId ?? 'unknown',
+            model: u.model ?? 'unknown',
+            inputTokens: u.inputTokens ?? 0,
+            outputTokens: u.outputTokens ?? 0,
+        }));
+        const inputTokens = perNode.reduce((s, u) => s + u.inputTokens, 0);
+        const outputTokens = perNode.reduce((s, u) => s + u.outputTokens, 0);
+        return {
+            output,
+            finalState: {
+                ...result,
+                ...state,
+                messages: Array.isArray(result['messages'])
+                    ? result['messages']
+                    : state.messages,
+                userId: state.userId,
+                loadedTools: state.loadedTools ?? result.loadedTools,
+                forceToolServer: state.forceToolServer ?? result.forceToolServer,
+                executionContext: state.executionContext ?? result.executionContext,
+            },
+            tokenUsage: {
+                input: inputTokens,
+                output: outputTokens,
+                total: inputTokens + outputTokens,
+                perNode,
+            },
+            duration,
+        };
+    }
+    /**
+     * 从运行中的图提取 Checkpoint
+     *
+     * 提取当前执行状态为可持久化的 CheckpointData。
+     */
+    checkpoint(graph) {
+        const now = new Date().toISOString();
+        return {
+            checkpointId: `cp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            threadId: resolveCheckpointThreadId({ graphId: graph.id }),
+            currentNodeId: graph.entryPoint,
+            historyPath: [],
+            state: {
+                messages: [],
+                userId: '',
+            },
+            createdBy: 'system',
+            createdAt: now,
+            updatedBy: 'system',
+            updatedAt: now,
+            isDeleted: false,
+        };
+    }
+    /**
+     * 从 CheckpointData 恢复可执行图
+     *
+     * HITL / Fork 续跑请走 `buildGraph(dsl)` + 同一 `thread_id` 的 state。
+     * 本方法无 DSL，无法编译出可用 `_engineInstance`。
+     */
+    async restore(checkpointData) {
+        // 恢复场景下，需要从 checkpointData 中重建图
+        // 实际使用时，DSL 应从外部存储（如 Agent Registry）获取
+        // 此处构建一个占位的 ExecutableGraph
+        const restoredGraph = {
+            id: `graph-restored-${Date.now()}`,
+            name: `restored-${checkpointData.threadId}`,
+            status: 'paused',
+            nodeIds: [],
+            entryPoint: checkpointData.currentNodeId,
+            finishPoints: ['__end__'],
+            dslVersion: '0.0.0',
+            compiledAt: new Date().toISOString(),
+            _engineInstance: undefined,
+        };
+        return restoredGraph;
+    }
+    // ─────────────────────────────────────────────
+    // Private helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 根据节点类型创建对应的执行函数
+     */
+    createNodeFunction(node) {
+        switch (node.type) {
+            case 'llm':
+                return this.createLLMNodeFunction(node);
+            case 'tool':
+                return this.createToolNodeFunction(node);
+            case 'condition':
+                return async (state) => {
+                    // 条件节点：根据 config 中的 conditionExpr 评估并写入 __conditionResult
+                    const conditionExpr = node.config?.['conditionExpr']
+                        ?? node.config?.['conditionFn'];
+                    if (conditionExpr) {
+                        const branchValues = node.config?.['branchValues']
+                            ?? this.extractBranchValuesFromDsl(node.id);
+                        const result = await this.conditionEvaluator.evaluate(conditionExpr, state, branchValues, node.config?.['fallback'] ?? '__default__');
+                        return { ...state, currentNode: node.id, __conditionResult: result };
+                    }
+                    // 无表达式时透传（由 addConditionalEdge 自行处理）
+                    return { ...state, currentNode: node.id };
+                };
+            case 'subgraph':
+                return this.createSubGraphNodeFunction(node);
+            case 'human':
+                return async (state) => {
+                    // HITL 节点：暂停等待人工介入（Task 14）
+                    return { ...state, currentNode: node.id };
+                };
+            case 'parallel':
+                return this.createParallelNodeFunction(node);
+            case 'code':
+                if (node.config?.['bindSkill'] === true) {
+                    return this.createSkillBindNodeFunction(node);
+                }
+                return this.createCodeNodeFunction(node);
+            default:
+                if (node.config?.['bindSkill'] === true) {
+                    return this.createSkillBindNodeFunction(node);
+                }
+                return async (state) => {
+                    return { ...state, currentNode: node.id };
+                };
+        }
+    }
+    createSkillBindNodeFunction(node) {
+        return async (state) => {
+            const patch = bindSelectedSkill(state);
+            if (patch.skillRoute === 'skill' && patch.activatedSkill) {
+                this.emitStreamEvent({
+                    type: 'skill.matched',
+                    taskId: undefined,
+                    correlationId: undefined,
+                    timestamp: new Date().toISOString(),
+                    payload: {
+                        skillName: patch.skillName || patch.activatedSkill,
+                        skillId: patch.activatedSkill,
+                        confidence: 1,
+                    },
+                });
+            }
+            else if (patch.unmatched) {
+                this.emitStreamEvent({
+                    type: 'skill.unmatched',
+                    taskId: undefined,
+                    correlationId: undefined,
+                    timestamp: new Date().toISOString(),
+                    payload: {
+                        userInput: '',
+                        userIntent: 'none',
+                        keywords: [],
+                        reason: 'skill not in assembled catalog',
+                    },
+                });
+            }
+            if (patch.skillRoute === 'clarify' && this.streamSink) {
+                const question = patch.messages.at(-1)?.content;
+                if (typeof question === 'string' && question.trim()) {
+                    this.streamSink({
+                        type: 'response.chunk',
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp: new Date().toISOString(),
+                        payload: { content: question, index: this.streamChunkIndex++, node: node.id },
+                    });
+                }
+            }
+            return {
+                currentNode: node.id,
+                skillRoute: patch.skillRoute,
+                activatedSkill: patch.activatedSkill,
+                activeSkillPrompt: patch.activeSkillPrompt,
+                skillInput: patch.skillInput,
+                messages: { __set: patch.messages },
+            };
+        };
+    }
+    buildSkillCatalog(defs) {
+        if (!defs)
+            return undefined;
+        const rows = Object.values(defs).map((skill) => {
+            const desc = (skill.description ?? '').replace(/\s+/g, ' ').trim();
+            return `- ${skill.skillId}${skill.name && skill.name !== skill.skillId ? `（${skill.name}）` : ''}${desc ? `：${desc}` : ''}`;
+        });
+        if (rows.length === 0)
+            return undefined;
+        return `# 可用技能\n下列技能已装配，引用时使用 skillId 或 name。\n${rows.join('\n')}`;
+    }
+    createToolNodeFunction(node) {
+        const toolName = node.config?.['tool'] ?? node.id;
+        const defaultArgs = node.config?.['arguments'] ?? {};
+        if (this.toolOrchestrator) {
+            const toolNode = new ToolNode(this.toolOrchestrator, this.toolResultInjector, {
+                userId: 'system',
+                delegationToken: '',
+                agentCode: '',
+            }, (progress) => this.emitToolExecutionEvents(progress), this.hitlHandler, node.id);
+            return (state) => toolNode.execute(state);
+        }
+        if (this.toolExecutor) {
+            return async (state) => {
+                const userId = String(state['userId'] ?? 'system');
+                const delegationToken = String(state['delegationToken'] ?? '');
+                const agentCode = String(state['agentCode'] ?? state['agentId'] ?? userId);
+                const correlationId = String(state['correlationId'] ?? `tc-${node.id}`);
+                const taskId = String(state['taskId'] ?? state['correlationId'] ?? `tc-${node.id}`);
+                const toolCallId = `tc-${node.id}`;
+                const startedAt = Date.now();
+                this.emitToolExecutionEvents({
+                    toolCallId,
+                    toolName,
+                    status: 'started',
+                    arguments: defaultArgs,
+                    node: node.id,
+                });
+                const result = await this.toolExecutor.execute({
+                    toolCallId,
+                    toolName,
+                    arguments: defaultArgs,
+                    authContext: { userId, delegationToken, agentCode },
+                    correlationId,
+                    taskId,
+                });
+                const executionTime = Date.now() - startedAt;
+                this.emitToolExecutionEvents({
+                    toolCallId: result.toolCallId,
+                    toolName: result.toolName,
+                    status: result.success ? 'completed' : 'error',
+                    content: result.content,
+                    error: result.error,
+                    executionTime,
+                    node: node.id,
+                });
+                // 重要：messages channel 的 reducer 是 append 语义，只返回新增消息
+                return {
+                    messages: [
+                        {
+                            role: 'tool',
+                            content: result.content || JSON.stringify(result),
+                            toolCallId,
+                            toolName,
+                            success: result.success ?? true,
+                        },
+                    ],
+                    currentNode: node.id,
+                };
+            };
+        }
+        // 无 toolOrchestrator / toolExecutor 时：兑底生成 skipped tool message
+        return async (_state) => {
+            return {
+                messages: [
+                    {
+                        role: 'tool',
+                        content: JSON.stringify({ toolName, skipped: true }),
+                        toolCallId: `tc-${node.id}`,
+                        toolName,
+                        success: false,
+                    },
+                ],
+                currentNode: node.id,
+            };
+        };
+    }
+    createLLMNodeFunction(node) {
+        const rawPrompt = (typeof node.config?.['systemPromptFile'] === 'string' && node.config['systemPromptFile'])
+            || (typeof node.config?.['systemPrompt'] === 'string' ? node.config['systemPrompt'] : undefined);
+        const baseConfig = {
+            model: node.config?.['model'] ?? 'default',
+            systemPrompt: typeof rawPrompt === 'string' ? rawPrompt : undefined,
+            temperature: node.config?.['temperature'],
+            maxTokens: node.config?.['maxTokens'],
+            tools: node.config?.['tools'],
+            toolChoice: node.config?.['toolChoice'],
+        };
+        const disableTools = node.config?.['disableTools'] === true;
+        const includeSkillCatalog = node.config?.['includeSkillCatalog'] === true;
+        const silent = node.config?.['silent'] === true;
+        return async (state) => {
+            // HITL 续跑：已有未闭合 toolCalls + hitlChoice 时不要再调 LLM（否则会换新 toolCallId）
+            const hitlChoice = state['hitlChoice'];
+            const rawMessages = Array.isArray(state['messages']) ? state['messages'] : [];
+            if (!disableTools &&
+                !silent &&
+                isHitlDecision(hitlChoice) &&
+                lastAssistantHasUnansweredToolCalls(rawMessages)) {
+                return { currentNode: node.id };
+            }
+            const promptRoots = Array.isArray(state['promptRoots']) ? state['promptRoots'] : [];
+            const resolvedPrompt = resolveGraphPrompt(baseConfig.systemPrompt, promptRoots);
+            const loadedTools = state['loadedTools'];
+            // 旧 Checkpoint 兼容：agentId 仅作读兜底
+            const agentCode = (state['agentCode'] ?? state['agentId']);
+            const activeSkillPrompt = state['activeSkillPrompt'];
+            const skillDefs = state['skillDefinitions'];
+            const activatedSkillId = state['activatedSkill'];
+            // [DEBUG] 打印 loadedTools 实际状态
+            if (process.env.EAP_LLM_DEBUG === '1') {
+                const toolNames = loadedTools ? Object.keys(loadedTools) : [];
+                console.log(`[LLM-DEBUG] node=${node.id} loadedTools=${toolNames.length}:`, toolNames);
+            }
+            const catalog = includeSkillCatalog ? this.buildSkillCatalog(skillDefs) : undefined;
+            const developerPrompt = [catalog, activeSkillPrompt, resolvedPrompt]
+                .filter((s) => Boolean(s && s.trim()))
+                .join('\n\n');
+            const execCtx = state['executionContext'];
+            const userId = (typeof execCtx?.userId === 'string' && execCtx.userId) || state['userId'];
+            // 1. 构建 system prompt（平台规则 + 技能提示 + 开发者提示词）
+            const builtPrompt = this.systemPromptBuilder.build({
+                developerPrompt: developerPrompt || undefined,
+                agentCode,
+                userId,
+            });
+            // 2. 工具走 API 的 tools 参数，不塞进 system prompt
+            const scopedTools = activatedSkillId && skillDefs
+                ? filterLoadedToolsForSkill(loadedTools, skillDefs[activatedSkillId])
+                : loadedTools;
+            const apiTools = disableTools ? [] : loadedToolsToApiTools(scopedTools);
+            const finalConfig = {
+                ...baseConfig,
+                systemPrompt: builtPrompt,
+                tools: disableTools ? undefined : (apiTools.length > 0 ? apiTools : baseConfig.tools),
+                toolChoice: disableTools ? 'none' : baseConfig.toolChoice,
+            };
+            // 流式旁路：有 streamSink 时启用 LLM token 推送；silent 节点不推给用户
+            const enableStream = Boolean(this.streamSink) && !silent;
+            this.reasoningStartedThisTurn = false;
+            this.streamedTextThisTurn = false;
+            const llmNode = new LLMNode(node.id, finalConfig, this.llmProvider, enableStream, enableStream
+                ? (text) => {
+                    if (!this.streamSink || !text)
+                        return;
+                    const timestamp = new Date().toISOString();
+                    if (!this.reasoningStartedThisTurn) {
+                        this.reasoningStartedThisTurn = true;
+                        this.streamIteration += 1;
+                        this.streamSink({
+                            type: 'reasoning.started',
+                            taskId: undefined,
+                            correlationId: undefined,
+                            timestamp,
+                            payload: {
+                                iterationCount: this.streamIteration,
+                                model: finalConfig.model,
+                            },
+                        });
+                    }
+                    this.streamedTextThisTurn = true;
+                    this.streamSink({
+                        type: 'response.chunk',
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp,
+                        payload: {
+                            content: text,
+                            index: this.streamChunkIndex++,
+                            node: node.id,
+                        },
+                    });
+                }
+                : undefined);
+            const next = await llmNode.execute(state);
+            if (!silent)
+                return next;
+            const added = Array.isArray(next.messages) ? next.messages[0] : undefined;
+            const raw = added && typeof added === 'object' && typeof added.content === 'string'
+                ? added.content
+                : '';
+            return {
+                ...next,
+                messages: [],
+                silentOutput: raw,
+                skillSelectRaw: raw,
+            };
+        };
+    }
+    /**
+     * 子图节点：优先 config.subgraphDsl；否则按 skillId 从 state.skillDefinitions.workflow 解析。
+     * 技能 prompt 由 SubGraphCompiler 写入 activeSkillPrompt，供入口 LLM 拼接。
+     */
+    createSubGraphNodeFunction(node) {
+        const embeddedDsl = node.config?.['subgraphDsl'];
+        const configuredSkillId = node.subgraphId ??
+            node.config?.['skillId'] ??
+            embeddedDsl?.name;
+        if (embeddedDsl) {
+            return this.subGraphCompiler.compileSubGraph(embeddedDsl, configuredSkillId);
+        }
+        return async (state) => {
+            const skillId = configuredSkillId ??
+                (typeof node.config?.['skillCode'] === 'string' ? node.config['skillCode'] : undefined);
+            const defs = state['skillDefinitions'];
+            const def = skillId && defs ? defs[skillId] : undefined;
+            const workflow = def?.workflow;
+            if (!workflow?.nodes?.length) {
+                throw preloadSkillNotFound(`子图节点无法解析 Skill workflow: node=${node.id}, skillId=${skillId ?? '(none)'}`, { nodeId: node.id, skillId });
+            }
+            const fn = this.subGraphCompiler.compileSubGraph(workflow, skillId ?? def?.skillId);
+            return fn(state);
+        };
+    }
+    /**
+     * 并行节点：并行执行多个子任务分支
+     *
+     * 支持两种并行模式：
+     * 1. branches 模式：node.branches 列出要并行执行的节点 ID，每个节点的执行函数由 DSL 定义
+     * 2. tasks 模式：node.config.tasks 列出要并行执行的异步任务函数
+     *
+     * 执行结果合并到 state.__parallelResults 中。
+     */
+    createParallelNodeFunction(node) {
+        return async (state) => {
+            const branchNodeIds = node.branches ?? node.config?.['branches'] ?? [];
+            const tasks = node.config?.['tasks'];
+            const results = [];
+            if (tasks?.length) {
+                // tasks 模式：并行执行配置的任务
+                const promises = tasks.map(async (task) => {
+                    try {
+                        // 任务结果由外部注入的 task executor 处理
+                        // 此处仅记录任务 ID，实际执行依赖外部编排
+                        return { branchId: task.id, success: true, result: { taskId: task.id, status: 'dispatched' } };
+                    }
+                    catch (err) {
+                        return {
+                            branchId: task.id,
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                });
+                results.push(...await Promise.all(promises));
+            }
+            else if (branchNodeIds.length) {
+                // branches 模式：并行执行分支节点
+                const promises = branchNodeIds.map(async (branchId) => {
+                    try {
+                        // 每个分支节点的实际执行由 LangGraph 编排层驱动
+                        // 并行节点仅负责触发并汇总状态
+                        return { branchId, success: true, result: { dispatched: true } };
+                    }
+                    catch (err) {
+                        return {
+                            branchId,
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                });
+                results.push(...await Promise.all(promises));
+            }
+            const allSuccess = results.every((r) => r.success);
+            return {
+                ...state,
+                currentNode: node.id,
+                __parallelResults: results,
+                __parallelAllSuccess: allSuccess,
+                __conditionResult: allSuccess ? 'success' : 'partial_failure',
+            };
+        };
+    }
+    /**
+     * 代码执行节点：在受限沙箱中执行用户代码
+     *
+     * 支持两种模式：
+     * 1. inline：node.config.code 为内联 JavaScript/TypeScript 代码字符串
+     * 2. handler：node.config.handler 为外部模块路径 + 函数名
+     *
+     * 安全措施：
+     * - 禁止 require/import 动态加载
+     * - 执行超时控制（默认 5000ms）
+     * - 限制可访问的 state 字段
+     */
+    createCodeNodeFunction(node) {
+        const code = node.config?.['code'];
+        const handler = node.config?.['handler'];
+        const timeoutMs = node.config?.['timeoutMs'] ?? 5000;
+        return async (state) => {
+            try {
+                let result;
+                if (code) {
+                    // inline 模式：在受限沙箱中执行
+                    result = await this.executeCodeInSandbox(code, state, timeoutMs);
+                }
+                else if (handler) {
+                    // handler 模式：记录警告，待外部实现
+                    result = { handler, status: 'skipped', reason: 'External handler execution not yet supported' };
+                }
+                else {
+                    result = { status: 'skipped', reason: 'No code or handler configured' };
+                }
+                const messages = [
+                    { role: 'tool', content: JSON.stringify({ nodeId: node.id, codeResult: result }) },
+                ];
+                if (node.config?.['emitReply'] === true
+                    && result && typeof result === 'object'
+                    && typeof result.reply === 'string') {
+                    const reply = result.reply.trim();
+                    if (reply)
+                        messages.push({ role: 'assistant', content: reply });
+                }
+                return {
+                    currentNode: node.id,
+                    __codeResult: result,
+                    messages,
+                };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                return {
+                    currentNode: node.id,
+                    __codeResult: { error },
+                    __codeError: error,
+                };
+            }
+        };
+    }
+    /**
+     * 受限沙箱执行代码
+     *
+     * 使用 Function 构造器 + 超时控制，禁止动态模块加载。
+     * 注意：这不是完整的安全沙箱，生产环境应使用 vm2/isolated-vm 或容器化方案。
+     */
+    async executeCodeInSandbox(code, state, timeoutMs) {
+        // 安全检查：禁止动态加载
+        const forbidden = ['require(', 'import(', 'eval(', 'Function('];
+        for (const pattern of forbidden) {
+            if (code.includes(pattern)) {
+                throw new Error(`Code execution forbidden: ${pattern} is not allowed in sandbox`);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`Code execution timeout: ${timeoutMs}ms`)), timeoutMs);
+            try {
+                // 构造受限执行环境：仅暴露 state 和 console 的简化版本
+                const sandboxConsole = {
+                    log: (...args) => { },
+                };
+                const fn = new Function('state', 'console', `
+          "use strict";
+          ${code}
+        `);
+                const result = fn(state, sandboxConsole);
+                clearTimeout(timer);
+                resolve(result instanceof Promise ? result : result);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                reject(err);
+            }
+        });
+    }
+    /**
+     * 从 DSL 中提取条件节点关联的分支值
+     */
+    extractBranchValuesFromDsl(nodeId) {
+        // 从 DSL 的 conditionalEdges 中查找以当前节点为 from 的分支值
+        // 此方法在 buildGraph 时可通过缓存 DSL 优化，当前为运行时查找
+        return [];
+    }
+    /**
+     * shouldContinue 的 call_tools 只能进 type:tool。
+     * 禁止指向 subgraph / llm / code：那是路由信号，不是 Tool 执行。
+     * 内嵌 subgraphDsl 同样校验。
+     */
+    assertShouldContinueTargetsTool(dsl) {
+        const graphName = dsl.name ?? 'unnamed';
+        const byId = new Map(dsl.nodes.map((node) => [node.id, node]));
+        for (const edge of dsl.conditionalEdges ?? []) {
+            if (edge.conditionFn !== 'shouldContinue')
+                continue;
+            for (const branch of edge.branches) {
+                if (branch.value !== 'call_tools')
+                    continue;
+                if (branch.to === '__end__') {
+                    throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph "${graphName}": shouldContinue call_tools cannot target __end__; must be type:tool`, { exposeMessage: true });
+                }
+                const target = byId.get(branch.to);
+                if (!target) {
+                    throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph "${graphName}": shouldContinue call_tools target "${branch.to}" is not a node`, { exposeMessage: true });
+                }
+                if (target.type !== 'tool') {
+                    throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph "${graphName}": shouldContinue call_tools must target type:tool, got type:${target.type} node "${branch.to}"`, { exposeMessage: true });
+                }
+            }
+        }
+        for (const node of dsl.nodes) {
+            const nested = node.config?.['subgraphDsl'];
+            if (nested?.nodes?.length)
+                this.assertShouldContinueTargetsTool(nested);
+        }
+    }
+    /**
+     * 添加条件路由边到 StateGraph
+     *
+     * 使用 ConditionEvaluator 对 DSL 中的 conditionFn 表达式求值，
+     * 支持 stateField 引用、简单表达式和自定义评估函数。
+     */
+    addConditionalEdge(stateGraph, condEdge) {
+        const from = condEdge.from === '__start__' ? START : condEdge.from;
+        // 构建路由映射 { branchValue → targetNodeId }
+        const mapping = {};
+        for (const branch of condEdge.branches) {
+            mapping[branch.value] = branch.to === '__end__' ? END : branch.to;
+        }
+        // 默认 fallback
+        const fallbackKey = '__default__';
+        if (condEdge.fallback) {
+            mapping[fallbackKey] = condEdge.fallback === '__end__' ? END : condEdge.fallback;
+        }
+        const branchValues = condEdge.branches.map((b) => b.value);
+        const conditionExpr = condEdge.conditionFn;
+        // 条件函数：使用 ConditionEvaluator 真实求值
+        const conditionFn = async (state) => {
+            const result = await this.conditionEvaluator.evaluate(conditionExpr, state, branchValues, fallbackKey);
+            return result;
+        };
+        stateGraph.addConditionalEdges(from, conditionFn, mapping);
+    }
+    /**
+     * 获取编译后图的内部引用
+     */
+    getCompiledRef(graph) {
+        const ref = graph._engineInstance;
+        if (!ref?.compiled) {
+            throw new Error(`Graph "${graph.name}" (${graph.id}) has no compiled engine instance. ` +
+                'Ensure buildGraph() was called or the graph was properly restored.');
+        }
+        return ref;
+    }
+    /**
+     * 将 GraphState 转换为 LangGraph 输入格式。
+     * 必须原样保留 toolCalls / toolCallId / reasoningContent 等字段，
+     * 否则多轮回放时 DeepSeek thinking 会因缺少 reasoning_content 而 400，
+     * tool 消息也会丢掉 tool_call_id。
+     */
+    graphStateToLangGraphInput(state) {
+        const mapped = (state.messages ?? []).map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+            ...(msg.toolCalls?.length ? { toolCalls: msg.toolCalls } : {}),
+            ...(msg.toolCallId ? { toolCallId: msg.toolCallId } : {}),
+            ...(msg.toolName ? { toolName: msg.toolName } : {}),
+            ...(typeof msg.success === 'boolean' ? { success: msg.success } : {}),
+            ...(msg.reasoningContent ? { reasoningContent: msg.reasoningContent } : {}),
+            ...(msg.file ? { file: msg.file } : {}),
+        }));
+        return {
+            ...state,
+            messages: state.replaceCheckpointMessages ? { __set: mapped } : mapped,
+        };
+    }
+    /**
+     * 将 LangGraph updates 模式输出转为平台 RuntimeEvent 序列
+     *
+     * updates 形态：`{ [nodeId]: partialState }`；partialState.messages 仅为该节点新增消息。
+     */
+    *convertUpdatesToEvents(update, graphId, nextChunkIndex, silentNodeIds = new Set(), subgraphNodeIds = new Set()) {
+        const timestamp = new Date().toISOString();
+        const entries = this.normalizeStreamUpdates(update);
+        for (const { nodeId, data } of entries) {
+            // LLM 节点 token 明细（写入 __llmTokenUsage）→ stats.node_token_usage
+            const usages = data['__llmTokenUsage'];
+            if (Array.isArray(usages)) {
+                for (const raw of usages) {
+                    if (!raw || typeof raw !== 'object')
+                        continue;
+                    const u = raw;
+                    yield {
+                        type: 'stats.node_token_usage',
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp,
+                        payload: {
+                            nodeId: String(u['nodeId'] ?? nodeId),
+                            model: String(u['model'] ?? 'unknown'),
+                            inputTokens: Number(u['inputTokens'] ?? 0),
+                            outputTokens: Number(u['outputTokens'] ?? 0),
+                            costEstimate: Number(u['costEstimate'] ?? 0),
+                            durationMs: typeof u['durationMs'] === 'number' ? u['durationMs'] : undefined,
+                            graphId,
+                        },
+                    };
+                }
+            }
+            const messages = this.extractMessagesFromPartial(data);
+            for (const msg of messages) {
+                if (msg.role === 'assistant' && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0) {
+                    // tool.called 由 Tool 节点在真正执行时发出，此处不再把 LLM function-call 当执行开始
+                    // 子图节点的 updates 是内层已 stream 过的回写，不要再发空 reasoning chunk
+                    if (subgraphNodeIds.has(nodeId) || silentNodeIds.has(nodeId)) {
+                        continue;
+                    }
+                    const hasText = typeof msg.content === 'string' && msg.content.trim().length > 0;
+                    if ((hasText || msg.reasoningContent) &&
+                        (!this.streamedTextThisTurn || msg.reasoningContent)) {
+                        if (this.streamedTextThisTurn && !msg.reasoningContent)
+                            continue;
+                        yield {
+                            type: 'response.chunk',
+                            taskId: undefined,
+                            correlationId: undefined,
+                            timestamp,
+                            payload: {
+                                content: this.streamedTextThisTurn ? '' : (msg.content ?? ''),
+                                index: nextChunkIndex(),
+                                node: nodeId,
+                                graphId,
+                                ...(msg.reasoningContent
+                                    ? { reasoningContent: msg.reasoningContent }
+                                    : {}),
+                            },
+                        };
+                    }
+                    continue;
+                }
+                if (msg.role === 'assistant' && typeof msg.content === 'string' && msg.content.length > 0) {
+                    if (silentNodeIds.has(nodeId) || subgraphNodeIds.has(nodeId))
+                        continue;
+                    // 已通过 onChunk 推送过 token，避免整段重复
+                    if (this.streamedTextThisTurn) {
+                        // token 已流过：仍补发一条带 reasoning 的标记 chunk（空 content），供落库回传
+                        if (msg.reasoningContent) {
+                            yield {
+                                type: 'response.chunk',
+                                taskId: undefined,
+                                correlationId: undefined,
+                                timestamp,
+                                payload: {
+                                    content: '',
+                                    index: nextChunkIndex(),
+                                    node: nodeId,
+                                    graphId,
+                                    reasoningContent: msg.reasoningContent,
+                                },
+                            };
+                        }
+                        continue;
+                    }
+                    yield {
+                        type: 'response.chunk',
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp,
+                        payload: {
+                            content: msg.content,
+                            index: nextChunkIndex(),
+                            node: nodeId,
+                            graphId,
+                            ...(msg.reasoningContent
+                                ? { reasoningContent: msg.reasoningContent }
+                                : {}),
+                        },
+                    };
+                    continue;
+                }
+                if (msg.role === 'tool') {
+                    // tool.result / tool.error 由 Tool 节点旁路发出，此处只补 file.created
+                    const raw = typeof msg.content === 'string' ? msg.content : '';
+                    const file = msg.file ?? fileArtifactFromToolOutput(raw);
+                    if (file) {
+                        yield {
+                            type: 'file.created',
+                            taskId: undefined,
+                            correlationId: undefined,
+                            timestamp,
+                            payload: {
+                                fileName: file.fileName,
+                                fileType: file.fileType,
+                                size: file.size,
+                                url: file.url,
+                                toolCallId: msg.toolCallId,
+                                toolName: msg.toolName ?? 'tool',
+                            },
+                        };
+                    }
+                }
+            }
+        }
+    }
+    /** 规范化 updates / values 两种 stream 输出 */
+    normalizeStreamUpdates(update) {
+        if (!update || typeof update !== 'object')
+            return [];
+        const obj = update;
+        // updates 模式：{ nodeId: partialState }
+        // values 模式兜底：整表 state（无明确 node 键时当作 __values__）
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return [];
+        // 若顶层已有 messages，视为 values 全量快照（仅取末条，避免重复刷屏）
+        if (Array.isArray(obj['messages'])) {
+            const messages = obj['messages'];
+            const last = messages.length > 0 ? messages[messages.length - 1] : undefined;
+            return [
+                {
+                    nodeId: String(obj['currentNode'] ?? '__values__'),
+                    data: { messages: last !== undefined ? [last] : [] },
+                },
+            ];
+        }
+        const out = [];
+        for (const [nodeId, value] of Object.entries(obj)) {
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                out.push({ nodeId, data: value });
+            }
+        }
+        return out;
+    }
+    extractMessagesFromPartial(data) {
+        const raw = data['messages'];
+        if (!Array.isArray(raw))
+            return [];
+        return raw.map((item) => {
+            if (!item || typeof item !== 'object') {
+                return { role: 'assistant', content: String(item) };
+            }
+            const m = item;
+            return {
+                role: typeof m['role'] === 'string' ? m['role'] : undefined,
+                content: typeof m['content'] === 'string' ? m['content'] : undefined,
+                toolCalls: m['toolCalls'],
+                toolCallId: typeof m['toolCallId'] === 'string' ? m['toolCallId'] : undefined,
+                toolName: typeof m['toolName'] === 'string' ? m['toolName'] : undefined,
+                success: typeof m['success'] === 'boolean' ? m['success'] : undefined,
+                reasoningContent: typeof m['reasoningContent'] === 'string' ? m['reasoningContent'] : undefined,
+                file: readFileArtifact(m['file']),
+            };
+        });
+    }
+}
+function readFileArtifact(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const rec = value;
+    if (typeof rec.fileName !== 'string' || typeof rec.url !== 'string')
+        return undefined;
+    return {
+        fileName: rec.fileName,
+        fileType: typeof rec.fileType === 'string' ? rec.fileType : 'file',
+        size: typeof rec.size === 'number' && Number.isFinite(rec.size) ? rec.size : 0,
+        url: rec.url,
+    };
+}