context.go

package agentgo

import "context"

// CompactReason identifies why context compaction was requested.
type CompactReason string

const (
	CompactReasonManual    CompactReason = "manual"
	CompactReasonOverflow  CompactReason = "overflow"
	CompactReasonThreshold CompactReason = "threshold"
)

// CompactionInfo describes a context rewrite. Committed becomes true only
// after the runtime accepts its messages and staged artifacts.
// It reports the aggregate effect of the configured compactor; individual
// strategies remain an implementation detail. A nil Compaction means no
// compaction changed the context.
type CompactionInfo struct {
	Reason         CompactReason
	Committed      bool
	TokensBefore   int
	TokensAfter    int
	MessagesBefore int
	MessagesAfter  int
	Summarized     bool
}

// ContextSnapshot describes both the runtime baseline and the current active
// context view, including its identifiable Items, plus the most recent rewrite
// details remembered by the manager.
//
// Snapshot is meant for debugging, observability, and UI surfaces such as
// /context. BaselineUsage always reflects the caller's current runtime message
// baseline. Usage reports the active view currently remembered by the manager,
// which may be the baseline runtime messages, a projected prompt view, or a
// candidate/recovered view depending on the most recent operation.
type ContextSnapshot struct {
	Items              []ContextItem
	BaselineUsage      *ContextUsage
	Usage              *ContextUsage
	Scope              string
	TranscriptMessages int
	ActiveMessages     int
	SummaryMessages    int
	ToolMessages       int
	ClearedToolResults int
	TrimmedTextBlocks  int
	LastChanged        bool
	LastCompactedCount int
	LastKeptCount      int
	LastSplitTurn      bool
}

// ContextCommitResult describes an explicit baseline rewrite candidate.
// The returned Messages should replace the runtime baseline when Changed is
// true, for example after a manual /compact command. AgentLoop also accepts
// successful artifact-only changes, retaining the original message baseline.
type ContextCommitResult struct {
	Messages []AgentMessage
	// Artifacts is the complete staged collection supplied by the loop to CommitContext.
	Artifacts      []Artifact
	Usage          *ContextUsage
	Changed        bool
	Compaction     *CompactionInfo
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
}

// ContextRecoveryResult is the result of overflow recovery.
//
// View is always the retryable prompt view. CommitMessages is optional and,
// when ShouldCommit is true, should replace the runtime message baseline so
// future usage reporting and turns start from the recovered state.
type ContextRecoveryResult struct {
	View           []AgentMessage
	CommitMessages []AgentMessage
	Usage          *ContextUsage
	Changed        bool
	ShouldCommit   bool
	Compaction     *CompactionInfo
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
}

// TransformContext carries the messages to project and their runtime's material
// capability. Direct context-engine users may omit Artifacts when their policies
// do not use material. AgentGo supplies it on all runtime-owned context calls.
// Compact/RecoverOverflow receive an isolated CRUD collection; Transform receives
// accepted runtime artifacts. Message and artifact payloads are shared values:
// replace them rather than mutate in place. Callers outside AgentLoop own staging.
type TransformContext struct {
	Artifacts ArtifactManager
	Messages  []AgentMessage
}

// ContextManager owns prompt projection, committed rewrites, overflow
// recovery, and usage reporting for long-running agent sessions.
//
// The manager deliberately distinguishes between transient prompt projection
// and explicit baseline rewrites:
//   - Transform builds a prompt view for one LLM call without committing it.
//   - Compact prepares an explicit baseline rewrite such as /compact.
//   - RecoverOverflow produces a retryable prompt view after context overflow
//     and may optionally return a new committed baseline.
//   - Sync updates the manager with the current runtime baseline after
//     external message replacement, session restore, or clear.
//   - Usage reports the latest effective usage remembered by the manager.
//   - Snapshot reports the current active view and recent rewrite details for
//     debugging and UI surfaces.
type ContextManager interface {
	// Transform builds the model view without mutating messages or committing
	// history. It may expand, shrink, or rewrite the view independently of budget.
	Transform(ctx context.Context, input TransformContext) ([]AgentMessage, error)

	// Compact returns an explicit baseline rewrite. Threshold requests must be
	// no-ops when the baseline fits the configured budget. The caller is
	// responsible for replacing its runtime baseline with the returned Messages
	// when Changed is true.
	Compact(ctx context.Context, input TransformContext, reason CompactReason) (ContextCommitResult, error)

	// RecoverOverflow produces a retryable view after a provider reports
	// context overflow. When ShouldCommit is true, CommitMessages should replace
	// the runtime baseline before continuing and staged artifact changes are accepted.
	// Otherwise View is request-local and staged CRUD changes are discarded.
	RecoverOverflow(ctx context.Context, input TransformContext, cause error) (ContextRecoveryResult, error)

	// Sync tells the manager what the current runtime baseline is after restore,
	// clear, import, or any other external replacement of messages.
	Sync(msgs []AgentMessage)

	// Usage returns the latest effective context usage remembered by the
	// manager. It may reflect a projected or recovered view rather than the raw
	// runtime baseline.
	Usage() *ContextUsage

	// Snapshot returns the latest active view snapshot remembered by the
	// manager. It is intended for observability and may be nil before the
	// manager has seen any messages.
	Snapshot() *ContextSnapshot
}

// ContextEstimator is an optional interface a ContextManager can implement
// to provide token estimation. When implemented, NewAgent auto-wires it.
type ContextEstimator interface {
	EstimateContext([]AgentMessage) (tokens, usageTokens, trailingTokens int)
}

// ContextWindowProvider is an optional interface a ContextManager can implement
// to report its configured context window size.
type ContextWindowProvider interface {
	ContextWindow() int
}

// ContextWindowSetter is an optional interface a ContextManager can implement
// to receive window updates pushed through Agent.SetContextWindow. When
// implemented, the agent and its context manager can never disagree on the
// window size after a model hot-switch — without it, callers had to update
// both sides manually and a missed call silently skewed compaction thresholds.
type ContextWindowSetter interface {
	SetContextWindow(n int)
}