Documentation
¶
Overview ¶
Package compaction plans context compaction summaries and preserves file-operation hints.
Index ¶
- Constants
- Variables
- func AppendDeterministicState(summary string, files []FileOperation, validations []ValidationRecord, ...) string
- func AppendFileOperationsSummary(summary string, operations []FileOperation) string
- func BranchTokens(branch []database.EntryEntity, countTokens TokenCounter) int
- func NothingToDoError(message string) error
- func RepairPrompt() string
- func StripDeterministicState(summary string) string
- func StripFileOperationsSummary(summary string) string
- func SystemPrompt(previousSummary, splitTurnSummary string) string
- func ValidateCheckpoint(text string) error
- type ActiveWorkRecord
- type CheckpointStructureError
- type Chunk
- type FileOperation
- type Operation
- type Plan
- type Reason
- type RetryIntent
- type SemanticGroup
- type SemanticGroupKind
- type SummaryError
- type SummaryOutcome
- type TokenCounter
- type ValidationOutcome
- type ValidationRecord
Constants ¶
const ( // MaxValidationRecords bounds validation records retained in a checkpoint. MaxValidationRecords = 32 // MaxActiveWorkRecords bounds active work records retained in a checkpoint. MaxActiveWorkRecords = 32 )
const ( // MaxChunksPerReductionRound bounds model calls in one reduction round. MaxChunksPerReductionRound = 32 // MaxReductionDepth bounds recursive summary reduction rounds. MaxReductionDepth = 4 )
const (
// FileOperationsKey is the details key used for preserved file-operation metadata.
FileOperationsKey = "file_operations"
)
Variables ¶
var ( // ErrSummaryInputOverflow indicates that summary input exceeds its budget. ErrSummaryInputOverflow = errors.New("summary input overflow") // ErrSummaryOutputTruncated indicates that the provider truncated summary output. ErrSummaryOutputTruncated = errors.New("summary output truncated") // ErrSummaryEmpty indicates that the provider returned an empty summary. ErrSummaryEmpty = errors.New("compaction summary was empty") // ErrSummaryContentFilter indicates that provider policy filtered the summary. ErrSummaryContentFilter = errors.New("compaction summary was content filtered") // ErrSummaryRefusal indicates that the model refused to produce the summary. ErrSummaryRefusal = errors.New("compaction summary was refused") // ErrSummaryProviderFailure indicates that generation ended without a usable summary. ErrSummaryProviderFailure = errors.New("compaction summary provider failure") // ErrSummaryAborted indicates that summary generation was canceled or aborted. ErrSummaryAborted = errors.New("compaction summary was aborted") // ErrSummaryReductionNoProgress indicates that reduction did not shrink the input. ErrSummaryReductionNoProgress = errors.New("summary reduction made no progress") // ErrSummaryFixedOverhead indicates that fixed prompt content exceeds the input budget. ErrSummaryFixedOverhead = errors.New("summary fixed overhead exceeds budget") // ErrSummaryIndivisibleGroup indicates that one semantic group exceeds the input budget. ErrSummaryIndivisibleGroup = errors.New("summary semantic group exceeds budget") )
var ErrCheckpointStructure = errors.New("invalid checkpoint structure")
ErrCheckpointStructure identifies an invalid generated checkpoint structure.
Functions ¶
func AppendDeterministicState ¶
func AppendDeterministicState( summary string, files []FileOperation, validations []ValidationRecord, work []ActiveWorkRecord, ) string
AppendDeterministicState is the sole appendix writer.
func AppendFileOperationsSummary ¶
func AppendFileOperationsSummary(summary string, operations []FileOperation) string
AppendFileOperationsSummary replaces stale operation text and appends current operations.
func BranchTokens ¶
func BranchTokens(branch []database.EntryEntity, countTokens TokenCounter) int
BranchTokens returns the estimated model-facing token count for the effective branch.
func NothingToDoError ¶
NothingToDoError returns the no-op compaction error used by planner callers.
func RepairPrompt ¶
func RepairPrompt() string
RepairPrompt asks for a single structural repair without authorizing new facts.
func StripDeterministicState ¶
StripDeterministicState removes deterministic appendices from a generated summary.
func StripFileOperationsSummary ¶
StripFileOperationsSummary removes the generated file-operation section from summary text.
func SystemPrompt ¶
SystemPrompt builds the summary prompt used for compaction provider requests.
func ValidateCheckpoint ¶
ValidateCheckpoint validates only the stable structure, never model prose.
Types ¶
type ActiveWorkRecord ¶
type ActiveWorkRecord struct {
EntryID string `json:"entry_id"`
ID string `json:"id"`
Kind string `json:"kind"`
State string `json:"state"`
OwningSession string `json:"owning_session,omitempty"`
}
ActiveWorkRecord describes a durable task that may still require attention.
func CollectActiveWorkRecords ¶
func CollectActiveWorkRecords(entries []database.EntryEntity) []ActiveWorkRecord
CollectActiveWorkRecords reads bounded typed task references from durable details.
type CheckpointStructureError ¶
CheckpointStructureError reports format defects without retaining summary text.
func (*CheckpointStructureError) Error ¶
func (err *CheckpointStructureError) Error() string
func (*CheckpointStructureError) Unwrap ¶
func (err *CheckpointStructureError) Unwrap() error
type Chunk ¶
type Chunk struct {
Groups []SemanticGroup
Messages []database.MessageEntity
Tokens int
}
Chunk is a deterministic, protocol-safe summary request unit.
type FileOperation ¶
type FileOperation struct {
EntryID string `json:"entry_id,omitempty"`
Action string `json:"action"`
Path string `json:"path"`
Tool string `json:"tool,omitempty"`
Command string `json:"command,omitempty"`
}
FileOperation records file activity that should survive compaction summaries.
func CollectFileOperations ¶
func CollectFileOperations(entries []database.EntryEntity) []FileOperation
CollectFileOperations extracts bounded, de-duplicated file operations from compacted entries.
type Operation ¶
type Operation struct {
ID string
Reason Reason
RetryIntent RetryIntent
}
Operation is immutable identity and policy for one logical compaction.
type Plan ¶
type Plan struct {
FirstKeptEntryID string
Messages []database.MessageEntity
PreviousSummary string
SplitTurnSummary string
SummarizedEntryIDs []string
KeptEntryIDs []string
FileOperations []FileOperation
ValidationRecords []ValidationRecord
ActiveWorkRecords []ActiveWorkRecord
SummaryGroups []SemanticGroup
TokensBefore int
FirstKeptEntryIndex int
}
Plan describes the history range selected for compaction and the retained tail.
func PlanBranch ¶
func PlanBranch( branch []database.EntryEntity, recentTailTokens int, countTokens TokenCounter, ) (Plan, error)
PlanBranch selects model-facing branch history for compaction while preserving a recent tail.
func PlanBranchFromFirstKept ¶
func PlanBranchFromFirstKept( branch []database.EntryEntity, firstKeptEntryID string, countTokens TokenCounter, ) (Plan, error)
PlanBranchFromFirstKept builds a compaction plan using an extension-selected retained tail.
type Reason ¶
type Reason string
Reason identifies why one logical compaction operation ran.
const ( // ReasonManual identifies user-requested compaction. ReasonManual Reason = "manual" // ReasonPreRequest identifies automatic compaction before a request. ReasonPreRequest Reason = "pre_request" // ReasonPostResponse identifies automatic compaction after a response. ReasonPostResponse Reason = "post_response" // ReasonProviderOverflow identifies recovery from provider context overflow. ReasonProviderOverflow Reason = "provider_overflow" )
type RetryIntent ¶
type RetryIntent string
RetryIntent describes whether a successful compaction is followed by a replacement request.
const ( // RetryNone indicates that compaction is not followed by a replacement request. RetryNone RetryIntent = "none" // RetryAfterCompaction requests a replacement model request after compaction. RetryAfterCompaction RetryIntent = "retry_after_compaction" )
func (RetryIntent) Validate ¶
func (intent RetryIntent) Validate() error
Validate rejects unknown retry intent values.
type SemanticGroup ¶
type SemanticGroup struct {
Kind SemanticGroupKind
EntryIDs []string
Messages []database.MessageEntity
Tokens int
}
SemanticGroup keeps a durable turn, including all tool results, intact.
func GroupsFromMessages ¶
func GroupsFromMessages(messages []database.MessageEntity, entryIDs []string) []SemanticGroup
GroupsFromMessages groups model-facing history at user/custom/bash turn boundaries. Tokens use the same complete-message estimator as summary request preflight.
type SemanticGroupKind ¶
type SemanticGroupKind string
SemanticGroupKind identifies an indivisible summary input unit.
const ( // SemanticGroupHistoryTurn identifies an original conversation turn. SemanticGroupHistoryTurn SemanticGroupKind = "history_turn" // SemanticGroupReduction identifies a prior reduction result. SemanticGroupReduction SemanticGroupKind = "reduction" )
type SummaryError ¶
type SummaryError struct {
Kind error
Cause error
Provider string
Model string
Reason Reason
Input int
Limit int
Before int
After int
}
SummaryError provides safe, typed summary failure context.
func (*SummaryError) Error ¶
func (summaryError *SummaryError) Error() string
func (*SummaryError) Unwrap ¶
func (summaryError *SummaryError) Unwrap() []error
Unwrap exposes both the stable category and an optional underlying cause.
type SummaryOutcome ¶
type SummaryOutcome struct {
Text string
Provider string
Model string
Reason Reason
FinishReason llm.FinishReason
EstimatedInputTokens int
ReportedInputTokens int
ReportedOutputTokens int
OutputLimit int
Truncated bool
}
SummaryOutcome records bounded summary generation without retaining prompt content.
type ValidationOutcome ¶
type ValidationOutcome string
ValidationOutcome describes the durable result of a validation command.
const ( // ValidationPassed indicates a successful validation command. ValidationPassed ValidationOutcome = "passed" // ValidationFailed indicates an unsuccessful validation command. ValidationFailed ValidationOutcome = "failed" // ValidationCanceled indicates a canceled validation command. ValidationCanceled ValidationOutcome = "canceled" // ValidationUnknown indicates a validation command without a recognized result. ValidationUnknown ValidationOutcome = "unknown" )
type ValidationRecord ¶
type ValidationRecord struct {
EntryID string `json:"entry_id"`
Command string `json:"command"`
Outcome ValidationOutcome `json:"outcome"`
}
ValidationRecord associates an exact validation command with its durable outcome.
func CollectValidationRecords ¶
func CollectValidationRecords(entries []database.EntryEntity) []ValidationRecord
CollectValidationRecords extracts exact bash commands and durable outcomes, retaining the latest outcome for each exact command.
Source Files