@gt-fe/eap-runtime 0.0.8 → 0.0.10

package/dist/graph/adapters/langgraph-checkpointer.js

@@ -8,6 +8,7 @@
  * @see tasks.md Task 11.5
  */
 import { BaseCheckpointSaver, } from '@langchain/langgraph';
+import { notifyCheckpointRef, stripCheckpointCollectors, } from '../../checkpoint/checkpoint-ref-notify.js';
 /**
  * LangGraphCheckpointer — 桥接 LangGraph BaseCheckpointSaver → ICheckpointSaver
  *
@@ -42,7 +43,8 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
     async put(config, checkpoint, metadata, _newVersions) {
         const threadId = this.extractThreadId(config) ?? `thread-${Date.now()}`;
         const data = this.checkpointToData(threadId, checkpoint, metadata);
-        await this.saver.save(threadId, data);
+        await this.saver.save(threadId, stripCheckpointCollectors(data));
+        await notifyCheckpointRef(data);
         return {
             ...config,
             configurable: {

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

@@ -64,6 +64,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.*。
      */
     private emitToolExecutionEvents;
     /**

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

@@ -18,13 +18,17 @@ import { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
 import { EchoLLMProvider } from '../../providers/echo-llm-provider.js';
 import { ConditionEvaluator } from '../condition-evaluator.js';
-import { SystemPromptBuilder, loadedToolsToApiTools, filterLoadedToolsForSkill } from '../../tool/system-prompt-builder.js';
+import { SystemPromptBuilder, buildToolCatalog, loadedToolsToApiTools } from '../../tool/system-prompt-builder.js';
+import { resolveJailRoots } from '../../tool/harness-primitives.js';
+import os from 'node:os';
 import { bindSelectedSkill } from '../nodes/skill-bind-node.js';
 import { resolveGraphPrompt } from '../resolve-graph-prompt.js';
 import { SkillAuditRecorder } from '../skill-audit-recorder.js';
 import { preloadSkillNotFound } from '../../registry/preload-errors.js';
 import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
+import { classifySkillRead } from './skill-read.js';
+import { withGraphSpan } from '../trace-span.js';
 // ─────────────────────────────────────────────
 // LangGraphAdapter
 // ─────────────────────────────────────────────
@@ -148,6 +152,7 @@ export class LangGraphAdapter {
     /**
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
+     * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
      */
     emitToolExecutionEvents(progress) {
         if (!this.streamSink)
@@ -158,6 +163,30 @@ export class LangGraphAdapter {
             ...(progress.node ? { node: progress.node } : {}),
             ...(progress.skillId ? { skillId: progress.skillId } : {}),
         };
+        const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
+        if (skillRead && progress.status === 'completed') {
+            if (skillRead.kind === 'loaded') {
+                this.streamSink({
+                    type: 'skill.loaded',
+                    taskId,
+                    correlationId,
+                    timestamp,
+                    payload: {
+                        skillId: skillRead.skillId || loc.skillId || skillRead.path,
+                        path: skillRead.path,
+                    },
+                });
+            }
+            else {
+                this.streamSink({
+                    type: 'skill.resource_read',
+                    taskId,
+                    correlationId,
+                    timestamp,
+                    payload: { skillId: skillRead.skillId || loc.skillId, path: skillRead.path },
+                });
+            }
+        }
         if (progress.status === 'started') {
             this.streamSink({
                 type: 'tool.called',
@@ -274,7 +303,6 @@ export class LangGraphAdapter {
                 activeSkillPrompt: ephemeral(undefined),
                 activatedSkill: ephemeral(undefined),
                 skillRoute: ephemeral(undefined),
-                skillSelectRaw: ephemeral(undefined),
                 silentOutput: ephemeral(undefined),
                 promptRoots: ephemeral(undefined),
                 executionContext: ephemeral(undefined),
@@ -282,6 +310,7 @@ export class LangGraphAdapter {
                 traceCollector: ephemeral(undefined),
                 traceId: ephemeral(undefined),
                 skillSpanId: ephemeral(undefined),
+                lastSpanId: ephemeral(undefined),
                 hitlChoice: ephemeral(undefined),
                 // ── LLM Token 使用量：数组累加器 reducer，每次 LLM 节点追加一条使用明细
                 __llmTokenUsage: {
@@ -546,25 +575,22 @@ export class LangGraphAdapter {
             case 'tool':
                 return this.createToolNodeFunction(node);
             case 'condition':
-                return async (state) => {
-                    // 条件节点：根据 config 中的 conditionExpr 评估并写入 __conditionResult
+                return async (state) => withGraphSpan(state, { name: node.id, type: 'condition' }, async () => {
                     const conditionExpr = node.config?.['conditionExpr']
                         ?? node.config?.['conditionFn'];
                     if (conditionExpr) {
                         const branchValues = node.config?.['branchValues']
                             ?? this.extractBranchValuesFromDsl(node.id);
                         const result = await this.conditionEvaluator.evaluate(conditionExpr, state, branchValues, node.config?.['fallback'] ?? '__default__');
-                        return { ...state, currentNode: node.id, __conditionResult: result };
+                        return { currentNode: node.id, __conditionResult: result };
                     }
-                    // 无表达式时透传（由 addConditionalEdge 自行处理）
-                    return { ...state, currentNode: node.id };
-                };
+                    return { currentNode: node.id };
+                });
             case 'subgraph':
                 return this.createSubGraphNodeFunction(node);
             case 'human':
                 return async (state) => {
-                    // HITL 节点：暂停等待人工介入（Task 14）
-                    return { ...state, currentNode: node.id };
+                    return { currentNode: node.id };
                 };
             case 'parallel':
                 return this.createParallelNodeFunction(node);
@@ -639,11 +665,14 @@ export class LangGraphAdapter {
             return undefined;
         const rows = Object.values(defs).map((skill) => {
             const desc = (skill.description ?? '').replace(/\s+/g, ' ').trim();
-            return `- ${skill.skillId}${skill.name && skill.name !== skill.skillId ? `（${skill.name}）` : ''}${desc ? `：${desc}` : ''}`;
+            const entry = skill.entryFile ?? (skill.bundlePath ? `${skill.bundlePath}/SKILL.md` : '');
+            const title = skill.name && skill.name !== skill.skillId ? `${skill.skillId}（${skill.name}）` : skill.skillId;
+            const pathLine = entry ? `\n  SKILL.md: ${entry}` : '';
+            return `- **${title}**${desc ? `：${desc}` : ''}${pathLine}`;
         });
         if (rows.length === 0)
             return undefined;
-        return `# 可用技能\n下列技能已装配，引用时使用 skillId 或 name。\n${rows.join('\n')}`;
+        return `# 可用技能\n要用某个技能时，调用 read_file 读取其 SKILL.md。脚本和参考文档默认在同一目录。\n${rows.join('\n')}`;
     }
     createToolNodeFunction(node) {
         const toolName = node.config?.['tool'] ?? node.id;
@@ -672,6 +701,10 @@ export class LangGraphAdapter {
                     arguments: defaultArgs,
                     node: node.id,
                 });
+                const skillDefs = state['skillDefinitions'];
+                const jailExtraRoots = Object.values(skillDefs ?? {})
+                    .map((skill) => skill.bundlePath)
+                    .filter((p) => Boolean(p));
                 const result = await this.toolExecutor.execute({
                     toolCallId,
                     toolName,
@@ -679,16 +712,22 @@ export class LangGraphAdapter {
                     authContext: { userId, delegationToken, agentCode },
                     correlationId,
                     taskId,
+                    ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
                 });
                 const executionTime = Date.now() - startedAt;
+                const skillDirs = Object.values(skillDefs ?? {})
+                    .filter((skill) => Boolean(skill.bundlePath))
+                    .map((skill) => ({ skillId: skill.skillId, bundlePath: skill.bundlePath }));
                 this.emitToolExecutionEvents({
                     toolCallId: result.toolCallId,
                     toolName: result.toolName,
                     status: result.success ? 'completed' : 'error',
+                    arguments: defaultArgs,
                     content: result.content,
                     error: result.error,
                     executionTime,
                     node: node.id,
+                    ...(skillDirs.length > 0 ? { skillDirs } : {}),
                 });
                 // 重要：messages channel 的 reducer 是 append 语义，只返回新增消息
                 return {
@@ -733,8 +772,8 @@ export class LangGraphAdapter {
             toolChoice: node.config?.['toolChoice'],
         };
         const disableTools = node.config?.['disableTools'] === true;
-        const includeSkillCatalog = node.config?.['includeSkillCatalog'] === true;
         const silent = node.config?.['silent'] === true;
+        const includeSkillCatalog = node.config?.['includeSkillCatalog'] !== false;
         return async (state) => {
             // HITL 续跑：已有未闭合 toolCalls + hitlChoice 时不要再调 LLM（否则会换新 toolCallId）
             const hitlChoice = state['hitlChoice'];
@@ -745,92 +784,109 @@ export class LangGraphAdapter {
                 lastAssistantHasUnansweredToolCalls(rawMessages)) {
                 return { currentNode: node.id };
             }
-            const promptRoots = Array.isArray(state['promptRoots']) ? state['promptRoots'] : [];
-            const resolvedPrompt = resolveGraphPrompt(baseConfig.systemPrompt, promptRoots);
-            const loadedTools = state['loadedTools'];
-            // 旧 Checkpoint 兼容：agentId 仅作读兜底
-            const agentCode = (state['agentCode'] ?? state['agentId']);
-            const activeSkillPrompt = state['activeSkillPrompt'];
-            const skillDefs = state['skillDefinitions'];
-            const activatedSkillId = state['activatedSkill'];
-            // [DEBUG] 打印 loadedTools 实际状态
-            if (process.env.EAP_LLM_DEBUG === '1') {
-                const toolNames = loadedTools ? Object.keys(loadedTools) : [];
-                console.log(`[LLM-DEBUG] node=${node.id} loadedTools=${toolNames.length}:`, toolNames);
-            }
-            const catalog = includeSkillCatalog ? this.buildSkillCatalog(skillDefs) : undefined;
-            const developerPrompt = [catalog, activeSkillPrompt, resolvedPrompt]
-                .filter((s) => Boolean(s && s.trim()))
-                .join('\n\n');
-            const execCtx = state['executionContext'];
-            const userId = (typeof execCtx?.userId === 'string' && execCtx.userId) || state['userId'];
-            // 1. 构建 system prompt（平台规则 + 技能提示 + 开发者提示词）
-            const builtPrompt = this.systemPromptBuilder.build({
-                developerPrompt: developerPrompt || undefined,
-                agentCode,
-                userId,
-            });
-            // 2. 工具走 API 的 tools 参数，不塞进 system prompt
-            const scopedTools = activatedSkillId && skillDefs
-                ? filterLoadedToolsForSkill(loadedTools, skillDefs[activatedSkillId])
-                : loadedTools;
-            const apiTools = disableTools ? [] : loadedToolsToApiTools(scopedTools);
-            const finalConfig = {
-                ...baseConfig,
-                systemPrompt: builtPrompt,
-                tools: disableTools ? undefined : (apiTools.length > 0 ? apiTools : baseConfig.tools),
-                toolChoice: disableTools ? 'none' : baseConfig.toolChoice,
-            };
-            // 流式旁路：有 streamSink 时启用 LLM token 推送；silent 节点不推给用户
-            const enableStream = Boolean(this.streamSink) && !silent;
-            this.reasoningStartedThisTurn = false;
-            this.streamedTextThisTurn = false;
-            const llmNode = new LLMNode(node.id, finalConfig, this.llmProvider, enableStream, enableStream
-                ? (text) => {
-                    if (!this.streamSink || !text)
-                        return;
-                    const timestamp = new Date().toISOString();
-                    if (!this.reasoningStartedThisTurn) {
-                        this.reasoningStartedThisTurn = true;
-                        this.streamIteration += 1;
+            return withGraphSpan(state, { name: node.id, type: 'llm' }, async () => {
+                const promptRoots = Array.isArray(state['promptRoots']) ? state['promptRoots'] : [];
+                const resolvedPrompt = resolveGraphPrompt(baseConfig.systemPrompt, promptRoots);
+                const loadedTools = state['loadedTools'];
+                const agentCode = typeof state['agentCode'] === 'string' ? state['agentCode'] : undefined;
+                const skillDefs = state['skillDefinitions'];
+                // [DEBUG] 打印 loadedTools 实际状态
+                if (process.env.EAP_LLM_DEBUG === '1') {
+                    const toolNames = loadedTools ? Object.keys(loadedTools) : [];
+                    console.log(`[LLM-DEBUG] node=${node.id} loadedTools=${toolNames.length}:`, toolNames);
+                }
+                const catalog = includeSkillCatalog ? this.buildSkillCatalog(skillDefs) : undefined;
+                const toolCatalog = disableTools ? undefined : buildToolCatalog(loadedTools);
+                const execCtx = state['executionContext'];
+                const userId = (typeof execCtx?.userId === 'string' && execCtx.userId) || state['userId'];
+                const workingDirectory = typeof process.cwd === 'function' ? process.cwd() : undefined;
+                const skillDirs = Object.values(skillDefs ?? {})
+                    .filter((skill) => Boolean(skill.bundlePath))
+                    .map((skill) => ({
+                    skillId: skill.skillId,
+                    bundlePath: skill.bundlePath,
+                    entryFile: skill.entryFile,
+                }));
+                const jailRoots = resolveJailRoots({
+                    workdir: workingDirectory,
+                    extraRoots: skillDirs.map((s) => s.bundlePath),
+                });
+                const assembled = this.systemPromptBuilder.build({
+                    developerPrompt: resolvedPrompt || undefined,
+                    skillCatalog: catalog,
+                    toolCatalog,
+                    agentCode,
+                    userId,
+                    workingDirectory,
+                    os: { platform: os.platform(), release: os.release() },
+                    jailRoots,
+                    skillDirs,
+                });
+                const apiTools = disableTools ? [] : loadedToolsToApiTools(loadedTools);
+                const finalConfig = {
+                    ...baseConfig,
+                    systemPrompt: assembled.text,
+                    systemSections: assembled.sections,
+                    turn: {
+                        sessionId: typeof state['sessionId'] === 'string' ? state['sessionId'] : undefined,
+                        taskId: typeof state['taskId'] === 'string' ? state['taskId'] : undefined,
+                        nodeId: node.id,
+                        agentCode,
+                        correlationId: typeof state['correlationId'] === 'string' ? state['correlationId'] : undefined,
+                    },
+                    tools: disableTools ? undefined : (apiTools.length > 0 ? apiTools : baseConfig.tools),
+                    toolChoice: disableTools ? 'none' : baseConfig.toolChoice,
+                };
+                // 流式旁路：有 streamSink 时启用 LLM token 推送；silent 节点不推给用户
+                const enableStream = Boolean(this.streamSink) && !silent;
+                this.reasoningStartedThisTurn = false;
+                this.streamedTextThisTurn = false;
+                const llmNode = new LLMNode(node.id, finalConfig, this.llmProvider, enableStream, enableStream
+                    ? (text) => {
+                        if (!this.streamSink || !text)
+                            return;
+                        const timestamp = new Date().toISOString();
+                        if (!this.reasoningStartedThisTurn) {
+                            this.reasoningStartedThisTurn = true;
+                            this.streamIteration += 1;
+                            this.streamSink({
+                                type: 'reasoning.started',
+                                taskId: undefined,
+                                correlationId: undefined,
+                                timestamp,
+                                payload: {
+                                    iterationCount: this.streamIteration,
+                                    model: finalConfig.model,
+                                },
+                            });
+                        }
+                        this.streamedTextThisTurn = true;
                         this.streamSink({
-                            type: 'reasoning.started',
+                            type: 'response.chunk',
                             taskId: undefined,
                             correlationId: undefined,
                             timestamp,
                             payload: {
-                                iterationCount: this.streamIteration,
-                                model: finalConfig.model,
+                                content: text,
+                                index: this.streamChunkIndex++,
+                                node: node.id,
                             },
                         });
                     }
-                    this.streamedTextThisTurn = true;
-                    this.streamSink({
-                        type: 'response.chunk',
-                        taskId: undefined,
-                        correlationId: undefined,
-                        timestamp,
-                        payload: {
-                            content: text,
-                            index: this.streamChunkIndex++,
-                            node: node.id,
-                        },
-                    });
-                }
-                : undefined);
-            const next = await llmNode.execute(state);
-            if (!silent)
-                return next;
-            const added = Array.isArray(next.messages) ? next.messages[0] : undefined;
-            const raw = added && typeof added === 'object' && typeof added.content === 'string'
-                ? added.content
-                : '';
-            return {
-                ...next,
-                messages: [],
-                silentOutput: raw,
-                skillSelectRaw: raw,
-            };
+                    : undefined);
+                const next = await llmNode.execute(state);
+                if (!silent)
+                    return next;
+                const added = Array.isArray(next.messages) ? next.messages[0] : undefined;
+                const raw = added && typeof added === 'object' && typeof added.content === 'string'
+                    ? added.content
+                    : '';
+                return {
+                    ...next,
+                    messages: [],
+                    silentOutput: raw,
+                };
+            });
         };
     }
     /**

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

@@ -0,0 +1,12 @@
+export interface SkillDirRef {
+    skillId: string;
+    bundlePath: string;
+}
+/**
+ * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ */
+export declare function classifySkillRead(toolName: string, args: Record<string, unknown> | undefined, skillDirs?: SkillDirRef[]): {
+    kind: 'loaded' | 'resource';
+    path: string;
+    skillId: string;
+} | null;

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

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeForMatch(p) {
+    const resolved = path.resolve(p);
+    return (tryRealpath(resolved) ?? resolved).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+function longestSkillMatch(filePath, skillDirs) {
+    if (!skillDirs?.length)
+        return undefined;
+    const target = normalizeForMatch(filePath);
+    let best;
+    for (const dir of skillDirs) {
+        if (!dir.bundlePath)
+            continue;
+        const root = normalizeForMatch(dir.bundlePath);
+        if (target === root || target.startsWith(`${root}/`)) {
+            if (!best || root.length > best.len) {
+                best = { skillId: dir.skillId, bundlePath: root, len: root.length };
+            }
+        }
+    }
+    return best;
+}
+function skillIdFromSkillsSegment(norm) {
+    const match = norm.match(/(?:^|\/)(?:preinstall\/)?skills\/([^/]+)(?:\/|$)/i);
+    return match?.[1] ?? '';
+}
+/**
+ * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ */
+export function classifySkillRead(toolName, args, skillDirs) {
+    const n = toolName.toLowerCase().replace(/-/g, '_');
+    if (n !== 'read_file' && n !== 'read_skill_file' && n !== 'readfile')
+        return null;
+    const filePath = String(args?.path ?? args?.file ?? '');
+    if (!filePath)
+        return null;
+    const norm = filePath.replace(/\\/g, '/');
+    const matched = longestSkillMatch(filePath, skillDirs);
+    const isEntry = /(^|\/)(SKILL\.md|skill\.md)$/i.test(norm);
+    if (matched) {
+        return {
+            kind: isEntry ? 'loaded' : 'resource',
+            path: filePath,
+            skillId: matched.skillId,
+        };
+    }
+    if (isEntry) {
+        return { kind: 'loaded', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
+    }
+    if (/(^|\/)(?:preinstall\/)?skills\//i.test(norm)) {
+        return { kind: 'resource', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
+    }
+    return null;
+}

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

@@ -138,6 +138,7 @@ export class SubGraphCompiler {
                     traceId,
                     traceCollector,
                     skillSpanId: skillSpanId ?? undefined,
+                    lastSpanId: skillSpanId ?? state['lastSpanId'],
                     hitlChoice: state['hitlChoice'],
                     hitlRespondedBy: state['hitlRespondedBy'],
                 };
@@ -185,9 +186,13 @@ export class SubGraphCompiler {
                         ? [{ role: 'assistant', content: result.output }]
                         : [];
                 const perNode = result.tokenUsage?.perNode;
+                const nestedLastSpanId = (typeof result.finalState?.lastSpanId === 'string' && result.finalState.lastSpanId) ||
+                    skillSpanId ||
+                    undefined;
                 return {
                     messages: outputMessages,
                     currentNode: `subgraph:${dsl.name}`,
+                    ...(nestedLastSpanId ? { lastSpanId: nestedLastSpanId } : {}),
                     ...(Array.isArray(perNode) && perNode.length > 0
                         ? {
                             __llmTokenUsage: perNode.map((u) => ({

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

@@ -185,7 +185,7 @@ export interface GraphState {
     forceToolServer?: string[];
     /** GraphLoader 注入：toolName → 运行期 manifest 引用 */
     loadedTools?: import('../../tool/loaded-tool-definition.js').LoadedToolMap;
-    /** GraphLoader 注入：已装配 Skill 列表（兼容） */
+    /** GraphLoader 注入：已装配 Skill 列表 */
     loadedSkills?: import('../../tool/system-prompt-builder.js').LoadedSkillInfo[];
     /** GraphLoader 注入：skillId → 完整定义（子图解析 / prompt） */
     skillDefinitions?: import('../../tool/system-prompt-builder.js').LoadedSkillMap;
@@ -193,8 +193,6 @@ export interface GraphState {
     activeSkillPrompt?: string;
     /** silent LLM 的原始输出；不入对话 messages */
     silentOutput?: string;
-    /** @deprecated 同 silentOutput，兼容旧图 */
-    skillSelectRaw?: string;
     /** 解析 graph 内 ./prompts/*.md 的根目录（agentDir + 工程根） */
     promptRoots?: string[];
     activatedSkill?: string | null;
@@ -207,6 +205,8 @@ export interface GraphState {
     traceCollector?: import('../../contracts/trace-collector.js').ITraceCollector;
     /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
     skillSpanId?: string;
+    /** 最近一次 createNode 的 span id；Checkpoint 引用挂在此 Span 上 */
+    lastSpanId?: string;
     /**
      * HITL 续跑：入口 messages 以 __set 覆盖 checkpoint 历史，避免 append 重复。
      * 仅 stream/invoke 入口使用，不入持久化语义。

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

@@ -11,6 +11,7 @@
  * @see tasks.md Task 14
  */
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { ITraceCollector } from '../../contracts/trace-collector.js';
 import type { ISSEEmitter } from '../../sse/contracts/sse-emitter.contract.js';
 import type { GraphState } from '../contracts/executable-graph.js';
 /** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
@@ -51,6 +52,7 @@ export interface HitlWaitingState {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    hitlSpanId?: string;
 }
 /** HITL 超时错误（保留类型；timer 不再 throw，resume 逾期改走 AppError） */
 export declare class HitlTimeoutError extends Error {
@@ -112,6 +114,7 @@ export interface PersistedHitlWaiting {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    hitlSpanId?: string;
     /** error/cancel 超时已占用此等待；resume 必须拒绝 */
     timedOut?: boolean;
 }
@@ -162,8 +165,12 @@ export declare class HitlHandler {
     private timeoutListener?;
     /** 同一 taskId 上串行化 resume 与 timeout，避免双边占用 */
     private taskLocks;
+    private traceCollector?;
+    /** 进程内 interrupt 的 collector，不进 Checkpoint */
+    private readonly waitingCollectors;
     constructor(checkpointSaver: ICheckpointSaver, sseEmitter: ISSEEmitter, timeoutListener?: HitlTimeoutListener);
     setTimeoutListener(listener: HitlTimeoutListener | undefined): void;
+    setTraceCollector(collector: ITraceCollector | undefined): void;
     /**
      * 中断 Graph 执行，等待人工确认
      *