Documentation
¶
Overview ¶
Package compaction owns bounded coding-session summary generation.
Index ¶
- Constants
- Variables
- func ArchiveIDs(path []harness.Entry) []string
- func BuildSeed(summary string, anchor ai.Message, archiveID string) (ai.Messages, error)
- func GuardModel(model ai.LanguageModel, policy *Policy) ai.LanguageModel
- func IsContextOverflow(err error) bool
- func RequestOverheadTokens(request ai.Request) (int, error)
- func SeedTokens(messages ai.Messages, fixed int) int
- type Input
- type Outcome
- type Plan
- type Policy
- type Result
- type Stage
- type Summarizer
- type SummaryError
Constants ¶
const ( DefaultThresholdPercent = 85 DefaultMinSummaryChars = 500 DefaultAttemptsPerStage = 3 DefaultRetryDelay = 3 * time.Second DefaultTimeout = 300 * time.Second )
Defaults bound the trigger, summary quality, retry count and wall-clock time.
const HistoryToolName = "session_history"
HistoryToolName is the restricted archive retrieval capability in seed hints.
Variables ¶
var ( // ErrInvalid identifies malformed input or an invalid policy. ErrInvalid = errors.New("coding compaction: invalid input or policy") // ErrBudget identifies a request or replacement that cannot fit its budget. ErrBudget = errors.New("coding compaction: context budget exhausted") // ErrPending prevents replacing history with unresolved tool calls. ErrPending = errors.New("coding compaction: unresolved tool calls") // ErrSummary identifies unusable summary content. ErrSummary = errors.New("coding compaction: unusable summary") )
var ErrNoReduction = errors.New("coding compaction: replacement does not reduce context below the threshold")
ErrNoReduction prevents a checkpoint that would not create useful headroom.
Functions ¶
func ArchiveIDs ¶
ArchiveIDs returns references on the selected branch, including old full checkpoints needed by historical navigation. Storage validates the IDs again.
func BuildSeed ¶
BuildSeed keeps the historical summary separate from the latest genuine user request. Runtime-owned instructions and control state are never persisted as system messages inside a checkpoint.
func GuardModel ¶
func GuardModel(model ai.LanguageModel, policy *Policy) ai.LanguageModel
GuardModel rejects an already prepared normal request that exceeds its known hard budget. It neither compacts during an open turn nor retries a request.
func IsContextOverflow ¶
IsContextOverflow only inspects provider errors. Tool output or arbitrary errors containing size-related words cannot trigger a request replay.
func RequestOverheadTokens ¶
RequestOverheadTokens estimates only current system instructions and tool declarations. A provider-reported request usage already includes this cost; callers must not add it twice to such a baseline.
Types ¶
type Input ¶
Input is a frozen view of the history and current constraints. SeedTokens is the fixed portion of the rebuilt normal context, excluding its new summary.
type Outcome ¶
type Outcome struct {
Result
CheckpointID string
ArchiveID string
TokensBefore int
TokensAfter int
Committed bool
PublicationUncertain bool
}
Outcome separates logical publication from failures during later cleanup. PublicationUncertain requires the owner to stop rather than retry appends.
func Execute ¶
func Execute( ctx context.Context, repository *session.Repository, handle *session.Handle, model ai.LanguageModel, apply func(*ai.Request), plan *Plan, policy Policy, instructions, stateContext string, ) (out Outcome, err error)
Execute performs the archive-before-checkpoint publication sequence. It does not mutate application Plan/Goal/permission state or emit frontend events.
type Plan ¶
type Plan struct {
Snapshot harness.SessionContextSnapshot
Anchor ai.Message
FixedTokens int
TokensBefore int
// PendingTokens reserves room for incoming input not yet in the journal.
PendingTokens int
}
Plan is a detached snapshot. The owner must bind its preview to the source leaf and policy and retain its structural lease through Execute.
type Policy ¶
type Policy struct {
ContextWindow int
ReserveTokens int
ThresholdPercent int
MaxOutputTokens int
MinSummaryChars int
AttemptsPerStage int
RetryDelay time.Duration
Timeout time.Duration
}
Policy separates the context reserve from the optional summary output cap. A zero MaxOutputTokens inherits the resolved model request policy.
func (Policy) ShouldCompact ¶
ShouldCompact compares the current-context gauge, never cumulative usage.
type Result ¶
type Result struct {
Summary string
Stage Stage
Attempts int
Usage ai.Usage
FinishReason ai.FinishReason
Truncated bool
}
Result includes attempt usage separately from the main context's token gauge. It is also returned on failure so callers can report actual attempts.
type Summarizer ¶
type Summarizer struct {
// contains filtered or unexported fields
}
Summarizer produces candidates only. The session owner archives and commits a validated result under its structural lease and expected-leaf guard.
func NewSummarizer ¶
func NewSummarizer(model ai.LanguageModel, policy Policy, apply func(*ai.Request)) (*Summarizer, error)
NewSummarizer binds a model and bounded policy without performing model I/O.
type SummaryError ¶
SummaryError identifies a bounded attempt's outcome without rendering provider response bodies into user-facing status text. Unwrap retains the cause.
func (*SummaryError) Error ¶
func (e *SummaryError) Error() string
func (*SummaryError) Unwrap ¶
func (e *SummaryError) Unwrap() error