contextmgr

type Calibration struct {
	// Alpha is the smoothing factor (0 < alpha <= 1). Higher values
	// react faster to changes. Defaults to 0.2.
	Alpha float64
	// Ratio is the current correction factor: reported/estimated.
	// Bounded to [calibrationMinRatio, calibrationMaxRatio] once samples
	// exist. The zero value is 0.0, which means no correction (treated as
	// 1.0 everywhere it is applied).
	Ratio float64
	// Samples is the number of updates applied.
	Samples int
}

type CheckpointCandidate struct {
	ActiveContext   []byte
	SummaryMetadata []byte
	SourceEvents    []contextstate.SourceEvent
	Payloads        []contextstate.PayloadRecord
	SourceRange     contextstate.SourceRange
}

type CheckpointPublisher interface {
	Commit(context.Context, Preparation, TurnResult) error
}

type CommitToken struct {
	Principal        contextstate.Principal
	Revision         contextstate.Revision
	Binding          contextstate.BindingRevision
	WorktreeInstance contextstate.WorktreeInstance
	Range            contextstate.SourceRange
	IdempotencyKey   string
}

type ContextManager struct {
	PreparationManager  PreparationManager
	CheckpointPublisher CheckpointPublisher
	// Summarizer is the optional LLM summarizer wiring point. Nil keeps every
	// path structural-only (today's production state: no SummaryProvider
	// exists). It is copied into chat turn configurations so both the agent
	// loop and plain chat can inject a validated summary at the request
	// boundary; the checkpoint committer reaches it through the
	// PreparationCommitter fields.
	Summarizer *Summarizer
	Enabled    bool
	// SummaryUnavailableReason names why Summarizer is nil, when it is: a
	// fixed, classified, content-free string set once at session setup (see
	// internal/cli's summaryDisabledReason). Every compaction path in the
	// session's lifetime reads it to report a real cause instead of a bare
	// "not summarized" boolean. Empty when Summarizer is configured.
	SummaryUnavailableReason string
	// UsageWriter is the optional durable usage-measurement sink. Nil keeps
	// usage events ephemeral (bus-only, today's production state everywhere
	// this isn't wired). Constructed once per session, alongside Summarizer,
	// and copied into agent.Options per turn the same way.
	UsageWriter usage.UsageWriter
}

type ElisionStats struct {
	Messages int
	Bytes    int
}

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

type PlanInput struct {
	Messages []provider.Message
	Budget   int
	Tools    []provider.ToolSpec
	// OutputReserve is validated (must not be negative) and folded into the
	// idempotency-key fingerprint (planIdempotencyKey) - it is NOT subtracted
	// from Budget anywhere in the trigger/target math below. Budget already
	// excludes the reserved completion allowance (callers derive it from
	// config.EffectivePromptTokens, which does the subtraction once, upstream
	// of the planner). Using OutputReserve again here would double-subtract
	// the same reserve. If a future caller needs the planner itself to
	// account for an output reserve, pass a Budget that has NOT already
	// excluded it and remove this comment along with the double-subtraction
	// it warns against - do not add a second, silent subtraction beside this
	// one.
	OutputReserve    int
	Force            bool
	CurrentObjective string
	SourceRange      contextstate.SourceRange
	SourceEvents     []contextstate.SourceEvent
	IdempotencyKey   string
	RecentTail       int
	// Revision is the session revision the compaction starts FROM. It is
	// part of the derived idempotency key: two compactions of the same
	// retained set off the same source range (a resumed process compacting
	// an already-compacted session again) are different operations that
	// commit different work, so sharing a key made the store reject the
	// second as a conflicting retry. Retries of the SAME compaction carry
	// the same revision and stay idempotent.
	Revision contextstate.Revision
	// PreserveNames lists provider.Message.Name values that structural
	// retention keeps whole alongside the mandatory set. The chat layer uses
	// it for the session-owned core-memory context frame so compaction never
	// drops it.
	PreserveNames []string
	// CalibrationRatio scales token estimates to correct for heuristic drift.
	// 0 means use 1.0 (no correction). Should come from a Calibration.Ratio.
	CalibrationRatio float64
	// ContextAccounting carries the bound provider's declared context-billing
	// profile (provider.ContextAccountingProfile) opaquely: the planner never
	// interprets its fields itself, only passes it to the provider estimators
	// it already calls. The zero value is the conservative "bill everything"
	// default, so a caller that leaves this unset behaves exactly as before
	// the field existed.
	ContextAccounting provider.ContextAccountingProfile
	// Spool: nil = elision mints no refs (plain notices), keeping the planner free of storage side effects.
	Spool *remainder.Spool
	// Principal: the session principal that receives the remainder grant when Spool is set.
	Principal contextstate.Principal
}

type PlanResult struct {
	Messages      []provider.Message
	Candidate     CheckpointCandidate
	BeforeTokens  int
	AfterTokens   int
	TriggerTokens int
	TargetTokens  int
	Compacted     bool
	// ElidedMessages and ElidedBytes are content-free aggregates of prior-turn
	// tool-result replacements applied on the compaction path. Both are zero
	// when the request is below the trigger or no body was eligible.
	ElidedMessages int
	ElidedBytes    int
	// ElidedReasoningMessages and ElidedReasoningBytes are content-free
	// aggregates of stale assistant reasoning replaced with
	// reasoningElisionMarker on the compaction path. Both are zero when the
	// request is below the trigger or no reasoning was eligible.
	ElidedReasoningMessages int
	ElidedReasoningBytes    int
	SourceRange             contextstate.SourceRange
	IdempotencyKey          string
}

type PlannerInput = PlanInput

type PlannerResult = PlanResult

type Preparation struct {
	Messages      []provider.Message
	Candidate     CheckpointCandidate
	Token         CommitToken
	Compacted     bool
	BeforeTokens  int
	AfterTokens   int
	TriggerTokens int
	TargetTokens  int
	// ElidedMessages and ElidedBytes are content-free aggregates of prior-turn
	// tool-result replacements from the planner (or turn-level accumulation on
	// the agent loop). Both are zero when nothing was elided.
	ElidedMessages int
	ElidedBytes    int
	// ElidedReasoningMessages and ElidedReasoningBytes are content-free
	// aggregates of stale assistant reasoning replaced with a constant marker
	// on the planner compaction path. Both are zero when nothing was elided.
	ElidedReasoningMessages int
	ElidedReasoningBytes    int
}

type PreparationCommitter struct {
	Store          contextstate.Store
	Summarizer     *Summarizer
	SummaryRequest SummaryRequest
	SummaryBuilder SummaryRequestBuilder
}

type PreparationManager interface {
	Prepare(context.Context, PrepareInput) (Preparation, error)
	Discard(Preparation)
}

type PrepareInput struct {
	// Spool, when non-nil, lets compaction elision store the full body of an
	// elided tool result and name the remainder ref in the notice, so the model
	// can fetch the original bytes with read_output. Nil keeps plain
	// (non-recoverable) notices.
	Spool *remainder.Spool

	Messages         []provider.Message
	Budget           int
	Tools            []provider.ToolSpec
	OutputReserve    int
	Force            bool
	CurrentObjective string
	RecentTail       int
	// PreserveNames lists provider.Message.Name values that structural
	// retention keeps whole alongside the mandatory set. The chat layer uses
	// it for the session-owned core-memory context frame so compaction never
	// drops it.
	PreserveNames []string
	// CalibrationRatio scales token estimates in the planner for
	// heuristic drift correction. 0 means no correction.
	CalibrationRatio float64
	// ContextAccounting carries the bound provider's declared context-billing
	// profile through to Plan(), opaquely - see PlanInput.ContextAccounting.
	ContextAccounting provider.ContextAccountingProfile
	SourceRange       contextstate.SourceRange
	Principal         contextstate.Principal
	Revision          contextstate.Revision
	Binding           contextstate.BindingRevision
	WorktreeInstance  contextstate.WorktreeInstance
	Policy            contextstate.PolicySnapshot
}

type PublicationRequest struct {
	Store          contextstate.Store
	Summarizer     *Summarizer
	SummaryRequest SummaryRequest
	SummaryBuilder SummaryRequestBuilder
	Preparation    Preparation
	Result         TurnResult
}

type SourceExcerpt struct {
	Role string
	Name string
	Text string
}

type StructuralPreparationManager struct {
	Tools         []map[string]any
	OutputReserve int
	RecentTail    int
}

type Summarizer struct {
	Provider SummaryProvider
	Binding  contextstate.BindingRevision
	Policy   contextstate.PolicySnapshot
	Timeout  time.Duration
}

type Summary struct {
	Version         uint32                   `json:"version"`
	Objective       string                   `json:"objective"`
	State           string                   `json:"state"`
	Decisions       []string                 `json:"decisions,omitempty"`
	Evidence        []string                 `json:"evidence,omitempty"`
	ChangedSurfaces []string                 `json:"changed_surfaces,omitempty"`
	OpenWork        []string                 `json:"open_work,omitempty"`
	Risks           []string                 `json:"risks,omitempty"`
	SourceRange     contextstate.SourceRange `json:"source_range"`
}

type SummaryBuildInput struct {
	Version           uint32
	Objective         string
	State             string
	Decisions         []string
	Evidence          []string
	ChangedSurfaces   []string
	OpenWork          []string
	Risks             []string
	SourceRange       contextstate.SourceRange
	PolicyDigest      string
	Provider          string
	Model             string
	EndpointAllowlist []string
	RedactionPolicy   contextstate.RedactionPolicy
	Budget            int
	OutputLimit       int
	// SourceExcerpts carries bounded quotes of the dropped messages for the
	// summarize REQUEST. BuildSummaryRequest sanitizes them and drops every
	// item the redaction policy flags; the envelope never sees them.
	SourceExcerpts []SourceExcerpt
	// Focus is an optional caller-supplied bias string telling the
	// summarizer what to prioritize (e.g. `/compact <focus instructions>`).
	// Empty is the default, unbiased behavior. See SummaryRequest.Focus.
	Focus string
}

type SummaryEnvelope struct {
	Version         uint32
	Objective       string
	State           string
	Decisions       []string
	Evidence        []string
	ChangedSurfaces []string
	OpenWork        []string
	Risks           []string
	SourceRange     contextstate.SourceRange
	PolicyDigest    string
	// contains filtered or unexported fields
}

type SummaryProvider interface {
	Summarize(context.Context, SummaryRequest) (Summary, error)
}

type SummaryRequest struct {
	Input             SummaryEnvelope
	Budget            int
	OutputLimit       int
	SourceRange       contextstate.SourceRange
	Provider          string
	Model             string
	EndpointAllowlist []string
	// SourceExcerpts are bounded quotes of the dropped messages, for the
	// summarize request only. The sealed envelope never carries them, so no
	// durable record or injected message contains excerpt content.
	SourceExcerpts []SourceExcerpt `json:"-"`
	// Focus is an optional caller-supplied bias string (e.g. `/compact <focus
	// instructions>`) telling the summarizer what to prioritize. It rides the
	// request only - never the sealed envelope the model echoes back or the
	// durable metadata - since it is host-side guidance, not conversation
	// content the model needs to round-trip.
	Focus           string                       `json:"-"`
	RedactionPolicy contextstate.RedactionPolicy `json:"-"`
}

type SummaryRequestBuilder func(Preparation) (SummaryRequest, error)

type TurnResult struct {
	User         []provider.Message
	Assistant    []provider.Message
	Tool         []provider.Message
	Active       []provider.Message
	Ordered      []provider.Message
	SourceEvents []contextstate.SourceEvent
	TurnID       uint64
	Outcome      string
	BaseDigest   string
}

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

type TurnStateSnapshot struct {
	State           string
	Decisions       []string
	Evidence        []string
	ChangedSurfaces []string
	OpenWork        []string
	Risks           []string
}

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