Documentation
¶
Overview ¶
Package ctxmgr manages agent context budgets, compaction, and branch summarization.
Index ¶
- Variables
- func CalculateContextTokens(usage msg.Usage) int
- func CollectBranchEntries(allEntries []session.TreeEntry, oldLeafID, newEntryID string) result.Result[branchEntriesResult, result.BranchSummaryError]
- func ComputeFileLists(ops FileOperations) (readFiles, modifiedFiles []string)
- func EstimateTokens(message msg.AgentMessage) int
- func ExtractFileOpsFromMessage(message msg.AgentMessage, ops FileOperations)
- func FormatFileOperations(readFiles, modifiedFiles []string) string
- func IsContextOverflowErr(err error) bool
- func IsContextOverflowMessage(message msg.AssistantMessage, contextWindow int) bool
- func IsOverflowResult(err error, messages []msg.AgentMessage, contextWindow int) bool
- func NewCompactionEntryID() string
- func PrepareCompaction(pathEntries []session.TreeEntry, settings Settings, opts PrepareOptions) result.Result[*CompactionPreparation, result.CompactionError]
- func PruneToolOutputs(messages []msg.AgentMessage, settings Settings) []msg.AgentMessage
- func RunBranchSummary(ctx context.Context, model llms.Model, modelName string, ...) result.Result[*BranchSummaryResult, result.BranchSummaryError]
- func RunCompaction(ctx context.Context, model llms.Model, modelName string, ...) result.Result[*CompactionResult, result.CompactionError]
- func SerializeConversation(messages []msg.AgentMessage) string
- func ShouldCompact(contextTokens, contextWindow int, settings Settings) bool
- func WrapOverflowError(err error) error
- type BranchSummaryResult
- type CompactOpts
- type CompactionPreparation
- type CompactionResult
- type ContextUsage
- type ContextUsageEstimate
- type CutPointResult
- type FileOperations
- type Manager
- func (m *Manager) CompactAndReload(ctx context.Context, sess *session.Session, ag *agent.Agent, opts CompactOpts) error
- func (m *Manager) ContextWindow() int
- func (m *Manager) EnsureWithinBudget(ctx context.Context, sess *session.Session, ag *agent.Agent) error
- func (m *Manager) GetContextUsage(path []session.TreeEntry) ContextUsage
- func (m *Manager) MoveTo(ctx context.Context, sess *session.Session, targetEntryID, summary string) error
- func (m *Manager) ReloadAgentState(ctx context.Context, sess *session.Session, ag *agent.Agent) error
- func (m *Manager) Settings() Settings
- func (m *Manager) UpdateSystemPrompt(systemPrompt string)
- type Options
- type PrepareOptions
- type Settings
Constants ¶
This section is empty.
Variables ¶
var ErrBranchSummaryAborted = result.NewBranchSummaryError("aborted", "branch summarization aborted", nil)
ErrBranchSummaryAborted indicates branch summarization was cancelled.
var ErrCompactionRequired = result.NewCompactionError("nothing_to_compact", "compaction required but no removable history", nil)
ErrCompactionRequired indicates context still exceeds budget but no history could be compacted.
var ErrSummarizationFailed = result.NewCompactionError("summarization_failed", "summarization failed", nil)
ErrSummarizationFailed indicates compaction summarization could not complete.
Functions ¶
func CalculateContextTokens ¶
CalculateContextTokens returns total tokens from provider usage metadata.
func CollectBranchEntries ¶
func CollectBranchEntries(allEntries []session.TreeEntry, oldLeafID, newEntryID string) result.Result[branchEntriesResult, result.BranchSummaryError]
CollectBranchEntries returns entries abandoned when moving from oldLeaf to newEntryID.
func ComputeFileLists ¶
func ComputeFileLists(ops FileOperations) (readFiles, modifiedFiles []string)
ComputeFileLists splits read-only and modified paths for summary output.
func EstimateTokens ¶
func EstimateTokens(message msg.AgentMessage) int
EstimateTokens conservatively estimates token count for one agent message.
func ExtractFileOpsFromMessage ¶
func ExtractFileOpsFromMessage(message msg.AgentMessage, ops FileOperations)
ExtractFileOpsFromMessage records file tool usage from an assistant message.
func FormatFileOperations ¶
FormatFileOperations renders file lists as XML blocks for summaries.
func IsContextOverflowErr ¶
IsContextOverflowErr reports whether an LLM error indicates context window overflow.
func IsContextOverflowMessage ¶
func IsContextOverflowMessage(message msg.AssistantMessage, contextWindow int) bool
IsContextOverflowMessage reports whether an assistant message indicates overflow.
func IsOverflowResult ¶
func IsOverflowResult(err error, messages []msg.AgentMessage, contextWindow int) bool
IsOverflowResult checks stream errors and the last assistant message for overflow.
func NewCompactionEntryID ¶
func NewCompactionEntryID() string
NewCompactionEntryID returns a unique compaction node identifier.
func PrepareCompaction ¶
func PrepareCompaction(pathEntries []session.TreeEntry, settings Settings, opts PrepareOptions) result.Result[*CompactionPreparation, result.CompactionError]
PrepareCompaction computes which session entries will be summarized.
func PruneToolOutputs ¶
func PruneToolOutputs(messages []msg.AgentMessage, settings Settings) []msg.AgentMessage
PruneToolOutputs removes older tool result payloads while keeping recent tool output intact.
func RunBranchSummary ¶
func RunBranchSummary( ctx context.Context, model llms.Model, modelName string, messages []msg.AgentMessage, fileOps FileOperations, settings Settings, ) result.Result[*BranchSummaryResult, result.BranchSummaryError]
RunBranchSummary generates a summary for abandoned branch entries.
func RunCompaction ¶
func RunCompaction( ctx context.Context, model llms.Model, modelName string, preparation *CompactionPreparation, ) result.Result[*CompactionResult, result.CompactionError]
RunCompaction generates a summary and returns compaction metadata.
func SerializeConversation ¶
func SerializeConversation(messages []msg.AgentMessage) string
SerializeConversation converts agent messages to plain text for summarization prompts.
func ShouldCompact ¶
ShouldCompact reports whether context usage exceeds the compaction threshold.
func WrapOverflowError ¶
WrapOverflowError wraps an underlying error as a typed OverflowError when overflow is detected.
Types ¶
type BranchSummaryResult ¶
BranchSummaryResult is the outcome of branch summarization during tree navigation.
type CompactOpts ¶
type CompactOpts struct {
// Force enables overflow-style re-compaction after a prior compaction leaf.
Force bool
}
CompactOpts configures a compaction run invoked by the manager.
type CompactionPreparation ¶
type CompactionPreparation struct {
FirstKeptEntryID string
MessagesToSummarize []msg.AgentMessage
TurnPrefixMessages []msg.AgentMessage
IsSplitTurn bool
TokensBefore int
PreviousSummary string
FileOps FileOperations
Settings Settings
}
CompactionPreparation holds precomputed compaction inputs.
type CompactionResult ¶
type CompactionResult struct {
Summary string
FirstKeptEntryID string
TokensBefore int
ReadFiles []string
ModifiedFiles []string
}
CompactionResult is the outcome of a successful compaction run.
type ContextUsage ¶
ContextUsage reports estimated context consumption for UI and hooks.
type ContextUsageEstimate ¶
type ContextUsageEstimate struct {
Tokens int
UsageTokens int
TrailingTokens int
LastUsageIndex int
}
ContextUsageEstimate is a token budget estimate for a message list.
func EstimateContextTokens ¶
func EstimateContextTokens(messages []msg.AgentMessage) ContextUsageEstimate
EstimateContextTokens estimates total context tokens, preferring the last assistant usage.
type CutPointResult ¶
CutPointResult describes where to split session history during compaction.
func FindCutPoint ¶
func FindCutPoint(entries []session.TreeEntry, startIndex, endIndex, keepRecentTokens int) CutPointResult
FindCutPoint selects the oldest entry index to keep within a token budget.
type FileOperations ¶
type FileOperations struct {
Read map[string]struct{}
Written map[string]struct{}
Edited map[string]struct{}
}
FileOperations tracks workspace file activity for compaction summaries.
func ExtractFileOperations ¶
func ExtractFileOperations(messages []msg.AgentMessage, entries []session.TreeEntry, prevCompactionIndex int) FileOperations
ExtractFileOperations aggregates file ops from messages and prior compaction details.
func NewFileOperations ¶
func NewFileOperations() FileOperations
NewFileOperations creates empty file operation sets.
func PrepareBranchSummary ¶
func PrepareBranchSummary(entries []session.TreeEntry, contextWindow int, settings Settings) ([]msg.AgentMessage, FileOperations, int)
PrepareBranchSummary selects messages to summarize within a token budget.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates compaction, branch summarization, and context budget checks.
func (*Manager) CompactAndReload ¶
func (m *Manager) CompactAndReload(ctx context.Context, sess *session.Session, ag *agent.Agent, opts CompactOpts) error
CompactAndReload compacts the current branch and reloads agent state.
func (*Manager) ContextWindow ¶
ContextWindow returns the configured model context window size.
func (*Manager) EnsureWithinBudget ¶
func (m *Manager) EnsureWithinBudget(ctx context.Context, sess *session.Session, ag *agent.Agent) error
EnsureWithinBudget compacts session history when usage exceeds the threshold.
func (*Manager) GetContextUsage ¶
func (m *Manager) GetContextUsage(path []session.TreeEntry) ContextUsage
GetContextUsage estimates current branch context consumption including system prompt overhead.
func (*Manager) MoveTo ¶
func (m *Manager) MoveTo(ctx context.Context, sess *session.Session, targetEntryID, summary string) error
MoveTo navigates the session tree, auto-summarizing abandoned branches when needed.
func (*Manager) ReloadAgentState ¶
func (*Manager) UpdateSystemPrompt ¶
UpdateSystemPrompt replaces the system prompt used for context usage estimates.
type Options ¶
type Options struct {
Model llms.Model
ModelName string
ContextWindow int
Settings Settings
SystemPrompt string
}
Options configures a context manager instance.
type PrepareOptions ¶
type PrepareOptions struct {
// Force allows re-compaction when the session leaf is already a compaction node.
Force bool
// ExtraMessages are unpersisted agent messages appended to the summarization set.
ExtraMessages []msg.AgentMessage
}
PrepareOptions configures compaction preparation behavior.
type Settings ¶
Settings controls compaction and branch summarization behavior.
func SettingsFromConfig ¶
func SettingsFromConfig(cfg config.CompactionConfig) Settings
SettingsFromConfig converts chat agent compaction config into runtime settings.
func (Settings) WithDefaults ¶
WithDefaults fills zero compaction settings.