@gt-fe/eap-runtime 0.0.20 → 0.0.22

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) |
 
@@ -163,7 +164,7 @@ DSL / 契约细节见 `.kiro/specs/04-runtime-core/design.md` §1.4 与 `src/gra
 |------|------|------|
 | `EAP_PREINSTALL_ROOT` | — | 预装根；也可用 `GraphLoader({ preinstallRoot })` |
 | `EAP_PRELOAD_REQUIRE_READY` | 关 | 缺 `.ready` → `runtime.preload.missing` |
-| `EAP_PRELOAD_REQUIRE_CHECKSUM` | 关 | snapshot 须含 sha256 或 artifacts。加载期比对文件摘要，不匹配则 warn、不中断 |
+| `EAP_PRELOAD_REQUIRE_CHECKSUM` | 关 | snapshot 须含 sha256 或 artifacts。开启时摘要不匹配抛 `RUNTIME_PRELOAD_PACKAGE_CORRUPT`；未开仍 warn、不中断 |
 | `EAP_PRELOAD_USER_SKILL_OVERRIDE` | 关 | `users` 优先于 `shared` |
 | `EAP_PRELOAD_VALIDATE_SKILL_IO` | 关 | 校验 Skill `inputDef.required`（`state.skillInput`） |
 | `EAP_PRELOAD_DEFINITION_CACHE` | 有预装时开 | 定义缓存；`0`/`false` 关闭，`1`/`true` 强制开 |

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,10 +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 } from '../../token/record-task-token-usage.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';
@@ -28,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, withCompressionSummaryModel, } from '../../session/apply-session-compression.js';
+import { applySessionMemory, } from '../../session/apply-session-memory.js';
 // ─────────────────────────────────────────────
 // Default Graph DSL fallback
 // ─────────────────────────────────────────────
@@ -64,6 +66,8 @@ export class InvokeOrchestrator {
     graphLoader;
     checkpointSaver;
     traceCollector;
+    sessionCompression;
+    sessionMemory;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -75,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;
     }
     /**
      * 执行同步调用编排
@@ -159,6 +165,7 @@ export class InvokeOrchestrator {
         });
         // ─── Step 5: 构建/执行 Graph ───
         let graphResult;
+        let finishPoints;
         try {
             // 构建图 — 每次请求创建独立 StateGraph 实例，确保请求间无共享可变状态
             const loadOpts = { agentVersion: req.agentVersion };
@@ -166,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;
@@ -185,7 +193,21 @@ 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: await withCompressionSummaryModel(this.sessionCompression, () => this.graphLoader
+                        ? this.graphLoader.resolveDefaultModel(agentCode, req.agentVersion)
+                        : Promise.resolve(undefined)),
+                }),
+                userId: effectiveUserId,
+                agentCode,
+                query: typeof req.input === 'string' ? req.input : undefined,
+                options: this.sessionMemory,
+            });
             const messages = await buildTurnGraphMessages({
                 history,
                 input: req.input,
@@ -205,6 +227,8 @@ export class InvokeOrchestrator {
                 sessionId,
                 executionContext: ctx,
                 forceToolServer: req.config?.forceToolServer,
+                ragScope: req.ragScope,
+                ragSources: req.ragSources,
                 loadedTools,
                 loadedSkills,
                 skillDefinitions,
@@ -217,6 +241,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({
@@ -236,7 +262,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: {
@@ -253,7 +279,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',
                 });
@@ -265,7 +291,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',
                 });
@@ -277,7 +303,7 @@ export class InvokeOrchestrator {
                 taskId: task.id,
                 sessionId,
                 output: errorMessage,
-                tokenUsage: { input: 0, output: 0, total: 0 },
+                tokenUsage,
                 duration: Date.now() - startTime,
                 status: 'failed',
             });
@@ -326,11 +352,13 @@ export class InvokeOrchestrator {
         // ─── 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);
+        const duration = Date.now() - startTime;
         await persistTurnTranscript(this.messageService, {
             sessionId,
             taskId: task.id,
@@ -338,9 +366,9 @@ export class InvokeOrchestrator {
             messages: newMessages,
             fallbackAssistantContent: graphResult.output ?? '',
             assistantTokenCount: tokenUsage.output,
+            assistantDurationMs: duration,
         });
         // ─── Step 8: 返回 InvokeResponse ───
-        const duration = Date.now() - startTime;
         // 从本轮 Graph 执行结果中提取 tool 事件明细（供 CLI / UI 渲染 ReAct 循环）
         const toolEvents = extractToolEvents(newMessages);
         return this.buildResponse(traceId, {
@@ -369,6 +397,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,10 +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, withCompressionSummaryModel, } 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';
@@ -72,6 +75,8 @@ export class StreamOrchestrator {
     graphLoader;
     checkpointSaver;
     traceCollector;
+    sessionCompression;
+    sessionMemory;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -83,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;
     }
     /**
      * 执行流式调用编排
@@ -207,7 +214,31 @@ 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);
+        const compressionOptions = await withCompressionSummaryModel(this.sessionCompression, () => this.graphLoader
+            ? this.graphLoader.resolveDefaultModel(agentCode, req.agentVersion)
+            : Promise.resolve(undefined));
+        for await (const step of iterSessionCompression({
+            history,
+            sessionId,
+            userId,
+            taskId,
+            options: compressionOptions,
+        })) {
+            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,
@@ -215,7 +246,7 @@ export class StreamOrchestrator {
             threadId: sessionId,
         });
         const skillInput = resolveSkillInputFromInvokeInput(req.input);
-        let assistantText = '';
+        const assistantBuckets = createStreamAssistantBuckets();
         let toolCallReasoningContent;
         let assistantReasoningContent;
         const pendingToolCalls = [];
@@ -233,6 +264,8 @@ export class StreamOrchestrator {
                 sessionId,
                 executionContext,
                 forceToolServer: req.config?.forceToolServer,
+                ragScope: req.ragScope,
+                ragSources: req.ragSources,
                 loadedTools,
                 loadedSkills,
                 skillDefinitions,
@@ -272,33 +305,14 @@ 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) {
@@ -325,12 +339,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,
@@ -342,6 +358,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;
@@ -350,21 +367,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
@@ -383,11 +401,14 @@ export class StreamOrchestrator {
             messages: buildTurnTranscriptFromStreamEvents({
                 pendingToolCalls,
                 toolResults,
-                assistantText,
+                assistantTexts: streamAssistantTexts(assistantBuckets),
+                assistantText: visibleStreamAssistantText(assistantBuckets),
+                finishPoints: graph.finishPoints,
                 toolCallReasoningContent,
                 assistantReasoningContent,
             }),
             assistantTokenCount: tokenStats.total.output ?? 0,
+            assistantDurationMs: duration,
         });
         // 关闭 SSE 连接
         emitter.close();

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/checkpoint/file-checkpoint-saver.d.ts

@@ -1,9 +1,12 @@
 /**
  * FileCheckpointSaver — 本地 JSON 文件存储
  * 适用场景：本地开发、单机部署
+ * 目录名对 threadId 做 encodeURIComponent：子图槽 `sessionId#父节点id` 不会变成带 `#` 的目录。
  */
 import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
 import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/** 存储键可含 `#`（子图槽）；目录名百分号编码，避免 URL/Markdown 把 `#` 当片段。 */
+export declare function checkpointFileThreadDir(baseDir: string, threadId: string): string;
 export declare class FileCheckpointSaver implements ICheckpointSaver {
     private readonly baseDir;
     constructor(baseDir: string);
@@ -11,6 +14,7 @@ export declare class FileCheckpointSaver implements ICheckpointSaver {
     load(threadId: string): Promise<CheckpointData | null>;
     loadByCheckpointId(checkpointId: string, threadId?: string): Promise<CheckpointData | null>;
     list(threadId: string): Promise<CheckpointData[]>;
+    private readLatestId;
     private readCheckpoint;
     /**
      * Fork: 从指定 Checkpoint 创建新的执行线程

package/dist/checkpoint/file-checkpoint-saver.js

@@ -1,36 +1,51 @@
 /**
  * FileCheckpointSaver — 本地 JSON 文件存储
  * 适用场景：本地开发、单机部署
+ * 目录名对 threadId 做 encodeURIComponent：子图槽 `sessionId#父节点id` 不会变成带 `#` 的目录。
  */
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { stringifyJsonSafe } from './checkpoint-serializer.js';
+/** 存储键可含 `#`（子图槽）；目录名百分号编码，避免 URL/Markdown 把 `#` 当片段。 */
+export function checkpointFileThreadDir(baseDir, threadId) {
+    return join(baseDir, encodeURIComponent(threadId));
+}
+function threadDirCandidates(baseDir, threadId) {
+    const encoded = checkpointFileThreadDir(baseDir, threadId);
+    const raw = join(baseDir, threadId);
+    return encoded === raw ? [encoded] : [encoded, raw];
+}
 export class FileCheckpointSaver {
     baseDir;
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
     async save(threadId, data) {
-        const dir = join(this.baseDir, threadId);
+        const dir = checkpointFileThreadDir(this.baseDir, threadId);
         await mkdir(dir, { recursive: true });
         await writeFile(join(dir, `${data.checkpointId}.json`), stringifyJsonSafe(data));
         // 更新 latest 指针
         await writeFile(join(dir, 'latest.json'), JSON.stringify({ checkpointId: data.checkpointId }));
     }
     async load(threadId) {
-        try {
-            const latestRaw = await readFile(join(this.baseDir, threadId, 'latest.json'), 'utf-8');
-            const { checkpointId } = JSON.parse(latestRaw);
-            return this.loadByCheckpointId(checkpointId, threadId);
-        }
-        catch {
-            return null;
+        for (const dir of threadDirCandidates(this.baseDir, threadId)) {
+            const checkpointId = await this.readLatestId(dir);
+            if (!checkpointId)
+                continue;
+            const data = await this.readCheckpoint(join(dir, `${checkpointId}.json`));
+            if (data)
+                return data;
         }
+        return null;
     }
     async loadByCheckpointId(checkpointId, threadId) {
-        // If threadId provided, look directly; otherwise scan all thread dirs
         if (threadId) {
-            return this.readCheckpoint(join(this.baseDir, threadId, `${checkpointId}.json`));
+            for (const dir of threadDirCandidates(this.baseDir, threadId)) {
+                const data = await this.readCheckpoint(join(dir, `${checkpointId}.json`));
+                if (data)
+                    return data;
+            }
+            return null;
         }
         // ponytail: brute scan — upgrade to index file if perf matters
         try {
@@ -45,21 +60,35 @@ export class FileCheckpointSaver {
         return null;
     }
     async list(threadId) {
-        const dir = join(this.baseDir, threadId);
-        try {
-            const files = await readdir(dir);
-            const results = [];
-            for (const f of files) {
-                if (f === 'latest.json' || !f.endsWith('.json'))
-                    continue;
-                const data = await this.readCheckpoint(join(dir, f));
-                if (data)
-                    results.push(data);
+        for (const dir of threadDirCandidates(this.baseDir, threadId)) {
+            try {
+                const files = await readdir(dir);
+                const results = [];
+                for (const f of files) {
+                    if (f === 'latest.json' || !f.endsWith('.json'))
+                        continue;
+                    const data = await this.readCheckpoint(join(dir, f));
+                    if (data)
+                        results.push(data);
+                }
+                if (results.length > 0) {
+                    return results.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+                }
+            }
+            catch {
+                // try next candidate
             }
-            return results.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        }
+        return [];
+    }
+    async readLatestId(dir) {
+        try {
+            const latestRaw = await readFile(join(dir, 'latest.json'), 'utf-8');
+            const { checkpointId } = JSON.parse(latestRaw);
+            return typeof checkpointId === 'string' && checkpointId.trim() ? checkpointId : null;
         }
         catch {
-            return [];
+            return null;
         }
     }
     async readCheckpoint(filePath) {

package/dist/checkpoint/index.d.ts

@@ -6,7 +6,7 @@ export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
 export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export type { CreateCheckpointParams } from './checkpoint-serializer.js';
-export { FileCheckpointSaver } from './file-checkpoint-saver.js';
+export { FileCheckpointSaver, checkpointFileThreadDir } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
 export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';
 export type { IMongoCollection, CheckpointDocument } from './mongo-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -5,7 +5,7 @@ export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
 export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
-export { FileCheckpointSaver } from './file-checkpoint-saver.js';
+export { FileCheckpointSaver, checkpointFileThreadDir } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
 export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';
 export { PostgresCheckpointSaver } from './pg-checkpoint-saver.js';

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