compaction

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package compaction prepares and summarizes durable harness entries with an embedded retained tail.

Index

Constants

View Source
const SummarizationSystemPrompt = `` /* 310-byte string literal not displayed */

Ports packages/agent/src/harness/compaction/compaction.ts (summary request boundaries).

Variables

View Source
var DefaultCompactionSettings = CompactionSettings{Enabled: true, ReserveTokens: 16384, KeepRecentTokens: 20000}

Functions

func CalculateContextTokens

func CalculateContextTokens(usage ai.Usage) int

func CompleteSimpleWithRetries

func CompleteSimpleWithRetries(ctx context.Context, models Models, model *ai.Model, request ai.Context, options ai.StreamOptions, retry *ai.RetryPolicy, callbacks ai.RetryCallbacks) (*ai.AssistantMessage, error)

func ComputeFileLists

func ComputeFileLists(ops FileOperations) (readFiles, modifiedFiles []string)

func CreateSummaryRequestOptions

func CreateSummaryRequestOptions(options ai.StreamOptions) ai.StreamOptions

CreateSummaryRequestOptions isolates routing and disables cache writes for a standalone summary.

func EstimateTokens

func EstimateTokens(message agent.AgentMessage) int

EstimateTokens counts UTF-16 characters and fixed image estimates. Native system messages are not counted by the harness heuristic.

func ExtractFileOpsFromMessage

func ExtractFileOpsFromMessage(message agent.AgentMessage, ops *FileOperations)

func FindTurnStartIndex

func FindTurnStartIndex(entries []session.Entry, index, start int) int

func FormatFileOperations

func FormatFileOperations(readFiles, modifiedFiles []string) string

func GenerateSummary

func GenerateSummary(ctx context.Context, messages []agent.AgentMessage, models Models, model *ai.Model, reserve int, custom, previous string, thinking ai.ThinkingLevel, retry *ai.RetryPolicy, callbacks ai.RetryCallbacks) (string, error)

func GetLastAssistantUsage

func GetLastAssistantUsage(entries []session.Entry) *ai.Usage

func SerializeConversation

func SerializeConversation(messages []ai.Message) string

SerializeConversation renders message text rather than continuing the conversation. Tool result text is limited to 2,000 UTF-16 units.

func ShouldCompact

func ShouldCompact(tokens, window int, settings CompactionSettings) bool

Types

type BranchPreparation

type BranchPreparation struct {
	Messages    []agent.AgentMessage
	FileOps     FileOperations
	TotalTokens int
}

BranchPreparation is the content selected for branch summarization.

func PrepareBranchEntries

func PrepareBranchEntries(entries []session.Entry, tokenBudget int) BranchPreparation

PrepareBranchEntries selects the newest content within a token budget, preserving summary priority and cumulative file operations. Zero means no budget.

type BranchSummaryDetails

type BranchSummaryDetails struct {
	ReadFiles     []string `json:"readFiles"`
	ModifiedFiles []string `json:"modifiedFiles"`
}

BranchSummaryDetails tracks the files mentioned in a branch summary.

type BranchSummaryResult

type BranchSummaryResult struct {
	Summary       string    `json:"summary"`
	Usage         *ai.Usage `json:"usage,omitempty"`
	ReadFiles     []string  `json:"readFiles"`
	ModifiedFiles []string  `json:"modifiedFiles"`
}

BranchSummaryResult is generated branch content ready for a durable summary entry.

func GenerateBranchSummary

func GenerateBranchSummary(ctx context.Context, entries []session.Entry, options GenerateBranchSummaryOptions) (BranchSummaryResult, error)

GenerateBranchSummary prepares abandoned entries and generates their summary through the provider collection.

func GenerateBranchSummaryWithRequest

func GenerateBranchSummaryWithRequest(ctx context.Context, preparation BranchPreparation, options PreparedBranchSummaryOptions, request SummaryRequest) (BranchSummaryResult, error)

GenerateBranchSummaryWithRequest awaits one caller-owned request and preserves coded response errors without swallowing request failures.

type CollectEntriesResult

type CollectEntriesResult struct {
	Entries          []session.Entry
	CommonAncestorID *string
}

CollectEntriesResult identifies the abandoned path and its deepest common ancestor.

func CollectEntriesForBranchSummary

func CollectEntriesForBranchSummary(ctx context.Context, branch session.Branch, opened session.Session, oldTipID *string, targetID string) (CollectEntriesResult, error)

CollectEntriesForBranchSummary collects the abandoned path in chronological order.

type CompactGenerationOptions

type CompactGenerationOptions struct {
	Model              *ai.Model
	CustomInstructions string
	ThinkingLevel      ai.ThinkingLevel
}

type CompactResult

type CompactResult struct {
	Summary      string               `json:"summary"`
	TokensBefore int                  `json:"tokensBefore"`
	Usage        *ai.Usage            `json:"usage,omitempty"`
	RetainedTail []agent.AgentMessage `json:"retainedTail"`
	Details      harness.JsonValue    `json:"details,omitempty"`
}

func Compact

func Compact(ctx context.Context, preparation CompactionPreparation, models Models, model *ai.Model, custom string, thinking ai.ThinkingLevel, retry *ai.RetryPolicy, callbacks ai.RetryCallbacks) (CompactResult, error)

func CompactWithRequest

func CompactWithRequest(ctx context.Context, p CompactionPreparation, options CompactGenerationOptions, request SummaryRequest) (CompactResult, error)

CompactWithRequest generates history and optional turn-prefix summaries in order, then retains the prepared tail verbatim.

type CompactionDetails

type CompactionDetails struct {
	ReadFiles     []string `json:"readFiles"`
	ModifiedFiles []string `json:"modifiedFiles"`
}

type CompactionPreparation

type CompactionPreparation struct {
	MessagesToSummarize []agent.AgentMessage `json:"messagesToSummarize"`
	TurnPrefixMessages  []agent.AgentMessage `json:"turnPrefixMessages"`
	RetainedTail        []agent.AgentMessage `json:"retainedTail"`
	IsSplitTurn         bool                 `json:"isSplitTurn"`
	TokensBefore        int                  `json:"tokensBefore"`
	PreviousSummary     string               `json:"previousSummary,omitempty"`
	// PreviousSummaryPresent retains an empty prior compaction summary when building durable preparation.
	PreviousSummaryPresent bool               `json:"-"`
	FileOps                FileOperations     `json:"fileOps"`
	Settings               CompactionSettings `json:"settings"`
}

func PrepareCompaction

func PrepareCompaction(entries []session.Entry, settings CompactionSettings) (*CompactionPreparation, error)

PrepareCompaction expands the latest embedded tail before finding a new cut point. Older summaries are carried as previousSummary rather than summarized again.

type CompactionSettings

type CompactionSettings = harness.CompactionSettings

Ports packages/agent/src/harness/compaction/compaction.ts.

type ContextUsageEstimate

type ContextUsageEstimate struct {
	Tokens         int  `json:"tokens"`
	UsageTokens    int  `json:"usageTokens"`
	TrailingTokens int  `json:"trailingTokens"`
	LastUsageIndex *int `json:"lastUsageIndex"`
}

func EstimateContextTokens

func EstimateContextTokens(messages []agent.AgentMessage) ContextUsageEstimate

type CutPointResult

type CutPointResult struct {
	FirstKeptEntryIndex int  `json:"firstKeptEntryIndex"`
	TurnStartIndex      int  `json:"turnStartIndex"`
	IsSplitTurn         bool `json:"isSplitTurn"`
}

func FindCutPoint

func FindCutPoint(entries []session.Entry, start, end, keep int) CutPointResult

type FileOperations

type FileOperations struct {
	Read    map[string]struct{}
	Written map[string]struct{}
	Edited  map[string]struct{}
	// contains filtered or unexported fields
}

Ports packages/agent/src/harness/compaction/utils.ts.

func CreateFileOps

func CreateFileOps() FileOperations

func (*FileOperations) AddEdited

func (ops *FileOperations) AddEdited(path string)

AddEdited records an edited path in first-observation order.

func (*FileOperations) AddRead

func (ops *FileOperations) AddRead(path string)

AddRead records a read path in first-observation order.

func (*FileOperations) AddWritten

func (ops *FileOperations) AddWritten(path string)

AddWritten records a written path in first-observation order.

func (FileOperations) MarshalJSON

func (ops FileOperations) MarshalJSON() ([]byte, error)

func (FileOperations) Paths

func (ops FileOperations) Paths() (read, written, edited []string)

Paths returns the three insertion-ordered sets as independent slices.

type GenerateBranchSummaryOptions

type GenerateBranchSummaryOptions struct {
	PreparedBranchSummaryOptions
	Models        Models
	Model         *ai.Model
	ReserveTokens *int
	Retry         *ai.RetryPolicy
	Callbacks     ai.RetryCallbacks
}

GenerateBranchSummaryOptions bind a provider collection and retry policy to branch summarization.

type Models

type Models interface {
	CompleteSimple(context.Context, *ai.Model, ai.Context, ai.StreamOptions) *ai.AssistantMessage
}

Models is the single provider operation used by standalone compaction helpers.

type PreparedBranchSummaryOptions

type PreparedBranchSummaryOptions struct {
	CustomInstructions  string
	ReplaceInstructions bool
}

PreparedBranchSummaryOptions control the summarization instructions.

type SummaryGenerationOptions

type SummaryGenerationOptions struct {
	Model                               *ai.Model
	ReserveTokens                       int
	CustomInstructions, PreviousSummary string
	ThinkingLevel                       ai.ThinkingLevel
}

type SummaryRequest

type SummaryRequest func(context.Context, ai.Context, ai.StreamOptions) (*ai.AssistantMessage, error)

SummaryRequest is a caller-owned, awaited provider-request boundary. The context carries cancellation and harness telemetry.

type SummaryResult

type SummaryResult struct {
	Text  string
	Usage ai.Usage
}

func GenerateSummaryWithRequest

func GenerateSummaryWithRequest(ctx context.Context, messages []agent.AgentMessage, options SummaryGenerationOptions, request SummaryRequest) (SummaryResult, error)

GenerateSummaryWithRequest preserves coded failed/aborted responses and propagates request errors without converting them into response failures.

func GenerateSummaryWithUsage

func GenerateSummaryWithUsage(ctx context.Context, messages []agent.AgentMessage, models Models, model *ai.Model, reserve int, custom, previous string, thinking ai.ThinkingLevel, retry *ai.RetryPolicy, callbacks ai.RetryCallbacks) (SummaryResult, error)

Jump to

Keyboard shortcuts

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