@gt-fe/eap-runtime 0.0.19 → 0.0.20

package/dist/api/handlers/invoke.handler.js

@@ -18,6 +18,7 @@ import { randomUUID } from 'node:crypto';
 import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../../session/persist-turn-messages.js';
 import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
 import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
+import { recordTaskTokenUsages } from '../../token/record-task-token-usage.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
 import { resolveAgentSystemPromptFromLoader } from '../../registry/graph-loader.js';
@@ -310,24 +311,17 @@ export class InvokeOrchestrator {
         };
         // 将 Graph 层面的 token 消耗记录到 Task（按节点明细逐个记录，便于审计）
         if (graphUsage.perNode && graphUsage.perNode.length > 0) {
-            for (const u of graphUsage.perNode) {
-                await this.taskService.recordTokenUsage(task.id, {
-                    nodeId: u.nodeId,
-                    model: u.model,
-                    inputTokens: u.inputTokens,
-                    outputTokens: u.outputTokens,
-                    costEstimate: 0,
-                });
-            }
+            await recordTaskTokenUsages(this.taskService, task.id, graphUsage.perNode);
         }
         else if (graphUsage.total > 0) {
-            await this.taskService.recordTokenUsage(task.id, {
-                nodeId: 'graph',
-                model: 'unknown',
-                inputTokens: graphUsage.input,
-                outputTokens: graphUsage.output,
-                costEstimate: 0,
-            });
+            await recordTaskTokenUsages(this.taskService, task.id, [
+                {
+                    nodeId: 'graph',
+                    model: 'unknown',
+                    inputTokens: graphUsage.input,
+                    outputTokens: graphUsage.output,
+                },
+            ]);
         }
         // ─── Step 7: 完成 Task (running → success) ───
         await this.taskService.updateStatus(task.id, 'success', graphResult.output);

package/dist/api/handlers/stream.handler.js

@@ -22,6 +22,7 @@
 import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../../session/persist-turn-messages.js';
 import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
 import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
+import { recordTaskTokenUsages } from '../../token/record-task-token-usage.js';
 import { SSEEmitter } from '../../sse/sse-emitter.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
@@ -303,6 +304,7 @@ export class StreamOrchestrator {
         catch (error) {
             const hitlPaused = unwrapHitlPaused(error);
             if (hitlPaused) {
+                await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
                 await this.taskService.updateStatus(taskId, 'waiting_hitl', buildHitlWaitingTaskOutput({
                     threadId: hitlPaused.threadId,
                     question: hitlPaused.question,
@@ -370,6 +372,7 @@ export class StreamOrchestrator {
             taskId,
             duration,
         }));
+        await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
         // Task 状态流转 → success
         await this.taskService.updateStatus(taskId, 'success');
         // ─── Step 8b: 持久化 transcript（与 invoke 同序）───

package/dist/contracts/index.d.ts

@@ -7,5 +7,5 @@
  * - LLM 调用：由模型路由模块实现
  * - 存储接口：由各存储后端实现
  */
-export type { ITraceCollector, TraceEvent, TraceSession, } from './trace-collector.js';
+export type { ITraceCollector, CompleteNodeParams, TraceEvent, TraceSession, } from './trace-collector.js';
 export type { IPermissionChecker } from './permission-checker.js';

package/dist/contracts/trace-collector.d.ts

@@ -85,6 +85,8 @@ export interface ExecutionNodeEvent {
     type: 'start' | 'llm' | 'tool' | 'skill' | 'condition' | 'hitl' | 'end';
     /** 工具运行环境（type=tool） */
     toolRuntime?: 'local' | 'server' | 'both';
+    /** skill/tool 包版本；与 TraceClient RecordSpanParams.version 同义 */
+    version?: string;
     /** Agent 对外主键 */
     agentCode?: string;
     /** 输入数据 */
@@ -92,6 +94,19 @@ export interface ExecutionNodeEvent {
     /** 扩展元数据（如 skillId） */
     metadata?: Record<string, unknown>;
 }
+/**
+ * 完成执行节点参数。llm Span 的 model / token 与 stats.node_token_usage 同源。
+ */
+export interface CompleteNodeParams {
+    status: 'completed' | 'failed';
+    output?: unknown;
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** llm Span：实际模型标识；与 NodeTokenUsage.model 相同 */
+    model?: string;
+}
 /**
  * 链路事件
  *
@@ -176,14 +191,7 @@ export interface ITraceCollector {
      * @param nodeId - 节点 ID
      * @param params - 完成参数
      */
-    completeNode(nodeId: string, params: {
-        status: 'completed' | 'failed';
-        output?: unknown;
-        error?: string;
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-    }): Promise<void>;
+    completeNode(nodeId: string, params: CompleteNodeParams): Promise<void>;
     /**
      * Checkpoint 已落盘后的引用回调。Hosting 适配 TraceClient.recordCheckpointRef。
      * Runtime 仅在同时有 traceId 与 spanId 时调用；不传 graph state 正文。

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

@@ -60,6 +60,7 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
      * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
+     * 读 SKILL.md 另发 skill.started / skill.completed（与 Trace type=skill Span 对齐）；子图内不重复。
      */
     private emitToolExecutionEvents;
     /**

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

@@ -30,6 +30,7 @@ import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { pickContextFields } from '../../token/context-window.js';
 import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
 import { classifySkillRead } from './skill-read.js';
+import { skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { withGraphSpan } from '../trace-span.js';
 import { executionTraceFromState, getExecutionStream, runWithExecutionTrace, } from '../execution-trace-context.js';
 /** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
@@ -171,6 +172,7 @@ export class LangGraphAdapter {
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
      * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
+     * 读 SKILL.md 另发 skill.started / skill.completed（与 Trace type=skill Span 对齐）；子图内不重复。
      */
     emitToolExecutionEvents(progress) {
         const stream = getExecutionStream();
@@ -185,16 +187,48 @@ export class LangGraphAdapter {
         const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
         if (skillRead && progress.status === 'completed') {
             if (skillRead.kind === 'loaded') {
+                const skillId = skillRead.skillId || loc.skillId || skillRead.path;
                 stream.sink({
                     type: 'skill.loaded',
                     taskId,
                     correlationId,
                     timestamp,
                     payload: {
-                        skillId: skillRead.skillId || loc.skillId || skillRead.path,
+                        skillId,
                         path: skillRead.path,
                     },
                 });
+                const catalogSkill = skillEntryInvocationFromTool({
+                    toolName: progress.toolName,
+                    arguments: progress.arguments,
+                    skillDirs: progress.skillDirs,
+                    alreadyInSkillSpan: progress.inSkillSubgraph,
+                });
+                if (catalogSkill) {
+                    stream.sink({
+                        type: 'skill.started',
+                        taskId,
+                        correlationId,
+                        timestamp,
+                        payload: {
+                            skillId: catalogSkill.skillId,
+                            skillName: progress.skillName || catalogSkill.skillId,
+                            path: catalogSkill.path,
+                            ...(progress.skillSpace ? { skillSpace: progress.skillSpace } : {}),
+                            ...(progress.skillVersion ? { skillVersion: progress.skillVersion } : {}),
+                        },
+                    });
+                    stream.sink({
+                        type: 'skill.completed',
+                        taskId,
+                        correlationId,
+                        timestamp,
+                        payload: {
+                            skillId: catalogSkill.skillId,
+                            skillName: catalogSkill.skillId,
+                        },
+                    });
+                }
             }
             else {
                 stream.sink({
@@ -216,6 +250,7 @@ export class LangGraphAdapter {
                     toolCallId: progress.toolCallId,
                     toolName: progress.toolName,
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
+                    ...(progress.toolVersion ? { toolVersion: progress.toolVersion } : {}),
                     arguments: progress.arguments ?? {},
                     ...loc,
                 },

package/dist/graph/adapters/skill-entry-span.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 成功读 SKILL.md 时写 Trace `type=skill` Span。
+ *
+ * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 与子图激活走同一 collector.createNode({ type: 'skill' })。
+ * 声明版本在 createNode.version；skillSpace 只在 input。
+ * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
+ */
+import { type SkillDirRef, type SkillSpace } from './skill-read.js';
+export interface SkillTraceIdentity {
+    skillId: string;
+    skillName?: string;
+    skillVersion?: string;
+    skillSpace?: SkillSpace;
+}
+export declare function skillTraceIdentity(state: Record<string, unknown>, skillId: string, fallbackPath?: string): SkillTraceIdentity;
+export declare function skillSpanFields(identity: SkillTraceIdentity, extra?: {
+    path?: string;
+    source?: string;
+}): {
+    version?: string;
+    input: Record<string, unknown>;
+};
+export declare function skillEntryInvocationFromTool(input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    skillDirs?: SkillDirRef[];
+    alreadyInSkillSpan?: boolean;
+}): {
+    skillId: string;
+    path: string;
+} | null;
+export declare function recordSkillEntrySpan(state: Record<string, unknown>, input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    skillDirs?: SkillDirRef[];
+}): Promise<void>;

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

@@ -10,6 +10,7 @@
 import { assertSkillPermission } from '../../governance/permission-guard.js';
 import { LangGraphAdapter } from './langgraph.adapter.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';
@@ -63,6 +64,7 @@ export class SubGraphCompiler {
             // 用父图这次调用上的 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,19 +73,27 @@ 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 (err) {
@@ -146,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,

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,11 +10,12 @@
  * @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 { 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'];
@@ -109,12 +110,14 @@ export class ToolNode {
         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,6 +144,7 @@ export class ToolNode {
                         taskId: req.taskId,
                         correlationId: req.correlationId,
                         skillId,
+                        ...(identity.toolset ? { toolset: identity.toolset } : {}),
                     },
                 });
             }
@@ -155,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,
                 });
@@ -198,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 {
@@ -213,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',
@@ -232,6 +254,13 @@ export class ToolNode {
                         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) {

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
  */

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

@@ -1,21 +1,14 @@
 /**
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
-import type { ITraceCollector, ExecutionNodeEvent } from '../contracts/trace-collector.js';
+import type { ITraceCollector, ExecutionNodeEvent, CompleteNodeParams } from '../contracts/trace-collector.js';
 export declare function startGraphSpan(state: Record<string, unknown>, input: {
     name: string;
     type: ExecutionNodeEvent['type'];
     parentSpanId?: string;
     extra?: Partial<Omit<ExecutionNodeEvent, 'traceId' | 'name' | 'type' | 'parentNodeId'>>;
 }): Promise<string | undefined>;
-export declare function completeGraphSpan(state: Record<string, unknown>, spanId: string | undefined, params: {
-    status: 'completed' | 'failed';
-    output?: unknown;
-    error?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-}, collectorOverride?: ITraceCollector): Promise<void>;
+export declare function completeGraphSpan(state: Record<string, unknown>, spanId: string | undefined, params: CompleteNodeParams, collectorOverride?: ITraceCollector): Promise<void>;
 export declare function withGraphSpan(state: Record<string, unknown>, spec: {
     name: string;
     type: ExecutionNodeEvent['type'];

package/dist/graph/trace-span.js

@@ -57,6 +57,7 @@ export async function withGraphSpan(state, spec, run) {
             totalTokens: usage?.inputTokens != null || usage?.outputTokens != null
                 ? (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0)
                 : undefined,
+            ...(typeof usage?.model === 'string' && usage.model ? { model: usage.model } : {}),
         });
         return spanId ? { ...result, lastSpanId: spanId } : result;
     }

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export * from './memory/index.js';
 export * from './common/index.js';
 export * from './registry/index.js';
 export * from './providers/index.js';
-export type { ITraceCollector, TraceEvent, TraceSession, ExecutionFlowEvent, ExecutionNodeEvent, TraceLinkEvent, TraceLinkNodeEvent, } from './contracts/trace-collector.js';
+export type { ITraceCollector, CompleteNodeParams, TraceEvent, TraceSession, ExecutionFlowEvent, ExecutionNodeEvent, TraceLinkEvent, TraceLinkNodeEvent, } from './contracts/trace-collector.js';
 export type { ExecutionContext, CallerType, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionDenyReason, } from '@gt-fe/eap-contracts';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
 export type { IGovernanceClient } from './governance/index.js';

package/dist/runtime/agent-runtime.js

@@ -17,6 +17,7 @@ import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { resolveExecutionContext } from '../governance/governance-client.js';
 import { resolveAgentCode } from '../common/agent-code.js';
 import { resolveTraceId } from '../common/trace-id.js';
+import { collectStreamNodeTokenUsage, recordTaskTokenUsages, } from '../token/record-task-token-usage.js';
 import { resolveSkillInputFromInvokeInput } from '../registry/skill-io-guard.js';
 const HITL_TERMINAL_STATUSES = [
     'success',
@@ -286,6 +287,7 @@ export class AgentRuntime {
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of this.deps.graphEngine.stream(graph, {
                 messages,
@@ -345,8 +347,10 @@ export class AgentRuntime {
                         assistantText += delta;
                     }
                 }
+                collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
                 yield this.runtimeEventToSSE(runtimeEvent, correlationId, task.id);
             }
+            await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
             await this.deps.taskService.updateStatus(task.id, 'success');
             await persistTurnTranscript(this.deps.messageService, {
                 sessionId,
@@ -368,6 +372,7 @@ export class AgentRuntime {
         catch (err) {
             const hitlPaused = unwrapHitlPaused(err);
             if (hitlPaused) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
                 await this.deps.taskService.updateStatus(task.id, 'waiting_hitl', buildHitlWaitingTaskOutput({
                     threadId: hitlPaused.threadId,
                     question: hitlPaused.question,
@@ -516,6 +521,7 @@ export class AgentRuntime {
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of this.deps.graphEngine.stream(graph, continueState)) {
                 if (runtimeEvent.type === 'tool.called') {
@@ -555,8 +561,10 @@ export class AgentRuntime {
                         assistantText += delta;
                     }
                 }
+                collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
                 yield this.runtimeEventToSSE(runtimeEvent, correlationId, taskId);
             }
+            await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
             await this.deps.taskService.updateStatus(taskId, 'success', assistantText || undefined);
             if (sessionId) {
                 await persistTurnTranscript(this.deps.messageService, {
@@ -580,6 +588,7 @@ export class AgentRuntime {
         catch (err) {
             const hitlPaused = unwrapHitlPaused(err);
             if (hitlPaused) {
+                await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
                 await this.deps.taskService.updateStatus(taskId, 'waiting_hitl', buildHitlWaitingTaskOutput({
                     threadId: hitlPaused.threadId,
                     question: hitlPaused.question,
@@ -676,6 +685,19 @@ export class AgentRuntime {
                 traceId,
                 traceCollector: this.deps.traceCollector,
             });
+            if (result.tokenUsage.perNode && result.tokenUsage.perNode.length > 0) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, result.tokenUsage.perNode);
+            }
+            else if (result.tokenUsage.total > 0) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, [
+                    {
+                        nodeId: 'graph',
+                        model: 'unknown',
+                        inputTokens: result.tokenUsage.input,
+                        outputTokens: result.tokenUsage.output,
+                    },
+                ]);
+            }
             await this.deps.taskService.updateStatus(task.id, 'success', result.output);
             if (this.deps.recordForkRelation) {
                 try {

package/dist/sse/trace-collector.d.ts

@@ -6,7 +6,7 @@
  * @see contracts/trace-collector.ts
  * @see sse/sse-emitter.ts
  */
-import type { ExecutionFlowEvent, ExecutionNodeEvent, ITraceCollector, TraceEvent, TraceLinkEvent, TraceLinkNodeEvent, TraceSession } from '../contracts/trace-collector.js';
+import type { CompleteNodeParams, ExecutionFlowEvent, ExecutionNodeEvent, ITraceCollector, TraceEvent, TraceLinkEvent, TraceLinkNodeEvent, TraceSession } from '../contracts/trace-collector.js';
 /**
  * InMemoryTraceCollector — 内存 Trace 采集器（测试用）
  */
@@ -18,14 +18,7 @@ export declare class InMemoryTraceCollector implements ITraceCollector {
     getSession(sessionId: string): Promise<TraceSession | null>;
     createFlow(_event: ExecutionFlowEvent): Promise<string>;
     createNode(_event: ExecutionNodeEvent): Promise<string>;
-    completeNode(_nodeId: string, _params: {
-        status: 'completed' | 'failed';
-        output?: unknown;
-        error?: string;
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-    }): Promise<void>;
+    completeNode(_nodeId: string, _params: CompleteNodeParams): Promise<void>;
     createLink(_event: TraceLinkEvent): Promise<string>;
     createLinkNode(_event: TraceLinkNodeEvent): Promise<string>;
     completeLinkNode(_nodeId: string, _params: {

package/dist/token/index.d.ts

@@ -6,6 +6,8 @@ export { TokenBudgetGuard, TokenBudgetExhaustedError, } from './token-budget-gua
 export { SessionBudgetChecker, SessionBudgetExhaustedError, } from './session-budget-checker.js';
 export type { NodeTokenUsage, TokenBreakdown, TaskTokenSummary, } from './token-stats.service.js';
 export { TokenStatsService } from './token-stats.service.js';
+export { recordTaskTokenUsages, tokenUsageFromNodePayload, collectStreamNodeTokenUsage, } from './record-task-token-usage.js';
+export type { TaskTokenUsageWriter } from './record-task-token-usage.js';
 export type { TokenDetailMode } from './token-detail-mode.js';
 export { contextWindowUsage, buildContextUsage, splitContextUsage, turnSectionChars, pickContextFields, type ContextWindowUsage, type ContextUsageParts, } from './context-window.js';
 export { TokenStatsEmitter } from './token-detail-mode.js';

package/dist/token/index.js

@@ -3,6 +3,7 @@ export { PostgresTokenBudgetRepository } from './pg-token-budget.repository.js';
 export { TokenBudgetGuard, TokenBudgetExhaustedError, } from './token-budget-guard.js';
 export { SessionBudgetChecker, SessionBudgetExhaustedError, } from './session-budget-checker.js';
 export { TokenStatsService } from './token-stats.service.js';
+export { recordTaskTokenUsages, tokenUsageFromNodePayload, collectStreamNodeTokenUsage, } from './record-task-token-usage.js';
 export { contextWindowUsage, buildContextUsage, splitContextUsage, turnSectionChars, pickContextFields, } from './context-window.js';
 export { TokenStatsEmitter } from './token-detail-mode.js';
 // 上下文窗口预算分配

package/dist/token/record-task-token-usage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Task.token_usage 写入：invoke / stream / HITL resume / fork 同一收口。
+ *
+ * 假设：一次 LLM 调用产生一条 TokenUsageRecord（nodeId + model + in/out）。
+ * 来源可以是 Graph.perNode，也可以是 SSE stats.node_token_usage，字段同一套。
+ * 写入失败只 warn，不挡 Task 终态 / HITL（与 Span 采集同一策略）。
+ */
+import type { RuntimeEvent } from '../graph/contracts/executable-graph.js';
+import type { TokenUsageRecord } from '../task/contracts/task-manager.contract.js';
+export interface TaskTokenUsageWriter {
+    recordTokenUsage(taskId: string, usage: TokenUsageRecord): Promise<void>;
+}
+export declare function tokenUsageFromNodePayload(payload: unknown): TokenUsageRecord | undefined;
+export declare function collectStreamNodeTokenUsage(event: Pick<RuntimeEvent, 'type' | 'payload'>, bucket: TokenUsageRecord[]): void;
+export declare function recordTaskTokenUsages(taskService: TaskTokenUsageWriter, taskId: string, usages: Array<{
+    nodeId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costEstimate?: number;
+}>): Promise<void>;

package/dist/token/record-task-token-usage.js

@@ -0,0 +1,52 @@
+/**
+ * Task.token_usage 写入：invoke / stream / HITL resume / fork 同一收口。
+ *
+ * 假设：一次 LLM 调用产生一条 TokenUsageRecord（nodeId + model + in/out）。
+ * 来源可以是 Graph.perNode，也可以是 SSE stats.node_token_usage，字段同一套。
+ * 写入失败只 warn，不挡 Task 终态 / HITL（与 Span 采集同一策略）。
+ */
+import { emitRuntimeLog } from '../common/logger.js';
+export function tokenUsageFromNodePayload(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    const inputTokens = Number(record['inputTokens'] ?? 0);
+    const outputTokens = Number(record['outputTokens'] ?? 0);
+    if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens))
+        return undefined;
+    return {
+        nodeId: typeof record['nodeId'] === 'string' && record['nodeId'] ? record['nodeId'] : 'unknown',
+        model: typeof record['model'] === 'string' && record['model'] ? record['model'] : 'unknown',
+        inputTokens,
+        outputTokens,
+        costEstimate: Number(record['costEstimate'] ?? 0) || 0,
+    };
+}
+export function collectStreamNodeTokenUsage(event, bucket) {
+    if (event.type !== 'stats.node_token_usage')
+        return;
+    const usage = tokenUsageFromNodePayload(event.payload);
+    if (usage)
+        bucket.push(usage);
+}
+export async function recordTaskTokenUsages(taskService, taskId, usages) {
+    for (const usage of usages) {
+        try {
+            await taskService.recordTokenUsage(taskId, {
+                nodeId: usage.nodeId,
+                model: usage.model,
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                costEstimate: usage.costEstimate ?? 0,
+            });
+        }
+        catch (err) {
+            emitRuntimeLog('warn', 'runtime.token', 'task token usage persist failed', {
+                event: 'runtime.token.persist_failed',
+                taskId,
+                nodeId: usage.nodeId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}

package/dist/token/token-stats.service.d.ts

@@ -67,6 +67,8 @@ export declare class TokenStatsService {
      * @param usage - 本次调用的 Token 消耗数据
      */
     record(taskId: string, usage: NodeTokenUsage): void;
+    /** 按记录顺序返回本 Task 的每次 LLM 用量（写入 Task.token_usage 用） */
+    list(taskId: string): NodeTokenUsage[];
     /**
      * 获取 Task 级聚合统计
      *

package/dist/token/token-stats.service.js

@@ -35,6 +35,10 @@ export class TokenStatsService {
             this.usageStore.set(taskId, [usage]);
         }
     }
+    /** 按记录顺序返回本 Task 的每次 LLM 用量（写入 Task.token_usage 用） */
+    list(taskId) {
+        return [...(this.usageStore.get(taskId) ?? [])];
+    }
     /**
      * 获取 Task 级聚合统计
      *

package/dist/tool/index.d.ts

@@ -1,5 +1,5 @@
 export type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCall, LLMToolCallResponse, IToolExecutor, McpListedTool, } from './tool-executor.interface.js';
-export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, } from './mcp-list.js';
+export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, toolsetCodeFromLoaded, toolTraceIdentity, } from './mcp-list.js';
 export { toLoadedToolMap, type LoadedToolDefinition, type LoadedToolMap, type LoadedToolManifestRef, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
 export { HttpToolExecutor, type HttpToolExecutorOptions, } from './http-tool-executor.js';

package/dist/tool/index.js

@@ -1,4 +1,4 @@
-export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, } from './mcp-list.js';
+export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, toolsetCodeFromLoaded, toolTraceIdentity, } from './mcp-list.js';
 export { toLoadedToolMap, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
 export { HttpToolExecutor, } from './http-tool-executor.js';

package/dist/tool/mcp-list.d.ts

@@ -32,6 +32,18 @@ export declare function toolsetCodeFromLoaded(loaded: {
         id?: string;
     };
 } | undefined): string | undefined;
+/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+export declare function toolTraceIdentity(loaded: {
+    toolId?: string;
+    name?: string;
+    manifest?: {
+        id?: string;
+        version?: string;
+    };
+} | undefined, toolName: string): {
+    toolset?: string;
+    toolVersion?: string;
+};
 export interface HydrateMcpToolsAuth {
     authContext: AuthContext;
     correlationId?: string;

package/dist/tool/mcp-list.js

@@ -84,6 +84,21 @@ export function toolsetCodeFromLoaded(loaded) {
     }
     return undefined;
 }
+function declaredToolVersion(toolName, version) {
+    const raw = version?.trim();
+    if (!raw || raw === toolName)
+        return undefined;
+    return raw;
+}
+/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+export function toolTraceIdentity(loaded, toolName) {
+    const toolset = toolsetCodeFromLoaded(loaded);
+    const toolVersion = declaredToolVersion(toolName, loaded?.manifest?.version);
+    return {
+        ...(toolset ? { toolset } : {}),
+        ...(toolVersion ? { toolVersion } : {}),
+    };
+}
 /**
  * 将 MCP discover stub 替换为 tools/list 结果。
  * 无 stub 时原样返回（同一引用）。按 endpoint+user+agent 在执行器内缓存 list。

package/package.json

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