@gt-fe/eap-runtime 0.0.17 → 0.0.19

package/README.md

@@ -277,26 +277,28 @@ EAP_TOOL_EXECUTION_MODE=mcp                  # 仅 createDevRuntime / eap chat
 
 ---
 
-## 11. 发布到公司私有 npm（可选）
+## 11. 发布 npm 包
 
-私服：`https://maven.gtcloud.cn/repository/npm-local/`（模板 [`.npmrc.example`](./.npmrc.example)）。
+升版、CHANGELOG、`git commit` / `git push` 不在脚本里，先做完再跑脚本。脚本只做构建、发布、核对 registry 上的版本号。
 
-> `@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中作为命令直接执行。
+| 脚本 | 包 | registry |
+|------|----|----------|
+| [`scripts/publish-intranet.sh`](./scripts/publish-intranet.sh) | `@eap/runtime` | Nexus `https://maven.gtcloud.cn/repository/npm-local/` |
+| [`scripts/publish-public.sh`](./scripts/publish-public.sh) | `@gt-fe/eap-runtime` | npmjs。临时目录改名；dist 里 `@eap/contracts` 改为 `@gt-fe/eap-contracts`。不改源码 `package.json` |
 
 ```bash
+# 登录（一次性）
 cp .npmrc.example .npmrc
 npm login --registry https://maven.gtcloud.cn/repository/npm-local/
+npm login --registry https://registry.npmjs.org/
 
-# 1) 先发 @eap/contracts（version 改为目标版，如 0.0.1）
-cd ../eap-contracts && cp .npmrc.example .npmrc
-pnpm run build && npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
-
-# 2) runtime：package.json 中 @eap/contracts 改为版本号（勿再用 file:）
-cd ../runtime && pnpm run build
-npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
+./scripts/publish-intranet.sh
+./scripts/publish-public.sh
 ```
 
-含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。
+不要在源码目录对 npmjs 执行 `npm publish`（`publishConfig` 指向 Nexus；公网 dist 必须改写 contracts）。含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。`@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中当命令执行。
+
+UAT Hosting 吃公网包：把 `@eap/runtime` 指到 `npm:@gt-fe/eap-runtime@<本版>` 后重建镜像。
 
 ---
 

package/dist/checkpoint/checkpoint-ref-notify.js

@@ -3,6 +3,7 @@
  * 无 traceId 或 spanId 则跳过；回调失败不抛。
  * collector 不得写入持久化正文。
  */
+import { getExecutionTrace } from '../graph/execution-trace-context.js';
 function pickString(...values) {
     for (const value of values) {
         if (typeof value === 'string' && value.trim())
@@ -34,10 +35,10 @@ export async function notifyCheckpointRef(data, collectorOverride) {
         ? data.engineSnapshot.channel_values
         : {};
     const state = (data.state ?? {});
-    const collector = (collectorOverride ??
-        channels['traceCollector'] ??
-        state['traceCollector']);
-    const traceId = pickString(state['traceId'], channels['traceId']);
+    const store = getExecutionTrace();
+    // collector 是活对象，不从 Checkpoint 正文读（落盘已剥掉）。
+    const collector = (collectorOverride ?? store?.collector);
+    const traceId = pickString(store?.traceId, state['traceId'], channels['traceId']);
     const spanId = pickString(state['lastSpanId'], channels['lastSpanId']);
     if (!collector?.recordCheckpointRef || !traceId || !spanId)
         return;

package/dist/checkpoint/checkpoint-serializer.d.ts

@@ -40,13 +40,17 @@ export interface CreateCheckpointParams {
  * 确保所有必要字段的一致性。
  */
 export declare function createCheckpointData(params: CreateCheckpointParams): CheckpointData;
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export declare function toJsonSafe(value: unknown, stack?: Set<object>): unknown;
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export declare function stringifyJsonSafe(value: unknown): string;
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export declare function serializeCheckpoint(data: CheckpointData): string;
 /**

package/dist/checkpoint/checkpoint-serializer.js

@@ -37,30 +37,69 @@ export function createCheckpointData(params) {
 // ─────────────────────────────────────────────
 // 序列化 / 反序列化
 // ─────────────────────────────────────────────
+function isTimerHandle(value) {
+    const name = value.constructor?.name;
+    if (name === 'Timeout' || name === 'TimersList' || name === 'Immediate')
+        return true;
+    return Object.prototype.hasOwnProperty.call(value, '_idlePrev')
+        && Object.prototype.hasOwnProperty.call(value, '_idleNext');
+}
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export function toJsonSafe(value, stack = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+        return undefined;
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value !== 'object')
+        return undefined;
+    if (isTimerHandle(value))
+        return undefined;
+    if (stack.has(value))
+        return undefined;
+    const maybeToJSON = value.toJSON;
+    if (typeof maybeToJSON === 'function') {
+        return toJsonSafe(maybeToJSON.call(value), stack);
+    }
+    if (Array.isArray(value)) {
+        stack.add(value);
+        const out = value.map((item) => {
+            const next = toJsonSafe(item, stack);
+            return next === undefined ? null : next;
+        });
+        stack.delete(value);
+        return out;
+    }
+    stack.add(value);
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        const next = toJsonSafe(child, stack);
+        if (next !== undefined)
+            out[key] = next;
+    }
+    stack.delete(value);
+    return out;
+}
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export function stringifyJsonSafe(value) {
+    return JSON.stringify(toJsonSafe(value));
+}
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export function serializeCheckpoint(data) {
-    const seen = new WeakSet();
-    return JSON.stringify(data, (_key, value) => {
-        // Date → ISO 字符串
-        if (value instanceof Date) {
-            return value.toISOString();
-        }
-        // 循环引用检测
-        if (typeof value === 'object' && value !== null) {
-            if (seen.has(value)) {
-                throw new Error(`[CheckpointSerializer] Circular reference detected during serialization`);
-            }
-            seen.add(value);
-        }
-        return value;
-    });
+    return stringifyJsonSafe(data);
 }
 /**
  * 反序列化 JSON 字符串为 CheckpointData

package/dist/checkpoint/file-checkpoint-saver.js

@@ -4,6 +4,7 @@
  */
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 export class FileCheckpointSaver {
     baseDir;
     constructor(baseDir) {
@@ -12,7 +13,7 @@ export class FileCheckpointSaver {
     async save(threadId, data) {
         const dir = join(this.baseDir, threadId);
         await mkdir(dir, { recursive: true });
-        await writeFile(join(dir, `${data.checkpointId}.json`), JSON.stringify(data));
+        await writeFile(join(dir, `${data.checkpointId}.json`), stringifyJsonSafe(data));
         // 更新 latest 指针
         await writeFile(join(dir, 'latest.json'), JSON.stringify({ checkpointId: data.checkpointId }));
     }

package/dist/checkpoint/index.d.ts

@@ -4,7 +4,7 @@ export type { RedisCheckpointSaverOptions } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export type { CreateCheckpointParams } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -4,7 +4,7 @@ export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
 export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';

package/dist/checkpoint/pg-checkpoint-saver.js

@@ -7,6 +7,7 @@
  * @see design.md §1.3 checkpoints 数据模型
  * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 // ─────────────────────────────────────────────
 // PostgresCheckpointSaver
 // ─────────────────────────────────────────────
@@ -38,9 +39,9 @@ export class PostgresCheckpointSaver {
             threadId,
             data.checkpointId,
             data.currentNodeId,
-            JSON.stringify(data.historyPath),
-            JSON.stringify(data.state),
-            data.engineSnapshot == null ? null : JSON.stringify(data.engineSnapshot),
+            stringifyJsonSafe(data.historyPath),
+            stringifyJsonSafe(data.state),
+            data.engineSnapshot == null ? null : stringifyJsonSafe(data.engineSnapshot),
             data.createdBy || 'system',
             data.createdAt,
             data.updatedBy || 'system',

package/dist/checkpoint/redis-checkpoint-saver.js

@@ -9,6 +9,7 @@
  *
  * @see design.md §1.3 checkpoints 数据模型
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 /**
  * RedisCheckpointSaver — ICheckpointSaver 的 Redis 实现
  *
@@ -52,7 +53,7 @@ export class RedisCheckpointSaver {
         const idxKey = this.threadIndexKey(threadId);
         const ltKey = this.latestKey(threadId);
         const revKey = this.reverseIndexKey(data.checkpointId);
-        const json = JSON.stringify(data);
+        const json = stringifyJsonSafe(data);
         const score = new Date(data.createdAt).getTime();
         const pipeline = this.redis.pipeline();
         // 存储 Checkpoint JSON

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

@@ -35,13 +35,6 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     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
@@ -56,7 +49,7 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     registerConditionEvaluator(name: string, fn: ConditionEvaluatorFn): void;
     /**
      * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
-     * 无 streamSink 时为空操作（纯 invoke）。
+     * 无本次执行流式袋时为空操作（纯 invoke）。
      */
     emitStreamEvent(event: RuntimeEvent): void;
     /**
@@ -72,9 +65,8 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     /**
      * 解析 GraphDSL 并构建可执行图
      *
-     * **Request Isolation**: 每次调用都创建全新的 StateGraph 实例并编译，
-     * 确保并发请求之间无共享可变状态。Adapter 自身仅持有 readonly 配置（checkpointer、subGraphCompiler），
-     * 不缓存任何编译产物或运行时状态。
+     * **Request Isolation**: 每次调用都创建全新的 StateGraph 实例并编译。
+     * 一次执行的 collector / 流式袋跟这次调用走，不挂 Adapter 字段。
      *
      * 流程：
      * 1. 创建 StateGraph 实例（配置 channels）
@@ -89,7 +81,7 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      * 流式驱动图执行，逐步 yield RuntimeEvent
      *
      * - LangGraph `streamMode: "updates"`：节点完成后产出 response.chunk / stats 等
-     * - LLM token / Tool 执行事件：经 streamSink 在节点执行中实时旁路入队
+     * - LLM token / Tool 执行事件：经本次执行流式袋在节点执行中实时旁路入队
      * （当前 @langchain/langgraph@0.2 无 messages mode，故用 LLMNode.onChunk 模拟）
      */
     stream(graph: ExecutableGraph, state: GraphState): AsyncIterableIterator<RuntimeEvent>;

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

@@ -31,6 +31,7 @@ import { pickContextFields } from '../../token/context-window.js';
 import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
 import { classifySkillRead } from './skill-read.js';
 import { withGraphSpan } from '../trace-span.js';
+import { executionTraceFromState, getExecutionStream, runWithExecutionTrace, } from '../execution-trace-context.js';
 /** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
 export const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
@@ -68,13 +69,6 @@ export class LangGraphAdapter {
     conditionEvaluator;
     systemPromptBuilder;
     skillAuditRecorder;
-    /** 流式旁路：LLM token / Tool 执行事件在节点执行中实时入队 */
-    streamSink = null;
-    streamEventContext = {};
-    streamChunkIndex = 0;
-    streamIteration = 0;
-    reasoningStartedThisTurn = false;
-    streamedTextThisTurn = false;
     /**
      * @param checkpointSaver - 可选的 ICheckpointSaver
      * @param llmProvider - LLM 调用提供者，默认 EchoLLMProvider
@@ -140,31 +134,37 @@ export class LangGraphAdapter {
     }
     /**
      * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
-     * 无 streamSink 时为空操作（纯 invoke）。
+     * 无本次执行流式袋时为空操作（纯 invoke）。
      */
     emitStreamEvent(event) {
-        if (!this.streamSink)
+        const stream = getExecutionStream();
+        if (!stream)
             return;
-        this.streamSink({
+        stream.sink({
             ...event,
-            taskId: event.taskId ?? this.streamEventContext.taskId,
-            correlationId: event.correlationId ?? this.streamEventContext.correlationId,
+            taskId: event.taskId ?? stream.eventContext.taskId,
+            correlationId: event.correlationId ?? stream.eventContext.correlationId,
         });
     }
     /**
      * 子图 LLM 可清零流式标志；结束后保留「已经 stream 过」以免父图 convertUpdates 再发一遍正文。
      */
     async runIsolatedLlmStreamFlags(work) {
-        const savedStreamed = this.streamedTextThisTurn;
-        const savedReasoning = this.reasoningStartedThisTurn;
-        this.reasoningStartedThisTurn = false;
-        this.streamedTextThisTurn = false;
+        const stream = getExecutionStream();
+        const savedStreamed = stream?.streamedTextThisTurn ?? false;
+        const savedReasoning = stream?.reasoningStartedThisTurn ?? false;
+        if (stream) {
+            stream.reasoningStartedThisTurn = false;
+            stream.streamedTextThisTurn = false;
+        }
         try {
             return await work();
         }
         finally {
-            this.streamedTextThisTurn = savedStreamed || this.streamedTextThisTurn;
-            this.reasoningStartedThisTurn = savedReasoning || this.reasoningStartedThisTurn;
+            if (stream) {
+                stream.streamedTextThisTurn = savedStreamed || stream.streamedTextThisTurn;
+                stream.reasoningStartedThisTurn = savedReasoning || stream.reasoningStartedThisTurn;
+            }
         }
     }
     /**
@@ -173,10 +173,11 @@ export class LangGraphAdapter {
      * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
      */
     emitToolExecutionEvents(progress) {
-        if (!this.streamSink)
+        const stream = getExecutionStream();
+        if (!stream)
             return;
         const timestamp = new Date().toISOString();
-        const { taskId, correlationId } = this.streamEventContext;
+        const { taskId, correlationId } = stream.eventContext;
         const loc = {
             ...(progress.node ? { node: progress.node } : {}),
             ...(progress.skillId ? { skillId: progress.skillId } : {}),
@@ -184,7 +185,7 @@ export class LangGraphAdapter {
         const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
         if (skillRead && progress.status === 'completed') {
             if (skillRead.kind === 'loaded') {
-                this.streamSink({
+                stream.sink({
                     type: 'skill.loaded',
                     taskId,
                     correlationId,
@@ -196,7 +197,7 @@ export class LangGraphAdapter {
                 });
             }
             else {
-                this.streamSink({
+                stream.sink({
                     type: 'skill.resource_read',
                     taskId,
                     correlationId,
@@ -206,7 +207,7 @@ export class LangGraphAdapter {
             }
         }
         if (progress.status === 'started') {
-            this.streamSink({
+            stream.sink({
                 type: 'tool.called',
                 taskId,
                 correlationId,
@@ -220,7 +221,7 @@ export class LangGraphAdapter {
                 },
             });
         }
-        this.streamSink({
+        stream.sink({
             type: 'tool.progress',
             taskId,
             correlationId,
@@ -228,7 +229,7 @@ export class LangGraphAdapter {
             payload: { ...progress },
         });
         if (progress.status === 'completed') {
-            this.streamSink({
+            stream.sink({
                 type: 'tool.result',
                 taskId,
                 correlationId,
@@ -244,7 +245,7 @@ export class LangGraphAdapter {
             });
         }
         else if (progress.status === 'error') {
-            this.streamSink({
+            stream.sink({
                 type: 'tool.error',
                 taskId,
                 correlationId,
@@ -263,9 +264,8 @@ export class LangGraphAdapter {
     /**
      * 解析 GraphDSL 并构建可执行图
      *
-     * **Request Isolation**: 每次调用都创建全新的 StateGraph 实例并编译，
-     * 确保并发请求之间无共享可变状态。Adapter 自身仅持有 readonly 配置（checkpointer、subGraphCompiler），
-     * 不缓存任何编译产物或运行时状态。
+     * **Request Isolation**: 每次调用都创建全新的 StateGraph 实例并编译。
+     * 一次执行的 collector / 流式袋跟这次调用走，不挂 Adapter 字段。
      *
      * 流程：
      * 1. 创建 StateGraph 实例（配置 channels）
@@ -410,7 +410,7 @@ export class LangGraphAdapter {
      * 流式驱动图执行，逐步 yield RuntimeEvent
      *
      * - LangGraph `streamMode: "updates"`：节点完成后产出 response.chunk / stats 等
-     * - LLM token / Tool 执行事件：经 streamSink 在节点执行中实时旁路入队
+     * - LLM token / Tool 执行事件：经本次执行流式袋在节点执行中实时旁路入队
      * （当前 @langchain/langgraph@0.2 无 messages mode，故用 LLMNode.onChunk 模拟）
      */
     async *stream(graph, state) {
@@ -434,13 +434,17 @@ export class LangGraphAdapter {
             });
             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 () => {
+        // 流式袋跟这次调用走，不挂 this：并行 stream 各写各的 queue。
+        const streamBag = {
+            sink: enqueue,
+            eventContext: { taskId: state.taskId, correlationId: state.correlationId },
+            chunkIndex: 0,
+            iteration: 0,
+            reasoningStartedThisTurn: false,
+            streamedTextThisTurn: false,
+        };
+        const traceCtx = executionTraceFromState(state);
+        const producer = runWithExecutionTrace({ ...traceCtx, stream: streamBag }, () => (async () => {
             try {
                 const streamIterator = await ref.compiled.stream(input, langGraphRunOptions(ref.dsl, {
                     configurable: {
@@ -453,7 +457,7 @@ export class LangGraphAdapter {
                     streamMode: 'updates',
                 }));
                 for await (const update of streamIterator) {
-                    for (const event of this.convertUpdatesToEvents(update, graph.id, () => this.streamChunkIndex++, ref.silentNodeIds, ref.subgraphNodeIds)) {
+                    for (const event of this.convertUpdatesToEvents(update, graph.id, () => streamBag.chunkIndex++, ref.silentNodeIds, ref.subgraphNodeIds)) {
                         enqueue(event);
                     }
                 }
@@ -463,11 +467,9 @@ export class LangGraphAdapter {
             }
             finally {
                 finished = true;
-                this.streamSink = null;
-                this.streamEventContext = {};
                 signal();
             }
-        })();
+        })());
         while (!finished || queue.length > 0) {
             if (queue.length === 0) {
                 await new Promise((resolve) => {
@@ -488,7 +490,9 @@ export class LangGraphAdapter {
         const ref = this.getCompiledRef(graph);
         const input = this.graphStateToLangGraphInput(state);
         const startTime = Date.now();
-        const result = await ref.compiled.invoke(input, langGraphRunOptions(ref.dsl, {
+        const traceCtx = executionTraceFromState(state);
+        // 只补 collector/traceId。子图套娃时外层 stream 袋经 ?? 保留。
+        const result = await runWithExecutionTrace(traceCtx, () => ref.compiled.invoke(input, langGraphRunOptions(ref.dsl, {
             configurable: {
                 thread_id: resolveCheckpointThreadId({
                     sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
@@ -496,7 +500,7 @@ export class LangGraphAdapter {
                     graphId: graph.id,
                 }),
             },
-        }));
+        })));
         const duration = Date.now() - startTime;
         const messages = Array.isArray(result['messages']) ? result['messages'] : [];
         const lastMessage = messages[messages.length - 1];
@@ -661,15 +665,16 @@ export class LangGraphAdapter {
                     },
                 });
             }
-            if (patch.skillRoute === 'clarify' && this.streamSink) {
+            const stream = getExecutionStream();
+            if (patch.skillRoute === 'clarify' && stream) {
                 const question = patch.messages.at(-1)?.content;
                 if (typeof question === 'string' && question.trim()) {
-                    this.streamSink({
+                    stream.sink({
                         type: 'response.chunk',
                         taskId: undefined,
                         correlationId: undefined,
                         timestamp: new Date().toISOString(),
-                        payload: { content: question, index: this.streamChunkIndex++, node: node.id },
+                        payload: { content: question, index: stream.chunkIndex++, node: node.id },
                     });
                 }
             }
@@ -892,38 +897,42 @@ export class LangGraphAdapter {
                     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;
+                // 流式旁路：有本次 stream 袋时启用 LLM token 推送；silent 节点不推给用户
+                const stream = getExecutionStream();
+                const enableStream = Boolean(stream) && !silent;
+                if (stream) {
+                    stream.reasoningStartedThisTurn = false;
+                    stream.streamedTextThisTurn = false;
+                }
                 const llmNode = new LLMNode(node.id, finalConfig, this.llmProvider, enableStream, enableStream
                     ? (text) => {
-                        if (!this.streamSink || !text)
+                        const live = getExecutionStream();
+                        if (!live || !text)
                             return;
                         const timestamp = new Date().toISOString();
-                        if (!this.reasoningStartedThisTurn) {
-                            this.reasoningStartedThisTurn = true;
-                            this.streamIteration += 1;
-                            this.streamSink({
+                        if (!live.reasoningStartedThisTurn) {
+                            live.reasoningStartedThisTurn = true;
+                            live.iteration += 1;
+                            live.sink({
                                 type: 'reasoning.started',
                                 taskId: undefined,
                                 correlationId: undefined,
                                 timestamp,
                                 payload: {
-                                    iterationCount: this.streamIteration,
+                                    iterationCount: live.iteration,
                                     model: finalConfig.model,
                                 },
                             });
                         }
-                        this.streamedTextThisTurn = true;
-                        this.streamSink({
+                        live.streamedTextThisTurn = true;
+                        live.sink({
                             type: 'response.chunk',
                             taskId: undefined,
                             correlationId: undefined,
                             timestamp,
                             payload: {
                                 content: text,
-                                index: this.streamChunkIndex++,
+                                index: live.chunkIndex++,
                                 node: node.id,
                             },
                         });
@@ -1229,6 +1238,7 @@ export class LangGraphAdapter {
      */
     *convertUpdatesToEvents(update, graphId, nextChunkIndex, silentNodeIds = new Set(), subgraphNodeIds = new Set()) {
         const timestamp = new Date().toISOString();
+        const streamedTextThisTurn = Boolean(getExecutionStream()?.streamedTextThisTurn);
         const entries = this.normalizeStreamUpdates(update);
         for (const { nodeId, data } of entries) {
             // LLM 节点 token 明细（写入 __llmTokenUsage）→ stats.node_token_usage
@@ -1266,8 +1276,8 @@ export class LangGraphAdapter {
                     }
                     const hasText = typeof msg.content === 'string' && msg.content.trim().length > 0;
                     if ((hasText || msg.reasoningContent) &&
-                        (!this.streamedTextThisTurn || msg.reasoningContent)) {
-                        if (this.streamedTextThisTurn && !msg.reasoningContent)
+                        (!streamedTextThisTurn || msg.reasoningContent)) {
+                        if (streamedTextThisTurn && !msg.reasoningContent)
                             continue;
                         yield {
                             type: 'response.chunk',
@@ -1275,7 +1285,7 @@ export class LangGraphAdapter {
                             correlationId: undefined,
                             timestamp,
                             payload: {
-                                content: this.streamedTextThisTurn ? '' : (msg.content ?? ''),
+                                content: streamedTextThisTurn ? '' : (msg.content ?? ''),
                                 index: nextChunkIndex(),
                                 node: nodeId,
                                 graphId,
@@ -1291,7 +1301,7 @@ export class LangGraphAdapter {
                     if (silentNodeIds.has(nodeId) || subgraphNodeIds.has(nodeId))
                         continue;
                     // 已通过 onChunk 推送过 token，避免整段重复
-                    if (this.streamedTextThisTurn) {
+                    if (streamedTextThisTurn) {
                         // token 已流过：仍补发一条带 reasoning 的标记 chunk（空 content），供落库回传
                         if (msg.reasoningContent) {
                             yield {

package/dist/graph/adapters/subgraph-compiler.js

@@ -9,7 +9,7 @@
  */
 import { assertSkillPermission } from '../../governance/permission-guard.js';
 import { LangGraphAdapter } from './langgraph.adapter.js';
-import { resolveTraceId } from '../../common/trace-id.js';
+import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { pickContextFields } from '../../token/context-window.js';
@@ -60,8 +60,8 @@ export class SubGraphCompiler {
                     taskId: state['taskId'],
                     correlationId: state['correlationId'],
                 });
-            const traceCollector = state['traceCollector'];
-            const traceId = resolveTraceId(state);
+            // 用父图这次调用上的 collector；内层 invoke 只补 collector/traceId，沿用外层流式袋。
+            const { collector: traceCollector, traceId } = resolveExecutionTrace(state);
             const skillName = dsl.name || resolvedSkillId;
             if (!resuming) {
                 adapter.emitStreamEvent({
@@ -86,7 +86,8 @@ export class SubGraphCompiler {
                         metadata: { skillId: resolvedSkillId, taskId: state['taskId'], correlationId: state['correlationId'] },
                     });
                 }
-                catch {
+                catch (err) {
+                    warnTraceSpanFailure('createNode', { type: 'skill', name: resolvedSkillId || dsl.name || 'skill', traceId }, err);
                     skillSpanId = null;
                 }
             }
@@ -160,8 +161,8 @@ export class SubGraphCompiler {
                             totalTokens: result.tokenUsage?.total,
                         });
                     }
-                    catch {
-                        // ignore
+                    catch (err) {
+                        warnTraceSpanFailure('completeNode', { type: 'skill', name: skillName, traceId, spanId: skillSpanId }, err);
                     }
                 }
                 // 4. 只回写子图本步新增消息（含内部 tool 回合），禁止把入口历史再 append
@@ -224,8 +225,8 @@ export class SubGraphCompiler {
                             error: err instanceof Error ? err.message : String(err),
                         });
                     }
-                    catch {
-                        // ignore
+                    catch (completeErr) {
+                        warnTraceSpanFailure('completeNode', { type: 'skill', name: skillName, traceId, spanId: skillSpanId }, completeErr);
                     }
                 }
                 adapter.emitStreamEvent({

package/dist/graph/contracts/executable-graph.d.ts

@@ -207,7 +207,10 @@ export interface GraphState {
     skillInput?: Record<string, unknown>;
     /** Hosting 已建 Trace id（与 Foundation traces.id 同值） */
     traceId?: string;
-    /** Trace 采集器（RT-7；不入 Checkpoint 序列化语义） */
+    /**
+     * 入口把 collector 绑到本次执行上下文；节点不从此字段读取。
+     * 不入 Checkpoint。
+     */
     traceCollector?: import('../../contracts/trace-collector.js').ITraceCollector;
     /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
     skillSpanId?: string;

package/dist/graph/execution-trace-context.d.ts

@@ -0,0 +1,38 @@
+import type { ITraceCollector } from '../contracts/trace-collector.js';
+import type { GraphState, RuntimeEvent } from './contracts/executable-graph.js';
+/** 同一次 stream 共用；套娃 invoke 共享引用，并行任务各一份。 */
+export interface ExecutionStreamBag {
+    sink: (event: RuntimeEvent) => void;
+    eventContext: {
+        taskId?: string;
+        correlationId?: string;
+    };
+    chunkIndex: number;
+    iteration: number;
+    reasoningStartedThisTurn: boolean;
+    streamedTextThisTurn: boolean;
+}
+export interface ExecutionRunContext {
+    collector?: ITraceCollector;
+    traceId?: string;
+    stream?: ExecutionStreamBag;
+}
+/** 入口从本次入参取出可绑定的 collector+traceId；缺一则不算。 */
+export declare function executionTraceFromState(state: GraphState | Record<string, unknown> | undefined): {
+    collector: ITraceCollector;
+    traceId: string;
+} | undefined;
+/**
+ * 绑到这次异步调用链。入参缺省时不新开一层。
+ * 套娃：只补 collector/traceId，stream 袋沿用外层引用。
+ * 并行：各 run 各一份 store。
+ */
+export declare function runWithExecutionTrace<T>(patch: ExecutionRunContext | undefined, fn: () => T): T;
+export declare function getExecutionTrace(): ExecutionRunContext | undefined;
+export declare function getExecutionStream(): ExecutionStreamBag | undefined;
+/** 节点只认这次调用链上的 collector。traceId 可回退 state（字符串，可落盘）。 */
+export declare function resolveExecutionTrace(state?: Record<string, unknown>): {
+    collector?: ITraceCollector;
+    traceId?: string;
+};
+export declare function warnTraceSpanFailure(op: 'createNode' | 'completeNode', extra: Record<string, unknown>, err: unknown): void;

package/dist/graph/execution-trace-context.js

@@ -0,0 +1,62 @@
+/**
+ * 图内 span 与流式旁路：绑在这次调用链上，不挂 Adapter 实例、不写库。
+ *
+ * 约束：套娃 invoke 必须共用外层流式袋（引用），不能 finally 清空；
+ * 并行 invoke/stream 必须各有一份 store，否则 span 与 tool.called 会串台。
+ * collector 不入 Checkpoint；节点不从 Graph state 读 collector。
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { emitRuntimeLog } from '../common/logger.js';
+import { resolveTraceId } from '../common/trace-id.js';
+const storage = new AsyncLocalStorage();
+/** 入口从本次入参取出可绑定的 collector+traceId；缺一则不算。 */
+export function executionTraceFromState(state) {
+    if (!state)
+        return undefined;
+    const collector = state.traceCollector;
+    const traceId = resolveTraceId(state);
+    if (!collector || !traceId)
+        return undefined;
+    return { collector, traceId };
+}
+/**
+ * 绑到这次异步调用链。入参缺省时不新开一层。
+ * 套娃：只补 collector/traceId，stream 袋沿用外层引用。
+ * 并行：各 run 各一份 store。
+ */
+export function runWithExecutionTrace(patch, fn) {
+    if (!patch)
+        return fn();
+    const outer = storage.getStore();
+    // stream 用 ?? 保留外层引用：子图 adapter.invoke 不得换袋、不得清空父 stream。
+    const next = {
+        collector: patch.collector ?? outer?.collector,
+        traceId: patch.traceId ?? outer?.traceId,
+        stream: patch.stream ?? outer?.stream,
+    };
+    if (!next.collector && !next.traceId && !next.stream)
+        return fn();
+    return storage.run(next, fn);
+}
+export function getExecutionTrace() {
+    return storage.getStore();
+}
+export function getExecutionStream() {
+    return storage.getStore()?.stream;
+}
+/** 节点只认这次调用链上的 collector。traceId 可回退 state（字符串，可落盘）。 */
+export function resolveExecutionTrace(state) {
+    const store = storage.getStore();
+    return {
+        collector: store?.collector,
+        traceId: store?.traceId ?? (state ? resolveTraceId(state) : undefined),
+    };
+}
+export function warnTraceSpanFailure(op, extra, err) {
+    emitRuntimeLog('warn', 'runtime.trace', `trace ${op} failed`, {
+        event: 'runtime.trace.span_failed',
+        op,
+        error: err instanceof Error ? err.message : String(err),
+        ...extra,
+    });
+}

package/dist/graph/hitl/hitl-handler.d.ts

@@ -169,7 +169,7 @@ export declare class HitlHandler {
     /** 同一 taskId 上串行化 resume 与 timeout，避免双边占用 */
     private taskLocks;
     private traceCollector?;
-    /** 进程内 interrupt 的 collector，不进 Checkpoint */
+    /** interrupt 当时的 collector。timeout/resume 已离开图的调用链，不能从 state 恢复。 */
     private readonly waitingCollectors;
     constructor(checkpointSaver: ICheckpointSaver, sseEmitter: ISSEEmitter, timeoutListener?: HitlTimeoutListener);
     setTimeoutListener(listener: HitlTimeoutListener | undefined): void;
@@ -182,6 +182,7 @@ export declare class HitlHandler {
      * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
      */
     interrupt(taskId: string, threadId: string, state: GraphState, config: HitlInterruptConfig, extras?: HitlInterruptExtras): Promise<void>;
+    private interruptCore;
     /**
      * 用户响应后恢复执行
      *

package/dist/graph/hitl/hitl-handler.js

@@ -12,6 +12,8 @@
  */
 import { notifyCheckpointRef, stripCheckpointCollectors, } from '../../checkpoint/checkpoint-ref-notify.js';
 import { startGraphSpan, completeGraphSpan } from '../trace-span.js';
+import { resolveTraceId } from '../../common/trace-id.js';
+import { executionTraceFromState, getExecutionTrace, runWithExecutionTrace, } from '../execution-trace-context.js';
 // ─────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────
@@ -225,7 +227,7 @@ export class HitlHandler {
     /** 同一 taskId 上串行化 resume 与 timeout，避免双边占用 */
     taskLocks = new Map();
     traceCollector;
-    /** 进程内 interrupt 的 collector，不进 Checkpoint */
+    /** interrupt 当时的 collector。timeout/resume 已离开图的调用链，不能从 state 恢复。 */
     waitingCollectors = new Map();
     constructor(checkpointSaver, sseEmitter, timeoutListener) {
         this.checkpointSaver = checkpointSaver;
@@ -246,6 +248,12 @@ export class HitlHandler {
      * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
      */
     async interrupt(taskId, threadId, state, config, extras = {}) {
+        const work = () => this.interruptCore(taskId, threadId, state, config, extras);
+        // 图内 interrupt 已在这次调用链上；单测直接 interrupt 时从入参绑一次。
+        const ctx = getExecutionTrace()?.collector ? undefined : executionTraceFromState(state);
+        return ctx ? runWithExecutionTrace(ctx, work) : work();
+    }
+    async interruptCore(taskId, threadId, state, config, extras) {
         const now = new Date().toISOString();
         const timeoutMs = toHitlTimeoutMs(config.timeout);
         const deadlineAt = new Date(Date.now() + timeoutMs).toISOString();
@@ -292,7 +300,7 @@ export class HitlHandler {
         };
         const persistedCheckpoint = stripCheckpointCollectors(checkpointData);
         await this.checkpointSaver.save(threadId, persistedCheckpoint);
-        const liveCollector = state.traceCollector;
+        const liveCollector = getExecutionTrace()?.collector;
         if (liveCollector) {
             this.waitingCollectors.set(taskId, liveCollector);
         }
@@ -386,10 +394,15 @@ export class HitlHandler {
                 updatedAt: now,
             }));
             const hitlSpanId = waiting.hitlSpanId ?? persisted?.hitlSpanId;
-            await completeGraphSpan(resumedState, hitlSpanId, {
+            const resumeTraceId = resolveTraceId(resumedState) ?? resolveTraceId(checkpoint.state);
+            const resumeCtx = liveCollector && resumeTraceId
+                ? { collector: liveCollector, traceId: resumeTraceId }
+                : undefined;
+            // 用户确认不在图执行链上，必须重新绑 collector。
+            await runWithExecutionTrace(resumeCtx, () => completeGraphSpan(resumedState, hitlSpanId, {
                 status: 'completed',
                 output: { choice, userId },
-            }, liveCollector);
+            }, liveCollector));
             const event = {
                 type: 'hitl.resumed',
                 data: { choice, userId },
@@ -445,10 +458,15 @@ export class HitlHandler {
                         updatedAt: new Date().toISOString(),
                     }));
                     const hitlSpanId = waiting.hitlSpanId ?? persisted.hitlSpanId;
-                    await completeGraphSpan(checkpoint.state, hitlSpanId, {
+                    const timeoutTraceId = resolveTraceId(checkpoint.state);
+                    const timeoutCtx = liveCollector && timeoutTraceId
+                        ? { collector: liveCollector, traceId: timeoutTraceId }
+                        : undefined;
+                    // timer 回调不在图的这次调用链上。
+                    await runWithExecutionTrace(timeoutCtx, () => completeGraphSpan(checkpoint.state, hitlSpanId, {
                         status: 'failed',
                         error: HITL_TIMEOUT_MESSAGE,
-                    }, liveCollector);
+                    }, liveCollector));
                 }
                 return timeoutEvent;
             });

package/dist/graph/nodes/tool-node.js

@@ -14,8 +14,8 @@ import { inferHarnessSkillDir } from '../../tool/skill-dir-infer.js';
 import { isHitlDecision, unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { ToolConfirmationInterceptor } from '../../tool/tool-confirmation.js';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
-import { resolveTraceId } from '../../common/trace-id.js';
 import { toolsetCodeFromLoaded } from '../../tool/mcp-list.js';
+import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 function skillDirsFromState(state) {
     const defs = state['skillDefinitions'];
     return Object.values(defs ?? {})
@@ -102,8 +102,8 @@ export class ToolNode {
             };
         });
         const executionContext = state['executionContext'];
-        const traceCollector = state['traceCollector'];
-        const traceId = resolveTraceId(state);
+        // 不读 state.traceCollector：存档会剥掉，后续节点会空。
+        const { collector: traceCollector, traceId } = resolveExecutionTrace(state);
         const agentCode = String(state['agentCode'] ?? '');
         const nodeId = this.nodeId ?? 'tool-node';
         const skillId = typeof state['activatedSkill'] === 'string' && state['activatedSkill']
@@ -142,7 +142,8 @@ export class ToolNode {
                     },
                 });
             }
-            catch {
+            catch (err) {
+                warnTraceSpanFailure('createNode', { type: 'tool', name: req.toolName, traceId, toolCallId: req.toolCallId }, err);
                 return null;
             }
         }));
@@ -227,8 +228,8 @@ export class ToolNode {
                             error: result.error,
                         });
                     }
-                    catch {
-                        // Trace 失败不影响主路径
+                    catch (err) {
+                        warnTraceSpanFailure('completeNode', { type: 'tool', name: req.toolName, traceId, spanId: nodeId }, err);
                     }
                 }
                 return result;
@@ -237,6 +238,7 @@ export class ToolNode {
                 // HITL 暂停必须向上抛出，供 invoke/stream 返回 waiting_hitl（不可降级为 tool failure）
                 const hitlPaused = unwrapHitlPaused(err);
                 if (hitlPaused) {
+                    // 暂停不 completeNode：span 保持 running，id 随错误交给 resume/timeout。
                     hitlPaused.toolSpanId = hitlPaused.toolSpanId ?? spanIds[i] ?? undefined;
                     hitlPaused.skillSpanId =
                         hitlPaused.skillSpanId ??
@@ -254,6 +256,18 @@ export class ToolNode {
                     error: message,
                     executionTime,
                 });
+                const failedSpanId = spanIds[i];
+                if (traceCollector && failedSpanId) {
+                    try {
+                        await traceCollector.completeNode(failedSpanId, {
+                            status: 'failed',
+                            error: message,
+                        });
+                    }
+                    catch (completeErr) {
+                        warnTraceSpanFailure('completeNode', { type: 'tool', name: req.toolName, traceId, spanId: failedSpanId }, completeErr);
+                    }
+                }
                 return {
                     toolCallId: req.toolCallId,
                     toolName: req.toolName,

package/dist/graph/trace-span.js

@@ -1,10 +1,10 @@
 /**
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
-import { resolveTraceId } from '../common/trace-id.js';
+import { resolveExecutionTrace, warnTraceSpanFailure, } from './execution-trace-context.js';
 export async function startGraphSpan(state, input) {
-    const collector = state['traceCollector'];
-    const traceId = resolveTraceId(state);
+    // collector 只从这次调用链取；state 只用来拼 parent/task 元数据。
+    const { collector, traceId } = resolveExecutionTrace(state);
     if (!collector || !traceId)
         return undefined;
     const parentNodeId = input.parentSpanId ??
@@ -27,19 +27,20 @@ export async function startGraphSpan(state, input) {
             },
         });
     }
-    catch {
+    catch (err) {
+        warnTraceSpanFailure('createNode', { type: input.type, name: input.name, traceId }, err);
         return undefined;
     }
 }
 export async function completeGraphSpan(state, spanId, params, collectorOverride) {
-    const collector = collectorOverride ?? state['traceCollector'];
+    const collector = collectorOverride ?? resolveExecutionTrace(state).collector;
     if (!collector?.completeNode || !spanId)
         return;
     try {
         await collector.completeNode(spanId, params);
     }
-    catch {
-        // Trace 失败不影响主路径
+    catch (err) {
+        warnTraceSpanFailure('completeNode', { spanId, traceId: resolveExecutionTrace(state).traceId }, err);
     }
 }
 export async function withGraphSpan(state, spec, run) {

package/dist/runtime/types.d.ts

@@ -24,7 +24,7 @@ export interface ExecuteParams {
     agentVersion?: string;
     /**
      * Hosting 已创建的 Trace id（Foundation `POST /traces` / TraceLinker.createTrace 的返回值）。
-     * 写入 GraphState 供 Skill/Tool span。
+     * 与装配期 `traceCollector` 同时存在时，invoke/stream 入口绑定到本次执行上下文供图内 span。
      */
     traceId?: string;
     config?: InvokeConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.17",
-  "description": "Enterprise Agent Platform \u2014 Runtime\u6838\u5fc3\uff1aGraph\u6267\u884c\u5f15\u64ce\u3001Task\u751f\u547d\u5468\u671f\u3001Session\u7ba1\u7406\u3001Checkpoint\u6301\u4e45\u5316",
+  "version": "0.0.19",
+  "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",