ctxmgr

package
v0.97.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 20, 2026 License: GPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package ctxmgr manages agent context budgets, compaction, and branch summarization.

Index

Constants

This section is empty.

Variables

View Source
var ErrBranchSummaryAborted = result.NewBranchSummaryError("aborted", "branch summarization aborted", nil)

ErrBranchSummaryAborted indicates branch summarization was cancelled.

View Source
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.

View Source
var ErrSummarizationFailed = result.NewCompactionError("summarization_failed", "summarization failed", nil)

ErrSummarizationFailed indicates compaction summarization could not complete.

Functions

func CalculateContextTokens

func CalculateContextTokens(usage msg.Usage) int

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

func FormatFileOperations(readFiles, modifiedFiles []string) string

FormatFileOperations renders file lists as XML blocks for summaries.

func IsContextOverflowErr

func IsContextOverflowErr(err error) bool

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

func ShouldCompact(contextTokens, contextWindow int, settings Settings) bool

ShouldCompact reports whether context usage exceeds the compaction threshold.

func WrapOverflowError

func WrapOverflowError(err error) error

WrapOverflowError wraps an underlying error as a typed OverflowError when overflow is detected.

Types

type BranchSummaryResult

type BranchSummaryResult struct {
	Summary       string
	ReadFiles     []string
	ModifiedFiles []string
}

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

type ContextUsage struct {
	Tokens        int
	ContextWindow int
	Percent       float64
}

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

type CutPointResult struct {
	FirstKeptEntryIndex int
	TurnStartIndex      int
	IsSplitTurn         bool
}

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 New

func New(opts Options) *Manager

New creates a context manager for harness integration.

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

func (m *Manager) ContextWindow() int

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 (m *Manager) ReloadAgentState(ctx context.Context, sess *session.Session, ag *agent.Agent) error

func (*Manager) Settings

func (m *Manager) Settings() Settings

Settings returns the active compaction settings.

func (*Manager) UpdateSystemPrompt

func (m *Manager) UpdateSystemPrompt(systemPrompt string)

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

type Settings struct {
	Enabled          bool
	PruneToolOutputs bool
	ReserveTokens    int
	KeepRecentTokens int
}

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

func (s Settings) WithDefaults() Settings

WithDefaults fills zero compaction settings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL