@gt-fe/eap-runtime 0.0.40 → 0.0.41

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

@@ -572,6 +572,7 @@ export class LangGraphAdapter {
                 traceCollector: ephemeral(undefined),
                 traceId: ephemeral(undefined),
                 skillSpanId: ephemeral(undefined),
+                llmSpanId: ephemeral(undefined),
                 toolSpanId: ephemeral(undefined),
                 hitlToolCallId: ephemeral(undefined),
                 lastSpanId: ephemeral(undefined),

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

@@ -12,6 +12,7 @@ import { assertSkillPermission } from '../../governance/permission-guard.js';
 import { LangGraphAdapter } from './langgraph.adapter.js';
 import { assertSkillGraphHasNoSubgraphNodes } from './graph-nesting.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
+import { startGraphSpan } from '../trace-span.js';
 import { skillSpanFields, skillTraceIdentity } from './skill-entry-span.js';
 import { filterLoadedToolsForSkill, spokenName, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
@@ -96,26 +97,16 @@ export class SubGraphCompiler {
                 });
             }
             let skillSpanId = existingSpanId || null;
-            if (!resuming && traceCollector && traceId) {
-                try {
-                    const fields = skillSpanFields(identity, { source: 'subgraph' });
-                    skillSpanId = await traceCollector.createNode({
-                        traceId,
-                        name: spanName,
-                        type: 'skill',
-                        agentCode: state['agentCode'] ?? state['agentId'],
+            if (!resuming) {
+                const fields = skillSpanFields(identity, { source: 'subgraph' });
+                skillSpanId = (await startGraphSpan(state, {
+                    name: spanName,
+                    type: 'skill',
+                    extra: {
                         ...(fields.version ? { version: fields.version } : {}),
                         input: fields.input,
-                        metadata: {
-                            taskId: state['taskId'],
-                            correlationId: state['correlationId'],
-                        },
-                    });
-                }
-                catch (err) {
-                    warnTraceSpanFailure('createNode', { type: 'skill', name: spanName, traceId }, err);
-                    skillSpanId = null;
-                }
+                    },
+                })) ?? null;
             }
             try {
                 // 1. 编译子图（每次执行时编译，确保子图实例独立）

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

@@ -240,6 +240,11 @@ export interface GraphState {
     skillIsolateContext?: boolean;
     /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
     skillSpanId?: string;
+    /**
+     * 本回合父图模型调用的 span id。父图 tool / 手册技能 / 子图技能入口挂到它下面。
+     * 只在 llm createNode 成功时更新。HITL 等待态一起带上。
+     */
+    llmSpanId?: string;
     /**
      * HITL 续跑：暂停时已 create 的 tool Span id。
      * 按 hitlToolCallId 复用，禁止再 createNode。

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

@@ -40,6 +40,7 @@ export interface HitlInterruptExtras {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
 }
 /** HITL 等待中状态（内存中维护） */
 export interface HitlWaitingState {
@@ -55,6 +56,7 @@ export interface HitlWaitingState {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
     hitlSpanId?: string;
 }
 /** HITL 超时错误（保留类型；timer 不再 throw，resume 逾期改走 AppError） */
@@ -119,6 +121,7 @@ export interface PersistedHitlWaiting {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
     hitlSpanId?: string;
     /** error/cancel 超时已占用此等待；resume 必须拒绝 */
     timedOut?: boolean;

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

@@ -194,6 +194,7 @@ function prepareHitlCheckpointState(state) {
         correlationId: state.correlationId ?? raw.correlationId,
         delegationToken: state.delegationToken ?? raw.delegationToken,
         skillSpanId: state.skillSpanId ?? raw.skillSpanId,
+        llmSpanId: state.llmSpanId ?? (typeof raw.llmSpanId === 'string' ? raw.llmSpanId : undefined),
         traceId: state.traceId ?? (typeof raw.traceId === 'string' ? raw.traceId : undefined),
         lastSpanId: state.lastSpanId ?? (typeof raw.lastSpanId === 'string' ? raw.lastSpanId : undefined),
     };
@@ -227,6 +228,7 @@ function waitingFromPersisted(persisted, taskId) {
         toolName: persisted.toolName,
         toolSpanId: persisted.toolSpanId,
         skillSpanId: persisted.skillSpanId,
+        llmSpanId: persisted.llmSpanId,
         hitlSpanId: persisted.hitlSpanId,
     };
 }
@@ -285,6 +287,8 @@ export class HitlHandler {
         const deadlineAt = new Date(Date.now() + timeoutMs).toISOString();
         const skillSpanId = extras.skillSpanId ??
             (typeof state.skillSpanId === 'string' ? state.skillSpanId : undefined);
+        const llmSpanId = extras.llmSpanId ??
+            (typeof state.llmSpanId === 'string' ? state.llmSpanId : undefined);
         const hitlSpanId = await startGraphSpan(state, {
             name: extras.toolName ?? 'hitl',
             type: 'hitl',
@@ -306,6 +310,7 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            llmSpanId,
             hitlSpanId,
         };
         const existing = await this.checkpointSaver.load(threadId);
@@ -392,6 +397,7 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            llmSpanId,
             hitlSpanId,
         });
     }
@@ -448,6 +454,7 @@ export class HitlHandler {
                 hitlRespondedBy: userId,
                 ...(waiting.toolSpanId ? { toolSpanId: waiting.toolSpanId } : {}),
                 ...(waiting.toolCallId ? { hitlToolCallId: waiting.toolCallId } : {}),
+                ...(waiting.llmSpanId ? { llmSpanId: waiting.llmSpanId } : {}),
             };
             const now = new Date().toISOString();
             await this.checkpointSaver.save(waiting.threadId, stripCheckpointCollectors({

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

@@ -8,6 +8,7 @@
  * @see design-v2 §5.2 / §5.3
  */
 import { resolveTraceId } from '../../../common/trace-id.js';
+import { withGraphSpan } from '../../trace-span.js';
 import { buildRagTools, resolveRagSources, mergeLocalDirs } from './tools.js';
 import { runReactLoop } from './react-loop.js';
 export class RagNode {
@@ -49,33 +50,40 @@ export class RagNode {
         if (excludedConfirmToolNames.length > 0) {
             throw new Error(`RagNode "${this.nodeId}" 检索源 tools 引用了需人工确认的工具: ${excludedConfirmToolNames.join(', ')}（requireConfirmation 工具的确认流挂在图级 tool 节点，rag 循环内执行会绕过确认，不支持挂载）`);
         }
-        const result = await runReactLoop({
-            nodeId: this.nodeId,
-            query: extractQuery(state),
-            history: extractHistory(state),
-            config: this.config,
-            apiTools,
-            kbToolNames,
-            llmProvider: this.deps.llmProvider,
-            toolOrchestrator: this.deps.toolOrchestrator,
-            retrievers,
-            loadedTools,
-            authContext: this.buildAuthContext(state),
-            executionContext: state['executionContext'],
-            forceToolServer: state['forceToolServer'],
-            userId: String(state['userId'] ?? ''),
-            ragScope,
-            emitEvent: this.deps.emitEvent,
-            traceCollector: state['traceCollector'],
-            traceId: resolveTraceId(state),
+        return withGraphSpan(state, {
+            name: this.nodeId,
+            type: 'llm',
+            extra: { metadata: { rag: true } },
+        }, async (spanId) => {
+            const result = await runReactLoop({
+                nodeId: this.nodeId,
+                query: extractQuery(state),
+                history: extractHistory(state),
+                config: this.config,
+                apiTools,
+                kbToolNames,
+                llmProvider: this.deps.llmProvider,
+                toolOrchestrator: this.deps.toolOrchestrator,
+                retrievers,
+                loadedTools,
+                authContext: this.buildAuthContext(state),
+                executionContext: state['executionContext'],
+                forceToolServer: state['forceToolServer'],
+                userId: String(state['userId'] ?? ''),
+                ragScope,
+                emitEvent: this.deps.emitEvent,
+                traceCollector: state['traceCollector'],
+                traceId: resolveTraceId(state),
+                parentSpanId: spanId,
+            });
+            // partial state 三连（与 LLMNode 同惯例）：
+            // messages 只返回新增（channel 为 append reducer）；token 走 __llmTokenUsage 累加器
+            return {
+                messages: [{ role: 'assistant', content: result.contextText }],
+                currentNode: this.nodeId,
+                __llmTokenUsage: result.tokenUsage,
+            };
         });
-        // partial state 三连（与 LLMNode 同惯例）：
-        // messages 只返回新增（channel 为 append reducer）；token 走 __llmTokenUsage 累加器
-        return {
-            messages: [{ role: 'assistant', content: result.contextText }],
-            currentNode: this.nodeId,
-            __llmTokenUsage: result.tokenUsage,
-        };
     }
     /** 身份组装照 ToolNode 惯例：executionContext 优先，state 兜底 */
     buildAuthContext(state) {

package/dist/graph/nodes/rag/react-loop.d.ts

@@ -45,6 +45,8 @@ export interface RagLoopInput {
     /** Trace 采集器 + 执行流 ID（缺省不建 span，照 ToolNode 模式：resolveTraceId） */
     traceCollector?: ITraceCollector;
     traceId?: string;
+    /** 本 RAG 节点 llm Span；内部检索/降噪挂到它下面 */
+    parentSpanId?: string;
 }
 export interface RagLoopOutput {
     /** 降噪上下文（近重去重 + LLM 判定 + 句子抽取后的拼装结果） */

package/dist/graph/nodes/rag/react-loop.js

@@ -444,6 +444,7 @@ async function startTraceSpan(input, event) {
             traceId: input.traceId,
             name: event.name,
             type: event.type,
+            parentNodeId: input.parentSpanId,
             input: event.input,
             metadata: { rag: true, ...event.metadata },
         });

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

@@ -19,6 +19,7 @@ import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.j
 import { mcpToolsetCode, toolTraceIdentity } from '../../tool/mcp-list.js';
 import { exposureScopeId, exposedNamesForScope, isUnloadedDeferredCall, mcpNamesToExpose, mergeExposed, partitionToolSearchCalls, runToolSearch, unloadedCallToolContent, } from '../../tool/mcp-tool-exposure.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
+import { resolveInvokedSpanParent } from '../trace-span.js';
 import { emitRuntimeLog } from '../../common/logger.js';
 import { toolResultHasArtifacts } from '../../tool/inject-public-artifact-links.js';
 import { decideBeforeTool, } from '../../execution/interceptors.js';
@@ -212,19 +213,21 @@ export class ToolNode {
             if (!traceCollector || !traceId)
                 return;
             try {
-                const parentNodeId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-                    ? state['skillSpanId']
-                    : undefined;
+                const parentNodeId = resolveInvokedSpanParent(state);
+                const identity = toolTraceIdentity(loadedTools?.[name], name);
                 const spanId = await traceCollector.createNode({
                     traceId,
                     name,
                     type: 'tool',
                     parentNodeId,
                     agentCode: agentCode || undefined,
+                    ...(identity.toolVersion ? { version: identity.toolVersion } : {}),
                     input,
                     metadata: {
                         toolCallId: callId,
                         ...(notExecuted ? { notExecuted: true } : {}),
+                        ...(identity.toolset ? { toolset: identity.toolset } : {}),
+                        ...(identity.toolDisplayName ? { toolDisplayName: identity.toolDisplayName } : {}),
                     },
                 });
                 sideSpanIds.push(spanId);
@@ -293,9 +296,7 @@ export class ToolNode {
             if (!traceCollector || !traceId)
                 return null;
             try {
-                const parentNodeId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-                    ? state['skillSpanId']
-                    : undefined;
+                const parentNodeId = resolveInvokedSpanParent(state);
                 const identity = toolTraceIdentity(loadedTools?.[req.toolName], req.toolName);
                 return await traceCollector.createNode({
                     traceId,
@@ -366,6 +367,7 @@ export class ToolNode {
                         const confirmed = await interceptor.executeWithConfirmation(req, graphState, req.taskId ?? String(state['taskId'] ?? req.toolCallId), threadId, {
                             toolSpanId: spanIds[i] ?? undefined,
                             skillSpanId: typeof state['skillSpanId'] === 'string' ? state['skillSpanId'] : undefined,
+                            llmSpanId: typeof state['llmSpanId'] === 'string' ? state['llmSpanId'] : undefined,
                         });
                         result =
                             confirmed ??

package/dist/graph/trace-span.d.ts

@@ -2,6 +2,11 @@
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
 import type { ITraceCollector, ExecutionNodeEvent, CompleteNodeParams } from '../contracts/trace-collector.js';
+/**
+ * 被这次模型调用出来的 tool / skill：子图内挂技能，否则挂本回合模型调用。
+ * 显式 parent 优先。不用 lastSpanId（工具跑完会把它改成工具自己）。
+ */
+export declare function resolveInvokedSpanParent(state: Record<string, unknown>, explicit?: string): string | undefined;
 export declare function startGraphSpan(state: Record<string, unknown>, input: {
     name: string;
     type: ExecutionNodeEvent['type'];
@@ -13,7 +18,7 @@ export declare function withGraphSpan(state: Record<string, unknown>, spec: {
     name: string;
     type: ExecutionNodeEvent['type'];
     extra?: Partial<Omit<ExecutionNodeEvent, 'traceId' | 'name' | 'type' | 'parentNodeId'>>;
-}, run: () => Promise<Record<string, unknown>>, complete?: {
+}, run: (spanId?: string) => Promise<Record<string, unknown>>, complete?: {
     outputFrom?: (result: Record<string, unknown>) => unknown;
 }): Promise<Record<string, unknown>>;
 /** llm Span create 时的 input：组装后的 system、工具短目录、本回合 messages。 */

package/dist/graph/trace-span.js

@@ -2,15 +2,27 @@
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
 import { resolveExecutionTrace, warnTraceSpanFailure, } from './execution-trace-context.js';
+function pickSpanId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/**
+ * 被这次模型调用出来的 tool / skill：子图内挂技能，否则挂本回合模型调用。
+ * 显式 parent 优先。不用 lastSpanId（工具跑完会把它改成工具自己）。
+ */
+export function resolveInvokedSpanParent(state, explicit) {
+    return pickSpanId(explicit) ?? pickSpanId(state['skillSpanId']) ?? pickSpanId(state['llmSpanId']);
+}
 export async function startGraphSpan(state, input) {
     // collector 只从这次调用链取；state 只用来拼 parent/task 元数据。
     const { collector, traceId } = resolveExecutionTrace(state);
     if (!collector || !traceId)
         return undefined;
-    const parentNodeId = input.parentSpanId ??
-        (typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-            ? state['skillSpanId']
-            : undefined);
+    const parentNodeId = input.type === 'tool' || input.type === 'skill'
+        ? resolveInvokedSpanParent(state, input.parentSpanId)
+        : pickSpanId(input.parentSpanId) ?? pickSpanId(state['skillSpanId']);
     try {
         return await collector.createNode({
             traceId,
@@ -23,6 +35,10 @@ export async function startGraphSpan(state, input) {
             metadata: {
                 taskId: state['taskId'],
                 correlationId: state['correlationId'],
+                // 对人展示名；name 仍是图节点 id / 函数名 / skillId。
+                ...(typeof state['agentName'] === 'string' && state['agentName'].trim()
+                    ? { agentName: state['agentName'].trim() }
+                    : {}),
                 ...(input.extra?.metadata ?? {}),
             },
         });
@@ -46,7 +62,7 @@ export async function completeGraphSpan(state, spanId, params, collectorOverride
 export async function withGraphSpan(state, spec, run, complete) {
     const spanId = await startGraphSpan(state, spec);
     try {
-        const result = await run();
+        const result = await run(spanId);
         const usage = Array.isArray(result['__llmTokenUsage'])
             ? result['__llmTokenUsage'].at(-1)
             : undefined;
@@ -61,7 +77,13 @@ export async function withGraphSpan(state, spec, run, complete) {
                 : undefined,
             ...(typeof usage?.model === 'string' && usage.model ? { model: usage.model } : {}),
         });
-        return spanId ? { ...result, lastSpanId: spanId } : result;
+        return spanId
+            ? {
+                ...result,
+                lastSpanId: spanId,
+                ...(spec.type === 'llm' ? { llmSpanId: spanId } : {}),
+            }
+            : result;
     }
     catch (err) {
         await completeGraphSpan(state, spanId, {

package/dist/tool/tool-confirmation.js

@@ -71,6 +71,8 @@ export class ToolConfirmationInterceptor {
             toolSpanId: extras.toolSpanId,
             skillSpanId: extras.skillSpanId ??
                 (typeof state.skillSpanId === 'string' ? state.skillSpanId : undefined),
+            llmSpanId: extras.llmSpanId ??
+                (typeof state.llmSpanId === 'string' ? state.llmSpanId : undefined),
         };
         await this.hitlHandler.interrupt(taskId, resolvedThreadId, state, {
             question,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",