@gt-fe/eap-runtime 0.0.8 → 0.0.10

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

@@ -10,6 +10,8 @@
  * @see design.md §1.6 hitl.waiting / hitl.resumed 事件
  * @see tasks.md Task 14
  */
+import { notifyCheckpointRef, stripCheckpointCollectors, } from '../../checkpoint/checkpoint-ref-notify.js';
+import { startGraphSpan, completeGraphSpan } from '../trace-span.js';
 // ─────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────
@@ -151,8 +153,9 @@ export function buildHitlWaitedPayload(paused) {
  */
 function prepareHitlCheckpointState(state) {
     const raw = state;
+    const { traceCollector: _drop, ...rest } = raw;
     return {
-        ...state,
+        ...rest,
         userId: state.userId ?? raw.userId ?? '',
         loadedTools: state.loadedTools ?? raw.loadedTools,
         forceToolServer: state.forceToolServer ?? raw.forceToolServer,
@@ -162,6 +165,7 @@ function prepareHitlCheckpointState(state) {
         delegationToken: state.delegationToken ?? raw.delegationToken,
         skillSpanId: state.skillSpanId ?? raw.skillSpanId,
         traceId: state.traceId ?? (typeof raw.traceId === 'string' ? raw.traceId : undefined),
+        lastSpanId: state.lastSpanId ?? (typeof raw.lastSpanId === 'string' ? raw.lastSpanId : undefined),
     };
 }
 function toTimeoutEvent(waiting) {
@@ -193,6 +197,7 @@ function waitingFromPersisted(persisted, taskId) {
         toolName: persisted.toolName,
         toolSpanId: persisted.toolSpanId,
         skillSpanId: persisted.skillSpanId,
+        hitlSpanId: persisted.hitlSpanId,
     };
 }
 // ─────────────────────────────────────────────
@@ -216,6 +221,9 @@ export class HitlHandler {
     timeoutListener;
     /** 同一 taskId 上串行化 resume 与 timeout，避免双边占用 */
     taskLocks = new Map();
+    traceCollector;
+    /** 进程内 interrupt 的 collector，不进 Checkpoint */
+    waitingCollectors = new Map();
     constructor(checkpointSaver, sseEmitter, timeoutListener) {
         this.checkpointSaver = checkpointSaver;
         this.sseEmitter = sseEmitter;
@@ -224,6 +232,9 @@ export class HitlHandler {
     setTimeoutListener(listener) {
         this.timeoutListener = listener;
     }
+    setTraceCollector(collector) {
+        this.traceCollector = collector;
+    }
     /**
      * 中断 Graph 执行，等待人工确认
      *
@@ -237,6 +248,11 @@ export class HitlHandler {
         const deadlineAt = new Date(Date.now() + timeoutMs).toISOString();
         const skillSpanId = extras.skillSpanId ??
             (typeof state.skillSpanId === 'string' ? state.skillSpanId : undefined);
+        const hitlSpanId = await startGraphSpan(state, {
+            name: extras.toolName ?? 'hitl',
+            type: 'hitl',
+            parentSpanId: extras.toolSpanId ?? skillSpanId,
+        });
         const persisted = {
             taskId,
             threadId,
@@ -247,11 +263,16 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            hitlSpanId,
         };
         const existing = await this.checkpointSaver.load(threadId);
+        const lastSpanId = hitlSpanId ??
+            extras.toolSpanId ??
+            (typeof state.lastSpanId === 'string' ? state.lastSpanId : undefined);
         const persistedState = {
             ...(existing?.state ?? {}),
             ...prepareHitlCheckpointState(state),
+            ...(lastSpanId ? { lastSpanId } : {}),
             [HITL_WAITING_STATE_KEY]: persisted,
         };
         const checkpointData = {
@@ -266,7 +287,13 @@ export class HitlHandler {
             updatedAt: now,
             isDeleted: false,
         };
-        await this.checkpointSaver.save(threadId, checkpointData);
+        const persistedCheckpoint = stripCheckpointCollectors(checkpointData);
+        await this.checkpointSaver.save(threadId, persistedCheckpoint);
+        const liveCollector = state.traceCollector;
+        if (liveCollector) {
+            this.waitingCollectors.set(taskId, liveCollector);
+        }
+        await notifyCheckpointRef(persistedCheckpoint, liveCollector);
         const event = {
             type: 'hitl.waiting',
             data: {
@@ -300,6 +327,7 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            hitlSpanId,
         });
     }
     /**
@@ -335,6 +363,7 @@ export class HitlHandler {
             if (!waiting) {
                 throw new HitlNotWaitingError(taskId);
             }
+            const liveCollector = this.waitingCollectors.get(taskId) ?? this.traceCollector;
             this.clearWaiting(taskId);
             this.resolvedChoices.set(taskId, choice);
             const baseState = prepareHitlCheckpointState(checkpoint.state);
@@ -346,13 +375,18 @@ export class HitlHandler {
                 hitlRespondedBy: userId,
             };
             const now = new Date().toISOString();
-            await this.checkpointSaver.save(waiting.threadId, {
+            await this.checkpointSaver.save(waiting.threadId, stripCheckpointCollectors({
                 ...checkpoint,
                 engineSnapshot: undefined,
                 state: resumedState,
                 updatedBy: userId,
                 updatedAt: now,
-            });
+            }));
+            const hitlSpanId = waiting.hitlSpanId ?? persisted?.hitlSpanId;
+            await completeGraphSpan(resumedState, hitlSpanId, {
+                status: 'completed',
+                output: { choice, userId },
+            }, liveCollector);
             const event = {
                 type: 'hitl.resumed',
                 data: { choice, userId },
@@ -390,6 +424,7 @@ export class HitlHandler {
                     toolSpanId: waiting.toolSpanId ?? persisted.toolSpanId,
                     skillSpanId: waiting.skillSpanId ?? persisted.skillSpanId,
                 });
+                const liveCollector = this.waitingCollectors.get(taskId) ?? this.traceCollector;
                 this.clearWaiting(taskId);
                 if (timeoutEvent.behavior !== 'auto-confirm' && checkpoint) {
                     const marked = {
@@ -400,12 +435,17 @@ export class HitlHandler {
                             timeoutBehavior: timeoutEvent.behavior,
                         },
                     };
-                    await this.checkpointSaver.save(waiting.threadId, {
+                    await this.checkpointSaver.save(waiting.threadId, stripCheckpointCollectors({
                         ...checkpoint,
                         engineSnapshot: undefined,
                         state: marked,
                         updatedAt: new Date().toISOString(),
-                    });
+                    }));
+                    const hitlSpanId = waiting.hitlSpanId ?? persisted.hitlSpanId;
+                    await completeGraphSpan(checkpoint.state, hitlSpanId, {
+                        status: 'failed',
+                        error: 'hitl_timeout',
+                    }, liveCollector);
                 }
                 return timeoutEvent;
             });
@@ -439,6 +479,7 @@ export class HitlHandler {
             clearTimeout(waiting.timer);
         }
         this.waitingTasks.delete(taskId);
+        this.waitingCollectors.delete(taskId);
     }
     async withTaskLock(taskId, fn) {
         const prev = this.taskLocks.get(taskId) ?? Promise.resolve();

package/dist/graph/nodes/llm-node.d.ts

@@ -44,6 +44,20 @@ export interface LLMNodeConfig {
             name: string;
         };
     };
+    /** 具名 system 段（落盘排查，不另发给模型） */
+    systemSections?: Array<{
+        id: string;
+        title: string;
+        body: string;
+    }>;
+    /** 本轮调用定位（session / task / node） */
+    turn?: {
+        sessionId?: string;
+        taskId?: string;
+        nodeId?: string;
+        agentCode?: string;
+        correlationId?: string;
+    };
 }
 /**
  * LLMResponse — LLM 完整响应

package/dist/graph/nodes/skill-bind-node.js

@@ -62,8 +62,7 @@ function buildSkillPrompt(skill, params) {
  */
 export function bindSelectedSkill(state) {
     const incoming = Array.isArray(state.messages) ? [...state.messages] : [];
-    const fromState = (typeof state.silentOutput === 'string' && state.silentOutput)
-        || (typeof state.skillSelectRaw === 'string' ? state.skillSelectRaw : '');
+    const fromState = typeof state.silentOutput === 'string' ? state.silentOutput : '';
     const lastText = lastAssistantText(incoming);
     const lastIsSelector = extractJsonObject(lastText) !== null;
     const parsed = extractJsonObject(fromState) ?? extractJsonObject(lastText);

package/dist/graph/nodes/tool-node.d.ts

@@ -12,6 +12,7 @@
 import type { AuthContext } from '../../tool/tool-executor.interface.js';
 import type { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
 import type { ToolResultInjector } from '../../tool/tool-result-injector.js';
+import type { SkillDirRef } from '../adapters/skill-read.js';
 import type { HitlHandler } from '../hitl/hitl-handler.js';
 /**
  * LangGraphState — LangGraph 内部状态（与 LLMNode 对齐）
@@ -39,6 +40,7 @@ export interface ToolNodeProgress {
     executionTime?: number;
     node?: string;
     skillId?: string;
+    skillDirs?: SkillDirRef[];
 }
 export declare class ToolNode {
     private readonly orchestrator;

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

@@ -13,6 +13,12 @@ import { isHitlDecision, unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { ToolConfirmationInterceptor } from '../../tool/tool-confirmation.js';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
 import { resolveTraceId } from '../../common/trace-id.js';
+function skillDirsFromState(state) {
+    const defs = state['skillDefinitions'];
+    return Object.values(defs ?? {})
+        .filter((skill) => Boolean(skill.bundlePath))
+        .map((skill) => ({ skillId: skill.skillId, bundlePath: skill.bundlePath }));
+}
 export class ToolNode {
     orchestrator;
     injector;
@@ -46,6 +52,8 @@ export class ToolNode {
             return state;
         }
         const loadedTools = state['loadedTools'];
+        const skillDirs = skillDirsFromState(state);
+        const jailExtraRoots = skillDirs.map((dir) => dir.bundlePath);
         // 4. 转换为 ToolCallRequest[]（附带 manifest 路由字段）
         const requests = lastAssistantMessage.toolCalls.map((tc) => {
             const loaded = loadedTools?.[tc.name];
@@ -62,20 +70,27 @@ export class ToolNode {
                 dataScope: loaded?.manifest.dataScope,
                 // dev 上下文 DevMcpExecutor 直连所需；server 上下文会忽略
                 execution: loaded?.manifest.execution,
+                ...(loaded?.manifest.version ? { toolVersion: loaded.manifest.version } : {}),
                 correlationId,
                 taskId,
+                ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
             };
         });
         const executionContext = state['executionContext'];
         const traceCollector = state['traceCollector'];
         const traceId = resolveTraceId(state);
-        const agentCode = String(state['agentCode'] ?? state['agentId'] ?? '');
+        const agentCode = String(state['agentCode'] ?? '');
         const nodeId = this.nodeId ?? 'tool-node';
         const skillId = typeof state['activatedSkill'] === 'string' && state['activatedSkill']
             ? state['activatedSkill']
             : undefined;
         const emitProgress = (data) => {
-            this.onProgress?.({ ...data, node: nodeId, ...(skillId ? { skillId } : {}) });
+            this.onProgress?.({
+                ...data,
+                node: nodeId,
+                ...(skillId ? { skillId } : {}),
+                ...(skillDirs.length > 0 ? { skillDirs } : {}),
+            });
         };
         // 5. 并行执行所有 Tool 调用（附 Trace span）
         const spanIds = await Promise.all(requests.map(async (req) => {
@@ -158,6 +173,7 @@ export class ToolNode {
                         toolCallId: result.toolCallId,
                         toolName: result.toolName,
                         status: 'completed',
+                        arguments: req.arguments,
                         content: result.content,
                         executionTime,
                     });
@@ -167,6 +183,7 @@ export class ToolNode {
                         toolCallId: result.toolCallId,
                         toolName: result.toolName,
                         status: 'error',
+                        arguments: req.arguments,
                         error: result.error ?? 'unknown error',
                         executionTime,
                     });
@@ -202,6 +219,7 @@ export class ToolNode {
                     toolCallId: req.toolCallId,
                     toolName: req.toolName,
                     status: 'error',
+                    arguments: req.arguments,
                     error: message,
                     executionTime,
                 });
@@ -240,10 +258,11 @@ export class ToolNode {
             success: result.success,
             ...('file' in result && result.file ? { file: result.file } : {}),
         }));
-        // 7. 返回更新后的 state（仅含新增 messages + currentNode）
+        const lastSpanId = [...spanIds].reverse().find((id) => Boolean(id));
         return {
             messages: toolMessages,
             currentNode: nodeId,
+            ...(lastSpanId ? { lastSpanId } : {}),
         };
     }
     // ─────────────────────────────────────────────
@@ -282,11 +301,7 @@ export class ToolNode {
     }
     buildAuthContext(state) {
         const executionContext = state['executionContext'];
-        // 旧 Checkpoint / 历史调用方兼容：agentId 仅作读兜底
-        const agentCode = String(state['agentCode'] ??
-            state['agentId'] ??
-            this.defaultAuthContext.agentCode ??
-            this.defaultAuthContext.agentId);
+        const agentCode = String(state['agentCode'] ?? this.defaultAuthContext.agentCode ?? '');
         // 优先 ExecutionContext（invoke Token.sub），保证所有 Tool/MCP 出站同一身份
         const userId = String(executionContext?.userId ?? state['userId'] ?? this.defaultAuthContext.userId);
         const delegationToken = String(executionContext?.delegationToken ??
@@ -315,7 +330,7 @@ export class ToolNode {
             loadedTools: state['loadedTools'],
             forceToolServer: state['forceToolServer'],
             executionContext: state['executionContext'],
-            agentCode: (state['agentCode'] ?? state['agentId']),
+            agentCode: state['agentCode'],
             correlationId: state['correlationId'],
             taskId: state['taskId'],
             sessionId: state['sessionId'],

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

@@ -0,0 +1,22 @@
+/**
+ * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
+ */
+import type { ITraceCollector, ExecutionNodeEvent } 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 withGraphSpan(state: Record<string, unknown>, spec: {
+    name: string;
+    type: ExecutionNodeEvent['type'];
+}, run: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;

package/dist/graph/trace-span.js

@@ -0,0 +1,69 @@
+/**
+ * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
+ */
+import { resolveTraceId } from '../common/trace-id.js';
+export async function startGraphSpan(state, input) {
+    const collector = state['traceCollector'];
+    const traceId = resolveTraceId(state);
+    if (!collector || !traceId)
+        return undefined;
+    const parentNodeId = input.parentSpanId ??
+        (typeof state['skillSpanId'] === 'string' && state['skillSpanId']
+            ? state['skillSpanId']
+            : undefined);
+    try {
+        return await collector.createNode({
+            traceId,
+            name: input.name,
+            type: input.type,
+            parentNodeId,
+            agentCode: (typeof state['agentCode'] === 'string' && state['agentCode']) ||
+                (typeof state['agentId'] === 'string' ? state['agentId'] : undefined),
+            ...input.extra,
+            metadata: {
+                taskId: state['taskId'],
+                correlationId: state['correlationId'],
+                ...(input.extra?.metadata ?? {}),
+            },
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function completeGraphSpan(state, spanId, params, collectorOverride) {
+    const collector = collectorOverride ?? state['traceCollector'];
+    if (!collector?.completeNode || !spanId)
+        return;
+    try {
+        await collector.completeNode(spanId, params);
+    }
+    catch {
+        // Trace 失败不影响主路径
+    }
+}
+export async function withGraphSpan(state, spec, run) {
+    const spanId = await startGraphSpan(state, spec);
+    try {
+        const result = await run();
+        const usage = Array.isArray(result['__llmTokenUsage'])
+            ? result['__llmTokenUsage'].at(-1)
+            : undefined;
+        await completeGraphSpan(state, spanId, {
+            status: 'completed',
+            inputTokens: usage?.inputTokens,
+            outputTokens: usage?.outputTokens,
+            totalTokens: usage?.inputTokens != null || usage?.outputTokens != null
+                ? (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0)
+                : undefined,
+        });
+        return spanId ? { ...result, lastSpanId: spanId } : result;
+    }
+    catch (err) {
+        await completeGraphSpan(state, spanId, {
+            status: 'failed',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}

package/dist/index.d.ts

@@ -19,3 +19,6 @@ export type { ITraceCollector, TraceEvent, TraceSession, ExecutionFlowEvent, Exe
 export type { ExecutionContext, CallerType, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionDenyReason, } from '@gt-fe/eap-contracts';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
 export type { IGovernanceClient } from './governance/index.js';
+export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
+export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';
+export type { ILlmTurnLog, LlmTurnRecord, LlmTurnIndexEntry, LlmTurnContext, LlmTurnLogKind, } from './debug/llm-turn-log.js';

package/dist/index.js

@@ -30,3 +30,5 @@ export * from './registry/index.js';
 // LLM Providers
 export * from './providers/index.js';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
+export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
+export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';

package/dist/memory/compression/compression.repository.d.ts

@@ -13,21 +13,7 @@ export interface IPgPool {
     }>;
 }
 /**
- * CREATE TABLE compression_records (
- *   id                    VARCHAR(36)   PRIMARY KEY,
- *   session_id            VARCHAR(36)   NOT NULL,
- *   task_id               VARCHAR(36)   NULL,
- *   original_message_count INT          NOT NULL,
- *   compressed_message_count INT        NOT NULL,
- *   original_tokens       INT           NOT NULL,
- *   compressed_tokens     INT           NOT NULL,
- *   strategy              VARCHAR(20)   NOT NULL,
- *   summary_content       TEXT          NOT NULL,
- *   created_by            VARCHAR(36)   NOT NULL DEFAULT 'system',
- *   created_at            TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
- *   INDEX idx_compression_session (session_id),
- *   INDEX idx_compression_task (task_id)
- * );
+ * `compression_records` 不在现行 Runtime DDL 内。见 runtime/docs/ddl.md。
  */
 /**
  * ICompressionRepository — 压缩记录持久化接口

package/dist/providers/echo-llm-provider.d.ts

@@ -7,4 +7,4 @@ export declare class EchoLLMProvider implements ILLMProvider {
     invoke(messages: GraphMessage[], config: LLMNodeConfig): Promise<LLMResponse>;
     stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
 }
-export declare function createDefaultLLMProvider(): ILLMProvider;
+export declare function createDefaultLLMProvider(turnLog?: import('../debug/llm-turn-log.js').ILlmTurnLog): ILLMProvider;

package/dist/providers/echo-llm-provider.js

@@ -75,12 +75,13 @@ export class EchoLLMProvider {
  * - 否则 → EchoLLMProvider
  */
 import { HttpLLMProvider } from './http-llm-provider.js';
-export function createDefaultLLMProvider() {
+export function createDefaultLLMProvider(turnLog) {
     if (process.env.OPENAI_API_KEY) {
         return new HttpLLMProvider({
             apiKey: process.env.OPENAI_API_KEY,
             baseUrl: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1',
             defaultModel: process.env.EAP_DEFAULT_MODEL ?? 'DeepSeek-V4-Pro',
+            turnLog,
         });
     }
     return new EchoLLMProvider();

package/dist/providers/http-llm-provider.d.ts

@@ -8,18 +8,22 @@
  */
 import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';
+import { type ILlmTurnLog } from '../debug/llm-turn-log.js';
 export interface HttpLLMProviderConfig {
     apiKey: string;
     baseUrl?: string;
     defaultModel?: string;
     timeoutMs?: number;
+    turnLog?: ILlmTurnLog;
 }
 export declare class HttpLLMProvider implements ILLMProvider {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly defaultModel;
     private readonly timeoutMs;
+    private readonly turnLog?;
     constructor(config: HttpLLMProviderConfig);
+    private writeTurn;
     invoke(messages: GraphMessage[], config: LLMNodeConfig): Promise<LLMResponse>;
     stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
     private buildRequestBody;