@gt-fe/eap-runtime 0.0.18 → 0.0.20

package/dist/graph/adapters/skill-entry-span.js

@@ -0,0 +1,78 @@
+/**
+ * 成功读 SKILL.md 时写 Trace `type=skill` Span。
+ *
+ * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 与子图激活走同一 collector.createNode({ type: 'skill' })。
+ * 声明版本在 createNode.version；skillSpace 只在 input。
+ * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
+ */
+import { classifySkillRead, classifySkillSpace } from './skill-read.js';
+import { completeGraphSpan, startGraphSpan } from '../trace-span.js';
+function declaredSkillVersion(skillId, version) {
+    const raw = version?.trim();
+    if (!raw || raw === skillId)
+        return undefined;
+    return raw;
+}
+export function skillTraceIdentity(state, skillId, fallbackPath) {
+    const defs = state['skillDefinitions'];
+    const info = defs?.[skillId];
+    const exec = state['executionContext'];
+    const userId = (typeof exec?.userId === 'string' && exec.userId.trim()) ||
+        (typeof state['userId'] === 'string' && state['userId'].trim()) ||
+        undefined;
+    const agentDir = typeof state['agentDir'] === 'string' ? state['agentDir'] : undefined;
+    const bundle = info?.bundlePath || fallbackPath;
+    const skillSpace = bundle ? classifySkillSpace(bundle, { agentDir, userId }) : undefined;
+    const skillVersion = declaredSkillVersion(skillId, info?.version);
+    return {
+        skillId,
+        ...(info?.name ? { skillName: info.name } : {}),
+        ...(skillVersion ? { skillVersion } : {}),
+        ...(skillSpace ? { skillSpace } : {}),
+    };
+}
+export function skillSpanFields(identity, extra) {
+    return {
+        ...(identity.skillVersion ? { version: identity.skillVersion } : {}),
+        input: {
+            skillId: identity.skillId,
+            ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
+            ...(extra?.path ? { path: extra.path } : {}),
+            ...(extra?.source ? { source: extra.source } : {}),
+        },
+    };
+}
+export function skillEntryInvocationFromTool(input) {
+    if (input.alreadyInSkillSpan)
+        return null;
+    const hit = classifySkillRead(input.toolName, input.arguments, input.skillDirs);
+    if (!hit || hit.kind !== 'loaded' || !hit.skillId)
+        return null;
+    return { skillId: hit.skillId, path: hit.path };
+}
+export async function recordSkillEntrySpan(state, input) {
+    const alreadyInSkillSpan = typeof state['skillSpanId'] === 'string' && Boolean(state['skillSpanId']);
+    const hit = skillEntryInvocationFromTool({
+        toolName: input.toolName,
+        arguments: input.arguments,
+        skillDirs: input.skillDirs,
+        alreadyInSkillSpan,
+    });
+    if (!hit)
+        return;
+    const identity = skillTraceIdentity(state, hit.skillId, hit.path);
+    const fields = skillSpanFields(identity, { path: hit.path, source: 'skill_md' });
+    const spanId = await startGraphSpan(state, {
+        name: hit.skillId,
+        type: 'skill',
+        extra: {
+            ...(fields.version ? { version: fields.version } : {}),
+            input: fields.input,
+        },
+    });
+    await completeGraphSpan(state, spanId, {
+        status: 'completed',
+        output: { skillId: hit.skillId, path: hit.path },
+    });
+}

package/dist/graph/adapters/skill-read.d.ts

@@ -2,6 +2,16 @@ export interface SkillDirRef {
     skillId: string;
     bundlePath: string;
 }
+/** 技能包落点：Agent 预装 / 用户装配 / 开发态 overlay。 */
+export type SkillSpace = 'agent' | 'user' | 'local';
+/**
+ * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
+ * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
+ */
+export declare function classifySkillSpace(bundleOrFilePath: string, opts?: {
+    agentDir?: string;
+    userId?: string;
+}): SkillSpace | undefined;
 /**
  * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
  */

package/dist/graph/adapters/skill-read.js

@@ -33,6 +33,39 @@ function skillIdFromSkillsSegment(norm) {
     const match = norm.match(/(?:^|\/)(?:preinstall\/)?skills\/([^/]+)(?:\/|$)/i);
     return match?.[1] ?? '';
 }
+/**
+ * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
+ * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
+ */
+export function classifySkillSpace(bundleOrFilePath, opts) {
+    if (!bundleOrFilePath)
+        return undefined;
+    const target = normalizeForMatch(bundleOrFilePath);
+    const agentDir = opts?.agentDir?.trim();
+    if (agentDir) {
+        const root = normalizeForMatch(agentDir);
+        const pre = `${root}/preinstall/skills`;
+        if (target === pre || target.startsWith(`${pre}/`))
+            return 'agent';
+        const uid = opts?.userId?.trim();
+        if (uid) {
+            const user = `${root}/users/${uid}/skills`;
+            if (target === user || target.startsWith(`${user}/`))
+                return 'user';
+        }
+        if (new RegExp(`^${escapeRegExp(root)}/users/[^/]+/skills(/|$)`).test(target))
+            return 'user';
+        return 'local';
+    }
+    if (/(^|\/)preinstall\/skills(\/|$)/i.test(target))
+        return 'agent';
+    if (/(^|\/)users\/[^/]+\/skills(\/|$)/i.test(target))
+        return 'user';
+    return undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
  */

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

@@ -9,7 +9,8 @@
  */
 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 { skillSpanFields, skillTraceIdentity } from './skill-entry-span.js';
 import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { pickContextFields } from '../../token/context-window.js';
@@ -60,9 +61,10 @@ 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;
+            const identity = skillTraceIdentity(state, resolvedSkillId);
             if (!resuming) {
                 adapter.emitStreamEvent({
                     type: 'skill.started',
@@ -71,22 +73,31 @@ export class SubGraphCompiler {
                     timestamp: new Date().toISOString(),
                     payload: {
                         skillId: resolvedSkillId,
-                        skillName,
+                        skillName: identity.skillName || skillName,
+                        ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
+                        ...(identity.skillVersion ? { skillVersion: identity.skillVersion } : {}),
                     },
                 });
             }
             let skillSpanId = existingSpanId || null;
             if (!resuming && traceCollector && traceId) {
                 try {
+                    const fields = skillSpanFields(identity, { source: 'subgraph' });
                     skillSpanId = await traceCollector.createNode({
                         traceId,
                         name: resolvedSkillId || dsl.name || 'skill',
                         type: 'skill',
                         agentCode: state['agentCode'] ?? state['agentId'],
-                        metadata: { skillId: resolvedSkillId, taskId: state['taskId'], correlationId: state['correlationId'] },
+                        ...(fields.version ? { version: fields.version } : {}),
+                        input: fields.input,
+                        metadata: {
+                            taskId: state['taskId'],
+                            correlationId: state['correlationId'],
+                        },
                     });
                 }
-                catch {
+                catch (err) {
+                    warnTraceSpanFailure('createNode', { type: 'skill', name: resolvedSkillId || dsl.name || 'skill', traceId }, err);
                     skillSpanId = null;
                 }
             }
@@ -145,7 +156,7 @@ export class SubGraphCompiler {
                     hitlRespondedBy: state['hitlRespondedBy'],
                 };
                 const result = await adapter.runIsolatedLlmStreamFlags(() => adapter.invoke(subGraph, subGraphState));
-                // RT-6: 记录成功
+                // 进程内调试记录；生产记录是上面的 skill Span
                 await auditCtx?.finish({
                     status: 'success',
                     tokenUsage: result.tokenUsage,
@@ -160,8 +171,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 +235,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.d.ts

@@ -43,6 +43,12 @@ export interface ToolNodeProgress {
     node?: string;
     skillId?: string;
     skillDirs?: SkillDirRef[];
+    /** 已在 Skill 子图内（state.skillSpanId）；读 SKILL.md 不再发 skill.started */
+    inSkillSubgraph?: boolean;
+    skillSpace?: 'agent' | 'user' | 'local';
+    skillVersion?: string;
+    skillName?: string;
+    toolVersion?: string;
 }
 export declare class ToolNode {
     private readonly orchestrator;

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

@@ -10,12 +10,13 @@
  * @see requirements.md Requirement 8 AC1, AC3, AC5
  */
 import { resolveJailFromState } from '../../tool/harness-primitives.js';
+import { recordSkillEntrySpan, skillEntryInvocationFromTool, skillTraceIdentity } from '../adapters/skill-entry-span.js';
 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 { toolTraceIdentity } 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,19 +103,21 @@ 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']
             ? state['activatedSkill']
             : undefined;
+        const inSkillSubgraph = typeof state['skillSpanId'] === 'string' && Boolean(state['skillSpanId']);
         const emitProgress = (data) => {
             this.onProgress?.({
                 ...data,
                 node: nodeId,
                 ...(skillId ? { skillId } : {}),
                 ...(skillDirs.length > 0 ? { skillDirs } : {}),
+                ...(inSkillSubgraph ? { inSkillSubgraph: true } : {}),
             });
         };
         // 5. 并行执行所有 Tool 调用（附 Trace span）
@@ -125,6 +128,7 @@ export class ToolNode {
                 const parentNodeId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
                     ? state['skillSpanId']
                     : undefined;
+                const identity = toolTraceIdentity(loadedTools?.[req.toolName], req.toolName);
                 return await traceCollector.createNode({
                     traceId,
                     name: req.toolName,
@@ -132,6 +136,7 @@ export class ToolNode {
                     parentNodeId,
                     toolRuntime: req.toolRuntime === 'both' ? 'both' : req.toolRuntime,
                     agentCode: agentCode || undefined,
+                    ...(identity.toolVersion ? { version: identity.toolVersion } : {}),
                     input: req.arguments,
                     metadata: {
                         toolCallId: req.toolCallId,
@@ -139,10 +144,12 @@ export class ToolNode {
                         taskId: req.taskId,
                         correlationId: req.correlationId,
                         skillId,
+                        ...(identity.toolset ? { toolset: identity.toolset } : {}),
                     },
                 });
             }
-            catch {
+            catch (err) {
+                warnTraceSpanFailure('createNode', { type: 'tool', name: req.toolName, traceId, toolCallId: req.toolCallId }, err);
                 return null;
             }
         }));
@@ -154,13 +161,15 @@ export class ToolNode {
         const needsHitl = Boolean(this.hitlHandler) &&
             requests.some((req) => confirmationTools.has(req.toolName));
         const runOne = async (req, i) => {
-            const toolset = toolsetCodeFromLoaded(loadedTools?.[req.toolName]);
+            const toolIdentity = toolTraceIdentity(loadedTools?.[req.toolName], req.toolName);
+            const toolset = toolIdentity.toolset;
             const resumingHitl = isHitlDecision(state['hitlChoice']);
             if (!resumingHitl) {
                 emitProgress({
                     toolCallId: req.toolCallId,
                     toolName: req.toolName,
                     ...(toolset ? { toolset } : {}),
+                    ...(toolIdentity.toolVersion ? { toolVersion: toolIdentity.toolVersion } : {}),
                     status: 'started',
                     arguments: req.arguments,
                 });
@@ -197,14 +206,27 @@ export class ToolNode {
                 }
                 const executionTime = Date.now() - startedAt;
                 if (result.success) {
+                    const catalog = skillEntryInvocationFromTool({
+                        toolName: req.toolName,
+                        arguments: req.arguments,
+                        skillDirs,
+                        alreadyInSkillSpan: inSkillSubgraph,
+                    });
+                    const skillIdentity = catalog
+                        ? skillTraceIdentity(state, catalog.skillId, catalog.path)
+                        : undefined;
                     emitProgress({
                         toolCallId: result.toolCallId,
                         toolName: result.toolName,
                         ...(toolset ? { toolset } : {}),
+                        ...(toolIdentity.toolVersion ? { toolVersion: toolIdentity.toolVersion } : {}),
                         status: 'completed',
                         arguments: req.arguments,
                         content: result.content,
                         executionTime,
+                        ...(skillIdentity?.skillSpace ? { skillSpace: skillIdentity.skillSpace } : {}),
+                        ...(skillIdentity?.skillVersion ? { skillVersion: skillIdentity.skillVersion } : {}),
+                        ...(skillIdentity?.skillName ? { skillName: skillIdentity.skillName } : {}),
                     });
                 }
                 else {
@@ -212,6 +234,7 @@ export class ToolNode {
                         toolCallId: result.toolCallId,
                         toolName: result.toolName,
                         ...(toolset ? { toolset } : {}),
+                        ...(toolIdentity.toolVersion ? { toolVersion: toolIdentity.toolVersion } : {}),
                         status: 'error',
                         arguments: req.arguments,
                         error: result.error ?? 'unknown error',
@@ -227,16 +250,24 @@ export class ToolNode {
                             error: result.error,
                         });
                     }
-                    catch {
-                        // Trace 失败不影响主路径
+                    catch (err) {
+                        warnTraceSpanFailure('completeNode', { type: 'tool', name: req.toolName, traceId, spanId: nodeId }, err);
                     }
                 }
+                if (result.success) {
+                    await recordSkillEntrySpan(state, {
+                        toolName: req.toolName,
+                        arguments: req.arguments,
+                        skillDirs,
+                    });
+                }
                 return result;
             }
             catch (err) {
                 // 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 +285,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/skill-audit-recorder.d.ts

@@ -1,8 +1,8 @@
 /**
- * SkillAuditRecorder — Skill 调用台账（RT-6）
+ * SkillAuditRecorder — 进程内 Skill 调用记录（调试用）
  *
- * 记录每次 Skill（子图）激活的审计明细，供后续分析与看板使用。
- * Runtime 负责写入；Gateway 看不到 Skill 调用。
+ * 生产记录是 Trace 上的 skill Span（子图激活，或成功读 SKILL.md）。
+ * 本记录器默认内存、不对外查询；分析从 Span 聚合，不读这里。
  *
  * @see docs/status/module-status-and-backlog.md RT-6
  */
@@ -48,7 +48,7 @@ export interface SkillInvocationRecord {
 /**
  * ISkillAuditStore — Skill 审计存储接口
  *
- * 默认实现为内存存储；生产环境应接入 PG 或外部审计服务。
+ * 默认内存存储。生产不依赖本接口；Skill 调用记录以 Trace skill Span 为准。
  */
 export interface ISkillAuditStore {
     /** 写入审计记录 */

package/dist/graph/skill-audit-recorder.js

@@ -1,8 +1,8 @@
 /**
- * SkillAuditRecorder — Skill 调用台账（RT-6）
+ * SkillAuditRecorder — 进程内 Skill 调用记录（调试用）
  *
- * 记录每次 Skill（子图）激活的审计明细，供后续分析与看板使用。
- * Runtime 负责写入；Gateway 看不到 Skill 调用。
+ * 生产记录是 Trace 上的 skill Span（子图激活，或成功读 SKILL.md）。
+ * 本记录器默认内存、不对外查询；分析从 Span 聚合，不读这里。
  *
  * @see docs/status/module-status-and-backlog.md RT-6
  */