context

Documentation

Index

• func AutoCompactThresholdRatio() float64
• func AutoCompactThresholdTokens(contextWindow int) int
• func EstimateTokens(text string) int
• type CompactResult
• type CompactSnapshot
  • func (s CompactSnapshot) Compact(ctx context.Context, prov provider.Provider) (CompactResult, error)
• type ContextManager
• type Manager
  • func NewManager(contextWindow int) *Manager
  • func (m *Manager) Add(msg provider.Message)
  • func (m *Manager) ApplyCompactResult(snapshot CompactSnapshot, result CompactResult) (bool, int)
  • func (m *Manager) AutoCompactThreshold() int
  • func (m *Manager) CheckAndSummarize(ctx context.Context, prov provider.Provider) (bool, error)
  • func (m *Manager) Clear()
  • func (m *Manager) CompactSnapshot() CompactSnapshot
  • func (m *Manager) ContextWindow() int
  • func (m *Manager) Messages() []provider.Message
  • func (m *Manager) MessagesAndTokenCount() ([]provider.Message, int)
  • func (m *Manager) Microcompact() bool
  • func (m *Manager) PromptBudget() int
  • func (m *Manager) ReconcileToolCalls() bool
  • func (m *Manager) RecordUsage(usage provider.TokenUsage)
  • func (m *Manager) SetContextWindow(n int)
  • func (m *Manager) SetOutputReserve(n int)
  • func (m *Manager) SetProvider(p provider.Provider)
  • func (m *Manager) SetTodoFilePath(path string)
  • func (m *Manager) SetUsageHandler(fn func(provider.TokenUsage))
  • func (m *Manager) Summarize(ctx context.Context, prov provider.Provider) error
  • func (m *Manager) TokenCount() int
  • func (m *Manager) TruncateOldestGroupForRetry() bool
  • func (m *Manager) UpdateFirstSystemMessage(msg provider.Message)
  • func (m *Manager) UsageRatio() float64

Functions

func AutoCompactThresholdRatio

func AutoCompactThresholdRatio() float64

func AutoCompactThresholdTokens

func AutoCompactThresholdTokens(contextWindow int) int

func EstimateTokens

func EstimateTokens(text string) int

EstimateTokens provides a rough token estimation. Uses ~4 chars/token for ASCII and ~1.5 chars/token for CJK, which matches common BPE tokenizer behavior more closely than a flat len/4.

Types

type CompactResult

type CompactResult struct {
	Messages   []provider.Message
	TokenCount int
	Changed    bool
}

CompactResult is the output of compacting a CompactSnapshot.

type CompactSnapshot

type CompactSnapshot struct {
	Messages      []provider.Message
	OrigLen       int
	ContextWindow int
	OutputReserve int
	TodoPath      string
	Version       int64
}

CompactSnapshot is an immutable point-in-time view used by background compaction. It lets callers summarize a stable copy without mutating the live conversation while an LLM turn may still be running.

func (CompactSnapshot) Compact

func (s CompactSnapshot) Compact(ctx context.Context, prov provider.Provider) (CompactResult, error)

type ContextManager

type ContextManager interface {
	Add(msg provider.Message)
	Messages() []provider.Message
	TokenCount() int
	// MessagesAndTokenCount returns both values under a single lock,
	// guaranteeing a consistent snapshot.
	MessagesAndTokenCount() ([]provider.Message, int)
	ContextWindow() int
	SetContextWindow(n int)
	SetOutputReserve(n int)
	RecordUsage(usage provider.TokenUsage)
	Summarize(ctx context.Context, prov provider.Provider) error
	CheckAndSummarize(ctx context.Context, prov provider.Provider) (bool, error)
	TruncateOldestGroupForRetry() bool
	Clear()
	UsageRatio() float64
	AutoCompactThreshold() int
	ReconcileToolCalls() bool
}

ContextManager manages conversation history, tracking tokens and auto-summarizing.

⚠️ Consuming packages must import this as "ctxpkg" to avoid collision with the standard library "context" package.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager implements ContextManager.

func NewManager

func NewManager(contextWindow int) *Manager

NewManager creates a ContextManager with the given context window limit.

func (*Manager) Add

func (m *Manager) Add(msg provider.Message)

func (*Manager) ApplyCompactResult

func (m *Manager) ApplyCompactResult(snapshot CompactSnapshot, result CompactResult) (bool, int)

func (*Manager) AutoCompactThreshold

func (m *Manager) AutoCompactThreshold() int

func (*Manager) CheckAndSummarize

func (m *Manager) CheckAndSummarize(ctx context.Context, prov provider.Provider) (bool, error)

CheckAndSummarize triggers summarization if usage ratio >= threshold.

func (*Manager) Clear

func (m *Manager) Clear()

func (*Manager) CompactSnapshot

func (m *Manager) CompactSnapshot() CompactSnapshot

func (*Manager) ContextWindow

func (m *Manager) ContextWindow() int

func (*Manager) Messages

func (m *Manager) Messages() []provider.Message

func (*Manager) MessagesAndTokenCount

func (m *Manager) MessagesAndTokenCount() ([]provider.Message, int)

func (*Manager) Microcompact

func (m *Manager) Microcompact() bool

Microcompact reduces old bulky tool results in-place before falling back to full summarization.

func (*Manager) PromptBudget

func (m *Manager) PromptBudget() int

func (*Manager) ReconcileToolCalls

func (m *Manager) ReconcileToolCalls() bool

ReconcileToolCalls checks whether any assistant message in the conversation has unpaired tool_use blocks (i.e. tool_calls without matching tool_result blocks in subsequent messages). If so, it inserts user messages containing the actual tool results at the correct position (before the next assistant), preserving real execution output rather than dropping it.

This handles two scenarios:

1. Session restoration from file: the process crashed while a tool was still pending, so the session file contains an assistant message with tool_use but no tool_result (or tool_results placed after another assistant message).
2. Runtime interruption: the user interrupted (e.g. Ctrl+C) while the agent was about to execute tools, and the next user message starts a new agent run without the cancelled tool_results having been added.

Returns true if any messages were inserted or moved. Returns true if any cancelled tool_result entries were added.

func (*Manager) RecordUsage

func (m *Manager) RecordUsage(usage provider.TokenUsage)

func (*Manager) SetContextWindow

func (m *Manager) SetContextWindow(n int)

func (*Manager) SetOutputReserve

func (m *Manager) SetOutputReserve(n int)

func (*Manager) SetProvider

func (m *Manager) SetProvider(p provider.Provider)

SetProvider sets the provider for provider-aware token counting.

func (*Manager) SetTodoFilePath

func (m *Manager) SetTodoFilePath(path string)

func (*Manager) SetUsageHandler

func (m *Manager) SetUsageHandler(fn func(provider.TokenUsage))

func (*Manager) Summarize

func (m *Manager) Summarize(ctx context.Context, prov provider.Provider) error

Summarize compresses old messages into a summary while retaining an adaptive recent suffix sized to fit within the target token budget.

func (*Manager) TokenCount

func (m *Manager) TokenCount() int

func (*Manager) TruncateOldestGroupForRetry

func (m *Manager) TruncateOldestGroupForRetry() bool

func (*Manager) UpdateFirstSystemMessage

func (m *Manager) UpdateFirstSystemMessage(msg provider.Message)

UpdateFirstSystemMessage replaces the first system message in the context. If no system message exists, it prepends one.

func (*Manager) UsageRatio

func (m *Manager) UsageRatio() float64