compaction

type ContextProviderConfig struct {
	// Strategy is the compaction strategy to apply before each agent run.
	Strategy Strategy

	// SourceID identifies this provider in the agent context pipeline.
	// When empty, a default compaction provider source ID is used.
	SourceID string

	// StateKey identifies where provider state is stored in the session.
	// When empty, SourceID is used.
	StateKey string

	// TokenCounter computes token counts for message groups.
	// When nil, token counts are estimated from UTF-8 byte counts.
	TokenCounter TokenCounter

	// Logger emits provider diagnostics when set.
	Logger *slog.Logger
}

type ContextWindowStrategy struct {
	// MaxContextWindowTokens is the maximum number of tokens the model's context window supports
	// (for example, 1,048,576 for gpt-4.1). Must be positive.
	MaxContextWindowTokens int

	// MaxOutputTokens is the maximum number of output tokens the model can generate per response
	// (for example, 32,768 for gpt-4.1). Must be non-negative and less than MaxContextWindowTokens.
	MaxOutputTokens int

	// ToolEvictionThreshold is the fraction of the input budget at which tool-result eviction
	// triggers. Must be in (0.0, 1.0]. Zero uses the default (0.5).
	ToolEvictionThreshold float64

	// TruncationThreshold is the fraction of the input budget at which truncation triggers.
	// Must be in (0.0, 1.0] and >= ToolEvictionThreshold. Zero uses the default (0.8).
	TruncationThreshold float64
}

type GroupKind int

type MessageGroup struct {
	// Kind is the kind of this message group.
	Kind GroupKind

	// Messages contains the messages in this group.
	Messages []*message.Message

	// MessageCount is the number of messages in this group.
	MessageCount int

	// ByteCount is the total UTF-8 byte count of this group's message content.
	ByteCount int

	// TokenCount is the estimated or counted token count for this group's messages.
	TokenCount int

	// TurnIndex identifies the user turn this group belongs to.
	//
	// System groups have a nil turn index. A turn starts with a user group and includes subsequent
	// non-user, non-system groups until the next user group or end of conversation.
	TurnIndex *int `json:",omitzero"`

	// IsExcluded indicates whether this group is omitted from the projected message list.
	IsExcluded bool

	// ExcludeReason optionally explains why this group was excluded.
	ExcludeReason string `json:",omitzero"`
}

type MessageIndex struct {
	// Groups is the ordered list of message groups in the index.
	Groups []*MessageGroup

	// TokenCounter is used to compute token counts for newly created groups.
	// When nil, token counts are estimated from byte counts.
	TokenCounter TokenCounter `json:"-"`
	// contains filtered or unexported fields
}

type PipelineStrategy struct {
	// Strategies is the ordered sequence of strategies to execute.
	Strategies []Strategy
}

type SlidingWindowStrategy struct {
	// Trigger controls whether sliding-window compaction should run.
	// When nil, compaction always runs.
	Trigger Trigger

	// Target controls when compaction stops after each excluded turn.
	// When nil, compaction stops when Trigger would no longer fire.
	Target Trigger

	// MinimumPreservedTurns is the minimum number of most-recent user turns to preserve.
	// Groups with nil or non-positive turn indexes are preserved independently of this value.
	//
	// When nil, a default floor is used. An explicit value is honored as-is, so a pointer to 0
	// disables the floor entirely; a negative value is clamped to 0.
	MinimumPreservedTurns *int
}

type Strategy interface {
	// Compact applies strategy-specific compaction to index.
	//
	// It returns true when the strategy changed the index. Implementations should honor ctx for
	// cancellation when they perform blocking work.
	Compact(context.Context, *MessageIndex) (bool, error)
}

type SummarizationStrategy struct {
	// Trigger controls whether summarization should run.
	// When nil, summarization always runs.
	Trigger Trigger

	// Target controls when summarization stops marking groups after each exclusion.
	// When nil, summarization stops when Trigger would no longer fire.
	Target Trigger

	// Summarizer generates the replacement summary text.
	// When nil, the strategy performs no compaction.
	Summarizer Summarizer

	// MinimumPreservedGroups is the minimum number of most-recent non-system groups to preserve.
	// This is a hard floor; summarization will not summarize groups within this protected window.
	//
	// When nil, a default floor is used. An explicit value is honored as-is, so a pointer to 0
	// disables the floor entirely; a negative value is clamped to 0.
	MinimumPreservedGroups *int

	// SummarizationPrompt is the system prompt prepended to messages sent to Summarizer.
	// When nil, a default prompt is used.
	SummarizationPrompt *string

	// SummaryUnavailableMessage is used when Summarizer returns only whitespace.
	// When empty, a default unavailable message is used.
	SummaryUnavailableMessage string
}

type Summarizer interface {
	// Summarize returns a textual summary of messages.
	Summarize(context.Context, []*message.Message) (string, error)
}

type SummarizerFunc func(context.Context, []*message.Message) (string, error)

type TokenCounter interface {
	// CountTokens returns the token count for text content.
	CountTokens(string) int
}

type ToolResultStrategy struct {
	// Trigger controls whether tool-result compaction should run.
	// When nil, compaction always runs.
	Trigger Trigger

	// Target controls when compaction stops after each collapsed tool-call group.
	// When nil, compaction stops when Trigger would no longer fire.
	Target Trigger

	// MinimumPreservedGroups is the minimum number of most-recent non-system groups to preserve.
	// This is a hard floor; tool-call groups within this protected window are not collapsed.
	//
	// When nil, a default floor is used. An explicit value is honored as-is, so a pointer to 0
	// disables the floor entirely; a negative value is clamped to 0.
	MinimumPreservedGroups *int

	// ToolCallFormatter formats a tool-call group as a compact summary string.
	// When nil, DefaultToolCallFormatter is used, which produces a YAML-like block listing
	// each tool name and its results.
	ToolCallFormatter func(*MessageGroup) string
}

type Trigger func(*MessageIndex) bool

type TruncationStrategy struct {
	// Trigger controls whether truncation should run.
	// When nil, truncation always runs.
	Trigger Trigger

	// Target controls when truncation stops after each exclusion.
	// When nil, truncation stops when Trigger would no longer fire.
	Target Trigger

	// MinimumPreservedGroups is the minimum number of most-recent non-system groups to preserve.
	// This is a hard floor; truncation will not remove groups beyond this limit.
	//
	// When nil, a default floor is used. An explicit value is honored as-is, so a pointer to 0
	// disables the floor entirely; a negative value is clamped to 0.
	MinimumPreservedGroups *int
}