compaction

package
v0.1.6 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package compaction owns bounded coding-session summary generation.

Index

Constants

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

View Source
const HistoryToolName = "session_history"

HistoryToolName is the restricted archive retrieval capability in seed hints.

Variables

View Source
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")
)
View Source
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

func ArchiveIDs(path []harness.Entry) []string

ArchiveIDs returns references on the selected branch, including old full checkpoints needed by historical navigation. Storage validates the IDs again.

func BuildSeed

func BuildSeed(summary string, anchor ai.Message, archiveID string) (ai.Messages, error)

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

func IsContextOverflow(err error) bool

IsContextOverflow only inspects provider errors. Tool output or arbitrary errors containing size-related words cannot trigger a request replay.

func RequestOverheadTokens

func RequestOverheadTokens(request ai.Request) (int, error)

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.

func SeedTokens

func SeedTokens(messages ai.Messages, fixed int) int

SeedTokens counts an already assembled checkpoint seed with current fixed overhead. It is an estimate, not request consumption or cumulative usage.

Types

type Input

type Input struct {
	Messages     ai.Messages
	Instructions string
	StateContext string
	SeedTokens   int
}

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.

func Capture

func Capture(value *harness.Session, fixedTokens *int, synthetic func(ai.Message) bool) (*Plan, error)

Capture binds raw history and visible messages atomically. The host supplies current fixed overhead when known, and classifies its own synthetic messages.

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

func (p Policy) ShouldCompact(tokens int) bool

ShouldCompact compares the current-context gauge, never cumulative usage.

func (Policy) Threshold

func (p Policy) Threshold() (int, error)

Threshold returns the earlier of the percentage and output-reserve limits.

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 Stage

type Stage string

Stage identifies the amount of detail supplied to the summary model.

const (
	StageFaithful Stage = "faithful"
	StageFitted   Stage = "fitted"
	StageLossy    Stage = "lossy"
)

Stages progressively reduce the detail of oversized summary input.

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.

func (*Summarizer) Summarize

func (s *Summarizer) Summarize(ctx context.Context, input Input) (Result, error)

Summarize returns a validated candidate without changing a session.

type SummaryError

type SummaryError struct {
	Stage    Stage
	Attempts int
	Cause    error
}

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

Jump to

Keyboard shortcuts

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