@gt-fe/eap-runtime 0.0.8 → 0.0.10

package/dist/registry/graph-loader.js

@@ -6,13 +6,13 @@
  */
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { resolveAgentModelAllowlist, resolveAgentPrimaryModel } from './agent-models.js';
+import { resolveAgentModelAllowlist, resolveAgentDefaultModel } from './agent-models.js';
 import { createDeploymentSnapshotFromEnv, isInlineToolDeclaration, overlayToolRefPolicies, } from './deployment-snapshot.js';
 import { preloadGraphNotFound, preloadManifestNotFound, preloadSkillNotFound, preloadToolNotFound, } from './preload-errors.js';
 import { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';
-import { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, } from './skill-tree.js';
-function applyPrimaryModelToGraph(graph, primary) {
-    if (!primary)
+import { inspectAgentSkillTree, listSkillDirs, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, } from './skill-tree.js';
+function applyDefaultModelToGraph(graph, defaultModel) {
+    if (!defaultModel)
         return graph;
     let changed = false;
     const nodes = graph.nodes.map((node) => {
@@ -22,7 +22,7 @@ function applyPrimaryModelToGraph(graph, primary) {
         if (current && current.toLowerCase() !== 'default')
             return node;
         changed = true;
-        return { ...node, config: { ...node.config, model: primary } };
+        return { ...node, config: { ...node.config, model: defaultModel } };
     });
     return changed ? { ...graph, nodes } : graph;
 }
@@ -41,7 +41,7 @@ function assertGraphModelsAllowed(graph, manifest) {
     return graph;
 }
 function finalizeLoadedGraph(graph, manifest) {
-    return assertGraphModelsAllowed(applyPrimaryModelToGraph(graph, resolveAgentPrimaryModel((manifest ?? {}))), manifest);
+    return assertGraphModelsAllowed(applyDefaultModelToGraph(graph, resolveAgentDefaultModel((manifest ?? {}))), manifest);
 }
 function asGraphDsl(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -94,57 +94,8 @@ async function resolveSkillPrompt(manifest, bundlePath) {
     }
     return raw;
 }
-/**
- * 解析 Skill scripts[] 为虚拟 Tool 定义。
- * scripts 为可选/非标字段：Skill 包仅强制要求 skill.md，其余文件结构不限；
- * 存在 scripts 声明时才物化为可调用的本地 Tool。
- */
-function resolveSkillScripts(manifest, bundlePath) {
-    const scripts = manifest.scripts;
-    if (!Array.isArray(scripts))
-        return [];
-    const tools = [];
-    for (const script of scripts) {
-        if (!script || typeof script !== 'object')
-            continue;
-        const s = script;
-        const name = s.name;
-        const command = s.command;
-        if (!name || !command)
-            continue;
-        const args = Array.isArray(s.args) ? s.args.map(String) : [];
-        tools.push({
-            toolId: `script:${name}`,
-            name,
-            manifest: {
-                id: `script:${name}`,
-                name,
-                version: '0.0.0',
-                type: 'code',
-                status: 'active',
-                description: s.description ?? `Skill script: ${name}`,
-                execution: {
-                    runtime: command === 'python3' || command === 'python' ? 'python'
-                        : command === 'node' ? 'node'
-                            : 'executable',
-                    handler: args[0] ?? command,
-                    args: args.slice(1),
-                    timeout: 30000,
-                    sandbox: false,
-                    bundlePath,
-                    command,
-                    /** 标记为 Skill 虚拟脚本：Router 优先本机执行，不经 Gateway */
-                    localPreferred: true,
-                    source: 'skill-script',
-                },
-            },
-            inputSchema: { type: 'object', properties: {}, additionalProperties: true },
-        });
-    }
-    return tools;
-}
-function extractSkillToolRefs(manifest) {
-    const refs = manifest.toolRefs ?? manifest.tools;
+function extractSkillToolsets(manifest) {
+    const refs = manifest.toolsets;
     if (!Array.isArray(refs))
         return undefined;
     const out = [];
@@ -156,14 +107,15 @@ function extractSkillToolRefs(manifest) {
         if (!item || typeof item !== 'object')
             continue;
         const o = item;
+        const code = o.code != null ? String(o.code) : undefined;
+        const enabled = Array.isArray(o.enabled)
+            ? o.enabled.filter((x) => typeof x === 'string')
+            : undefined;
         out.push({
-            toolId: o.toolId != null ? String(o.toolId) : undefined,
-            name: o.name != null ? String(o.name) : o.toolset != null ? String(o.toolset) : undefined,
+            name: o.name != null ? String(o.name) : code,
             version: o.version != null ? String(o.version) : undefined,
-            toolset: o.toolset != null ? String(o.toolset) : undefined,
-            enabledTools: Array.isArray(o.enabledTools)
-                ? o.enabledTools.filter((x) => typeof x === 'string')
-                : undefined,
+            code,
+            enabled,
             autoApprove: Array.isArray(o.autoApprove)
                 ? o.autoApprove.filter((x) => typeof x === 'string')
                 : undefined,
@@ -305,7 +257,7 @@ function fromPreinstallTool(pre) {
  * 以工具集为管理单元：单个 MCP 服务 / 单个代码包 = 一个工具集，可含多个子工具；
  * 子工具继承集级 server/package 配置，合成各自的 execution。
  * 无 tools[] 时回退为单工具 manifest（tool.manifest.json 结构）。
- * enabledTools 为可选白名单（agent.manifest toolRefs）；缺省启用全部子工具。
+ * enabled 为可选白名单（agent.manifest toolsets[].enabled）；缺省启用全部子工具。
  */
 function expandPreinstallToolset(pre, options) {
     const m = pre.manifest;
@@ -659,7 +611,7 @@ export class GraphLoader {
         if (graphFromManifest && typeof graphFromManifest === 'object') {
             return finalizeLoadedGraph(yamlGraphToDsl(agentCode, graphFromManifest), manifest);
         }
-        const model = resolveAgentPrimaryModel(manifest) ?? 'default';
+        const model = resolveAgentDefaultModel(manifest) ?? 'default';
         return {
             ...DEFAULT_GRAPH_DSL,
             name: agentCode,
@@ -851,7 +803,7 @@ export class GraphLoader {
         return definitions;
     }
     /**
-     * 从预装快照加载已装配 Skill 完整定义（workflow / prompt / toolRefs）
+     * 加载已装配 Skill：SKILL.md 目录（Agent Skills）或可选 skill.manifest.json。
      * @param options.userId 用于解析 users/<userId>/skills（优先于 preinstall/skills）
      * @param options.allowMissingSkills 缺失时跳过而非抛错（warm 预热用）
      */
@@ -889,8 +841,7 @@ export class GraphLoader {
                     asGraphDsl(pre.manifest.definitionSnapshot);
                 // 解析 prompt：支持文件路径引用（./ 开头）
                 const prompt = await resolveSkillPrompt(pre.manifest, pre.bundlePath);
-                // 解析 scripts[] 为虚拟 Tool
-                const scriptTools = resolveSkillScripts(pre.manifest, pre.bundlePath);
+                const entryFile = typeof pre.manifest.skillEntryFile === 'string' ? pre.manifest.skillEntryFile : undefined;
                 skills.push({
                     skillId: pre.skillId,
                     name: pre.name,
@@ -898,10 +849,11 @@ export class GraphLoader {
                     version: pre.version,
                     workflow,
                     prompt,
-                    toolRefs: extractSkillToolRefs(pre.manifest),
+                    bundlePath: pre.bundlePath,
+                    entryFile,
+                    toolsets: extractSkillToolsets(pre.manifest),
                     inputDef: pre.manifest.inputDef,
                     outputDef: pre.manifest.outputDef,
-                    scriptTools: scriptTools.length > 0 ? scriptTools : undefined,
                 });
             }
             else if (!this.strictPreinstall) {
@@ -940,16 +892,25 @@ export class GraphLoader {
      * 磁盘多出来的未声明目录不进选择清单；正文热加载仍看已装配目录的 mtime。
      */
     async resolveSkillRefs(snap, agentDir, userId) {
+        const byId = new Map();
+        const add = (ref) => {
+            if (ref.skillId && !byId.has(ref.skillId))
+                byId.set(ref.skillId, ref);
+        };
         if (agentDir) {
             const assembly = await readSkillAssembly(agentDir, userId);
             if (assembly && assembly.skills.length > 0) {
-                return assembly.skills.map((skillId) => ({ skillId }));
+                for (const skillId of assembly.skills)
+                    add({ skillId });
             }
         }
-        const byId = new Map();
-        for (const ref of snap?.skills ?? []) {
-            if (ref.skillId)
-                byId.set(ref.skillId, ref);
+        if (byId.size === 0) {
+            for (const ref of snap?.skills ?? [])
+                add(ref);
+        }
+        for (const root of this.localSkillRoots()) {
+            for (const skillId of await listSkillDirs(root))
+                add({ skillId });
         }
         return [...byId.values()];
     }
@@ -981,5 +942,7 @@ export class GraphLoader {
 }
 function resolveLocalSkillsDir(explicit) {
     const candidate = explicit?.trim() || process.env.EAP_LOCAL_SKILLS_DIR?.trim();
-    return candidate || undefined;
+    if (candidate)
+        return path.resolve(candidate);
+    return path.resolve(process.cwd(), 'skills');
 }

package/dist/registry/index.d.ts

@@ -1,4 +1,4 @@
-export { resolveAgentPrimaryModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
+export { resolveAgentDefaultModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
 export { createAgentRegistryClient, type AgentRegistryClient, type AgentRegistryRecord, type AgentManifest } from './agent-registry-client.js';
 export { GraphLoader, type GraphLoaderConfig, type LoadToolDefinitionsOptions, type LoadAgentOptions } from './graph-loader.js';
 export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, type CachedAgentDefinitions, } from './definition-cache.js';

package/dist/registry/index.js

@@ -1,4 +1,4 @@
-export { resolveAgentPrimaryModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
+export { resolveAgentDefaultModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
 export { createAgentRegistryClient } from './agent-registry-client.js';
 export { GraphLoader } from './graph-loader.js';
 export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';

package/dist/registry/skill-tree.d.ts

@@ -3,6 +3,9 @@ export interface AgentSkillTree {
     /** `${count}:${maxMtimeMs}`；增删改任一 skill 文件都会变 */
     stamp: string;
 }
+/** Agent Skills 入口：目录内的 SKILL.md（规范名优先）。 */
+export declare function findSkillEntryFile(bundlePath: string): Promise<string | null>;
+export declare function listSkillDirs(root: string): Promise<string[]>;
 export interface SkillAssembly {
     skills: string[];
     source: string;

package/dist/registry/skill-tree.js

@@ -10,6 +10,7 @@ import { readdir, stat, access, readFile } from 'node:fs/promises';
 import { watch } from 'node:fs';
 import { constants as fsConstants } from 'node:fs';
 import path from 'node:path';
+import { SKILL_ENTRY_CANDIDATES } from '@gt-fe/eap-contracts';
 const SKILL_CODE = /^[a-z0-9][a-z0-9-]*$/;
 async function exists(p) {
     try {
@@ -20,6 +21,43 @@ async function exists(p) {
         return false;
     }
 }
+/** Agent Skills 入口：目录内的 SKILL.md（规范名优先）。 */
+export async function findSkillEntryFile(bundlePath) {
+    for (const name of SKILL_ENTRY_CANDIDATES) {
+        const candidate = path.join(bundlePath, name);
+        if (await exists(candidate))
+            return candidate;
+    }
+    try {
+        const files = await readdir(bundlePath);
+        const hit = files.find((file) => file.toLowerCase() === 'skill.md');
+        return hit ? path.join(bundlePath, hit) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function listSkillDirs(root) {
+    let names = [];
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const codes = [];
+    for (const name of names) {
+        if (!SKILL_CODE.test(name))
+            continue;
+        const bundle = path.join(root, name);
+        const info = await stat(bundle).catch(() => undefined);
+        if (!info?.isDirectory())
+            continue;
+        if (await findSkillEntryFile(bundle))
+            codes.push(name);
+    }
+    return codes.sort();
+}
 async function maxMtime(filePath, fallback = 0) {
     try {
         const info = await stat(filePath);
@@ -101,9 +139,9 @@ export async function inspectAgentSkillTree(agentDir, userId, extraRoots = []) {
             const bundleStat = await stat(bundle).catch(() => undefined);
             if (!bundleStat?.isDirectory())
                 continue;
-            const hasMain = (await exists(path.join(bundle, 'skill.md'))) ||
-                (await exists(path.join(bundle, 'skill.manifest.json')));
-            if (!hasMain)
+            const hasEntry = await findSkillEntryFile(bundle);
+            const hasOverlay = await exists(path.join(bundle, 'skill.manifest.json'));
+            if (!hasEntry && !hasOverlay)
                 continue;
             codes.add(name);
             latest = Math.max(latest, bundleStat.mtimeMs);

package/dist/runtime/agent-runtime.d.ts

@@ -14,9 +14,11 @@ import { HitlHandler } from '../graph/hitl/hitl-handler.js';
 import type { GraphLoader } from '../registry/graph-loader.js';
 import type { SessionContextService } from '../session/session-context.service.js';
 import type { MessageService } from '../session/message.service.js';
+import type { SessionService, SessionRecord, MessageRecord } from '../session/session.service.js';
+import { type ILlmTurnLog, type LlmTurnIndexEntry, type LlmTurnLogKind, type LlmTurnRecord } from '../debug/llm-turn-log.js';
 import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
 import type { TaskService } from '../task/task.service.js';
-import type { ExecuteParams, ExecuteResult, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SeedSessionMessagesParams, SeedSessionMessagesResult } from './types.js';
+import type { ExecuteParams, ExecuteResult, ForkParams, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SeedSessionMessagesParams, SeedSessionMessagesResult } from './types.js';
 export interface ForkRelationRecord {
     originalTraceId: string;
     forkedTraceId: string;
@@ -34,6 +36,10 @@ export interface AgentRuntimeDeps {
     graphLoader?: GraphLoader;
     /** 多轮短期记忆写回；未注入时 AgentRuntime.stream 跳过持久化 */
     messageService?: MessageService;
+    /** 会话查询（getConversation）；未注入时仅返回 messages/llmTurns */
+    sessionService?: SessionService;
+    /** 每步 LLM 入参/响应落盘；未注入时按环境默认 `.eap/llm-turns` */
+    turnLog?: ILlmTurnLog;
     /**
      * Hosting 注入的 Trace 采集器。与 ExecuteParams.traceId 同时存在时，
      * Skill/Tool 节点会 createNode/completeNode。不注入则只发 SSE，不写 Span。
@@ -41,6 +47,27 @@ export interface AgentRuntimeDeps {
     traceCollector?: ITraceCollector;
     recordForkRelation?: RecordForkRelation;
 }
+/** 一次对话详情：消息 + 每步 LLM 入参/响应。File / 内存 / Postgres 同一套结构。 */
+export interface ConversationDetail {
+    sessionId: string;
+    session: SessionRecord | null;
+    messages: MessageRecord[];
+    llmTurns: LlmTurnRecord[];
+    llmTurnIndex: LlmTurnIndexEntry[];
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+        byNode: Record<string, {
+            input: number;
+            output: number;
+        }>;
+    };
+    storage: {
+        llmTurnKind?: LlmTurnLogKind;
+        llmTurnDir?: string;
+    };
+}
 /**
  * AgentRuntime — 管理 Graph 执行的 SDK 门面
  */
@@ -69,6 +96,17 @@ export declare class AgentRuntime {
      * @throws PARAMS_INVALID messageService 未注入（无存储无法写入）
      */
     seedSessionMessages(params: SeedSessionMessagesParams): Promise<SeedSessionMessagesResult>;
+    /**
+     * 查询一次对话详情：会话元数据、消息、每步 LLM 落盘（入参、响应、URL、模型、脱敏 sk、提示词）。
+     * 本地默认读 `.eap/sessions` + `.eap/llm-turns/{sessionId}/`。
+     */
+    getConversation(sessionId: string): Promise<ConversationDetail>;
+    listLlmTurns(sessionId: string): Promise<LlmTurnIndexEntry[]>;
+    getLlmTurn(sessionId: string, turnId: string): Promise<LlmTurnRecord | null>;
+    listConversations(options?: {
+        userId?: string;
+    }): Promise<SessionRecord[]>;
+    private resolveTurnLog;
     /** 同步执行 Graph（经 InvokeOrchestrator，内含 loadedTools 注入） */
     execute(params: ExecuteParams): Promise<ExecuteResult>;
     /**
@@ -92,9 +130,10 @@ export declare class AgentRuntime {
      */
     streamResumeHitl(taskId: string, response: HitlResponse): AsyncIterable<SSEEvent>;
     /**
-     * 从 Checkpoint Fork 并真实重新执行
+     * 从 Checkpoint Fork 并真实重新执行。
+     * taskId / traceId 由上层发号；Runtime 不 createFlow、不另发 Task 号。
      */
-    fork(checkpointId: string, overrides?: ForkOverrides): Promise<ForkResult>;
+    fork(params: ForkParams): Promise<ForkResult>;
     private prepareHitlResume;
     private rebuildExecutableGraph;
     private handleHitlTimeout;

package/dist/runtime/agent-runtime.js

@@ -8,7 +8,9 @@
  */
 import { randomUUID } from 'node:crypto';
 import { HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
-import { toLoadedSkillMap, mergeSkillScriptTools } from '../tool/system-prompt-builder.js';
+import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
+import { assembleLoadedTools } from '../tool/harness-primitives.js';
+import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
 import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractHitlThreadId, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../session/persist-turn-messages.js';
 import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { resolveExecutionContext } from '../governance/governance-client.js';
@@ -42,6 +44,7 @@ export class AgentRuntime {
         if (typeof this.deps.hitlHandler.setTimeoutListener === 'function') {
             this.deps.hitlHandler.setTimeoutListener((event) => this.handleHitlTimeout(event));
         }
+        this.deps.hitlHandler.setTraceCollector?.(this.deps.traceCollector);
     }
     /** 从 GraphLoader 解析 tool manifest 映射（invoke/stream/resume/fork 共用） */
     async resolveLoadedTools(agentCode, agentVersion) {
@@ -126,6 +129,64 @@ export class AgentRuntime {
         })));
         return { sessionId, seeded: true };
     }
+    /**
+     * 查询一次对话详情：会话元数据、消息、每步 LLM 落盘（入参、响应、URL、模型、脱敏 sk、提示词）。
+     * 本地默认读 `.eap/sessions` + `.eap/llm-turns/{sessionId}/`。
+     */
+    async getConversation(sessionId) {
+        const turnLog = this.resolveTurnLog();
+        const [session, messages, llmTurnIndex] = await Promise.all([
+            this.deps.sessionService
+                ? this.deps.sessionService.findSession(sessionId).catch(() => null)
+                : Promise.resolve(null),
+            this.deps.messageService
+                ? this.deps.messageService.getMessages(sessionId)
+                : Promise.resolve([]),
+            turnLog ? turnLog.list(sessionId) : Promise.resolve([]),
+        ]);
+        const llmTurns = [];
+        if (turnLog) {
+            for (const entry of llmTurnIndex) {
+                const record = await turnLog.read(sessionId, entry.id);
+                if (record)
+                    llmTurns.push(record);
+            }
+        }
+        const tokens = summarizeTurnTokens(llmTurns);
+        return {
+            sessionId,
+            session,
+            messages,
+            llmTurns,
+            llmTurnIndex,
+            tokens,
+            storage: { llmTurnKind: turnLog?.kind, llmTurnDir: turnLog?.baseDir },
+        };
+    }
+    async listLlmTurns(sessionId) {
+        const turnLog = this.resolveTurnLog();
+        if (!turnLog)
+            return [];
+        return turnLog.list(sessionId);
+    }
+    async getLlmTurn(sessionId, turnId) {
+        const turnLog = this.resolveTurnLog();
+        if (!turnLog)
+            return null;
+        return turnLog.read(sessionId, turnId);
+    }
+    async listConversations(options) {
+        if (options?.userId && this.deps.sessionService) {
+            return this.deps.sessionService.listSessions(options.userId);
+        }
+        if (this.deps.sessionService) {
+            return this.deps.sessionService.listAllSessions();
+        }
+        return [];
+    }
+    resolveTurnLog() {
+        return this.deps.turnLog ?? createFileLlmTurnLogFromEnv();
+    }
     /** 同步执行 Graph（经 InvokeOrchestrator，内含 loadedTools 注入） */
     async execute(params) {
         const agentCode = resolveAgentCode(params);
@@ -203,8 +264,7 @@ export class AgentRuntime {
             })
             : undefined;
         const skillDefinitions = toLoadedSkillMap(loadedSkills);
-        // Skill scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）
-        const loadedTools = mergeSkillScriptTools(loadedToolsBase, loadedSkills);
+        const loadedTools = assembleLoadedTools(loadedToolsBase);
         const promptRoots = this.deps.graphLoader
             ? await this.deps.graphLoader.resolvePromptRoots(agentCode, params.agentVersion)
             : [];
@@ -405,8 +465,8 @@ export class AgentRuntime {
         const agentVersion = (typeof resumedState.agentVersion === 'string' && resumedState.agentVersion) ||
             undefined;
         const graph = await this.rebuildExecutableGraph(agentCode, agentVersion);
-        const loadedTools = resumedState.loadedTools ??
-            (await this.resolveLoadedTools(agentCode, agentVersion));
+        const loadedTools = assembleLoadedTools(resumedState.loadedTools ??
+            (await this.resolveLoadedTools(agentCode, agentVersion)));
         const skillFromState = resumedState.skillDefinitions;
         const skillBundle = skillFromState
             ? {
@@ -536,16 +596,23 @@ export class AgentRuntime {
         }
     }
     /**
-     * 从 Checkpoint Fork 并真实重新执行
+     * 从 Checkpoint Fork 并真实重新执行。
+     * taskId / traceId 由上层发号；Runtime 不 createFlow、不另发 Task 号。
      */
-    async fork(checkpointId, overrides = {}) {
+    async fork(params) {
+        const { checkpointId, taskId, traceId } = params;
+        if (!taskId?.trim() || !traceId?.trim()) {
+            throw new AppError(ErrorCodes.PARAMS_INVALID, 'fork requires non-empty taskId and traceId from the caller', { exposeMessage: true });
+        }
+        const overrides = {
+            ...params.overrides,
+            executionContext: params.executionContext ?? params.overrides?.executionContext,
+        };
         const source = await this.deps.checkpointSaver.loadByCheckpointId(checkpointId);
         if (!source) {
             throw new AppError(ErrorCodes.HOSTING_CHECKPOINT_NOT_FOUND, `Checkpoint not found: ${checkpointId}`, { exposeMessage: true });
         }
-        // 优先级：overrides（agentCode > 废弃 agentId）> Checkpoint state
         const agentCode = overrides.agentCode ??
-            overrides.agentId ??
             source.state.agentCode ??
             source.state.agentId ??
             'unknown-agent';
@@ -556,8 +623,9 @@ export class AgentRuntime {
             source.checkpointId;
         const newThreadId = randomUUID();
         const forkedCheckpoint = await this.deps.checkpointSaver.fork(checkpointId, newThreadId, overrides);
-        const correlationId = randomUUID();
+        const correlationId = overrides.executionContext?.correlationId ?? randomUUID();
         const task = await this.deps.taskService.create({
+            id: taskId,
             agentId: agentCode,
             sessionId,
             userId,
@@ -566,25 +634,12 @@ export class AgentRuntime {
             timeout: 600_000,
         });
         await this.deps.taskService.updateStatus(task.id, 'running');
-        let newTraceId = randomUUID();
-        if (this.deps.traceCollector) {
-            newTraceId = await this.deps.traceCollector.createFlow({
-                traceId: newTraceId,
-                agentId: agentCode,
-                agentCode,
-                sessionId,
-                userId,
-                correlationId,
-                callType: 'fork',
-                metadata: { checkpointId, originalTraceId },
-            });
-        }
         const agentVersion = overrides.agentVersion ??
             (typeof source.state.agentVersion === 'string' ? source.state.agentVersion : undefined);
         const graph = await this.rebuildExecutableGraph(agentCode, agentVersion);
         const loadedToolsBase = await this.resolveLoadedTools(agentCode, agentVersion);
         const skillBundle = await this.resolveLoadedSkills(agentCode, userId, agentVersion);
-        const loadedTools = mergeSkillScriptTools(loadedToolsBase, skillBundle.loadedSkills);
+        const loadedTools = assembleLoadedTools(loadedToolsBase);
         try {
             const result = await this.deps.graphEngine.invoke(graph, {
                 ...forkedCheckpoint.state,
@@ -594,20 +649,26 @@ export class AgentRuntime {
                 executionContext: overrides.executionContext,
                 loadedTools,
                 ...skillBundle,
-                traceId: newTraceId,
+                taskId: task.id,
+                traceId,
                 traceCollector: this.deps.traceCollector,
             });
             await this.deps.taskService.updateStatus(task.id, 'success', result.output);
             if (this.deps.recordForkRelation) {
-                await this.deps.recordForkRelation({
-                    originalTraceId,
-                    forkedTraceId: newTraceId,
-                    checkpointId,
-                    overrides,
-                });
+                try {
+                    await this.deps.recordForkRelation({
+                        originalTraceId,
+                        forkedTraceId: traceId,
+                        checkpointId,
+                        overrides,
+                    });
+                }
+                catch {
+                    // Fork 关系上报失败不阻断执行结果
+                }
             }
             return {
-                newTraceId,
+                newTraceId: traceId,
                 originalTraceId,
                 newTaskId: task.id,
                 checkpointId,
@@ -618,14 +679,14 @@ export class AgentRuntime {
                     output_tokens: result.tokenUsage.output,
                     total_tokens: result.tokenUsage.total,
                 },
-                compareUrl: `/traces/compare?traceId1=${originalTraceId}&traceId2=${newTraceId}`,
+                compareUrl: `/traces/compare?traceId1=${originalTraceId}&traceId2=${traceId}`,
             };
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Unknown error';
             await this.deps.taskService.updateStatus(task.id, 'failed', message);
             return {
-                newTraceId,
+                newTraceId: traceId,
                 originalTraceId,
                 newTaskId: task.id,
                 checkpointId,
@@ -771,6 +832,21 @@ export class AgentRuntime {
         };
     }
 }
+function summarizeTurnTokens(turns) {
+    const byNode = {};
+    let input = 0;
+    let output = 0;
+    for (const turn of turns) {
+        input += turn.response.inputTokens ?? 0;
+        output += turn.response.outputTokens ?? 0;
+        const nodeId = turn.nodeId ?? 'llm';
+        const bucket = byNode[nodeId] ?? { input: 0, output: 0 };
+        bucket.input += turn.response.inputTokens ?? 0;
+        bucket.output += turn.response.outputTokens ?? 0;
+        byNode[nodeId] = bucket;
+    }
+    return { input, output, total: input + output, byNode };
+}
 /** 工厂：从运行时依赖组装 AgentRuntime */
 export function createAgentRuntime(deps) {
     return new AgentRuntime(deps);

package/dist/runtime/dev-runtime.d.ts

@@ -27,6 +27,7 @@ import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService,
 import { type AgentRuntime } from './agent-runtime.js';
 import type { RuntimeStorageProfile } from './storage-profile.js';
 import type { HitlResponse, ResumeHitlResult, SSEEvent } from './types.js';
+import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
 /** createDevRuntime 返回值（CLI 嵌入用，可选字段后续扩展） */
 export interface DevRuntime {
     invokeOrchestrator: InvokeOrchestrator;
@@ -39,6 +40,7 @@ export interface DevRuntime {
     streamResumeHitl: (taskId: string, response: HitlResponse) => AsyncIterable<SSEEvent>;
     sessionService: SessionService;
     messageService: MessageService;
+    turnLog?: ILlmTurnLog;
     sessionContextService: SessionContextService;
     taskService: TaskService;
     tokenStatsService: TokenStatsService;
@@ -53,9 +55,10 @@ export interface DevRuntime {
         llmDefaultModel: string;
         governanceKind: 'AllowAll' | 'Http';
         storageProfile: RuntimeStorageProfile;
-        sessionStoreKind: 'file' | 'in-memory';
-        messageStoreKind: 'memory' | 'file' | 'postgres';
-        checkpointKind: 'memory' | 'file' | 'redis+pg' | 'pg';
+        sessionStoreKind: 'file' | 'hosting';
+        messageStoreKind: 'file' | 'postgres';
+        checkpointKind: 'file' | 'redis+pg';
+        llmTurnKind: 'file' | 'postgres';
         foundationConfigured: boolean;
         skillHotReload: boolean;
     };