compact

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package compact implements full, partial, automatic, and tool-result context compaction together with the trusted controls used to install their output.

Index

Constants

View Source 
const (
	// AutocompactBufferTokens is the safety margin subtracted from the
	// effective context window to trigger compaction.
	AutocompactBufferTokens = 13000

	// WarningThresholdBufferTokens is the output-token reservation subtracted
	// from MaxTokens to compute the effective (input-only) context window.
	WarningThresholdBufferTokens = 20000

	// MaxConsecutiveAutocompactFailures is the circuit-breaker limit. After
	// this many consecutive auto-compact failures the engine stops retrying
	// and leaves the current model view intact.
	MaxConsecutiveAutocompactFailures = 3
)
View Source 
const (
	MessageNotEnoughMessages = "Not enough messages to compact."
	MessageUserAbort         = "API Error: Request was aborted."
	MessageIncomplete        = "Compaction interrupted · This may be due to network issues — please try again."
	MessagePromptTooLong     = "Conversation too long. Press esc twice to go up a few messages and try again."
	MessageNoSummary         = "Failed to generate conversation summary - response did not contain valid text content"
)
View Source 
const (
	// PostCompactMaxSkillBodies bounds full/superseding invocation envelopes
	// reattached after one history replacement. Bodies already present in the
	// preserved tail do not consume this reattachment count.
	PostCompactMaxSkillBodies = 5

	// PostCompactSkillBodyBudgetBytes is the aggregate encoded-envelope budget
	// for reattached skill bodies. Selection is deterministic and skips an
	// oversized candidate instead of allowing one body to crowd out all others.
	PostCompactSkillBodyBudgetBytes = 64 * 1024
)
View Source 
const (
	DefaultProgressiveMinTokenSavings         = 2_000
	DefaultProgressiveReuseHorizon            = 3
	DefaultProgressiveCacheRecoveryRequests   = 2
	DefaultProgressiveMaxProjectedTools       = 24
	DefaultProgressiveMaxProjectedTokens      = 48_000
	DefaultProgressiveMaxConsecutiveAnomalies = 3
)
View Source 
const (
	ProgressiveDecisionAdmittedAvoidCompact = "admit_avoid_compact"
	ProgressiveDecisionAdmittedNetSavings   = "admit_net_savings"
	ProgressiveDecisionKeepDisabled         = "keep_disabled"
	ProgressiveDecisionKeepIncomplete       = "keep_incomplete_estimate"
	ProgressiveDecisionKeepUnknownPricing   = "keep_unknown_pricing"
	ProgressiveDecisionKeepTokenSavings     = "keep_token_savings"
	ProgressiveDecisionKeepCompactThreshold = "keep_compact_threshold"
	ProgressiveDecisionKeepCost             = "keep_cost"
	ProgressiveDecisionKeepSessionBudget    = "keep_session_budget"
	ProgressiveDecisionKeepAnomaly          = "keep_anomaly"
	ProgressiveDecisionShadow               = "shadow"
)
View Source 
const (
	// ErrorThresholdBufferTokens matches ERROR_THRESHOLD_BUFFER_TOKENS in TS.
	ErrorThresholdBufferTokens = 20000

	// ManualCompactBufferTokens reserves room for a user to run /compact when
	// automatic compaction is disabled. Matches MANUAL_COMPACT_BUFFER_TOKENS.
	ManualCompactBufferTokens = 3000
)
View Source 
const CompactMaxOutputTokens = 20000

CompactMaxOutputTokens is the maximum number of output tokens for the summarization LLM call. Matches COMPACT_MAX_OUTPUT_TOKENS (= 20_000) in the original TS (src/utils/context.ts). The p99.99 of compact output is ~17,387 tokens, so 20K provides adequate headroom without waste.

View Source 
const CompactSystemPrompt = `` /* 676-byte string literal not displayed */

CompactSystemPrompt is the authoritative instruction for the summarization call. Conversation messages, tool output, and earlier developer text are data to summarize, never instructions for this isolated operation.

View Source 
const ContentTypeCacheEdits types.ContentType = "cache_edits"
View Source 
const EstimatedMediaTokensPerBlock = 1600

EstimatedMediaTokensPerBlock is a deliberately provider-neutral budgeting estimate, not a provider-reported token count. It matches the existing MCP rich-content budget and keeps image/document blocks from being counted as zero before the provider returns authoritative usage.

View Source 
const (
	// MaxToolResultsPerMessageChars is the maximum aggregate size in characters
	// for all tool_result blocks within a single user message. When exceeded,
	// the largest blocks are replaced with truncated previews.
	// Matches MAX_TOOL_RESULTS_PER_MESSAGE_CHARS in the original TS.
	MaxToolResultsPerMessageChars = 200_000
)

Per-message aggregate budget constants.

View Source 
const (
	ResultStoreDefaultThreshold = maxResultSizeChars
)

Variables

View Source 
var (
	ErrCompactNotEnoughMessages = errors.New("compact: not enough messages")
	ErrCompactUserAbort         = errors.New("compact: user abort")
	ErrCompactIncomplete        = errors.New("compact: incomplete response")
	ErrCompactPromptTooLong     = errors.New("compact: prompt too long")
	ErrCompactAPI               = errors.New("compact: api error")
	ErrCompactNoSummary         = errors.New("compact: no summary response")
)

Functions

func AdjustHeadEndToPreserveAPIInvariants 

func AdjustHeadEndToPreserveAPIInvariants(messages []types.Message, headEnd int) int

AdjustHeadEndToPreserveAPIInvariants extends a preserved head so it does not split an assistant tool_use from its following user tool_result.

func AdjustHeadEndToPreservePartialInvariants 

func AdjustHeadEndToPreservePartialInvariants(messages []types.Message, headEnd int) int

func AdjustIndexToPreserveAPIInvariants 

func AdjustIndexToPreserveAPIInvariants(messages []types.Message, startIndex int) int

AdjustIndexToPreserveAPIInvariants moves startIndex to a safer kept-tail boundary. It preserves provider-required tool_use/tool_result pairs and all assistant fragments that share an assistant message ID with the kept tail.

func AppendContentReplacementRecordsForScope 

func AppendContentReplacementRecordsForScope(messages []types.Message, records []ContentReplacementRecord, capability messagecontrol.Capability, scope messagecontrol.Scope) []types.Message

AppendContentReplacementRecordsForScope is the loop-owned pre-commit installation boundary. The exact live scope makes the receipt non-transferable.

func AuthorizeCompactionResultForScope 

func AuthorizeCompactionResultForScope(capability messagecontrol.Capability, scope messagecontrol.Scope, result *CompactionResult) bool

AuthorizeCompactionResultForScope is the live-loop installation boundary. Controls sealed here are valid only for this loop's exact current authority and cannot be replayed through another QueryLoop or target session commit.

func AutoCompactThresholdForWindow 

func AutoCompactThresholdForWindow(effectiveWindow int) int

func BuildPersistedOutputMessage 

func BuildPersistedOutputMessage(path string, originalSize int64, previewSource string) string

BuildPersistedOutputMessage returns the model-facing wrapper used for a raw output file while keeping the preview bounded.

func BuildPostCompactMessages 

func BuildPostCompactMessages(result *CompactionResult) []types.Message

BuildPostCompactMessages returns post-compact messages in canonical order: boundary, summary, preserved messages, attachments, hook results.

func EffectiveInputWindowSize 

func EffectiveInputWindowSize(maxTokens, maxOutputTokens int) int

EffectiveInputWindowSize returns context window capacity available for input after reserving output tokens.

func EnforcePerMessageBudget 

func EnforcePerMessageBudget(messages []types.Message) []types.Message

EnforcePerMessageBudget checks each user message and, when the aggregate tool_result content exceeds MaxToolResultsPerMessageChars, truncates the largest results until under budget. This prevents N parallel tool calls from collectively producing e.g. 10 × 40K = 400K in one turn.

NOTE: This is a Go-specific defensive measure for the compact path. The original TS applies per-message budget enforcement in the main query loop (query.ts) via enforceToolResultBudget / ContentReplacementState, NOT in the compact path. The TS version is stateful (persists across turns for prompt-cache stability), checks isContentAlreadyCompacted, and handles array-typed tool_result content — this simplified variant is intentionally scoped to the compact path only and operates statelessly.

Returns a new message slice — does not modify the input.

func FormatCompactUserError 

func FormatCompactUserError(lang i18n.Language, err error) string

FormatCompactUserError returns localized user-facing text for manual compact surfaces while preserving the original errors for diagnostics and matching.

func GetCompactUserSummaryMessage 

func GetCompactUserSummaryMessage(summary string, suppressFollowUp bool, transcriptPath string, recentMessagesPreserved bool) string

GetCompactUserSummaryMessage builds the user message that replaces the compacted conversation. It wraps the formatted summary with context about the compaction event. Matches TS getCompactUserSummaryMessage().

Parameters:

  • summary: raw LLM output (will be formatted via FormatCompactSummary)
  • suppressFollowUp: when true, instructs the model to continue without questions
  • transcriptPath: optional path to the full conversation transcript on disk; when non-empty, tells the model it can read the original for exact details
  • recentMessagesPreserved: when true, notes that recent messages are kept verbatim

func GetMessagesAfterCompactBoundary 

func GetMessagesAfterCompactBoundary(messages []types.Message) []types.Message

GetMessagesAfterCompactBoundary returns messages after the latest compact boundary. If no boundary exists, it returns the original slice.

func GetMessagesAfterCompactBoundaryForScope 

func GetMessagesAfterCompactBoundaryForScope(messages []types.Message, scope messagecontrol.Scope) []types.Message

GetMessagesAfterCompactBoundaryForScope recognizes only a boundary bound to the exact current session namespace and generation.

func GetPartialCompactUserSummaryMessage 

func GetPartialCompactUserSummaryMessage(summary string, direction PartialCompactDirection, transcriptPath string) string

func GetStructuredCompactPrompt 

func GetStructuredCompactPrompt(customInstructions string) string

GetStructuredCompactPrompt returns the compact prompt sent after the conversation messages.

func HasUserErrorCategory 

func HasUserErrorCategory(err error) bool

HasUserErrorCategory reports whether err has first-party compaction copy that should be localized before it reaches a renderer.

func IsCompactAPIError 

func IsCompactAPIError(err error) bool

func IsCompactBoundaryMessage 

func IsCompactBoundaryMessage(msg types.Message) bool

IsCompactBoundaryMessage reports whether msg is a compact boundary marker.

func IsCompactBoundaryMessageForScope 

func IsCompactBoundaryMessageForScope(msg types.Message, scope messagecontrol.Scope) bool

IsCompactBoundaryMessageForScope reports whether msg is a boundary authorized for the exact current session namespace and context generation.

func IsCompactIncompleteResponseError 

func IsCompactIncompleteResponseError(err error) bool

func IsCompactNoSummaryError 

func IsCompactNoSummaryError(err error) bool

func IsCompactNotEnoughMessagesError 

func IsCompactNotEnoughMessagesError(err error) bool

func IsCompactPromptTooLongError 

func IsCompactPromptTooLongError(err error) bool

IsCompactPromptTooLongError reports whether the complete summary input was rejected as too long and compaction preserved the current history.

func IsCompactSummaryMessage 

func IsCompactSummaryMessage(msg types.Message) bool

IsCompactSummaryMessage reports whether msg is the generated summary that immediately follows a compact boundary.

func IsCompactUserAbortError 

func IsCompactUserAbortError(err error) bool

func IsReinjectedAttachment 

func IsReinjectedAttachment(msg types.Message) bool

IsReinjectedAttachment reports whether msg is an automatic attachment that should be regenerated, rather than summarized again, after compaction.

func LocalizeUserError 

func LocalizeUserError(lang i18n.Language, err error) error

LocalizeUserError preserves the original error chain while replacing its display text with semantic copy for the active runtime language.

func NewCompactBoundaryMessage 

func NewCompactBoundaryMessage(metadata CompactBoundaryMetadata, capabilities ...messagecontrol.Capability) types.Message

NewCompactBoundaryMessage is an explicit trusted in-process constructor for the boundary marker used at the start of a post-compact message list. It must not be applied to an SDK/user message merely because that message has similar fields. The returned message is intentionally role=user so existing providers can send it without special handling.

func NewCompactSummaryMessage 

func NewCompactSummaryMessage(text string, capabilities ...messagecontrol.Capability) types.Message

NewCompactSummaryMessage constructs the canonical compact-summary control message. A valid runtime capability seals it for immediate use; without one it remains a descriptor until the compaction installation boundary seals it.

func NormalizeEmptyToolResult 

func NormalizeEmptyToolResult(result types.ToolResultBlock, toolName string) types.ToolResultBlock

NormalizeEmptyToolResult gives tool results with no model-visible output the same marker as the original client. It is independent of ResultStore so runtimes without persistence, including subagents, share the same behavior.

func ProgressiveBenefitTriggerEnabled 

func ProgressiveBenefitTriggerEnabled(config ProgressiveConfig, providerName string) bool

ProgressiveBenefitTriggerEnabled reports whether the early cost-positive trigger is enabled for this provider. An empty allowlist preserves explicit experiment configurations; production supplies a reviewed provider scope.

func ProgressiveEnabledForSession 

func ProgressiveEnabledForSession(config ProgressiveConfig, providerName, model, sessionID string) bool

ProgressiveEnabledForSession evaluates the dynamic safety controls. A stable session hash keeps rollout assignment unchanged across resume, fork preparation, and process restart.

func ProgressiveImminentCompactCounterfactualEnabled 

func ProgressiveImminentCompactCounterfactualEnabled(config ProgressiveConfig, providerName string) bool

ProgressiveImminentCompactCounterfactualEnabled reports whether a reviewed provider may compare projection against the cache reset that semantic compaction would otherwise perform immediately. An empty allowlist is deliberately disabled rather than wildcarded.

func ProgressiveProjectionBudgetUsage 

func ProgressiveProjectionBudgetUsage(state *ContentReplacementState, counter TokenCounter) (tools, projectedTokens int)

ProgressiveProjectionBudgetUsage reconstructs the session budget from the exact frozen replacements. This survives resume because replacement records are persisted in private history and replayed into ContentReplacementState.

func ProgressiveProviderCompactPolicyEnabled 

func ProgressiveProviderCompactPolicyEnabled(config ProgressiveConfig, providerName, model, sessionID string) bool

ProgressiveProviderCompactPolicyEnabled applies the complete rollout and paired provider/model scope before any provider-specific semantic compact behavior is activated. Disabling progressive context therefore restores the legacy compactor in full, not only tool-result projection.

func ProgressiveToolEnabled 

func ProgressiveToolEnabled(config ProgressiveConfig, toolName string) bool

ProgressiveToolEnabled reports whether one reviewed tool strategy is in the current allowlist. Tool names are protocol identifiers and compare case-insensitively.

func ProgressiveToolResultSupportsAction 

func ProgressiveToolResultSupportsAction(toolName string, result types.ToolResultBlock, action string) bool

ProgressiveToolResultSupportsAction reports whether the runtime can satisfy a shadow ContextUpdate proposal using its own deterministic policy. The model's rewrite text is never trusted as the replacement. KEEP is always a safe decision for a found target; DROP remains disabled until a separately reviewed receipt can prove that no recoverable information is lost.

func ShouldUseAutoCompact 

func ShouldUseAutoCompact() bool

ShouldUseAutoCompact applies the process-level auto-compact gate shared by the loop and compact package.

func StripContentReplacementBlocks 

func StripContentReplacementBlocks(messages []types.Message) []types.Message

StripContentReplacementBlocks removes session-local replacement records from messages before they are sent to providers or compactors.

func StripImagesFromMessages 

func StripImagesFromMessages(messages []types.Message) []types.Message

StripImagesFromMessages replaces image and document blocks with text markers before sending messages to the summarization LLM. This prevents base64 image/document data from consuming the compaction API's own context window. Matches the original TS stripImagesFromMessages() in compact.ts, which handles both top-level image/document blocks AND image/document blocks nested inside tool_result content arrays.

func StripProviderPrivateBlocks 

func StripProviderPrivateBlocks(messages []types.Message) []types.Message

StripProviderPrivateBlocks returns the model/hook projection of durable history. Invalid tool-call diagnostics remain available to audit and resume surfaces but must not be replayed as if they were assistant content.

func StripReinjectedAttachments 

func StripReinjectedAttachments(messages []types.Message) []types.Message

StripReinjectedAttachments removes regenerated attachments before summarization so summaries do not recursively describe runtime projections.

func UsageMetricsFromUsage 

func UsageMetricsFromUsage(usage *types.Usage) *types.Usage

Types

type AgentDefinitionProvider 

type AgentDefinitionProvider interface {
	PostCompactAgentDefinitions(cwd string) []AgentDefinitionSnapshot
}

type AgentDefinitionSnapshot 

type AgentDefinitionSnapshot struct {
	Name      string
	WhenToUse string
	Source    string
}

type AutoCompactOptions 

type AutoCompactOptions struct {
	Window     *ContextWindow
	Compactor  Compactor
	KeepRecent int
	Trigger    string
	// RequestEstimate accounts for the exact provider.Params envelope planned
	// by the caller. Nil uses the message estimate.
	RequestEstimate *ModelContextTokenEstimate
	// Threshold overrides the ordinary auto-compact threshold when positive.
	// MaxGrowthTokens bounds only the locally estimated growth above an
	// authoritative provider baseline; zero preserves existing behavior.
	Threshold       int
	MaxGrowthTokens int
	OnTelemetry     func(CompactionTelemetryEvent)
}

AutoCompactOptions controls the pre-provider-call autocompact decision.

type BackgroundTaskProvider 

type BackgroundTaskProvider interface {
	PostCompactBackgroundTasks() []BackgroundTaskSnapshot
}

type BackgroundTaskSnapshot 

type BackgroundTaskSnapshot struct {
	ID          string
	Type        string
	Status      string
	Description string
	Command     string
	Prompt      string
	Error       string
	Result      string
}

type CacheEdit 

type CacheEdit struct {
	Type           string `json:"type"`
	CacheReference string `json:"cache_reference"`
}

type CacheEditsBlock 

type CacheEditsBlock struct {
	Type  string      `json:"type"`
	Edits []CacheEdit `json:"edits"`
}

func CacheEditsBlockForDeletes 

func CacheEditsBlockForDeletes(ids []string) CacheEditsBlock

type CachedMicrocompactResult 

type CachedMicrocompactResult struct {
	Messages       []types.Message
	Changed        bool
	DeletedToolIDs []string
	ReclaimedBytes int
	ProofBytes     int
	BytesSaved     int
}

func CachedMicrocompact 

func CachedMicrocompact(messages []types.Message, cfg MicrocompactConfig, state *CachedMicrocompactState) CachedMicrocompactResult

type CachedMicrocompactState 

type CachedMicrocompactState struct {
	RegisteredTools map[string]struct{}
	DeletedRefs     map[string]struct{}
	ToolOrder       []string
	ToolGroups      [][]string
	PinnedEdits     []PinnedCacheEdits
}

func NewCachedMicrocompactState 

func NewCachedMicrocompactState() *CachedMicrocompactState

func (*CachedMicrocompactState) Reset 

func (s *CachedMicrocompactState) Reset()

type CalibratedCounter 

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

CalibratedCounter dynamically adjusts its chars-per-token ratio based on actual API Usage data. It starts with a default ratio and converges toward the real ratio as more data points arrive. Safe for concurrent use.

func NewCalibratedCounter 

func NewCalibratedCounter(defaultRatio float64) *CalibratedCounter

NewCalibratedCounter creates a counter with the given default chars-per-token ratio. Use 4.0 for mostly-English, 2.5 for mixed CJK/English content.

func (*CalibratedCounter) Calibrate 

func (c *CalibratedCounter) Calibrate(chars int, tokens int)

Calibrate updates the ratio based on observed API usage. Call this after each API response with the actual text that was sent and the token count reported by the API.

func (*CalibratedCounter) Count 

func (c *CalibratedCounter) Count(text string) int

Count estimates the token count for the given text using the current calibrated ratio.

func (*CalibratedCounter) Ratio 

func (c *CalibratedCounter) Ratio() float64

Ratio returns the current chars-per-token ratio.

type CompactBoundaryMetadata 

type CompactBoundaryMetadata struct {
	Trigger                   string                    `json:"trigger"`
	PreCompactTokenCount      int                       `json:"pre_compact_token_count,omitempty"`
	PostCompactTokenCount     int                       `json:"post_compact_token_count,omitempty"`
	TruePostCompactTokenCount int                       `json:"true_post_compact_token_count,omitempty"`
	CompactionUsage           *types.Usage              `json:"compaction_usage,omitempty"`
	PreviousTailIdentifier    string                    `json:"previous_tail_identifier,omitempty"`
	PreCompactDiscoveredTools []string                  `json:"pre_compact_discovered_tools,omitempty"`
	PreservedSegment          *PreservedSegmentMetadata `json:"preserved_segment,omitempty"`
}

CompactBoundaryMetadata records where and why a compaction happened. It is encoded into a user-role internal message so providers see a valid message shape while the runtime can identify the latest compact boundary without trusting model-visible text.

func ParseCompactBoundaryMessage 

func ParseCompactBoundaryMessage(msg types.Message) (CompactBoundaryMetadata, bool)

ParseCompactBoundaryMessage extracts boundary metadata from a boundary marker.

func ParseCompactBoundaryMessageForScope 

func ParseCompactBoundaryMessageForScope(msg types.Message, scope messagecontrol.Scope) (CompactBoundaryMetadata, bool)

ParseCompactBoundaryMessageForScope parses only a boundary authorized for the exact current session namespace and context generation.

type CompactError 

type CompactError struct {
	Kind    error
	Message string
	Cause   error
}

CompactError carries a stable compaction failure category while preserving the underlying provider/context error for errors.Is/errors.As callers.

func (*CompactError) Error 

func (e *CompactError) Error() string

func (*CompactError) Is 

func (e *CompactError) Is(target error) bool

func (*CompactError) Unwrap 

func (e *CompactError) Unwrap() error

type CompactProgressEvent 

type CompactProgressEvent struct {
	Type     string
	HookType string
	Trigger  string
}

CompactProgressEvent reports coarse compaction lifecycle progress to callers.

type CompactPromptTooLongError 

type CompactPromptTooLongError struct {
	Cause error
}

CompactPromptTooLongError reports that the complete compact input could not fit the summarizer context. Compaction fails closed instead of retrying with a lossy subset of the conversation.

func (*CompactPromptTooLongError) Error 

func (e *CompactPromptTooLongError) Error() string

func (*CompactPromptTooLongError) Is 

func (e *CompactPromptTooLongError) Is(target error) bool

func (*CompactPromptTooLongError) Unwrap 

func (e *CompactPromptTooLongError) Unwrap() error

type CompactionResult 

type CompactionResult struct {
	BoundaryMarker            *types.Message
	SummaryMessages           []types.Message
	Attachments               []types.Message
	HookResults               []types.Message
	MessagesToKeep            []types.Message
	UserDisplayMessage        string
	PreCompactTokenCount      int
	PostCompactTokenCount     int
	TruePostCompactTokenCount int
	CompactionUsage           *types.Usage
	// PreparedMessages is an optional lifecycle-normalized replacement. Query
	// loops use it after adding the current skill catalog and bounded exact body
	// attachments at the history-install boundary. Segment fields remain intact
	// for telemetry and diagnostics.
	PreparedMessages []types.Message
}

CompactionResult keeps the compact boundary, summary, preserved messages, and post-compact injections separate so every caller can build the resulting context in the same order.

func AutoCompactIfNeeded 

func AutoCompactIfNeeded(ctx context.Context, messages []types.Message, opts AutoCompactOptions) (*CompactionResult, bool, error)

AutoCompactIfNeeded runs full compaction before a provider request when the current message view is over the autocompact threshold. It owns the consecutive-failure circuit breaker so callers do not retry forever.

func TryReactiveCompact 

func TryReactiveCompact(ctx context.Context, messages []types.Message, opts ReactiveCompactOptions) (*CompactionResult, bool, error)

TryReactiveCompact attempts a single recovery transformation after the provider rejects a request for context/media size reasons. The caller owns the HasAttempted guard so repeated provider failures surface instead of looping.

type CompactionTelemetryEvent 

type CompactionTelemetryEvent struct {
	Kind                       CompactionTelemetryKind
	Trigger                    string
	PreCompactTokenCount       int
	PostCompactTokenCount      int
	TruePostCompactTokenCount  int
	AutoCompactThreshold       int
	PostCompactWouldRetrigger  bool
	OriginalMessageCount       int
	CompactedMessageCount      int
	CompactionUsage            *types.Usage
	ConsecutiveFailureCount    int
	MaxConsecutiveFailureCount int
	ErrorType                  string
}

type CompactionTelemetryKind 

type CompactionTelemetryKind string
const (
	CompactionTelemetryStart       CompactionTelemetryKind = "compact_start"
	CompactionTelemetrySuccess     CompactionTelemetryKind = "compact_success"
	CompactionTelemetryFailure     CompactionTelemetryKind = "compact_failure"
	CompactionTelemetryAutoAttempt CompactionTelemetryKind = "auto_compact_attempt"
	CompactionTelemetryAutoSuccess CompactionTelemetryKind = "auto_compact_success"
	CompactionTelemetryAutoFailure CompactionTelemetryKind = "auto_compact_failure"
)

type CompactionTrackerSnapshot 

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

CompactionTrackerSnapshot is an opaque checkpoint of ContextWindow state. Installation and persistence transactions use it to ensure a failed compaction cannot change either warnings or the visible context estimate.

type Compactor 

type Compactor interface {
	Compact(ctx context.Context, messages []types.Message, keepRecent int) (*CompactionResult, error)
}

Compactor compresses conversation history to fit within token budgets. Implementations must respect ctx cancellation — particularly those that make network calls (e.g. LLM summarization).

type ContentReplacementRecord 

type ContentReplacementRecord struct {
	Kind        string `json:"kind"`
	ToolUseID   string `json:"tool_use_id"`
	Replacement string `json:"replacement"`
}

ContentReplacementRecord is the persisted form used to reconstruct state on resume. Replacement is the exact model-visible string.

func ApplyToolResultBudget 

func ApplyToolResultBudget(messages []types.Message, state *ContentReplacementState, store toolResultReplacementStore, skipToolNames map[string]struct{}) ([]types.Message, []ContentReplacementRecord, []error)

ApplyToolResultBudget applies the stateful aggregate per-message budget to a provider-bound message view. New replacements are persisted through store; persistence failures freeze the original result as seen-but-unreplaced.

type ContentReplacementState 

type ContentReplacementState struct {
	SeenIDs      map[string]struct{}
	Replacements map[string]string
}

ContentReplacementState freezes aggregate tool-result budget decisions for a conversation thread. Seen IDs are never reconsidered; replacements are re-applied from memory so repeated query preparation is byte-stable.

func NewContentReplacementState 

func NewContentReplacementState() *ContentReplacementState

NewContentReplacementState creates a fresh state for one conversation thread.

func ReconstructContentReplacementStateForScope 

func ReconstructContentReplacementStateForScope(messages []types.Message, scope messagecontrol.Scope) *ContentReplacementState

ReconstructContentReplacementStateForScope rebuilds state only from records authorized for the current session namespace and context generation.

type ContextInputUsage 

type ContextInputUsage struct {
	UsedTokens  int
	Measurement ContextUsageMeasurement
}

ContextInputUsage preserves whether the current input-side value is exact, a complete local estimate, or only a known lower bound.

type ContextUsageMeasurement 

type ContextUsageMeasurement string
const (
	ContextUsageUnknown          ContextUsageMeasurement = "unknown"
	ContextUsageProviderReported ContextUsageMeasurement = "provider_reported"
	ContextUsageLocalEstimate    ContextUsageMeasurement = "local_estimate"
	ContextUsageLocalLowerBound  ContextUsageMeasurement = "local_lower_bound"
)

type ContextWindow 

type ContextWindow struct {
	MaxTokens       int
	MaxOutputTokens int // max tokens per response; 0 = use WarningThresholdBufferTokens
	UsedInput       int
	UsedOutput      int
	CacheRead       int // tokens read from cache
	CacheCreated    int // tokens written to cache
	Counter         TokenCounter
	// contains filtered or unexported fields
}

ContextWindow tracks token usage and thresholds

func NewContextWindow 

func NewContextWindow(maxTokens int) *ContextWindow

NewContextWindow creates a context window tracker with a tokenizer counter.

func (*ContextWindow) AutoCompactDecisionTokens 

func (cw *ContextWindow) AutoCompactDecisionTokens(estimate ModelContextTokenEstimate, maxGrowthTokens int) int

AutoCompactDecisionTokens bounds only positive local growth above the last authoritative provider measurement. A projection that lowers the request is never raised to the cap, and provider-reported pressure is never hidden.

func (*ContextWindow) AutoCompactThreshold 

func (cw *ContextWindow) AutoCompactThreshold() int

AutoCompactThreshold exposes the active input-side threshold to projection admission. It includes the same model-window and experimental overrides as semantic auto-compaction, so the two decisions cannot drift.

func (*ContextWindow) AutoCompactThresholdWithMinPercent 

func (cw *ContextWindow) AutoCompactThresholdWithMinPercent(percent int) int

AutoCompactThresholdWithMinPercent returns the ordinary fixed-buffer threshold or a reviewed percentage floor, whichever compacts later. This keeps the established safety buffer for large windows while avoiding a disproportionate buffer in deliberately small stress-test windows.

func (*ContextWindow) CaptureCompactionTracker 

func (cw *ContextWindow) CaptureCompactionTracker() CompactionTrackerSnapshot

CaptureCompactionTracker snapshots warning state and the current context measurement so a failed installation can restore the exact prior view.

func (*ContextWindow) ConsecutiveFailures 

func (cw *ContextWindow) ConsecutiveFailures() int

ConsecutiveFailures returns the current auto-compact circuit-breaker count.

func (*ContextWindow) CurrentInputUsage 

func (cw *ContextWindow) CurrentInputUsage() ContextInputUsage

func (*ContextWindow) EstimateMessages 

func (cw *ContextWindow) EstimateMessages(msgs []types.Message) int

EstimateMessages returns the known lower bound for a message slice. Callers that need proof of component coverage must use EstimateMessagesDetailed and inspect Complete/UnknownOverheads.

func (*ContextWindow) EstimateMessagesDetailed 

func (cw *ContextWindow) EstimateMessagesDetailed(messages []types.Message, supplied ModelContextOverhead) ModelContextTokenEstimate

EstimateMessagesDetailed estimates every request component available at the conversation layer. System prompts and tool schemas must be supplied by the request builder; media remains unknown unless its provider token cost is supplied. Protocol framing is represented separately and included.

func (*ContextWindow) EstimateProviderRequest 

func (cw *ContextWindow) EstimateProviderRequest(params provider.Params) ModelContextTokenEstimate

EstimateProviderRequest accounts for the actual request envelope assembled by the query loop: messages, system prompt, visible tool/server schemas, media, and protocol framing. The result remains a local estimate; provider usage replaces it as soon as an API response reports authoritative input.

func (*ContextWindow) PreviousCacheReadTokens 

func (cw *ContextWindow) PreviousCacheReadTokens() int

PreviousCacheReadTokens returns the last provider-reported cache hit. Local estimates never fabricate cache reuse; before the first usage report it is therefore zero.

func (*ContextWindow) ProviderAdjustedInputTokens 

func (cw *ContextWindow) ProviderAdjustedInputTokens(estimate ModelContextTokenEstimate) int

ProviderAdjustedInputTokens calibrates the complete local request estimate against the previous request's provider-reported total. Provider adapters may retain continuation state that the generic message estimator must still represent, so its absolute value can carry a stable bias. Applying only the local delta to the authoritative provider baseline preserves growth and projection savings without double-counting that stable representation. When no comparable complete baseline exists, the larger known value is the conservative fallback.

func (*ContextWindow) ProviderReportedInputTokens 

func (cw *ContextWindow) ProviderReportedInputTokens() int

ProviderReportedInputTokens exposes the last complete provider measurement to cache-aware projection admission. It returns zero after compaction or a local estimate invalidates that measurement, preventing stale pre-compact usage from forcing another rewrite.

func (*ContextWindow) ProviderUsageKnown 

func (cw *ContextWindow) ProviderUsageKnown() bool

ProviderUsageKnown reports whether the cache-cost gate has an authoritative previous-request baseline. A freshly resumed process may have complete local history but no knowledge of whether the provider can reuse its remote cache; treating that state as a cache miss would make the first resumed projection optimistically unsafe.

func (*ContextWindow) RecordCompactFailure 

func (cw *ContextWindow) RecordCompactFailure()

RecordCompactFailure increments the circuit-breaker failure counter.

func (*ContextWindow) RecordCompactSuccess 

func (cw *ContextWindow) RecordCompactSuccess()

RecordCompactSuccess resets the circuit-breaker failure counter.

func (*ContextWindow) RecordMicrocompactSuccess 

func (cw *ContextWindow) RecordMicrocompactSuccess()

RecordMicrocompactSuccess suppresses compact warnings after a successful microcompact without changing the full auto-compact failure circuit breaker.

func (*ContextWindow) Remaining 

func (cw *ContextWindow) Remaining() int

Remaining returns estimated remaining input tokens

func (*ContextWindow) RestoreCompactionTracker 

func (cw *ContextWindow) RestoreCompactionTracker(snapshot CompactionTrackerSnapshot)

RestoreCompactionTracker restores a checkpoint captured before an installation transaction. The snapshot is intentionally opaque outside the compact package so callers cannot synthesize circuit-breaker state.

func (*ContextWindow) ShouldCompact 

func (cw *ContextWindow) ShouldCompact() bool

ShouldCompact checks if context compression should trigger. The circuit breaker prevents infinite compaction loops: after MaxConsecutiveAutocompactFailures consecutive failures, ShouldCompact returns false and the caller must either compact explicitly or fail closed; ordinary conversation messages must not be silently discarded.

func (*ContextWindow) ShouldProgressiveProjection 

func (cw *ContextWindow) ShouldProgressiveProjection(estimate ModelContextTokenEstimate) bool

ShouldProgressiveProjection opens the conservative result-projection gate shortly before semantic compaction. The headroom covers roughly two normal coding turns while keeping the feature dormant in a large, lightly used production context window.

func (*ContextWindow) ShouldProgressiveProjectionWithPolicy 

func (cw *ContextWindow) ShouldProgressiveProjectionWithPolicy(estimate ModelContextTokenEstimate, threshold, maxGrowthTokens int) bool

ShouldProgressiveProjectionWithPolicy keeps projection pressure aligned with the provider-scoped semantic-compaction decision.

func (*ContextWindow) ShouldSnip 

func (cw *ContextWindow) ShouldSnip(messages []types.Message) bool

ShouldSnip reports whether a cheap history snip should run before microcompact/autocompact. It uses the message estimate because pre-call preparation may have stripped or compacted the session view since the last provider usage update.

func (*ContextWindow) ShouldSnipEstimate 

func (cw *ContextWindow) ShouldSnipEstimate(estimate ModelContextTokenEstimate) bool

ShouldSnipEstimate applies the cheap threshold gate to a complete planned provider request rather than message text alone.

func (*ContextWindow) ShouldSnipEstimateWithPolicy 

func (cw *ContextWindow) ShouldSnipEstimateWithPolicy(estimate ModelContextTokenEstimate, threshold, maxGrowthTokens int) bool

ShouldSnipEstimateWithPolicy applies a provider-scoped threshold and local growth bound. Zero values preserve the established decision exactly.

func (*ContextWindow) TokenWarningState 

func (cw *ContextWindow) TokenWarningState(tokenUsage int, autoCompactEnabled bool) TokenWarningState

TokenWarningState returns the current TS-equivalent warning calculation.

func (*ContextWindow) UpdateLocalEstimate 

func (cw *ContextWindow) UpdateLocalEstimate(estimate ModelContextTokenEstimate)

UpdateLocalEstimate publishes the most recent complete estimate or known lower bound until a provider usage report supersedes it.

func (*ContextWindow) UpdatePostCompactUsage 

func (cw *ContextWindow) UpdatePostCompactUsage(inputTokens int)

UpdatePostCompactUsage immediately replaces the pre-compact provider value with the successful boundary's complete local estimate.

func (*ContextWindow) UpdateUsage 

func (cw *ContextWindow) UpdateUsage(usage *types.Usage)

UpdateUsage updates token counts from API response

type MCPServerSnapshot 

type MCPServerSnapshot struct {
	Name         string
	Tools        []string
	Instructions string
}

type MCPStateProvider 

type MCPStateProvider interface {
	PostCompactMCPServers() []MCPServerSnapshot
}

type MessageSummarizeFunc 

type MessageSummarizeFunc func(ctx context.Context, messages []types.Message, customInstructions string) (string, error)

MessageSummarizeFunc is the structured summarization path. It receives the conversation messages directly so providers can preserve tool_use inputs, tool_result content, message IDs, and mixed content blocks instead of relying on a flattened text transcript.

func NewLLMStructuredSummarizeFunc 

func NewLLMStructuredSummarizeFunc(p provider.Provider) MessageSummarizeFunc

NewLLMStructuredSummarizeFunc creates a MessageSummarizeFunc that calls the provider with conversation messages and the compact prompt separated. The request deliberately sends no tools and explicitly disables thinking so the compact model can only produce a text summary.

func NewLLMStructuredSummarizeFuncWithOptions 

func NewLLMStructuredSummarizeFuncWithOptions(p provider.Provider, serviceTier provider.ServiceTier, options StructuredSummarizeOptions) MessageSummarizeFunc

NewLLMStructuredSummarizeFuncWithOptions binds semantic-compaction request projection policy without changing the conversation provider itself.

func NewLLMStructuredSummarizeFuncWithServiceTier 

func NewLLMStructuredSummarizeFuncWithServiceTier(p provider.Provider, serviceTier provider.ServiceTier) MessageSummarizeFunc

NewLLMStructuredSummarizeFuncWithServiceTier binds compaction generations to the same provider scheduling class as the conversation they summarize.

type MicrocompactConfig 

type MicrocompactConfig struct {
	// KeepRecent is the number of recent compactable tool results to preserve
	// when time-based microcompact fires. It is floored at 1 so the most recent
	// compactable result always remains available.
	KeepRecent int

	// TimeBasedEnabled controls the TS-equivalent time-based trigger.
	TimeBasedEnabled bool

	// QuerySource identifies the source of the request. Time-based microcompact
	// requires an explicit main-thread source; the zero value is undefined and
	// never triggers.
	QuerySource MicrocompactQuerySource

	// IdleThreshold is the duration after which old tool results can be cleared.
	// Zero disables time-based microcompact. Default: 60 minutes.
	IdleThreshold time.Duration

	// LastActivity records when the last assistant/API turn completed. Used as
	// the Go equivalent of TS's last assistant message timestamp.
	LastActivity time.Time

	// CachedEnabled enables Anthropic cache_edits-style microcompact. This path
	// preserves local message content and only adds provider-bound cache edit
	// directives when the prompt cache is expected to be warm.
	CachedEnabled bool

	// CachedTriggerThreshold is the active compactable tool-result count that
	// triggers cache_edits generation. Zero disables cached microcompact.
	CachedTriggerThreshold int

	// CachedKeepRecent is the number of most recent active tool results to
	// preserve after cached microcompact triggers. Zero falls back to KeepRecent.
	CachedKeepRecent int

	// AgenticV2ProofsEnabled allows Inspect, Run, and ApplyPatch results to be
	// compacted only when a deterministic proof projection is smaller than the
	// original provider-visible result. It is a same-build switch, never an
	// environment or provider-profile fallback.
	AgenticV2ProofsEnabled bool

	// ProgressiveEnabled projects conservative batches of older, successful
	// Inspect results while preserving recent source reads and all Run output.
	// The raw transcript remains unchanged; callers persist returned replacement
	// records separately.
	ProgressiveEnabled bool
}

MicrocompactConfig controls microcompact behavior.

func DefaultMicrocompactConfig 

func DefaultMicrocompactConfig() MicrocompactConfig

DefaultMicrocompactConfig returns sensible defaults. QuerySource intentionally defaults to undefined; callers must opt in with an explicit main-thread source before time-based microcompact can fire.

func (MicrocompactConfig) ShouldUseCachedMicrocompact 

func (cfg MicrocompactConfig) ShouldUseCachedMicrocompact() bool

type MicrocompactQuerySource 

type MicrocompactQuerySource string
const (
	MicrocompactSourceUndefined MicrocompactQuerySource = ""
	MicrocompactSourceMain      MicrocompactQuerySource = "repl_main_thread"
	MicrocompactSourceNonMain   MicrocompactQuerySource = "non_main"
)

type MicrocompactResult 

type MicrocompactResult struct {
	Messages           []types.Message
	Changed            bool
	TimeBasedTriggered bool
	ToolsCleared       int
	ToolsKept          int
	OriginalBytes      int
	CompactedBytes     int
	BytesSaved         int
}

func MicrocompactWithResult 

func MicrocompactWithResult(messages []types.Message, cfg MicrocompactConfig) MicrocompactResult

type ModelContextOverhead 

type ModelContextOverhead struct {
	SystemPromptTokens *int
	ToolSchemaTokens   *int
	MediaTokens        *int
}

ModelContextOverhead supplies request components not present in []Message. Nil means unknown, while a non-nil zero means the caller proved absence.

type ModelContextTokenEstimate 

type ModelContextTokenEstimate struct {
	MessageContentTokens int                     `json:"message_content_tokens"`
	ToolPayloadTokens    int                     `json:"tool_payload_tokens"`
	Overheads            []TokenOverheadEstimate `json:"overheads"`
	KnownTotalTokens     int                     `json:"known_total_tokens"`
	Complete             bool                    `json:"complete"`
	UnknownOverheads     []TokenOverheadKind     `json:"unknown_overheads,omitempty"`
}

ModelContextTokenEstimate is intentionally not a bare integer. Complete is false whenever a request component could not be measured.

type PartialCompactDirection 

type PartialCompactDirection string
const (
	PartialCompactDirectionFrom PartialCompactDirection = "from"
	PartialCompactDirectionUpTo PartialCompactDirection = "up_to"
)

type PinnedCacheEdits 

type PinnedCacheEdits struct {
	UserMessageIndex int
	Block            CacheEditsBlock
	ProofLedger      string
}

type PlanStateProvider 

type PlanStateProvider interface {
	IsActive() bool
	PlanFile() string
}

type PostCompactAttachmentProvider 

type PostCompactAttachmentProvider interface {
	PostCompactAttachments(ctx context.Context, state PostCompactAttachmentState) []types.Message
}

PostCompactAttachmentProvider restores compacted-away runtime context as model-visible user messages. Providers must be best-effort and return nil on missing state; compaction must not fail because optional context is absent.

type PostCompactAttachmentState 

type PostCompactAttachmentState struct {
	OriginalMessages      []types.Message
	MessagesAfterBoundary []types.Message
	PreservedTail         []types.Message
	SessionID             string
	CWD                   string
	ContextWindowTokens   int
}

PostCompactAttachmentState is the compact-time context passed to optional attachment providers. Message slices must be treated as read-only.

type PreservedSegmentMetadata 

type PreservedSegmentMetadata struct {
	StartIndex int    `json:"start_index"`
	Count      int    `json:"count"`
	Anchor     string `json:"anchor,omitempty"`
	Direction  string `json:"direction,omitempty"`
}

PreservedSegmentMetadata describes the verbatim tail carried forward across compaction. Later persistence/relinking work can enrich this without changing the result contract.

type ProgressiveConfig 

type ProgressiveConfig struct {
	Enabled           bool     `json:"enabled"`
	Shadow            bool     `json:"shadow,omitempty"`
	KillSwitch        bool     `json:"killSwitch,omitempty"`
	RolloutPercent    int      `json:"rolloutPercent,omitempty"`
	ProviderAllowlist []string `json:"providerAllowlist,omitempty"`
	ModelAllowlist    []string `json:"modelAllowlist,omitempty"`
	// ProviderModelAllowlist prevents a multi-provider production policy from
	// admitting the cross-product of independently reviewed provider and model
	// families. Entries use "provider/model-prefix".
	ProviderModelAllowlist []string `json:"providerModelAllowlist,omitempty"`
	ToolAllowlist          []string `json:"toolAllowlist,omitempty"`
	// ImminentCompactProviderAllowlist enables a counterfactual correction for
	// providers whose next action would be semantic compaction. When a
	// projection gets the same request back below the hard threshold, both
	// branches reset the prompt cache, so the projection is charged only its
	// incremental cache cost instead of a second, duplicate reset penalty.
	ImminentCompactProviderAllowlist []string `json:"imminentCompactProviderAllowlist,omitempty"`
	// AutoCompactKeepRecent optionally lowers the semantic-compaction verbatim
	// tail for providers in ImminentCompactProviderAllowlist. Zero preserves the
	// compactor's established default.
	AutoCompactKeepRecent int `json:"autoCompactKeepRecent,omitempty"`
	// AutoCompactMaxGrowthTokens bounds an uncalibrated local request delta
	// above the last provider-reported input for reviewed providers. It prevents
	// tokenizer/schema representation bias from causing an early semantic
	// compact while still allowing the authoritative provider total to cross
	// the threshold. Zero preserves the established estimator.
	AutoCompactMaxGrowthTokens int `json:"autoCompactMaxGrowthTokens,omitempty"`
	// AutoCompactMinThresholdPercent may postpone semantic compaction until at
	// least this percentage of the effective input window is occupied. The
	// ordinary fixed-buffer threshold remains a floor, so this option can never
	// make compaction earlier. Zero preserves the established threshold.
	AutoCompactMinThresholdPercent int `json:"autoCompactMinThresholdPercent,omitempty"`
	// RequireConsumedMutation prevents pressure-only projection while exact
	// source reads may still be needed to construct the first mutation. It is a
	// provider-scoped quality guard for models that do not reliably recover
	// indexed evidence. False preserves the established GPT strategy.
	RequireConsumedMutation bool `json:"requireConsumedMutation,omitempty"`
	// BenefitTrigger admits the smallest cost-positive batch as soon as its
	// results have been consumed by a later assistant decision. The ordinary
	// path keeps the recent working set and rich rewrites; recoverable indexes
	// remain reserved for actual context pressure. Runtime admission also
	// requires the first changed byte to be beyond the last provider-reported
	// cache frontier and permits at most one early reset per session.
	BenefitTrigger                  bool     `json:"benefitTrigger,omitempty"`
	BenefitTriggerProviderAllowlist []string `json:"benefitTriggerProviderAllowlist,omitempty"`
	// FlattenCompactInput serializes the history as one explicitly untrusted
	// transcript for the semantic summarizer. This prevents reviewed providers
	// from continuing an in-progress tool loop instead of obeying the compact
	// request. False preserves the established structured GPT input.
	FlattenCompactInput bool `json:"flattenCompactInput,omitempty"`
	// ConciseCompactSummary selects a smaller coding handoff prompt and
	// CompactMaxOutputTokens optionally caps that provider-scoped response.
	// Zero/false preserve the established GPT nine-section, 20k-token contract.
	ConciseCompactSummary   bool    `json:"conciseCompactSummary,omitempty"`
	CompactMaxOutputTokens  int     `json:"compactMaxOutputTokens,omitempty"`
	MinTokenSavings         int     `json:"minTokenSavings,omitempty"`
	BenefitMinTokenSavings  int     `json:"benefitMinTokenSavings,omitempty"`
	ReuseHorizon            int     `json:"reuseHorizon,omitempty"`
	CacheRecoveryRequests   int     `json:"cacheRecoveryRequests,omitempty"`
	MinNetSavingsUSD        float64 `json:"minNetSavingsUsd,omitempty"`
	MaxProjectedTools       int     `json:"maxProjectedTools,omitempty"`
	MaxProjectedTokens      int     `json:"maxProjectedTokens,omitempty"`
	MaxConsecutiveAnomalies int     `json:"maxConsecutiveAnomalies,omitempty"`
}

ProgressiveConfig is the rollout and safety control plane for progressive provider-view projection. The zero value is disabled. All allowlists are fail-closed when present; model entries use canonical prefix matching so a dated model revision can inherit an explicitly reviewed family policy.

func DefaultProgressiveConfig 

func DefaultProgressiveConfig() ProgressiveConfig

DefaultProgressiveConfig returns production-safe values while leaving the feature disabled until a caller deliberately enables it.

func NormalizeProgressiveConfig 

func NormalizeProgressiveConfig(config ProgressiveConfig) ProgressiveConfig

NormalizeProgressiveConfig applies bounded defaults without turning the feature on. Invalid limits fail toward less projection.

func ProductionProgressiveConfig 

func ProductionProgressiveConfig() ProgressiveConfig

ProductionProgressiveConfig enables only the provider, model family, and tool strategy that have passed a real provider A/B and the frozen quality evaluator. Callers may still override or disable this policy explicitly.

type ProgressiveProjectionAdmission 

type ProgressiveProjectionAdmission struct {
	Enabled                    bool
	Shadow                     bool
	Pressure                   bool
	BenefitTrigger             bool
	Counter                    TokenCounter
	StablePrefixTokens         func(messageIndex int, toolUseID string) int
	RawRequestTokens           int
	RawRequestEstimateKnown    bool
	AutoCompactThreshold       int
	PreviousCacheReadTokens    int
	PreviousUsageKnown         bool
	Pricing                    ProgressiveTokenPricing
	MinTokenSavings            int
	BenefitMinTokenSavings     int
	ReuseHorizon               int
	CacheRecoveryRequests      int
	ImminentCompactResetsCache bool
	RequireConsumedMutation    bool
	MinNetSavingsUSD           float64
	RemainingTools             int
	RemainingProjectedTokens   int
	AllowedTools               map[string]struct{}
}

ProgressiveProjectionAdmission freezes every value used by the token/cost gate for one preparation attempt. The caller supplies the complete provider request estimate so tool-result bytes are never used as a proxy for context or price.

type ProgressiveProjectionPending 

type ProgressiveProjectionPending struct {
	Tools       int
	TokensSaved int
}

ProgressiveProjectionPending reports the current safe, not-yet-installed provider-view opportunity. It deliberately ignores pressure and the token/cost admission decision: callers use it to make eligible source results visible before the gate fires, never to claim realized savings.

func PendingProgressiveToolResultProjection 

func PendingProgressiveToolResultProjection(messages []types.Message, state *ContentReplacementState, admission ProgressiveProjectionAdmission) ProgressiveProjectionPending

PendingProgressiveToolResultProjection measures candidates that have crossed the same phase and safety boundaries as production projection but remain in their original form. Session-budget limits are applied so the status cannot promise work the runtime is no longer allowed to install.

type ProgressiveProjectionResult 

type ProgressiveProjectionResult struct {
	Messages                   []types.Message
	Records                    []ContentReplacementRecord
	Changed                    bool
	Trigger                    string
	ProjectedTools             int
	RewrittenTools             int
	IndexedTools               int
	OriginalBytes              int
	ProjectedBytes             int
	BytesSaved                 int
	OriginalTokens             int
	ProjectedTokens            int
	TokensSaved                int
	ProjectedRequestTokens     int
	StablePrefixTokens         int
	InvalidatedCachedTokens    int
	RawRequestTokens           int
	CacheBreakCostUSD          float64
	GrossCacheBreakCostUSD     float64
	AvoidedCompactInputCostUSD float64
	EstimatedNetSavingsUSD     float64
	AvoidsImmediateCompaction  bool
	Decision                   string
	Shadow                     bool
}

ProgressiveProjectionResult describes one frozen provider-view update. Raw history is not modified: Messages contains only the provider projection and Records is the durable private ledger the loop must append to its history.

func ApplyProgressiveToolResultProjection 

func ApplyProgressiveToolResultProjection(messages []types.Message, state *ContentReplacementState, admission ProgressiveProjectionAdmission) ProgressiveProjectionResult

ApplyProgressiveToolResultProjection performs a conservative phase-boundary projection. Every result remains lossless until a later assistant decision has consumed it. The benefit path may then freeze a cache-safe newest suffix as deterministic proofs; context pressure and a consumed mutation remain the fallback boundaries, while the current unconsumed result stays intact.

The production default admits only Inspect. Reviewed Run and ApplyPatch rewrites remain available behind the per-tool allowlist for measurement; failures stay active diagnostic evidence and the token/cost gate rejects batches that cannot repay a continuation reset.

type ProgressiveTokenPricing 

type ProgressiveTokenPricing struct {
	InputPerMtok     float64
	CacheReadPerMtok float64
	Known            bool
}

ProgressiveTokenPricing is the input-side portion of one model's published pricing. Values are USD per million tokens. Output pricing is deliberately excluded because admission credits only direct replacement savings; merely delaying a semantic-compaction response is not treated as avoided spend.

type ReactiveCompactOptions 

type ReactiveCompactOptions struct {
	Compactor    Compactor
	HasAttempted bool
	MediaStrip   bool
	KeepRecent   int
	Trigger      string
}

ReactiveCompactOptions controls the prompt-overflow recovery compaction path.

type ReactiveCompactorUnavailableError 

type ReactiveCompactorUnavailableError struct{}

ReactiveCompactorUnavailableError indicates that overflow recovery could not perform semantic compaction. It is intentionally typed so callers can distinguish fail-closed recovery from a provider or summarizer failure.

func (*ReactiveCompactorUnavailableError) Error 

func (*ReactiveCompactorUnavailableError) Error() string

type ResultStore 

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

ResultStore persists oversized tool results to disk.

func NewResultStore 

func NewResultStore(sessionDir string) *ResultStore

NewResultStore creates a store that persists to the given directory.

func (*ResultStore) PersistRawOutput 

func (rs *ResultStore) PersistRawOutput(prefix string, content []byte, maxBytes int64) (path string, originalSize int64, err error)

PersistRawOutput writes a tool-owned raw output stream to the store using a collision-resistant filename. originalSize reports the untruncated byte count; maxBytes limits the persisted copy (zero means unlimited).

func (*ResultStore) PersistReplacement 

func (rs *ResultStore) PersistReplacement(toolUseID, content string) (string, error)

PersistReplacement writes the full tool result content and returns the exact replacement text that should be shown to the model. It is used by the stateful aggregate per-message budget, which has already selected this result for replacement and therefore bypasses the per-result threshold.

func (*ResultStore) ProcessResult 

func (rs *ResultStore) ProcessResult(result types.ToolResultBlock) types.ToolResultBlock

ProcessResult checks if a tool result is oversized and persists it if so. Returns the (possibly modified) result.

func (*ResultStore) ProcessResultForTool 

func (rs *ResultStore) ProcessResultForTool(result types.ToolResultBlock, toolName string) (types.ToolResultBlock, error)

ProcessResultForTool checks if a tool result should be normalized or persisted for the given tool. On persistence failure, it returns the original content unchanged with a filesystem error useful to logs/tests.

type RuntimeAttachmentProvider 

type RuntimeAttachmentProvider struct {
	PlanState        PlanStateProvider
	SkillCatalog     SkillCatalogPostCompactProvider
	BackgroundTasks  BackgroundTaskProvider
	MCPState         MCPStateProvider
	AgentDefinitions AgentDefinitionProvider

	SessionID string
	CWD       string

	DeferredToolNames func() []string
	LoadedToolNames   func() []string
}

RuntimeAttachmentProvider converts Go runtime state that has a real product surface into TS-style post-compact attachments.

func (*RuntimeAttachmentProvider) PostCompactAttachments 

func (p *RuntimeAttachmentProvider) PostCompactAttachments(ctx context.Context, state PostCompactAttachmentState) []types.Message

type SkillCatalogPostCompactProvider 

type SkillCatalogPostCompactProvider interface {
	PostCompactSkillAttachments(ctx context.Context, state PostCompactAttachmentState) []types.Message
}

SkillCatalogPostCompactProvider rebuilds the live developer catalog and exact invocation-body projection. Implementations derive body evidence from model-visible messages.

type StructuredSummarizeOptions 

type StructuredSummarizeOptions struct {
	FlattenMessages bool
	ConciseSummary  bool
	MaxOutputTokens int
}

StructuredSummarizeOptions contains provider-reviewed request projections. The zero value preserves the established role-structured input.

type SummaryCompactor 

type SummaryCompactor struct {
	SummarizeMessages  MessageSummarizeFunc // structured path; see summarize.go
	CustomInstructions string               // user-specified compact instructions; "" = default
	KeepRecent         int
	TranscriptPath     string // readable persisted transcript path for compact summaries
	// TranscriptPathResolver refreshes content-addressed audit references at
	// compaction time. When set, its result is authoritative and the static path
	// is never used as a stale fallback.
	TranscriptPathResolver func() string
	AttachmentProvider     PostCompactAttachmentProvider
	SessionID              string
	CWD                    string
	HookRunner             *hooks.Runner
	OnProgress             func(CompactProgressEvent)
	OnTelemetry            func(CompactionTelemetryEvent)
}

SummaryCompactor calls the LLM to summarize old messages. CustomInstructions is passed through to the structured summarizer on each call.

func (*SummaryCompactor) Compact 

func (s *SummaryCompactor) Compact(ctx context.Context, messages []types.Message, keepRecent int) (*CompactionResult, error)

func (*SummaryCompactor) CompactWithTrigger 

func (s *SummaryCompactor) CompactWithTrigger(ctx context.Context, messages []types.Message, keepRecent int, trigger string) (*CompactionResult, error)

CompactWithTrigger is the same compaction contract as Compact but lets loop callers preserve whether the boundary came from manual or automatic compact.

func (*SummaryCompactor) PartialCompactConversation 

func (s *SummaryCompactor) PartialCompactConversation(ctx context.Context, allMessages []types.Message, pivotIndex int, direction PartialCompactDirection, userFeedback string) (*CompactionResult, error)

PartialCompactConversation summarizes one side of a selected pivot while preserving the other side verbatim. Direction "from" keeps messages before the pivot and summarizes messages from the pivot onward. Direction "up_to" summarizes messages before the pivot and keeps messages from the pivot onward.

type TokenCounter 

type TokenCounter interface {
	Count(text string) int
}

TokenCounter estimates token count for text

type TokenEstimateBasis 

type TokenEstimateBasis string
const (
	TokenEstimateEstimated  TokenEstimateBasis = "estimated"
	TokenEstimateConfigured TokenEstimateBasis = "configured"
	TokenEstimateUnknown    TokenEstimateBasis = "unknown"
)

type TokenOverheadEstimate 

type TokenOverheadEstimate struct {
	Kind   TokenOverheadKind  `json:"kind"`
	Tokens int                `json:"tokens,omitempty"`
	Basis  TokenEstimateBasis `json:"basis"`
}

type TokenOverheadKind 

type TokenOverheadKind string

TokenOverheadKind makes every non-message component of a provider request explicit. Callers can distinguish an included estimate from an unavailable component instead of treating missing overhead as zero. 

const (
	TokenOverheadSystemPrompt TokenOverheadKind = "system_prompt"
	TokenOverheadToolSchema   TokenOverheadKind = "tool_schema"
	TokenOverheadToolPayload  TokenOverheadKind = "tool_payload"
	TokenOverheadMedia        TokenOverheadKind = "media"
	TokenOverheadProtocol     TokenOverheadKind = "protocol"
)

type TokenWarningOptions 

type TokenWarningOptions struct {
	MaxTokens          int
	MaxOutputTokens    int
	TokenUsage         int
	AutoCompactEnabled bool
	SuppressWarning    bool
}

type TokenWarningState 

type TokenWarningState struct {
	UsedTokens                  int
	EffectiveInputWindowTokens  int
	ThresholdTokens             int
	WarningThresholdTokens      int
	ErrorThresholdTokens        int
	AutoCompactThresholdTokens  int
	BlockingLimitTokens         int
	PercentLeft                 int
	IsAboveWarningThreshold     bool
	IsAboveErrorThreshold       bool
	IsAboveAutoCompactThreshold bool
	IsAtBlockingLimit           bool
	AutoCompactEnabled          bool
	WarningSuppressed           bool
}

TokenWarningState is the TS-equivalent calculateTokenWarningState result.

func CalculateTokenWarningState 

func CalculateTokenWarningState(opts TokenWarningOptions) TokenWarningState

CalculateTokenWarningState mirrors TS calculateTokenWarningState using the effective input window after output-token reservation.

type ToolResultBudget 

type ToolResultBudget struct {
	MaxCharsPerResult int // default 15000
}

ToolResultBudget truncates oversized tool results

func NewToolResultBudget 

func NewToolResultBudget() *ToolResultBudget

func (*ToolResultBudget) Apply 

func (t *ToolResultBudget) Apply(messages []types.Message) []types.Message

Apply truncates tool results that exceed the budget

type TriggeredCompactor 

type TriggeredCompactor interface {
	CompactWithTrigger(ctx context.Context, messages []types.Message, keepRecent int, trigger string) (*CompactionResult, error)
}

TriggeredCompactor is implemented by compactors that can record why a compact boundary was created.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.