Index 08: Context Compact — 四层上下文压缩

[DEBUG] Compact check: tokens=180000, threshold=160000, shouldCompact=true
[INFO] Compacting 45 messages (cut at 50, total 95)
[INFO] Summary complete: The user asked to implement a REST API with the following
       endpoints: GET /users, POST /users, PUT /users/:id, DELETE /users/:id...
[INFO] Context compacted: layer=SUMMARIZE, messages 95→51, tokens 180000→45000

messagesHistory.add(Message(Role.ASSISTANT, content, toolCalls = [...]))   // tool_use 块
messagesHistory.add(Message(Role.USER, "", toolResults = [...]))           // tool_result 块

AgentLoop.run() 每次迭代:
  buildRequestMessages()
    ↓
  Layer 1: compactor.shouldCompact(requestMessages)  ← TokenEstimator.estimate()
    ↓ 超 compactTriggerRatio (80%)?
  Layer 2: BoundaryDetector.findSafeCut()  → 安全切割点
  Layer 3: SummaryBuffer → LLM → 摘要 SYSTEM 消息
    ↓ 仍超 emergencyTriggerRatio (95%)?
  Layer 4: emergencyTruncate() → FIFO 丢弃最旧消息
    ↓
  llmProvider.chat(requestMessages)
    ↓ stopReason == MAX_TOKENS?
  compactor.compact(messagesHistory) → continue 重试

class ContextCompactor(
    private val llmProvider: LLMProvider,
    private val config: CompactionConfig = CompactionConfig()
) {
    fun estimateTokens(messages: List<Message>): Int          // Layer 1
    fun shouldCompact(messages: List<Message>): Boolean       // Layer 1 判断
    suspend fun compact(messagesHistory: MutableList<Message>): CompactEvent?  // Layer 1-4 全流程
    fun emergencyTruncate(messagesHistory: MutableList<Message>): CompactEvent? // Layer 4 only
}

object TokenEstimator {
    /** 字符数除以该值得到估算 token 数（保守估计：3 个字符 ≈ 1 个 token） */
    private const val TOKEN_CHAR_RATIO = 3

    private val json = Json { encodeDefaults = true }

    fun estimate(messages: List<Message>): Int {
        return messages.sumOf { estimateOne(it) }
    }

    fun estimateOne(message: Message): Int {
        var charCount = message.content.length

        // 工具调用的输入参数也占用 token（会序列化为 JSON 发送给 API）
        if (message.role == Role.ASSISTANT && message.toolCalls.isNotEmpty()) {
            for (tc in message.toolCalls) {
                charCount += tc.name.length
                charCount += json.encodeToString(
                    JsonObject.serializer(), tc.input
                ).length
            }
        }

        // 工具执行结果也占用 token
        if (message.role == Role.USER && message.toolResults.isNotEmpty()) {
            for (tr in message.toolResults) {
                charCount += tr.toolCallId.length
                charCount += tr.content.length
            }
        }

        return charCount / TOKEN_CHAR_RATIO
    }
}

USER("read the file")
ASSISTANT("I'll read it", toolCalls=[read_file])     ← tool_use
USER("", toolResults=[file content])                 ← tool_result（紧随 tool_use）
ASSISTANT("The file says hello")
USER("thanks")
...

object BoundaryDetector {
    /**
     * 找到安全的消息切割位置。
     *
     * 从理想切割点（保留最近 [keepRecentCount] 条消息）开始向前回溯，
     * 直到找到安全位置。安全切割点保证不会分割 tool_use / tool_result 配对。
     *
     * @param messages 完整消息列表
     * @param keepRecentCount 保留的最近消息数（从末尾开始计数）
     * @return 安全切割位置索引。0 表示无法安全切割或不需切割。
     */
    fun findSafeCut(messages: List<Message>, keepRecentCount: Int): Int {
        if (keepRecentCount >= messages.size) return 0

        var cut = messages.size - keepRecentCount

        // 如果切割点恰好在一条带有 toolResults 的 USER 消息上，
        // 则表示该消息对应的 tool_use 在切割点之前被移除，
        // 导致保留的 tool_result 没有对应的 tool_use，需要前移切割点。
        while (cut > 0 && cut < messages.size &&
            messages[cut].role == Role.USER && messages[cut].toolResults.isNotEmpty()
        ) {
            cut--
        }

        return cut
    }
}

class SummaryBuffer {
    /** 当前累积的摘要文本。null 表示尚无摘要（首次压缩）。 */
    var currentSummary: String? = null
        private set

    /** 用新摘要替换当前摘要（滚动更新）。 */
    fun update(newSummary: String) {
        currentSummary = newSummary
    }

    /** 构建发给 LLM 的摘要请求 prompt。 */
    fun buildSummaryPrompt(oldMessages: List<Message>): String {
        val sb = StringBuilder()
        sb.appendLine(SUMMARY_INSTRUCTION)
        sb.appendLine()

        if (currentSummary != null) {
            sb.appendLine("## Previous Summary")
            sb.appendLine(currentSummary)
            sb.appendLine()
            sb.appendLine("Incorporate the above previous summary with the " +
                "new messages below into a single updated summary.")
            sb.appendLine()
        }

        sb.appendLine("## Messages to Summarize")
        sb.appendLine()
        for (msg in oldMessages) {
            val roleLabel = msg.role.name
            sb.appendLine("$roleLabel: ${msg.content}")
            if (msg.toolCalls.isNotEmpty()) {
                sb.appendLine("  [Tool Calls: ${msg.toolCalls.joinToString { it.name }}]")
            }
            if (msg.toolResults.isNotEmpty()) {
                val resultsPreview = msg.toolResults.joinToString { tr ->
                    if (tr.content.length > TOOL_RESULT_PREVIEW_LENGTH) {
                        tr.content.take(TOOL_RESULT_PREVIEW_LENGTH) + "..."
                    } else {
                        tr.content
                    }
                }
                sb.appendLine("  [Tool Results: $resultsPreview]")
            }
        }

        return sb.toString()
    }

    /** 清空摘要缓冲区 */
    fun clear() { currentSummary = null }

    companion object {
        private const val TOOL_RESULT_PREVIEW_LENGTH = 100
        private const val SUMMARY_INSTRUCTION =
            "You are a conversation summarizer. Your task is to create a concise " +
            "but comprehensive conversation summary. Focus on:\n" +
            "1. Key decisions and actions taken\n" +
            "2. Important information discovered (file contents, command outputs)\n" +
            "3. The user's explicit requests and preferences\n" +
            "4. Any errors encountered and how they were resolved\n\n" +
            "Write the summary in plain English. It will be inserted into the " +
            "conversation history to help the assistant remember what happened " +
            "earlier. Be factual and specific — include file paths, command names, " +
            "and key findings."
    }
}

You are a conversation summarizer. Your task is to create a concise but
comprehensive conversation summary. Focus on:
1. Key decisions and actions taken
2. Important information discovered (file contents, command outputs)
3. The user's explicit requests and preferences
4. Any errors encountered and how they were resolved
...

## Messages to Summarize

USER: Read the config file at /home/user/project/settings.conf
ASSISTANT: I'll read the config file and check the settings.
  [Tool Calls: read_file]
USER:
  [Tool Results: server.port=8080, db.url=jdbc:postgresql://local...]
ASSISTANT: The config shows server port 8080 and a PostgreSQL database connection.

...
## Previous Summary
The user inspected the project configuration. Key findings: server runs on
port 8080, uses PostgreSQL database, and has debug mode enabled.

Incorporate the above previous summary with the new messages below into a
single updated summary.

## Messages to Summarize

USER: Update the database connection timeout to 30 seconds
...

fun emergencyTruncate(messagesHistory: MutableList<Message>): CompactEvent? {
    val tokensBefore = estimateTokens(messagesHistory)
    val messagesBefore = messagesHistory.size
    val emergencyThreshold = (config.contextWindow * config.emergencyTriggerRatio).toInt()

    if (tokensBefore < emergencyThreshold) {
        return null  // 没到紧急阈值，不需要截断
    }

    val targetTokens = (config.contextWindow * config.keepRecentRatio).toInt()
    var removed = 0

    while (messagesHistory.size > config.minHistoryToCompact &&
        estimateTokens(messagesHistory) > targetTokens
    ) {
        // 每次只移除一批安全消息（通过 BoundaryDetector 找安全切割点）
        val keepCount = (messagesHistory.size - 1).coerceAtLeast(1)
        val cut = BoundaryDetector.findSafeCut(messagesHistory, keepCount)
        if (cut <= 0) {
            logger.warn { "Emergency truncate: cannot find safe cut, breaking" }
            break
        }
        messagesHistory.subList(0, cut).clear()
        removed += cut
    }

    val tokensAfter = estimateTokens(messagesHistory)
    return CompactEvent(
        layer = CompactLayer.TRUNCATE,
        messagesBefore = messagesBefore,
        messagesAfter = messagesHistory.size,
        tokensBefore = tokensBefore,
        tokensAfter = tokensAfter
    )
}

data class CompactionConfig(
    val compactTriggerRatio: Double = DEFAULT_COMPACT_TRIGGER_RATIO,        // 0.8
    val emergencyTriggerRatio: Double = DEFAULT_EMERGENCY_TRIGGER_RATIO,    // 0.95
    val keepRecentRatio: Double = DEFAULT_KEEP_RECENT_RATIO,                // 0.5
    val summaryMaxTokens: Int = DEFAULT_SUMMARY_MAX_TOKENS,                 // 2048
    val minHistoryToCompact: Int = DEFAULT_MIN_HISTORY_TO_COMPACT,          // 4
    val contextWindow: Int = DEFAULT_CONTEXT_WINDOW                         // 200_000
) {
    companion object {
        const val DEFAULT_COMPACT_TRIGGER_RATIO = 0.8
        const val DEFAULT_EMERGENCY_TRIGGER_RATIO = 0.95
        const val DEFAULT_KEEP_RECENT_RATIO = 0.5
        const val DEFAULT_SUMMARY_MAX_TOKENS = 2048
        const val DEFAULT_MIN_HISTORY_TO_COMPACT = 4
        const val DEFAULT_CONTEXT_WINDOW = 200_000
    }
}

suspend fun run(userInput: String): String {
    sanitizeHistory()
    messagesHistory.add(Message(Role.USER, userInput))

    val toolDefinitions = toolRegistry.getDefinitions()

    for (iteration in 1..config.maxIterations) {
        val baseMessages = buildRequestMessages()
        val appended = hooks.onPreLlmRequest?.invoke(baseMessages) ?: emptyList()
        var requestMessages = if (appended.isEmpty()) baseMessages else baseMessages + appended

        // s08: 主动压缩检查 —— 在 token 超限前压缩历史
        if (compactor.shouldCompact(requestMessages)) {
            logger.info { "Pre-request compaction triggered" }
            val event = compactor.compact(messagesHistory)
            if (event != null) {
                hooks.onCompact?.invoke(event)
                val rebuilt = buildRequestMessages()
                val reappended = hooks.onPreLlmRequest?.invoke(rebuilt) ?: emptyList()
                requestMessages = if (reappended.isEmpty()) rebuilt else rebuilt + reappended
            }
        }

        val response = llmProvider.chat(requestMessages, options, toolDefinitions)

        when (response.stopReason) {
            StopReason.END_TURN -> {
                messagesHistory.add(Message(Role.ASSISTANT, response.content))
                return response.content
            }

            StopReason.TOOL_USE -> {
                messagesHistory.add(Message(Role.ASSISTANT, response.content,
                    toolCalls = response.toolCalls))
                val toolResults = executeTools(response.toolCalls)
                messagesHistory.add(Message(Role.USER, "", toolResults = toolResults))
                continue
            }

            StopReason.MAX_TOKENS -> {
                // s08: 被动压缩 + 重试
                logger.warn { "MAX_TOKENS received, compacting and retrying" }
                val event = compactor.compact(messagesHistory)
                if (event != null) {
                    hooks.onCompact?.invoke(event)
                    continue  // 重试本轮
                }
                // 压缩失败（历史太短无法压缩），返回截断内容
                if (response.content.isNotBlank()) {
                    messagesHistory.add(Message(Role.ASSISTANT, response.content))
                }
                return response.content
            }

            StopReason.ERROR, StopReason.STOP_SEQUENCE -> {
                if (response.content.isNotBlank()) {
                    messagesHistory.add(Message(Role.ASSISTANT, response.content))
                }
                return response.content
            }
        }
    }
    // ...
}

class AgentLoop(
    private val llmProvider: LLMProvider,
    private val systemPrompt: String,
    private val config: AgentConfig = AgentConfig(),
    private val hooks: AgentLoopHooks = AgentLoopHooks(),
    private val toolRegistry: ToolRegistry = ToolRegistry(),
    private val compactor: ContextCompactor = ContextCompactor(llmProvider)  // s08
)

data class AgentLoopHooks(
    val onBeforeToolExecute: (suspend (ToolCall) -> Boolean)? = null,
    val onPreToolUse: (suspend (ToolCall) -> String?)? = null,
    val onPostToolUse: (suspend (ToolCall, ToolResult) -> ToolResult)? = null,
    val onPreLlmRequest: (suspend (List<Message>) -> List<Message>)? = null,
    val onCompact: (suspend (CompactEvent) -> Unit)? = null  // s08
)

fun start() {
    // ... 工具注册、权限管线、Hook 管理器、skill 加载 ...

    // s08: 构建上下文压缩器（复用主 LLMProvider 做摘要）
    val compactionConfig = CompactionConfig(
        contextWindow = config.contextWindow   // 从 AgentConfig 读取
    )
    val contextCompactor = ContextCompactor(llmProvider, compactionConfig)

    agentLoop = AgentLoop(
        llmProvider = llmProvider,
        systemPrompt = systemPrompt,
        config = config,
        hooks = AgentLoopHooks(
            onBeforeToolExecute = { tc -> pipeline.approve(tc) },
            onPreToolUse = { tc -> hookManager.firePreToolUse(tc) },
            onPostToolUse = { tc, result -> hookManager.firePostToolUse(tc, result) },
            onPreLlmRequest = { msgs -> hookManager.firePreLlmRequest(msgs) },
            onCompact = { event ->  // s08: 日志记录压缩事件
                logger.info { "Context compacted: layer=${event.layer}, " +
                    "messages ${event.messagesBefore}→${event.messagesAfter}, " +
                    "tokens ${event.tokensBefore}→${event.tokensAfter}" }
            }
        ),
        toolRegistry = toolRegistry,
        compactor = contextCompactor  // s08
    )
    // ...
}

data class CompactEvent(
    val layer: CompactLayer,       // SUMMARIZE or TRUNCATE
    val messagesBefore: Int,       // 压缩前消息数
    val messagesAfter: Int,        // 压缩后消息数
    val tokensBefore: Int,         // 压缩前估算 token
    val tokensAfter: Int,          // 压缩后估算 token
    val summaryText: String? = null  // 摘要文本，仅 SUMMARIZE 时非空
)

enum class CompactLayer {
    SUMMARIZE,   // LLM 摘要压缩（Layer 3），温和，保留信息
    TRUNCATE     // 紧急 FIFO 截断（Layer 4），激进，丢弃消息
}

src/main/kotlin/com/sepcai/code/
├── context/                                 # [新建] 上下文压缩领域包
│   ├── CompactionConfig.kt                 # data class 配置参数 + companion 默认值
│   ├── TokenEstimator.kt                   # object，字符法 token 估算
│   ├── CompactEvent.kt                     # data class 压缩事件 + CompactLayer 枚举
│   ├── BoundaryDetector.kt                 # object，安全切割点检测
│   ├── SummaryBuffer.kt                    # class，滚动摘要状态管理
│   └── ContextCompactor.kt                 # class，四层流水线协调器
├── agent/
│   ├── AgentConfig.kt                      # [修改] +contextWindow 字段
│   ├── AgentLoop.kt                        # [修改] +compactor 参数 +主动检查 +MAX_TOKENS 重试
│   └── AgentLoopHooks.kt                  # [修改] +onCompact 字段 +import
└── repl/
    └── ReplLoop.kt                         # [修改] 构建 ContextCompactor + 注入 AgentLoop + 欢迎语

src/test/kotlin/com/sepcai/code/
└── context/                                # [新建]
    ├── TokenEstimatorTest.kt               # 7 用例
    ├── BoundaryDetectorTest.kt             # 9 用例
    ├── SummaryBufferTest.kt               # 6 用例
    └── ContextCompactorTest.kt             # 8 用例（含 FakeSummaryProvider）