Skip to main content

Crate compaction

Crate compaction 

Source
Expand description

Context compaction and branch summarization, ported from packages/coding-agent/src/core/compaction/ (compaction.ts, branch-summarization.ts, utils.ts).

Session entries and agent messages are JSON values in the session file format (see session-file), so custom roles (bashExecution, custom, branchSummary, compactionSummary) and unknown fields pass through untouched. Summaries are produced by a caller-supplied async model call that receives a SummaryRequest built from ai types and returns the provider’s AssistantMessage; this crate does no I/O.

Structs§

BranchPreparation
BranchSummary
A generated branch summary; usage is None when there was nothing to summarize.
BranchSummaryOptions
GenerateBranchSummaryOptions without transport settings (those belong to the caller’s model call).
CompactOptions
Settings of one compaction run (compact’s model, focus, thinking level and routing session).
CompactionPreparation
CompactionPreparation: what compact summarizes and keeps.
CompactionResult
CompactionResult; details holds the file lists.
CompactionSettings
CutPoint
FileOperations
Files touched by read, write and edit tool calls, in first-seen order.
SummaryRequest
One summarization call. The caller adds its credentials, headers and abort signal, always sends it with cacheRetention: "none" (one-off summaries must not write the cache), and mints a fresh routing session id when session_id is None.

Enums§

BranchSummaryError
Why no branch summary was produced.

Constants§

NO_PRIOR_HISTORY
The history summary a split turn uses when nothing before the turn was summarized.

Functions§

bug_summary_request
The summary request for the session’s messages, with the user’s hint.
bug_summary_text
The report text of a summary response, or why there is none.
calculate_context_tokens
calculateContextTokens: totalTokens, else the sum of input, output and cache tokens.
collect_entries_for_branch_summary
collectEntriesForBranchSummary: the entries from old_leaf_id back to (not including) its deepest common ancestor with target_id, oldest first, and that ancestor’s id.
compact
compact: summarizes a prepared compaction through call (history, then the split turn’s prefix when cutting mid-turn) and appends the file lists.
compute_file_lists
computeFileLists: (read-only files, modified files), each sorted.
convert_for_summary
convert_to_llm for a summary’s conversation (Rust-only): recalled long-term memory and the active refinements are left out. They came from memory and the ledger; a summary that repeated them would be kept or proposed again as if the session had learned them.
estimate_context_tokens
estimateContextTokens: the newest valid assistant usage plus estimates for the messages after it.
estimate_projected_context_tokens
estimateProjectedContextTokens: like estimate_context_tokens, but usage recorded before the latest context edit or compaction on the branch is stale, so then every projected message is estimated instead.
estimate_tokens
estimateTokens: characters / 4, rounded up (an overestimate); images count 4800 characters.
extract_file_ops_from_message
extractFileOpsFromMessage: records the path argument of assistant read/write/edit tool calls.
find_cut_point
findCutPoint: the first entry to keep so that roughly keep_recent_tokens of recent context survive. Cuts only at user-like or assistant messages, never at tool results.
find_turn_start_index
findTurnStartIndex: the nearest entry at or before entry_index (not before start_index) that starts a turn.
format_file_operations
formatFileOperations: the <read-files>/<modified-files> sections appended to a summary.
generate_branch_summary
generateBranchSummary: summarizes abandoned branch entries (oldest first) through call.
history_summary_request
generateSummaryWithUsage: the history summary request (an update when previous_summary is set).
prepare_branch_entries
prepareBranchEntries: the newest messages that fit token_budget (0 or less: no limit), plus file operations from every entry, including the lists recorded by earlier pi-generated branch summaries.
prepare_compaction
prepareCompaction: picks the cut on the session path and collects what to summarize. None when the path ends in a compaction or nothing would be summarized.
serialize_conversation
serializeConversation: LLM messages (see convert_to_llm) as [Role]: ... text, so the summarizer reads the transcript instead of continuing it. Tool results are cut to 2000 characters.
should_compact
shouldCompact: whether the context leaves less than reserve_tokens of the window.
split_turn_summary
The summary of a split turn: the history’s summary, then the turn prefix’s.
turn_prefix_request
generateTurnPrefixSummary’s request: a checkpoint of the start of a split turn, with half the budget.
turn_prefix_request_of
A turn prefix summary request asking prompt: the summary request’s shape (system prompt, reasoning, session) with half the reserve as its budget.