compaction

Documentation

Overview

Package compaction is the PURE, testable core of in-session context compaction: deciding WHERE to cut a running conversation and rendering the cut-off part into a plain transcript for an Anthropic summarizer. It owns no model call and no I/O — the runtime orchestrates those — so the load-bearing invariant (never split a tool_use from its tool_result) can be proven in isolation.

The doctrine (three layers — hot raw turns / warm summary / cold session log) lives in COMPACTION.md. This package implements the warm layer's mechanics.

Index

• Constants
• func CountTurns(messages []wire.Message) int
• func EstimateTokens(messages []wire.Message) int
• func EvictStaleToolResults(messages []wire.Message, keepRecent int) int
• func EvictStaleToolResultsOpts(messages []wire.Message, keepRecent int, opts EvictOpts) int
• func Plan(messages []wire.Message, keepRecent int) (head, tail []wire.Message, ok bool)
• func Render(messages []wire.Message) string
• type EvictOpts

Constants

const OmittedToolResult = "[earlier tool output omitted to keep this turn within the context window]"

OmittedToolResult is the LEGACY blank placeholder; offloadRef now writes a TYPED pointer back to the source instead (below). Kept so isOffloaded still recognizes results elided by older builds.

Functions

func CountTurns

func CountTurns(messages []wire.Message) int

CountTurns reports how many user-turn boundaries a message slice contains — used for the "summarized N earlier turns" telemetry and status line.

func EstimateTokens

func EstimateTokens(messages []wire.Message) int

EstimateTokens approximates the prompt size of a message slice the way the gateway's router does: ~4 chars/token over all text and tool-result content.

func EvictStaleToolResults

func EvictStaleToolResults(messages []wire.Message, keepRecent int) int

EvictStaleToolResults offloads the payload of OLD tool_result blocks — replacing each with a TYPED pointer (offloadRef) back to its source — so a long turn stops re-sending stale grep/read/test dumps every iteration. It is RELEVANCE-FIRST, not purely age-based:

• a SUPERSEDED read (an earlier read of a file that's read AGAIN later) is offloaded eagerly, even if recent — the newer copy is authoritative, so the older is dead weight; and
• among what's left, the most recent keepRecent stay verbatim (the active working set).

A file read's pointer is lossless (the file is on disk; re-read to restore); other outputs name how to re-fetch. It NEVER removes a block — only swaps payload for a pointer — so tool_use↔ tool_result adjacency holds. Returns how many it offloaded.

func EvictStaleToolResultsOpts

func EvictStaleToolResultsOpts(messages []wire.Message, keepRecent int, opts EvictOpts) int

EvictStaleToolResultsOpts is EvictStaleToolResults with options (hot-path pinning).

func Plan

func Plan(messages []wire.Message, keepRecent int) (head, tail []wire.Message, ok bool)

Plan splits a conversation into a HEAD to summarize and a TAIL to keep verbatim, cutting at a user-turn boundary so the last keepRecent turns survive raw and no tool_use/tool_result pair is ever divided. ok is false when the session is still short enough that there's nothing worth compacting (≤ keepRecent turns).

func Render

func Render(messages []wire.Message) string

Render flattens the head messages into a plain-text transcript for the summarizer. It is deliberately lossy in the safe direction: tool mechanics are reduced to a one-liner and tool output is clipped, while user/assistant prose is preserved nearly whole. The output carries NO doctrine — it is pure session content; the compaction prompt lives server-side.

Types

type EvictOpts

type EvictOpts struct {
	// Pinned reports whether a read_file path is HOT — the session has observed
	// it being re-read (typically right after a prior eviction), so evicting it
	// again just forces another re-read (the measured read-evict-reread thrash:
	// the same 9 files re-read 13-14x in one session). A pinned path's LATEST
	// live read survives even past the keepRecent cutoff. Superseded duplicates
	// of a pinned path still offload — that is deduplication, not thrash.
	Pinned func(path string) bool
}

EvictOpts tunes EvictStaleToolResultsOpts beyond the keep count.