Compaction

Compaction

Edge adaptation of the upstream context window management system.

Upstream reference: Compaction

What Upstream Provides

Compaction keeps long sessions within the model's context window by summarizing older conversation segments and replacing them with compressed summaries. It follows the capability seam pattern with three tiers:

• CompactionEngine (ctx.compaction, dsh-compaction) — service definition: trigger policy, range selection, lock semantics, durable event lifecycle (compaction/start → compaction/summary → compaction/end).
• BasicCompactionEngine (dsh-compaction-basic) — provider: implements the engine with LLM-based summarization. Triggers on pressure (normal threshold) or context-overflow (provider-confirmed, more aggressive). Runs during agent/pre-step before request derivation.
• ToolResultPruner (dsh-compaction-tool-result-pruner) — optional pre-compaction step: deterministically trims text-heavy tool results (middle-slice, preserving block order) before range selection, potentially recovering enough space to skip full summarization.

Compaction events are log-only — the summary appears as a user/message with a surfaceOp: replace directive that shadows the original range. The operation is bracketed by start/end lock events to detect incomplete compactions across crashes.

What Edge Changed

All compaction plugins

Both BasicCompactionEngine and ToolResultPruner are installed as-is with zero Edge-specific code. No configuration overrides, no adapter, no patches. Compaction uses the same LLM provider (DeepSeek) that handles regular turns, so it works automatically once LlmRuntime is available.

What Edge Did NOT Change

• Trigger policy (pressure threshold, context-overflow detection)
• Range selection algorithm (balanced tool call/result pairs)
• LLM summarization and summary event format
• Tool result pruning strategy (Unicode code point measurement, middle-slice)
• Lock semantics and crash recovery
• Compaction events (compaction/start, compaction/summary, compaction/end, compaction/prune)

Performance Characteristics

When compaction triggers

Compaction runs at agent/pre-step — before each model request — when the context window is under pressure. The engine first tries tool result pruning (cheap, no LLM call). If pruning doesn't free enough space, it selects a range of older events and generates a summary via an LLM call. This adds one extra LLM round-trip to the step, typically 2–5 seconds.

Compaction vs chunk packing

These are independent optimizations solving different problems:

| Concern | Compaction | Chunk Packing|

Problem	Context window overflow	DO SQL row count limits
Layer	Model context (surface events)	Storage (persistence rows)
---	---	---
Mechanism	LLM summarization + surface replace	Merge consecutive chunk events into single rows
---	---	---
Owner	Upstream BasicCompactionEngine	Edge DurableObjectSessionPersistence
---	---	---
Trigger	Context pressure at pre-step	Every event batch write

Compaction reduces what the model sees. Chunk packing reduces how many rows the database stores. Both can operate on the same session independently.

Architecture Summary

| Component | Category | Edge Code|

BasicCompactionEngine		One ctx.plugin() call
ToolResultPruner		One ctx.plugin() call

Key observation: Compaction is a pure upstream capability with zero Edge adaptation. The engine, pruner, trigger policy, and event lifecycle are all upstream code. Edge only provides the two ctx.plugin() install lines — the smallest possible integration.

压缩

上游上下文窗口管理系统在 Edge 中的适配。

上游参考：Compaction

上游提供了什么

压缩通过摘要旧的对话片段来保持长会话在模型上下文窗口范围内。遵循能力接缝模式，分三层：

• CompactionEngine（ctx.compaction，dsh-compaction）— 服务定义：触发策略、范围选择、锁语义、持久事件生命周期（compaction/start → compaction/summary → compaction/end）。
• BasicCompactionEngine（dsh-compaction-basic）— 提供者：用 LLM 生成摘要。触发条件：pressure（正常阈值）或 context-overflow（提供者确认，更激进）。在 agent/pre-step 阶段、请求派生之前运行。
• ToolResultPruner（dsh-compaction-tool-result-pruner）— 可选的预压缩步骤：确定性地裁剪过长的工具结果文本（中间切片，保留块顺序），可能回收足够空间以跳过完整摘要。

压缩事件仅存在于日志——摘要以 user/message + surfaceOp: replace 指令出现，遮蔽原始范围。操作由 start/end 锁事件包裹，用于检测跨崩溃的不完整压缩。

Edge 改了什么

全部压缩插件

BasicCompactionEngine 和 ToolResultPruner 全部原封安装，零 Edge 代码。无配置覆盖、无适配器、无补丁。压缩使用与普通 turn 相同的 LLM 提供者（DeepSeek），LlmRuntime 可用后即自动工作。

Edge 没有改什么

• 触发策略（压力阈值、上下文溢出检测）
• 范围选择算法（平衡的工具调用/结果对）
• LLM 摘要生成和摘要事件格式
• 工具结果裁剪策略（Unicode 码点度量、中间切片）
• 锁语义和崩溃恢复
• 压缩事件（compaction/start、compaction/summary、compaction/end、compaction/prune）

性能特征

压缩触发时机

压缩在 agent/pre-step 阶段运行——每次模型请求之前——当上下文窗口承压时。引擎先尝试工具结果裁剪（低成本，无 LLM 调用）。如果裁剪不够，选择一段旧事件并通过 LLM 调用生成摘要。这为该步骤增加一次额外的 LLM 往返，通常 2–5 秒。

压缩 vs chunk packing

两者是独立的优化，解决不同的问题：

| 关注点 | 压缩 | Chunk Packing|

问题	上下文窗口溢出	DO SQL 行数限制
层次	模型上下文（surface 事件）	存储（持久化行）
---	---	---
机制	LLM 摘要 + surface 替换	合并连续 chunk 事件为单行
---	---	---
所有者	上游 BasicCompactionEngine	Edge DurableObjectSessionPersistence
---	---	---
触发	pre-step 时上下文压力	每次事件批写入

压缩减少模型看到的内容。Chunk packing 减少数据库存储的行数。两者可以在同一个 session 上独立运作。

架构总结

| 组件 | 分类 | Edge 代码|

BasicCompactionEngine		一行 ctx.plugin() 调用
ToolResultPruner		一行 ctx.plugin() 调用

关键观察：压缩是纯上游能力，零 Edge 适配。引擎、裁剪器、触发策略和事件生命周期全是上游代码。Edge 只提供两行 ctx.plugin() 安装——最小可能的集成。