@gt-fe/eap-runtime 0.0.24 → 0.0.26

package/README.md

@@ -8,6 +8,7 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 
 | 日期 | 摘要 |
 |------|------|
+| 2026-09-14 | 会话滑动窗口压缩默认开；`EAP_RUNTIME_COMPRESSION=0` 关闭 |
 | 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) |

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

@@ -15,7 +15,7 @@
  * @see requirements.md Requirement 11 AC1-AC2
  */
 import { randomUUID } from 'node:crypto';
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, sessionVisibleGraphMessages, } from '../../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, loadModelFacingHistory, messageRecordsToGraphMessages, persistGraphMessageBaseline, turnGraphMessagesAfterCompression, 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';
@@ -33,7 +33,7 @@ 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 { runSessionCompression, withCompressionSummaryModel, } from '../../session/apply-session-compression.js';
 import { applySessionMemory, } from '../../session/apply-session-memory.js';
 // ─────────────────────────────────────────────
 // Default Graph DSL fallback
@@ -180,6 +180,7 @@ export class InvokeOrchestrator {
         // ─── Step 5: 构建/执行 Graph ───
         let graphResult;
         let finishPoints;
+        let persistBaseline = 0;
         try {
             // 构建图 — 每次请求创建独立 StateGraph 实例，确保请求间无共享可变状态
             const graph = await this.graphEngine.buildGraph(graphDsl);
@@ -202,32 +203,45 @@ export class InvokeOrchestrator {
                 ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
                 : undefined;
             const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
-            // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
+            // 模型上下文：Checkpoint 已有 messages 则压它；压成功用 __set 写回最新 Checkpoint。Message 库不改。
+            const facing = await loadModelFacingHistory({
+                sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
+                checkpointSaver: this.checkpointSaver,
+                threadId: sessionId,
+            });
+            const compression = await runSessionCompression({
+                history: facing.messages,
+                sessionId,
+                userId: effectiveUserId,
+                taskId: task.id,
+                options: await withCompressionSummaryModel(this.sessionCompression, () => this.graphLoader
+                    ? this.graphLoader.resolveDefaultModel(agentCode, req.agentVersion)
+                    : Promise.resolve(undefined)),
+            });
             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)),
-                }),
+                history: compression.messages,
                 userId: effectiveUserId,
                 agentCode,
                 query: typeof req.input === 'string' ? req.input : undefined,
                 options: this.sessionMemory,
             });
-            const messages = await buildTurnGraphMessages({
+            const { messages, replaceCheckpointMessages } = turnGraphMessagesAfterCompression({
                 history,
                 input: req.input,
-                checkpointSaver: this.checkpointSaver,
-                threadId: sessionId,
+                fromCheckpoint: facing.fromCheckpoint,
+                compressed: compression.compressed,
+            });
+            persistBaseline = persistGraphMessageBaseline({
+                fromCheckpoint: facing.fromCheckpoint,
+                replaceCheckpointMessages,
+                graphInputCount: messages.length,
+                modelFacingCount: facing.messages.length,
             });
             const skillInput = resolveSkillInputFromInvokeInput(req.input);
             // 同步执行图
             graphResult = await runWithExecutionTrace({ abortSignal }, () => this.graphEngine.invoke(graph, {
                 messages,
+                replaceCheckpointMessages,
                 userId: effectiveUserId,
                 delegationToken: ctx.delegationToken,
                 agentCode,
@@ -369,12 +383,11 @@ 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 文本）───
-        // 按 Session 已有行数切 Graph 增量。多段正文收成一条后 Session 比 Graph 短，切点可能提前；finishPoints 只含一个实际节点 id 时靠最后一条纯文本仍落到 merge。
-        const initialMessagesCount = sessionContext.messages.length + 1;
+        // 切点是入图 messages 基线（压缩 `__set` 后 Graph 短于 Session 全文）。user 已在 4b 写入。
         const allMessages = Array.isArray(graphResult.finalState?.messages)
             ? graphResult.finalState.messages
             : [];
-        const newMessages = sessionVisibleGraphMessages(allMessages.slice(initialMessagesCount), finishPoints);
+        const newMessages = sessionVisibleGraphMessages(allMessages.slice(persistBaseline), finishPoints);
         const duration = Date.now() - startTime;
         await persistTurnTranscript(this.messageService, {
             sessionId,

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

@@ -19,7 +19,7 @@
  * @see design.md §1.5 /stream 内部执行逻辑
  * @see requirements.md Requirement 11 AC2
  */
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, appendTerminalToolResult, } from '../../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, 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';
@@ -221,8 +221,14 @@ export class StreamOrchestrator {
             ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
-        // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
-        let history = messageRecordsToGraphMessages(sessionContext.messages);
+        // 模型上下文：Checkpoint 已有 messages 则压它；压成功用 __set 写回最新 Checkpoint。Message 库不改。
+        const facing = await loadModelFacingHistory({
+            sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
+            checkpointSaver: this.checkpointSaver,
+            threadId: sessionId,
+        });
+        let history = facing.messages;
+        let compressed = false;
         const compressionOptions = await withCompressionSummaryModel(this.sessionCompression, () => this.graphLoader
             ? this.graphLoader.resolveDefaultModel(agentCode, req.agentVersion)
             : Promise.resolve(undefined));
@@ -237,6 +243,9 @@ export class StreamOrchestrator {
                 history = step.messages;
                 continue;
             }
+            if (step.kind === 'completed') {
+                compressed = step.payload.success === true;
+            }
             emitter.emit(this.buildSSEEvent(step.kind === 'started' ? 'session.compression.started' : 'session.compression.completed', correlationId, taskId, { ...step.payload }));
         }
         history = await applySessionMemory({
@@ -247,11 +256,11 @@ export class StreamOrchestrator {
             options: this.sessionMemory,
         });
         const tokenDetail = resolveTokenDetail(req.config?.tokenDetail);
-        const messages = await buildTurnGraphMessages({
+        const { messages, replaceCheckpointMessages } = turnGraphMessagesAfterCompression({
             history,
             input: req.input,
-            checkpointSaver: this.checkpointSaver,
-            threadId: sessionId,
+            fromCheckpoint: facing.fromCheckpoint,
+            compressed,
         });
         const skillInput = resolveSkillInputFromInvokeInput(req.input);
         const assistantBuckets = createStreamAssistantBuckets();
@@ -263,6 +272,7 @@ export class StreamOrchestrator {
         try {
             const eventStream = runWithExecutionTrace({ abortSignal }, () => this.graphEngine.stream(graph, {
                 messages,
+                replaceCheckpointMessages,
                 userId,
                 delegationToken: executionContext.delegationToken,
                 agentCode,

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

@@ -239,8 +239,8 @@ export interface GraphState {
     /** 最近一次 createNode 的 span id；Checkpoint 引用挂在此 Span 上 */
     lastSpanId?: string;
     /**
-     * HITL 续跑：入口 messages 以 __set 覆盖 checkpoint 历史，避免 append 重复。
-     * 仅 stream/invoke 入口使用，不入持久化语义。
+     * 入口 messages 以 __set 覆盖 checkpoint 历史，避免 append 重复。
+     * HITL 续跑与会话压缩写回最新 Checkpoint 使用。不入持久化语义。
      */
     replaceCheckpointMessages?: boolean;
     /**

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

@@ -48,7 +48,7 @@ export interface AgentRuntimeDeps {
      */
     traceCollector?: ITraceCollector;
     recordForkRelation?: RecordForkRelation;
-    /** 历史压缩；默认关。见 EAP_RUNTIME_COMPRESSION */
+    /** 历史压缩；默认开。EAP_RUNTIME_COMPRESSION=0 关闭 */
     sessionCompression?: SessionCompressionOptions;
     /** 长期记忆注入；默认关。见 EAP_RUNTIME_MEMORY */
     sessionMemory?: import('../session/apply-session-memory.js').SessionMemoryOptions;

package/dist/runtime/agent-runtime.js

@@ -15,7 +15,7 @@ import { resolveAgentSystemPromptFromLoader } from '../registry/graph-loader.js'
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractHitlThreadId, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, extractHitlThreadId, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.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';
@@ -294,7 +294,13 @@ export class AgentRuntime {
             ? (await this.deps.graphLoader.resolveAgentDir(agentCode, params.agentVersion)) ?? undefined
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, params.agentVersion);
-        let history = messageRecordsToGraphMessages(sessionContext.messages);
+        const facing = await loadModelFacingHistory({
+            sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
+            checkpointSaver: this.deps.checkpointSaver,
+            threadId: sessionId,
+        });
+        let history = facing.messages;
+        let compressed = false;
         const compressionOptions = await withCompressionSummaryModel({
             ...this.deps.sessionCompression,
             turnLog: this.deps.sessionCompression?.turnLog ?? this.deps.turnLog,
@@ -312,6 +318,9 @@ export class AgentRuntime {
                 history = step.messages;
                 continue;
             }
+            if (step.kind === 'completed') {
+                compressed = step.payload.success === true;
+            }
             yield this.toSSE(step.kind === 'started' ? 'session.compression.started' : 'session.compression.completed', correlationId, task.id, { ...step.payload });
         }
         history = await applySessionMemory({
@@ -322,11 +331,11 @@ export class AgentRuntime {
             options: this.deps.sessionMemory,
         });
         const tokenDetail = resolveTokenDetail(params.config?.tokenDetail);
-        const messages = await buildTurnGraphMessages({
+        const { messages, replaceCheckpointMessages } = turnGraphMessagesAfterCompression({
             history,
             input: params.input,
-            checkpointSaver: this.deps.checkpointSaver,
-            threadId: sessionId,
+            fromCheckpoint: facing.fromCheckpoint,
+            compressed,
         });
         const startTime = Date.now();
         const assistantBuckets = createStreamAssistantBuckets();
@@ -338,6 +347,7 @@ export class AgentRuntime {
         try {
             for await (const runtimeEvent of runWithExecutionTrace({ abortSignal }, () => this.deps.graphEngine.stream(graph, {
                 messages,
+                replaceCheckpointMessages,
                 userId,
                 delegationToken: ctx.delegationToken,
                 agentCode,

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

@@ -33,6 +33,7 @@ import { LongTermMemoryService } from '../memory/long-term-memory.service.js';
 export interface CreateDevRuntimeOptions {
     interceptors?: ExecutionInterceptors;
     compression?: {
+        /** 默认开。false 或 EAP_RUNTIME_COMPRESSION=0 关闭 */
         enabled?: boolean;
         persistCompressed?: boolean;
     };

package/dist/session/apply-session-compression.d.ts

@@ -1,11 +1,11 @@
 /**
- * execute/stream 装载历史后的压缩入口。默认关。
+ * execute/stream 装载历史后的压缩入口。默认开。
  *
- * C-1a 开关：options.enabled 或 EAP_RUNTIME_COMPRESSION=1
+ * C-1a 开关：默认开。options.enabled=false 或 EAP_RUNTIME_COMPRESSION=0 / false 关闭
  * C-1b 有窗口：用上一轮 llm_turns 的 used/window，不用字符估窗
  * C-1c 无窗口：只按轮次上限，不按窗压
- * C-1d 摘要只走 ILLMProvider；失败则不压缩
- * C-1e 默认只改本轮内存历史；persistCompressed 时必须能写 compression record
+ * C-1d 摘要只走 ILLMProvider；Echo 或未注入 provider 则不压；失败则不压缩
+ * C-1e 压成功且来自 Checkpoint 时，入图 `__set` 覆盖最新 Checkpoint messages；不回写 Message 库。persistCompressed 只写审计 record
  * C-1f 流式路径在摘要前产出 session.compression.started，结束后产出 completed。
  *      不新开「占用 ≥ 80% 再 compact」链；触发仍是 C-1b/c。
  */
@@ -15,6 +15,8 @@ import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
 import { type CompressionRecord } from '../memory/message-compression.service.js';
 import type { ICompressionRepository } from '../memory/compression/compression.repository.js';
 import type { SessionCompressionCompletedPayload, SessionCompressionReason, SessionCompressionStartedPayload } from '../sse/events/session-events.js';
+/** 摘要 LLM 写入 llm_turns 的 nodeId。lastTurnUsage 跳过，避免用摘要占用触发下一轮压缩。 */
+export declare const COMPRESSION_TURN_NODE_ID = "session-compression";
 export interface SessionCompressionOptions {
     enabled?: boolean;
     persistCompressed?: boolean;

package/dist/session/apply-session-compression.js

@@ -1,11 +1,11 @@
 /**
- * execute/stream 装载历史后的压缩入口。默认关。
+ * execute/stream 装载历史后的压缩入口。默认开。
  *
- * C-1a 开关：options.enabled 或 EAP_RUNTIME_COMPRESSION=1
+ * C-1a 开关：默认开。options.enabled=false 或 EAP_RUNTIME_COMPRESSION=0 / false 关闭
  * C-1b 有窗口：用上一轮 llm_turns 的 used/window，不用字符估窗
  * C-1c 无窗口：只按轮次上限，不按窗压
- * C-1d 摘要只走 ILLMProvider；失败则不压缩
- * C-1e 默认只改本轮内存历史；persistCompressed 时必须能写 compression record
+ * C-1d 摘要只走 ILLMProvider；Echo 或未注入 provider 则不压；失败则不压缩
+ * C-1e 压成功且来自 Checkpoint 时，入图 `__set` 覆盖最新 Checkpoint messages；不回写 Message 库。persistCompressed 只写审计 record
  * C-1f 流式路径在摘要前产出 session.compression.started，结束后产出 completed。
  *      不新开「占用 ≥ 80% 再 compact」链；触发仍是 C-1b/c。
  */
@@ -13,13 +13,17 @@ import { EchoLLMProvider } from '../providers/echo-llm-provider.js';
 import { COMPRESSION_WINDOW_FACTOR, countRounds, DEFAULT_COMPRESSION_CONFIG, } from '../memory/message-compression.service.js';
 import { SlidingWindowCompression } from '../memory/compression/sliding-window.compression.js';
 import { emitRuntimeLog } from '../common/logger.js';
+/** 摘要 LLM 写入 llm_turns 的 nodeId。lastTurnUsage 跳过，避免用摘要占用触发下一轮压缩。 */
+export const COMPRESSION_TURN_NODE_ID = 'session-compression';
 export function isRuntimeCompressionEnabled(explicit, env = process.env) {
     if (explicit === true)
         return true;
     if (explicit === false)
         return false;
     const raw = env.EAP_RUNTIME_COMPRESSION ?? env.EAP_COMPRESSION_ENABLED;
-    return raw === '1' || raw === 'true';
+    if (raw === '0' || raw === 'false')
+        return false;
+    return true;
 }
 export function isRuntimeCompressionPersist(explicit, env = process.env) {
     if (explicit === true)
@@ -164,7 +168,7 @@ async function runDecidedSessionCompression(params, decision) {
             maxRounds,
             preserveRecentRounds: options.preserveRecentRounds ?? DEFAULT_COMPRESSION_CONFIG.preserveRecentRounds,
             ...(decision.window ? { maxContextTokens: decision.window } : {}),
-        }, async (msgs) => summarizeWithProvider(provider, msgs, options.summaryModel));
+        }, async (msgs) => summarizeWithProvider(provider, msgs, options.summaryModel, params.sessionId));
         const compressed = await compression.compress(history);
         if (compressed === history) {
             return {
@@ -250,12 +254,17 @@ async function lastTurnUsage(turnLog, sessionId) {
     if (!turnLog || !sessionId)
         return undefined;
     const index = await turnLog.list(sessionId);
-    const last = index[index.length - 1];
-    if (!last || typeof last.used !== 'number')
-        return undefined;
-    return { used: last.used, window: last.window };
+    for (let i = index.length - 1; i >= 0; i--) {
+        const entry = index[i];
+        if (!entry || entry.nodeId === COMPRESSION_TURN_NODE_ID)
+            continue;
+        if (typeof entry.used !== 'number')
+            continue;
+        return { used: entry.used, window: entry.window };
+    }
+    return undefined;
 }
-async function summarizeWithProvider(provider, messages, summaryModel) {
+async function summarizeWithProvider(provider, messages, summaryModel, sessionId) {
     const body = messages
         .map((m) => `${m.role}: ${m.content}`)
         .join('\n')
@@ -272,6 +281,10 @@ async function summarizeWithProvider(provider, messages, summaryModel) {
         model,
         temperature: 0.2,
         maxTokens: 1024,
+        turn: {
+            sessionId,
+            nodeId: COMPRESSION_TURN_NODE_ID,
+        },
     });
     const text = response.content?.trim();
     if (!text) {

package/dist/session/index.d.ts

@@ -10,6 +10,6 @@ export type { FileMessageRepositoryOptions } from './file-message.repository.js'
 export { SessionContextService } from './session-context.service.js';
 export type { ResolveSessionParams, SessionContext, } from './session-context.service.js';
 export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';
-export { applySessionCompression, withCompressionSummaryModel, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, type SessionCompressionOptions, type RunSessionCompressionParams, type RunSessionCompressionResult, type SessionCompressionDecision, type SessionCompressionStep, } from './apply-session-compression.js';
+export { applySessionCompression, COMPRESSION_TURN_NODE_ID, withCompressionSummaryModel, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, type SessionCompressionOptions, type RunSessionCompressionParams, type RunSessionCompressionResult, type SessionCompressionDecision, type SessionCompressionStep, } from './apply-session-compression.js';
 export type { CompressionMiddlewareConfig } from './compression-middleware.js';
 export { applySessionMemory, isRuntimeMemoryEnabled, type SessionMemoryOptions, } from './apply-session-memory.js';

package/dist/session/index.js

@@ -10,5 +10,5 @@ export { FileMessageRepository } from './file-message.repository.js';
 export { SessionContextService } from './session-context.service.js';
 // 压缩中间件
 export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';
-export { applySessionCompression, withCompressionSummaryModel, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, } from './apply-session-compression.js';
+export { applySessionCompression, COMPRESSION_TURN_NODE_ID, withCompressionSummaryModel, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, } from './apply-session-compression.js';
 export { applySessionMemory, isRuntimeMemoryEnabled, } from './apply-session-memory.js';

package/dist/session/persist-turn-messages.d.ts

@@ -99,6 +99,15 @@ export declare function appendTerminalToolResult(eventType: string, payload: unk
 }>): void;
 /** 历史 MessageRecord → GraphMessage（保留 tool 元数据与 reasoning） */
 export declare function messageRecordsToGraphMessages(records: MessageRecord[]): GraphMessage[];
+type CheckpointLoad = {
+    state?: {
+        messages?: unknown;
+    };
+    engineSnapshot?: Record<string, unknown>;
+} | null;
+type CheckpointLoader = {
+    load(threadId: string): Promise<CheckpointLoad>;
+};
 /**
  * 组装本轮送入 Graph 的 messages。
  *
@@ -107,21 +116,52 @@ export declare function messageRecordsToGraphMessages(records: MessageRecord[]):
  * - Session 级 Checkpoint 持有图内 messages（含 reasoning）
  * - 当 Checkpoint 已有历史时，只追加本轮 user，避免双重 append
  * - Checkpoint 缺失/无 messages 时，回退 Session 全量历史
+ * - 压缩针对 Checkpoint（无则 Session）中的模型上下文；压成功且来自 Checkpoint 时由调用方设 `replaceCheckpointMessages`
  */
 export declare function buildTurnGraphMessages(params: {
     history: GraphMessage[];
     input: string;
-    checkpointSaver?: {
-        load(threadId: string): Promise<{
-            state?: {
-                messages?: unknown;
-            };
-            engineSnapshot?: Record<string, unknown>;
-        } | null>;
-    } | null;
+    checkpointSaver?: CheckpointLoader | null;
     /** 与 LangGraph configurable.thread_id 一致（通常为 sessionId） */
     threadId?: string;
 }): Promise<GraphMessage[]>;
+/**
+ * 模型上下文：Checkpoint 已有 messages 用它，否则用 Session 历史。
+ * 压缩必须压这份列表，不能只压 Session 再在有 Checkpoint 时丢掉。
+ */
+export declare function loadModelFacingHistory(params: {
+    sessionHistory: GraphMessage[];
+    checkpointSaver?: CheckpointLoader | null;
+    threadId?: string;
+}): Promise<{
+    messages: GraphMessage[];
+    fromCheckpoint: boolean;
+}>;
+/**
+ * 压缩后的入图列表。来自 Checkpoint 且本轮压成功：整表 `__set` 覆盖，写入最新 Checkpoint。
+ * 未压且来自 Checkpoint：只追加本轮 user。无 Checkpoint：历史 + 本轮 user。
+ */
+export declare function turnGraphMessagesAfterCompression(params: {
+    history: GraphMessage[];
+    input: string;
+    fromCheckpoint: boolean;
+    compressed: boolean;
+}): {
+    messages: GraphMessage[];
+    replaceCheckpointMessages: boolean;
+};
+/**
+ * invoke 从 Graph 最终 messages 切本轮增量的起点。
+ * 覆盖（`__set`）或无 Checkpoint：入图数组长度（已含本轮 user）。
+ * 追加到已有 Checkpoint：模型上下文条数 + 入图条数（通常 1 条 user）。
+ */
+export declare function persistGraphMessageBaseline(params: {
+    fromCheckpoint: boolean;
+    replaceCheckpointMessages: boolean;
+    graphInputCount: number;
+    modelFacingCount: number;
+}): number;
+export declare function graphMessagesFromCheckpoint(cp: CheckpointLoad): GraphMessage[];
 /**
  * HITL 等待态写入 Task.output 的结构化载荷。
  * 冷恢复时优先读 `hitlThreadId`，避免误用 correlationId。
@@ -146,7 +186,7 @@ export declare function extractHitlThreadId(output: unknown): string | undefined
  * 与 LangGraph put / 子图内 HITL interrupt 同一把钥匙。
  *
  * 注意：session 级 thread + 全量 Session 历史同时注入会导致 messages 双重 append。
- * 组装本轮 Graph 输入请用 {@link buildTurnGraphMessages}（有 Checkpoint 历史则只追加 user）。
+ * 组装本轮 Graph 输入请用 {@link loadModelFacingHistory} 与 {@link turnGraphMessagesAfterCompression}。
  */
 export declare function resolveCheckpointThreadId(params: {
     sessionId?: string;
@@ -199,3 +239,4 @@ export declare function persistTurnTranscript(messageService: MessageService | u
     assistantTokenCount?: number;
     assistantDurationMs?: number | null;
 }): Promise<void>;
+export {};

package/dist/session/persist-turn-messages.js

@@ -305,31 +305,149 @@ function extractReasoningContent(reasoning) {
  * - Session 级 Checkpoint 持有图内 messages（含 reasoning）
  * - 当 Checkpoint 已有历史时，只追加本轮 user，避免双重 append
  * - Checkpoint 缺失/无 messages 时，回退 Session 全量历史
+ * - 压缩针对 Checkpoint（无则 Session）中的模型上下文；压成功且来自 Checkpoint 时由调用方设 `replaceCheckpointMessages`
  */
 export async function buildTurnGraphMessages(params) {
-    const newUser = { role: 'user', content: params.input };
-    const history = params.history;
-    if (!params.checkpointSaver || !params.threadId || history.length === 0) {
-        return [...history, newUser];
+    const facing = await loadModelFacingHistory({
+        sessionHistory: params.history,
+        checkpointSaver: params.checkpointSaver,
+        threadId: params.threadId,
+    });
+    return turnGraphMessagesAfterCompression({
+        history: facing.messages,
+        input: params.input,
+        fromCheckpoint: facing.fromCheckpoint,
+        compressed: false,
+    }).messages;
+}
+/**
+ * 模型上下文：Checkpoint 已有 messages 用它，否则用 Session 历史。
+ * 压缩必须压这份列表，不能只压 Session 再在有 Checkpoint 时丢掉。
+ */
+export async function loadModelFacingHistory(params) {
+    const sessionHistory = params.sessionHistory ?? [];
+    if (!params.checkpointSaver || !params.threadId) {
+        return { messages: sessionHistory, fromCheckpoint: false };
     }
     const cp = await params.checkpointSaver.load(params.threadId);
-    if (checkpointHasMessages(cp)) {
-        return [newUser];
+    const checkpointMessages = graphMessagesFromCheckpoint(cp);
+    if (checkpointMessages.length > 0) {
+        return { messages: checkpointMessages, fromCheckpoint: true };
     }
-    return [...history, newUser];
+    return { messages: sessionHistory, fromCheckpoint: false };
 }
-function checkpointHasMessages(cp) {
+/**
+ * 压缩后的入图列表。来自 Checkpoint 且本轮压成功：整表 `__set` 覆盖，写入最新 Checkpoint。
+ * 未压且来自 Checkpoint：只追加本轮 user。无 Checkpoint：历史 + 本轮 user。
+ */
+export function turnGraphMessagesAfterCompression(params) {
+    const newUser = { role: 'user', content: params.input };
+    if (params.fromCheckpoint && params.compressed) {
+        return {
+            messages: [...params.history, newUser],
+            replaceCheckpointMessages: true,
+        };
+    }
+    if (params.fromCheckpoint) {
+        return { messages: [newUser], replaceCheckpointMessages: false };
+    }
+    return {
+        messages: [...params.history, newUser],
+        replaceCheckpointMessages: false,
+    };
+}
+/**
+ * invoke 从 Graph 最终 messages 切本轮增量的起点。
+ * 覆盖（`__set`）或无 Checkpoint：入图数组长度（已含本轮 user）。
+ * 追加到已有 Checkpoint：模型上下文条数 + 入图条数（通常 1 条 user）。
+ */
+export function persistGraphMessageBaseline(params) {
+    if (params.replaceCheckpointMessages || !params.fromCheckpoint) {
+        return params.graphInputCount;
+    }
+    return params.modelFacingCount + params.graphInputCount;
+}
+export function graphMessagesFromCheckpoint(cp) {
     if (!cp)
-        return false;
-    if (Array.isArray(cp.state?.messages) && cp.state.messages.length > 0)
-        return true;
+        return [];
     const channelValues = cp.engineSnapshot?.['channel_values'];
     if (channelValues && typeof channelValues === 'object') {
         const messages = channelValues['messages'];
-        if (Array.isArray(messages) && messages.length > 0)
-            return true;
+        if (Array.isArray(messages) && messages.length > 0) {
+            return unknownListToGraphMessages(messages);
+        }
+    }
+    if (Array.isArray(cp.state?.messages) && cp.state.messages.length > 0) {
+        return unknownListToGraphMessages(cp.state.messages);
+    }
+    return [];
+}
+function unknownListToGraphMessages(raw) {
+    return raw.map((msg) => unknownToGraphMessage(msg));
+}
+function unknownToGraphMessage(msg) {
+    if (typeof msg !== 'object' || msg === null) {
+        return { role: 'user', content: String(msg) };
     }
-    return false;
+    const m = msg;
+    const nested = m.kwargs && typeof m.kwargs === 'object' ? m.kwargs : undefined;
+    const lcName = Array.isArray(m.id) ? m.id[m.id.length - 1] : undefined;
+    const typeHint = m.type === 'constructor' ? undefined : m.type;
+    const role = graphRoleFromUnknown(m.role ?? nested?.role ?? nested?.type ?? typeHint ?? lcName);
+    const content = messageContentToString(m.content ?? nested?.content);
+    const toolCalls = (m.toolCalls ?? m.tool_calls ?? nested?.tool_calls);
+    const toolCallId = (typeof m.toolCallId === 'string' && m.toolCallId) ||
+        (typeof m.tool_call_id === 'string' && m.tool_call_id) ||
+        (typeof nested?.tool_call_id === 'string' && nested.tool_call_id) ||
+        undefined;
+    const toolName = (typeof m.toolName === 'string' && m.toolName) ||
+        (typeof nested?.name === 'string' && nested.name) ||
+        undefined;
+    const success = typeof m.success === 'boolean' ? m.success : undefined;
+    const reasoningContent = (typeof m.reasoningContent === 'string' && m.reasoningContent) ||
+        (typeof m.reasoning_content === 'string' && m.reasoning_content) ||
+        undefined;
+    return {
+        role,
+        content,
+        ...(toolCalls ? { toolCalls } : {}),
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(toolName ? { toolName } : {}),
+        ...(success !== undefined ? { success } : {}),
+        ...(reasoningContent ? { reasoningContent } : {}),
+    };
+}
+function graphRoleFromUnknown(raw) {
+    if (raw === 'user' || raw === 'assistant' || raw === 'system' || raw === 'tool')
+        return raw;
+    if (raw === 'human' || raw === 'HumanMessage')
+        return 'user';
+    if (raw === 'ai' || raw === 'AIMessage')
+        return 'assistant';
+    if (raw === 'system' || raw === 'SystemMessage')
+        return 'system';
+    if (raw === 'tool' || raw === 'ToolMessage')
+        return 'tool';
+    return 'user';
+}
+function messageContentToString(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (typeof part === 'string')
+                return part;
+            if (part && typeof part === 'object' && typeof part.text === 'string') {
+                return part.text;
+            }
+            return '';
+        })
+            .join('');
+    }
+    if (content == null)
+        return '';
+    return String(content);
 }
 export function buildHitlWaitingTaskOutput(params) {
     return {
@@ -362,7 +480,7 @@ export function extractHitlThreadId(output) {
  * 与 LangGraph put / 子图内 HITL interrupt 同一把钥匙。
  *
  * 注意：session 级 thread + 全量 Session 历史同时注入会导致 messages 双重 append。
- * 组装本轮 Graph 输入请用 {@link buildTurnGraphMessages}（有 Checkpoint 历史则只追加 user）。
+ * 组装本轮 Graph 输入请用 {@link loadModelFacingHistory} 与 {@link turnGraphMessagesAfterCompression}。
  */
 export function resolveCheckpointThreadId(params) {
     if (params.sessionId)

package/dist/tool/harness-primitives.js

@@ -53,7 +53,25 @@ function harnessDefinitions() {
             manifest: {
                 id: 'builtin:write_file',
                 name: 'write_file',
-                description: '写入当前用户目录（含用户自己的 skills）。预装 tools / skills 只读。',
+                description: '写入当前用户目录（含用户自己的 skills）。预装 tools / skills 只读。覆盖已有文件。',
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string' },
+                },
+            },
+        },
+        {
+            toolId: 'builtin:append_to_file',
+            name: 'append_to_file',
+            manifest: {
+                id: 'builtin:append_to_file',
+                name: 'append_to_file',
+                description: '向当前用户目录内的文件追加文本。文件不存在则创建。预装 tools / skills 只读。',
                 ...common,
             },
             inputSchema: {
@@ -199,10 +217,10 @@ export function resolveJailRoots(options) {
     }
     return roots;
 }
-async function writeFileNoFollow(target, content) {
+async function writeFileNoFollow(target, content, append = false) {
     const flags = fsConstants.O_WRONLY |
         fsConstants.O_CREAT |
-        fsConstants.O_TRUNC |
+        (append ? fsConstants.O_APPEND : fsConstants.O_TRUNC) |
         (fsConstants.O_NOFOLLOW ?? 0);
     let handle;
     try {
@@ -216,7 +234,8 @@ async function writeFileNoFollow(target, content) {
         throw err;
     }
     try {
-        await handle.writeFile(content, 'utf8');
+        const { bytesWritten } = await handle.write(content, undefined, 'utf8');
+        return bytesWritten;
     }
     finally {
         await handle.close();
@@ -408,7 +427,9 @@ export class HarnessPrimitiveExecutor {
                 case 'read_file':
                     return await this.readFile(request);
                 case 'write_file':
-                    return await this.writeFile(request);
+                    return await this.writeFile(request, false);
+                case 'append_to_file':
+                    return await this.writeFile(request, true);
                 case 'execute_command':
                     return await this.executeCommand(request);
                 default:
@@ -459,7 +480,7 @@ export class HarnessPrimitiveExecutor {
         }
         return ok(request, text);
     }
-    async writeFile(request) {
+    async writeFile(request, append) {
         const filePath = String(request.arguments.path ?? '');
         const content = String(request.arguments.content ?? '');
         const workdir = this.requireWorkdir(request);
@@ -474,8 +495,8 @@ export class HarnessPrimitiveExecutor {
         if (PROTECTED_WRITE_NAMES.has(path.basename(recast))) {
             throw new Error(`禁止写入平台文件：${path.basename(recast)}`);
         }
-        await writeFileNoFollow(recast, content);
-        return ok(request, JSON.stringify({ ok: true, path: path.relative(workdir, recast) }));
+        const bytesWritten = await writeFileNoFollow(recast, content, append);
+        return ok(request, JSON.stringify({ ok: true, path: path.relative(workdir, recast), bytesWritten }));
     }
     async executeCommand(request) {
         const command = substituteSkillDir(String(request.arguments.command ?? '').trim(), request.skillDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "ioredis": "^5.4.0",
     "pg": "^8.13.0",
     "yaml": "^2.6.1",
-    "@gt-fe/eap-contracts": "0.0.14"
+    "@gt-fe/eap-contracts": "0.0.15"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",