@gt-fe/eap-runtime 0.0.19 → 0.0.21

package/README.md

@@ -8,7 +8,8 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 
 | 日期 | 摘要 |
 |------|------|
-| 2026-08-29 | 待办收口：[`docs/TODO.md`](./docs/TODO.md)。压缩主路径未接；窗口展示不在 Runtime；Gateway 须 `tools/list` |
+| 2026-09-08 | [`docs/TODO.md`](./docs/TODO.md) 改为主路径状态（已落地 / 不在本包），不是排期 |
+| 2026-08-29 | 待办收口：[`docs/TODO.md`](./docs/TODO.md)。此后压缩已挂主路径（默认关）；窗口展示不在 Runtime；Gateway 须 `tools/list` |
 | 2026-08-24 | 0.0.10：官方 Skill / Harness、`ForkParams`、对话详情、存储两档。依赖 `@eap/contracts@0.0.9`。详见 [CHANGELOG.md](./CHANGELOG.md) |
 | 2026-08-21 | 0.0.9：Gateway `/mcp` JSON-RPC 补 `Accept`；`tools/call` 透传工具版本。详见 [CHANGELOG.md](./CHANGELOG.md) |
 | 2026-08-19 | 0.0.8：Skill 子图 SSE 闭环；`ExecuteParams.traceId`；`tool.called` 改为 Tool 节点开始执行。依赖 `@eap/contracts@0.0.8`。详见 [CHANGELOG.md](./CHANGELOG.md) |
@@ -29,7 +30,7 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 | 环境变量总表 | [`docs/governance/governance-env-config.md`](../docs/governance/governance-env-config.md) |
 | 预装联调契约 | [`docs/contracts/preload-hosting-runtime-contract.md`](../docs/contracts/preload-hosting-runtime-contract.md) |
 | 预装加载与请求流转 | [`docs/contracts/runtime-preinstall-load-flow.md`](../docs/contracts/runtime-preinstall-load-flow.md) |
-| Runtime 待办 | [`docs/TODO.md`](./docs/TODO.md) | 压缩主路径、窗口展示、Gateway `tools/list` |
+| Runtime 主路径状态 | [`docs/TODO.md`](./docs/TODO.md) |
 | 技能 FS 待办 | [`docs/TODO-skill-fs.md`](./docs/TODO-skill-fs.md) |
 | 本地 Agent 闭环 | [`docs/workflows/local-agent-dev-loop.md`](../docs/workflows/local-agent-dev-loop.md) |
 

package/dist/api/handlers/invoke.handler.d.ts

@@ -25,6 +25,8 @@ import type { InvokeRequest, InvokeResponse } from '../routes/agent.routes.js';
 import { type GraphLoader } from '../../registry/graph-loader.js';
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
 import type { ITraceCollector } from '../../contracts/trace-collector.js';
+import { type SessionCompressionOptions } from '../../session/apply-session-compression.js';
+import { type SessionMemoryOptions } from '../../session/apply-session-memory.js';
 /**
  * InvokeOrchestrator 构造器依赖
  */
@@ -42,6 +44,8 @@ export interface InvokeOrchestratorDeps {
     /** 用于判断 session Checkpoint 是否已有历史，避免双重 append */
     checkpointSaver?: ICheckpointSaver;
     traceCollector?: ITraceCollector;
+    sessionCompression?: SessionCompressionOptions;
+    sessionMemory?: SessionMemoryOptions;
 }
 /**
  * InvokeOrchestrator — 同步调用全流程编排
@@ -60,6 +64,8 @@ export declare class InvokeOrchestrator {
     private readonly graphLoader?;
     private readonly checkpointSaver?;
     private readonly traceCollector?;
+    private readonly sessionCompression?;
+    private readonly sessionMemory?;
     constructor(deps: InvokeOrchestratorDeps);
     /**
      * 执行同步调用编排
@@ -72,6 +78,7 @@ export declare class InvokeOrchestrator {
     private buildResponse;
     private buildErrorResponse;
     private isTimeoutError;
+    private persistInvokeUsages;
 }
 /** @deprecated 请直接从 `graph/hitl/hitl-handler` 导入；此处保留 re-export 兼容旧测试引用 */
 export { unwrapHitlPaused } from '../../graph/hitl/hitl-handler.js';

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

@@ -15,9 +15,10 @@
  * @see requirements.md Requirement 11 AC1-AC2
  */
 import { randomUUID } from 'node:crypto';
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, sessionVisibleGraphMessages, } from '../../session/persist-turn-messages.js';
 import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
 import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
+import { recordTaskTokenUsages, tokenUsagesFromLlmChannel, } 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';
@@ -27,6 +28,8 @@ import { assembleLoadedTools } from '../../tool/harness-primitives.js';
 import { resolveAgentCode } from '../../common/agent-code.js';
 import { unwrapHitlPaused } from '../../graph/hitl/hitl-handler.js';
 import { resolveTraceId } from '../../common/trace-id.js';
+import { applySessionCompression, } from '../../session/apply-session-compression.js';
+import { applySessionMemory, } from '../../session/apply-session-memory.js';
 // ─────────────────────────────────────────────
 // Default Graph DSL fallback
 // ─────────────────────────────────────────────
@@ -63,6 +66,8 @@ export class InvokeOrchestrator {
     graphLoader;
     checkpointSaver;
     traceCollector;
+    sessionCompression;
+    sessionMemory;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -74,6 +79,8 @@ export class InvokeOrchestrator {
         this.graphLoader = deps.graphLoader;
         this.checkpointSaver = deps.checkpointSaver;
         this.traceCollector = deps.traceCollector;
+        this.sessionCompression = deps.sessionCompression;
+        this.sessionMemory = deps.sessionMemory;
     }
     /**
      * 执行同步调用编排
@@ -158,6 +165,7 @@ export class InvokeOrchestrator {
         });
         // ─── Step 5: 构建/执行 Graph ───
         let graphResult;
+        let finishPoints;
         try {
             // 构建图 — 每次请求创建独立 StateGraph 实例，确保请求间无共享可变状态
             const loadOpts = { agentVersion: req.agentVersion };
@@ -165,6 +173,7 @@ export class InvokeOrchestrator {
                 ? await this.graphLoader.loadGraph(agentCode, loadOpts)
                 : DEFAULT_GRAPH_DSL;
             const graph = await this.graphEngine.buildGraph(graphDsl);
+            finishPoints = graph.finishPoints;
             const loadedToolsBase = this.graphLoader
                 ? toLoadedToolMap(await this.graphLoader.loadToolDefinitions(agentCode, loadOpts))
                 : undefined;
@@ -184,7 +193,19 @@ export class InvokeOrchestrator {
                 : undefined;
             const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
             // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
-            const history = messageRecordsToGraphMessages(sessionContext.messages);
+            const history = await applySessionMemory({
+                history: await applySessionCompression({
+                    history: messageRecordsToGraphMessages(sessionContext.messages),
+                    sessionId,
+                    userId: effectiveUserId,
+                    taskId: task.id,
+                    options: this.sessionCompression,
+                }),
+                userId: effectiveUserId,
+                agentCode,
+                query: typeof req.input === 'string' ? req.input : undefined,
+                options: this.sessionMemory,
+            });
             const messages = await buildTurnGraphMessages({
                 history,
                 input: req.input,
@@ -204,6 +225,8 @@ export class InvokeOrchestrator {
                 sessionId,
                 executionContext: ctx,
                 forceToolServer: req.config?.forceToolServer,
+                ragScope: req.ragScope,
+                ragSources: req.ragSources,
                 loadedTools,
                 loadedSkills,
                 skillDefinitions,
@@ -216,6 +239,8 @@ export class InvokeOrchestrator {
             });
         }
         catch (error) {
+            const usages = await this.persistInvokeUsages(task.id, sessionId);
+            const tokenUsage = tokenUsageTotals(usages);
             const hitlPaused = unwrapHitlPaused(error);
             if (hitlPaused) {
                 await this.taskService.updateStatus(task.id, 'waiting_hitl', buildHitlWaitingTaskOutput({
@@ -235,7 +260,7 @@ export class InvokeOrchestrator {
                     taskId: task.id,
                     sessionId,
                     output: hitlPaused.question,
-                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    tokenUsage,
                     duration: Date.now() - startTime,
                     status: 'waiting_hitl',
                     hitl: {
@@ -252,7 +277,7 @@ export class InvokeOrchestrator {
                     taskId: task.id,
                     sessionId,
                     output: error.message,
-                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    tokenUsage,
                     duration: Date.now() - startTime,
                     status: 'token_exhausted',
                 });
@@ -264,7 +289,7 @@ export class InvokeOrchestrator {
                     taskId: task.id,
                     sessionId,
                     output: 'Task execution timed out',
-                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    tokenUsage,
                     duration: Date.now() - startTime,
                     status: 'timeout',
                 });
@@ -276,7 +301,7 @@ export class InvokeOrchestrator {
                 taskId: task.id,
                 sessionId,
                 output: errorMessage,
-                tokenUsage: { input: 0, output: 0, total: 0 },
+                tokenUsage,
                 duration: Date.now() - startTime,
                 status: 'failed',
             });
@@ -310,33 +335,27 @@ 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);
         // ─── Step 7b: 持久化本轮 transcript（统一顺序：assistant tool_calls → tool → assistant 文本）───
-        const initialMessagesCount = sessionContext.messages.length + 1; // history + 本轮 user
+        // 按 Session 已有行数切 Graph 增量。多段正文收成一条后 Session 比 Graph 短，切点可能提前；finishPoints 只含一个实际节点 id 时靠最后一条纯文本仍落到 merge。
+        const initialMessagesCount = sessionContext.messages.length + 1;
         const allMessages = Array.isArray(graphResult.finalState?.messages)
             ? graphResult.finalState.messages
             : [];
-        const newMessages = allMessages.slice(initialMessagesCount);
+        const newMessages = sessionVisibleGraphMessages(allMessages.slice(initialMessagesCount), finishPoints);
         await persistTurnTranscript(this.messageService, {
             sessionId,
             taskId: task.id,
@@ -375,6 +394,20 @@ export class InvokeOrchestrator {
         }
         return false;
     }
+    async persistInvokeUsages(taskId, sessionId) {
+        if (!this.checkpointSaver)
+            return [];
+        const threadId = resolveCheckpointThreadId({ sessionId, taskId });
+        const ck = await this.checkpointSaver.load(threadId);
+        const usages = tokenUsagesFromLlmChannel(ck?.state);
+        await recordTaskTokenUsages(this.taskService, taskId, usages);
+        return usages;
+    }
+}
+function tokenUsageTotals(usages) {
+    const input = usages.reduce((sum, row) => sum + row.inputTokens, 0);
+    const output = usages.reduce((sum, row) => sum + row.outputTokens, 0);
+    return { input, output, total: input + output };
 }
 // ─────────────────────────────────────────────
 // Module-level Helpers

package/dist/api/handlers/stream.handler.d.ts

@@ -27,6 +27,8 @@ import type { IStateGraphEngine } from '../../graph/contracts/state-graph.contra
 import type { TokenStatsService } from '../../token/token-stats.service.js';
 import type { TokenBudgetGuard } from '../../token/token-budget-guard.js';
 import type { SessionBudgetChecker } from '../../token/session-budget-checker.js';
+import { type SessionCompressionOptions } from '../../session/apply-session-compression.js';
+import { type SessionMemoryOptions } from '../../session/apply-session-memory.js';
 import type { StreamRequest } from '../routes/agent.routes.js';
 import { type GraphLoader } from '../../registry/graph-loader.js';
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
@@ -48,6 +50,8 @@ export interface StreamOrchestratorDeps {
     checkpointSaver?: ICheckpointSaver;
     /** Hosting 注入的 Trace 采集器；与 traceId 同时存在时创建 Skill/Tool span */
     traceCollector?: ITraceCollector;
+    sessionCompression?: SessionCompressionOptions;
+    sessionMemory?: SessionMemoryOptions;
 }
 /**
  * StreamOrchestrator — 流式调用全流程编排
@@ -66,6 +70,8 @@ export declare class StreamOrchestrator {
     private readonly graphLoader?;
     private readonly checkpointSaver?;
     private readonly traceCollector?;
+    private readonly sessionCompression?;
+    private readonly sessionMemory?;
     constructor(deps: StreamOrchestratorDeps);
     /**
      * 执行流式调用编排

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

@@ -19,9 +19,13 @@
  * @see design.md §1.5 /stream 内部执行逻辑
  * @see requirements.md Requirement 11 AC2
  */
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, appendTerminalToolResult, } 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 { iterSessionCompression, } from '../../session/apply-session-compression.js';
+import { applySessionMemory, } from '../../session/apply-session-memory.js';
+import { resolveTokenDetail, shouldEmitTokenSse } from '../../token/token-detail.js';
 import { SSEEmitter } from '../../sse/sse-emitter.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
@@ -71,6 +75,8 @@ export class StreamOrchestrator {
     graphLoader;
     checkpointSaver;
     traceCollector;
+    sessionCompression;
+    sessionMemory;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -82,6 +88,8 @@ export class StreamOrchestrator {
         this.graphLoader = deps.graphLoader;
         this.checkpointSaver = deps.checkpointSaver;
         this.traceCollector = deps.traceCollector;
+        this.sessionCompression = deps.sessionCompression;
+        this.sessionMemory = deps.sessionMemory;
     }
     /**
      * 执行流式调用编排
@@ -206,7 +214,28 @@ export class StreamOrchestrator {
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
         // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
-        const history = messageRecordsToGraphMessages(sessionContext.messages);
+        let history = messageRecordsToGraphMessages(sessionContext.messages);
+        for await (const step of iterSessionCompression({
+            history,
+            sessionId,
+            userId,
+            taskId,
+            options: this.sessionCompression,
+        })) {
+            if (step.kind === 'history') {
+                history = step.messages;
+                continue;
+            }
+            emitter.emit(this.buildSSEEvent(step.kind === 'started' ? 'session.compression.started' : 'session.compression.completed', correlationId, taskId, { ...step.payload }));
+        }
+        history = await applySessionMemory({
+            history,
+            userId,
+            agentCode,
+            query: typeof req.input === 'string' ? req.input : undefined,
+            options: this.sessionMemory,
+        });
+        const tokenDetail = resolveTokenDetail(req.config?.tokenDetail);
         const messages = await buildTurnGraphMessages({
             history,
             input: req.input,
@@ -214,7 +243,7 @@ export class StreamOrchestrator {
             threadId: sessionId,
         });
         const skillInput = resolveSkillInputFromInvokeInput(req.input);
-        let assistantText = '';
+        const assistantBuckets = createStreamAssistantBuckets();
         let toolCallReasoningContent;
         let assistantReasoningContent;
         const pendingToolCalls = [];
@@ -232,6 +261,8 @@ export class StreamOrchestrator {
                 sessionId,
                 executionContext,
                 forceToolServer: req.config?.forceToolServer,
+                ragScope: req.ragScope,
+                ragSources: req.ragSources,
                 loadedTools,
                 loadedSkills,
                 skillDefinitions,
@@ -271,38 +302,20 @@ export class StreamOrchestrator {
                         toolCallReasoningContent = p.reasoningContent;
                     }
                 }
-                if (runtimeEvent.type === 'tool.result') {
-                    const p = runtimeEvent.payload;
-                    if (p.toolCallId && p.toolName) {
-                        toolResults.push({
-                            toolCallId: p.toolCallId,
-                            toolName: p.toolName,
-                            content: p.content,
-                            success: p.success !== false,
-                        });
-                    }
-                }
+                appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
-                const delta = extractStreamTextDelta(runtimeEvent.type, runtimeEvent.payload);
-                if (delta) {
-                    if (runtimeEvent.type === 'response.final') {
-                        // final 若带完整文本则覆盖累加，避免与 chunk 重复拼接
-                        if (delta.trim())
-                            assistantText = delta;
-                    }
-                    else {
-                        assistantText += delta;
-                    }
+                applyStreamTextDelta(assistantBuckets, runtimeEvent.type, runtimeEvent.payload);
+                if (shouldEmitTokenSse(tokenDetail, runtimeEvent.type)) {
+                    emitter.emit(this.runtimeEventToSSE(runtimeEvent, correlationId, taskId));
                 }
-                // 将 RuntimeEvent 转为 SSEEvent 并推送
-                emitter.emit(this.runtimeEventToSSE(runtimeEvent, correlationId, taskId));
             }
         }
         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,
@@ -323,12 +336,14 @@ export class StreamOrchestrator {
             }
             // ─── 错误处理：TokenBudgetExhausted ───
             if (error instanceof TokenBudgetExhaustedError) {
+                await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
                 await this.taskService.updateStatus(taskId, 'token_exhausted', error.message);
                 this.emitErrorAndClose(emitter, correlationId, taskId, error);
                 return;
             }
             // ─── 错误处理：Timeout ───
             if (this.isTimeoutError(error)) {
+                await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
                 await this.taskService.updateStatus(taskId, 'timeout');
                 emitter.emit(this.buildSSEEvent('task.error', correlationId, taskId, {
                     code: ErrorCodes.TASK_TIMEOUT,
@@ -340,6 +355,7 @@ export class StreamOrchestrator {
             }
             // ─── 错误处理：通用错误 ───
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
             await this.taskService.updateStatus(taskId, 'failed', errorMessage);
             this.emitErrorAndClose(emitter, correlationId, taskId, error);
             return;
@@ -348,21 +364,22 @@ export class StreamOrchestrator {
         // Emit: response.final（带完整 assistant 文本，供客户端兜底）
         const tokenStats = this.tokenStatsService.getTaskStats(taskId);
         emitter.emit(this.buildSSEEvent('response.final', correlationId, taskId, {
-            content: assistantText,
+            content: visibleStreamAssistantText(assistantBuckets),
             format: 'text',
         }));
-        // Emit: stats.token_usage
         const totalTokens = (tokenStats.total.input ?? 0) + (tokenStats.total.output ?? 0);
-        emitter.emit(this.buildSSEEvent('stats.token_usage', correlationId, taskId, {
-            total: {
-                input: tokenStats.total.input,
-                output: tokenStats.total.output,
-                total: tokenStats.total.total ?? totalTokens,
-            },
-            byNode: tokenStats.byNode,
-            byModel: tokenStats.byModel,
-            costEstimate: tokenStats.costEstimate,
-        }));
+        if (shouldEmitTokenSse(tokenDetail, 'stats.token_usage')) {
+            emitter.emit(this.buildSSEEvent('stats.token_usage', correlationId, taskId, {
+                total: {
+                    input: tokenStats.total.input,
+                    output: tokenStats.total.output,
+                    total: tokenStats.total.total ?? totalTokens,
+                },
+                byNode: tokenStats.byNode,
+                byModel: tokenStats.byModel,
+                costEstimate: tokenStats.costEstimate,
+            }));
+        }
         // ─── Step 8: 记录 Token + 完成 Task + 关闭 SSE ───
         const duration = Date.now() - startTime;
         // Emit: task.completed
@@ -370,6 +387,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 同序）───
@@ -380,7 +398,9 @@ export class StreamOrchestrator {
             messages: buildTurnTranscriptFromStreamEvents({
                 pendingToolCalls,
                 toolResults,
-                assistantText,
+                assistantTexts: streamAssistantTexts(assistantBuckets),
+                assistantText: visibleStreamAssistantText(assistantBuckets),
+                finishPoints: graph.finishPoints,
                 toolCallReasoningContent,
                 assistantReasoningContent,
             }),

package/dist/api/routes/agent.routes.d.ts

@@ -11,10 +11,17 @@ import type { IStateGraphEngine } from '../../graph/contracts/executable-graph.j
 import type { SSEEmitter } from '../../sse/sse-emitter.js';
 export type { InvokeConfig, InvokeResponseData } from '@gt-fe/eap-contracts';
 /**
- * dev HTTP 层 Invoke 请求（扩展 userId，Hosting 从 auth 注入）
+ * dev HTTP 层 Invoke 请求（扩展 userId，Hosting 从 auth 注入；ragScope 为请求级
+ * 检索范围——前端圈定已向量化文件/目录，仅 rag 节点本地检索源生效）
  */
 export type InvokeRequest = ContractInvokeRequest & {
     userId?: string;
+    ragScope?: {
+        fileIds?: string[];
+        dirPaths?: string[];
+    };
+    /** 会话级数据源勾选（数据源 id 列表；缺省 = 智能体预定义目录全部启用） */
+    ragSources?: string[];
 };
 export type InvokeResponse = ContractInvokeResponse;
 /** 流式调用请求 — 与 InvokeRequest 相同 */

package/dist/common/types.d.ts

@@ -9,7 +9,7 @@
  * Token 统计输出粒度控制
  * - none: 不输出任何 Token 统计事件
  * - summary: 仅 Task 结束时输出 stats.token_usage 汇总
- * - detail: 每次 LLM 调用输出 stats.node_token + 结束时汇总
+ * - detail: 每次 LLM 调用输出 stats.node_token_usage + 结束时汇总
  */
 export type TokenDetailLevel = 'none' | 'summary' | 'detail';
 /**
@@ -79,7 +79,7 @@ export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
  *
  * 与 @gt-fe/eap-contracts.TokenUsage 的区别：
  * - contracts 版本是 Task 级聚合结果（含 byNode/byModel）
- * - 本类型是单次调用粒度的原始记录，用于 Runtime 内部累计和 stats.node_token 事件
+ * - 本类型是单次调用粒度的原始记录，用于 Runtime 内部累计和 stats.node_token_usage 事件
  */
 export interface TokenUsage {
     /** 输入 Token 数 */

package/dist/common/types.js

@@ -7,7 +7,7 @@
  */
 /** RuntimeConfig 默认值 */
 export const DEFAULT_RUNTIME_CONFIG = {
-    tokenDetail: 'summary',
+    tokenDetail: 'detail',
     timeout: 60000,
     maxIterations: 10,
     heartbeatInterval: 30000,

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/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { decideBeforeModel, decideBeforeTool, type AfterModelInterceptor, type AfterToolInterceptor, type BeforeModelInput, type BeforeModelInterceptor, type BeforeToolInterceptor, type ExecutionInterceptors, type ModelInterceptorDecision, type ToolInterceptorDecision, } from './interceptors.js';
+export { sandboxFromJail, type ISandbox, type IApproval } from './ports.js';

package/dist/execution/index.js

@@ -0,0 +1,2 @@
+export { decideBeforeModel, decideBeforeTool, } from './interceptors.js';
+export { sandboxFromJail } from './ports.js';

package/dist/execution/interceptors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 执行拦截：Tool / LLM 调用前可拒绝，默认无注入则与未装配时相同。
+ * 不是规格 R13 Hook，不做插件发现、不读项目 hook 目录。
+ */
+import type { ExecutionContext } from '@gt-fe/eap-contracts';
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { LLMNodeConfig, LLMResponse } from '../graph/nodes/llm-node.js';
+import type { ToolCallRequest, ToolCallResult } from '../tool/tool-executor.interface.js';
+export type ToolInterceptorDecision = {
+    action: 'allow';
+} | {
+    action: 'deny';
+    reason: string;
+} | {
+    action: 'ask';
+};
+export type BeforeToolInterceptor = (request: ToolCallRequest, ctx?: ExecutionContext) => Promise<ToolInterceptorDecision | void> | ToolInterceptorDecision | void;
+export type AfterToolInterceptor = (request: ToolCallRequest, result: ToolCallResult) => Promise<void> | void;
+export interface BeforeModelInput {
+    messages: GraphMessage[];
+    config: LLMNodeConfig;
+    nodeId: string;
+}
+export type ModelInterceptorDecision = {
+    action: 'allow';
+    messages?: GraphMessage[];
+} | {
+    action: 'deny';
+    reason: string;
+};
+export type BeforeModelInterceptor = (input: BeforeModelInput) => Promise<ModelInterceptorDecision | void> | ModelInterceptorDecision | void;
+export type AfterModelInterceptor = (input: BeforeModelInput, response: LLMResponse) => Promise<void> | void;
+export interface ExecutionInterceptors {
+    beforeTool?: BeforeToolInterceptor;
+    afterTool?: AfterToolInterceptor;
+    beforeModel?: BeforeModelInterceptor;
+    afterModel?: AfterModelInterceptor;
+}
+export declare function decideBeforeTool(interceptor: BeforeToolInterceptor | undefined, request: ToolCallRequest, ctx?: ExecutionContext): Promise<ToolInterceptorDecision>;
+export declare function decideBeforeModel(interceptor: BeforeModelInterceptor | undefined, input: BeforeModelInput): Promise<ModelInterceptorDecision>;

package/dist/execution/interceptors.js

@@ -0,0 +1,23 @@
+/**
+ * 执行拦截：Tool / LLM 调用前可拒绝，默认无注入则与未装配时相同。
+ * 不是规格 R13 Hook，不做插件发现、不读项目 hook 目录。
+ */
+export async function decideBeforeTool(interceptor, request, ctx) {
+    if (!interceptor)
+        return { action: 'allow' };
+    const raw = await interceptor(request, ctx);
+    if (!raw || raw.action === 'allow')
+        return { action: 'allow' };
+    if (raw.action === 'ask')
+        return { action: 'ask' };
+    return { action: 'deny', reason: raw.reason || '拦截拒绝' };
+}
+export async function decideBeforeModel(interceptor, input) {
+    if (!interceptor)
+        return { action: 'allow' };
+    const raw = await interceptor(input);
+    if (!raw || raw.action === 'allow') {
+        return { action: 'allow', messages: raw && raw.action === 'allow' ? raw.messages : undefined };
+    }
+    return { action: 'deny', reason: raw.reason || '拦截拒绝' };
+}