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§
- Branch
Preparation - Branch
Summary - A generated branch summary;
usageisNonewhen there was nothing to summarize. - Branch
Summary Options GenerateBranchSummaryOptionswithout transport settings (those belong to the caller’s model call).- Compact
Options - Settings of one compaction run (
compact’s model, focus, thinking level and routing session). - Compaction
Preparation CompactionPreparation: whatcompactsummarizes and keeps.- Compaction
Result CompactionResult;detailsholds the file lists.- Compaction
Settings - CutPoint
- File
Operations - Files touched by
read,writeandedittool calls, in first-seen order. - Summary
Request - 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 whensession_idisNone.
Enums§
- Branch
Summary Error - 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’shint. - 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 fromold_leaf_idback to (not including) its deepest common ancestor withtarget_id, oldest first, and that ancestor’s id.- compact
compact: summarizes a prepared compaction throughcall(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_llmfor 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: likeestimate_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 thepathargument of assistantread/write/edittool calls.- find_
cut_ point findCutPoint: the first entry to keep so that roughlykeep_recent_tokensof 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 beforeentry_index(not beforestart_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 branchentries(oldest first) throughcall.- history_
summary_ request generateSummaryWithUsage: the history summary request (an update whenprevious_summaryis set).- prepare_
branch_ entries prepareBranchEntries: the newest messages that fittoken_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.Nonewhen the path ends in a compaction or nothing would be summarized.- serialize_
conversation serializeConversation: LLM messages (seeconvert_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 thanreserve_tokensof 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.