agent

type CharsByFour struct{}

type CharsByThree struct{}

type ClearRequest struct {
	Clear   bool   `json:"clear"`
	GroupBy string `json:"group_by"`
	Key     string `json:"key"`
}

type Compaction struct {
	Marker   Entry   // Kind=KindCompaction, Content=summary, CreatedAt already placed
	Subsumes []Entry // the entries folded into Marker (Origin intact)
}

type CompactionInfo struct {
	Summary       string // the tight summary that replaced the folded prefix
	SubsumedCount int    // how many entries were folded into the summary
	TokensBefore  int    // estimated active-window tokens before this compaction
	TokensAfter   int    // estimated active-window tokens after

	// Duration is how long the fold took, dominated by the summarizer's own
	// round-trip. Reported because compaction is an unasked-for LLM call in the
	// middle of somebody's turn: it is the one part of a slow turn that is not
	// the work, and a host that cannot separate it will read its own latency
	// wrong. It is also the number that says whether compacting is cheaper than
	// the context it saves.
	Duration time.Duration

	// IndexErr is a failed Shaper.Index Put. The fold applied regardless; the
	// host decides whether a fold its index missed is worth saying.
	IndexErr error
}

type CompactionStart struct {
	SessionID string
	// TokensBefore is the active window that triggered the fold.
	TokensBefore int
	// Target is the size the shaper is folding down to. Together with
	// TokensBefore it says how much has to go.
	Target int
	// Subsuming is how many entries are about to be folded.
	Subsuming int
	At        time.Time
}

type ContextBuilder func(ctx context.Context, sessionID string, system string) ([]llm.Message, error)

type DocFinder interface {
	Find(ctx context.Context, texts []string) ([]DocHit, error)
}

type DocHit struct {
	DocID string  // stable id — the dedup key AND what the model passes to the fetch tool
	Title string  // human title
	Score float64 // relevance; hits below FinderOpts.MinScore are dropped
	Line  string  // one-line pointer (snippet/summary); NOT the document body
}

type Entry struct {
	ID      string
	Kind    EntryKind
	Content string
	// Parts, when non-empty, carries MULTIMODAL content (text + image, audio,
	// video or file parts)
	// for this entry and replaces Content when the entry is rendered to an
	// llm.Message. Content should still be set to a plain-text summary of the
	// parts: it is what LOD truncation, compaction summaries, and any
	// text-only consumer will see, so an entry with Parts but an empty Content
	// goes blank the moment the shaper substitutes a stub.
	//
	// Empty Parts (the overwhelming majority) renders exactly as before, so
	// existing hosts and stores are unaffected. A Store that does not persist
	// Parts simply loses the attachment across a reload, degrading to the text
	// Content — acceptable, and the reason Content stays authoritative. Media
	// parts hold their bytes as base64: a Store keeps a reference and rebuilds
	// Parts on load rather than persisting them.
	//
	// Only KindUser is rendered multimodally today; provider APIs accept image
	// parts on user messages, not on tool results or assistant turns.
	Parts      []llm.ContentPart
	ToolCallID string // correlates KindToolCall / KindToolResult

	// Usage records what the round-trip that PRODUCED this entry cost, stamped
	// on KindAssistant entries. It lives on the entry — and therefore in the
	// session log — rather than only in a trace sidecar, because the log is the
	// durable record: a replay can then answer how long each turn took and what
	// it spent without a second file that may not exist.
	//
	// Nil on every other kind, and omitted when marshalled, so stores and
	// consumers that predate it are unaffected.
	Usage *EntryUsage `json:"Usage,omitempty"`
	// Reasoning is the model's reasoning text for the round that produced this
	// entry, when the provider streamed it. Stamped on the entry that carries
	// the round's Usage: the KindAssistant reply, or — for a round with no
	// prose — its first KindToolCall.
	//
	// RECORD ONLY. It is never rendered into an llm.Message: replaying reasoning
	// would spend context on thought the model already acted on. A Store that
	// does not persist it loses nothing the loop needs.
	Reasoning string `json:"Reasoning,omitempty"`
	ToolName  string // the tool for KindToolCall / KindToolResult
	// Tag is an opaque display label used only when rendering a
	// KindNotification (e.g. the host's raw event-type "nudge"). Empty →
	// the Kind string is used.
	Tag string
	// Origin is an opaque host provenance tag. agent never reads it; it is
	// carried on entries returned by Store.Context and handed back inside
	// Compaction.Subsumes so the host can route subsumed rows to the right
	// storage (e.g. autowork3's public-delivery vs private-log streams).
	Origin    string
	CreatedAt int64 // ns; ordering key
}

type EntryKind string

type EntryUsage struct {
	LatencyMS int64 `json:"latency_ms,omitempty"`
	Cached    int   `json:"cached,omitempty"`
	Processed int   `json:"processed,omitempty"`
	Generated int   `json:"generated,omitempty"`
	// Reasoning is the part of Generated spent reasoning, and ReasoningSource
	// says where the number came from. An empty source means the provider
	// neither counted reasoning nor streamed it: UNKNOWN, not zero.
	Reasoning       int    `json:"reasoning,omitempty"`
	ReasoningSource string `json:"reasoning_source,omitempty"`

	// The model server's own report of this round (llama.cpp "timings"), when it
	// sent one, so a rate can be derived: cache read = CacheN/(CacheN+PromptN),
	// unfused prefill = PromptN/PromptMS, fused = (CacheN+PromptN)/PromptMS,
	// decode = PredictedN/PredictedMS, and the queue wait is LatencyMS less
	// PromptMS+PredictedMS. DraftN/DraftNAccepted are the speculative-decoding
	// counts. All omitted when absent: absent is unknown, not zero.
	CacheN         int     `json:"cache_n,omitempty"`
	PromptN        int     `json:"prompt_n,omitempty"`
	PromptMS       float64 `json:"prompt_ms,omitempty"`
	PredictedN     int     `json:"predicted_n,omitempty"`
	PredictedMS    float64 `json:"predicted_ms,omitempty"`
	DraftN         int     `json:"draft_n,omitempty"`
	DraftNAccepted int     `json:"draft_n_accepted,omitempty"`
}

type FinderOpts struct {
	// MinScore drops hits below this relevance. Default 0 (keep all) — set it,
	// or the passive channel is a firehose.
	MinScore float64
	// MaxHits caps notices injected per pass (the "hard top-k into the prompt"
	// defense against context rot). Default 3; <=0 means uncapped.
	MaxHits int
	// Tag labels the injected KindNotification (render.go prefixes "[tag] ").
	// Default "rag".
	Tag string
	// Kinds selects which entry kinds to observe. Default: KindUser +
	// KindAssistant (listen to both the user's request and the agent's reply).
	Kinds []EntryKind
	// Timeout bounds a single Find call so a slow finder can't stall the Turn.
	// On timeout (or any Find error) the pass fails OPEN: no notice, and the
	// watermark does NOT advance, so the same entries are retried next pass.
	// Default 3s; <=0 means no timeout (inherit the ctx deadline only).
	Timeout time.Duration
	// Render formats a hit into the notice body. Default: a pointer line that
	// tells the model to fetch the body with the search tool.
	Render func(DocHit) string
	// Now overrides the clock (tests). Default time.Now().UnixNano.
	Now func() int64
}

type LLMRunner interface {
	ChatStream(ctx context.Context, messages []llm.Message, tools []llm.ToolDef, opts *llm.ChatOpts) (<-chan llm.StreamChunk, error)
}

type LODKeep string

type LiftRequest struct {
	Pending       bool   `json:"pending"`
	CorrelationID string `json:"correlation_id"`
	TTLSeconds    int    `json:"ttl_s"`
}

type NotificationPreparer interface {
	PrepareNotifications(ctx context.Context, sessionID string) error
}

type Overflow struct {
	// PromptTokens and Generated are the PROVIDER's counts for the round that
	// was cut, or 0 when it reported none. Provider numbers rather than
	// estimates on purpose: the host is about to decide whether the prompt or
	// the response filled the window, and that decision is exactly the one an
	// estimate gets wrong.
	PromptTokens int
	Generated    int

	// TruncatedToolCalls names the calls whose arguments the cut left
	// unparseable. Empty means the cut landed in prose — see Retry, which is
	// only consulted in that case.
	TruncatedToolCalls []string

	// Attempt counts consecutive cut rounds in this Turn, from 1. A host uses it
	// to escalate: hint first, shed context after that.
	Attempt int
}

type OverflowDecision struct {
	// Note is appended to the conversation as a tail-kept notification tagged
	// OverflowTag. Empty appends nothing.
	Note string
	// Retry re-runs the round after the note is appended. Only consulted when
	// the cut landed in PROSE: a cut tool call is already answered with an error
	// result, and re-running the round on top of that would ask the model the
	// same question twice.
	//
	// The point of retrying is that the host has CHANGED something first —
	// compacted the history, lowered a budget, queued the note. Retrying without
	// changing anything reproduces the cut exactly, which is the loop this whole
	// file exists to break.
	Retry bool
}

type PendingNotice struct {
	GroupBy string // e.g. "file"
	Key     string // e.g. "src/main.go"
}

type PreparerFunc func(ctx context.Context, sessionID string) error

type RecapSink interface {
	Store(entries []Entry) (name string, err error)
}

type RecapSpan struct {
	// Subsumes are the entries that would leave the context.
	Subsumes []Entry
	// Kept are entries preserved inside the span: tool pairs named by `keep`,
	// and the live call that must survive.
	Kept []Entry
	// Anchor is the entry the phrase matched; nil means the start of the
	// session.
	Anchor *Entry
	// Chars is how much would leave.
	Chars int
	// Unmatched are keep terms that named nothing. Reported rather than
	// ignored: a model that asked to keep a result and silently lost it has been
	// told the opposite of the truth.
	Unmatched []string
	// KeptCalls names the tools kept, for the report.
	KeptCalls []string
}

type RevalidateStore interface {
	// PendingNotices lists the session's unshown notices carrying a group key.
	PendingNotices(ctx context.Context, sessionID string) ([]PendingNotice, error)
	// Clear retracts the notice for (groupBy, key) in the session.
	Clear(ctx context.Context, sessionID, groupBy, key string) error
}

type Revalidator interface {
	Revalidate(ctx context.Context, groupBy, key string) (result string, ok bool, err error)
}

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

type Session struct {
	ThreadID  string // opaque grouping label (stamped on spans + the chat trace id)
	SessionID string
	System    string // baseline system prompt

	Store    Store
	Runner   LLMRunner
	Build    ContextBuilder // nil → DefaultContextBuilder over Store
	Tools    []llm.ToolDef
	Dispatch ToolDispatcher

	// ToolFormat selects the tool-call transport. Empty = the provider's native
	// tool_calls. See ToolFormatHeredoc for when to leave it.
	ToolFormat ToolFormat

	// ChatOpts forwards LLM-call options on every round-trip. Nil OK. Used
	// by protocol-bound roles to force tool_choice=required.
	ChatOpts *llm.ChatOpts

	// OnAssistantToken, if set, receives streamed content chunks for
	// SSE / live broadcast.
	OnAssistantToken func(string)

	// OnTurnStart, if set, fires once at the top of Turn, before the first chat
	// round. Paired with OnTurnEnd, which fires on every exit path.
	OnTurnStart func(TurnStart)

	// OnTurnEnd, if set, fires exactly once per Turn with WHY the loop stopped,
	// and with how much of its wall clock the proxy admits was not the model.
	//
	// The reason is the point. Without it a host distinguishes six exits by the
	// text of an error, so "a terminal tool closed the session" and "the store
	// failed" look alike to anything that is not a person reading a log.
	OnTurnEnd func(TurnEnd)

	// OnCompactionStart, if set, fires when the Shaper decides to fold, BEFORE
	// the summarizer is called. Paired with OnCompactionComplete.
	//
	// Compaction is the one thing that happens to a turn without anyone asking,
	// and it costs an LLM round-trip. With only a completion hook a host cannot
	// say "this is compacting" while it happens — the turn stalls and the reason
	// arrives after the wait is over.
	OnCompactionStart func(CompactionStart)

	// OnCompactionComplete, if set, fires when the fold is recorded — the same
	// info Turn returns in TurnResult.Compactions, plus how long it took.
	//
	// The summary is the whole record of what was folded: an append-only host
	// stores THIS, not a flag on the entries it replaced. See CompactionInfo.
	OnCompactionComplete func(CompactionInfo)

	// OnUsage, if set, fires after each chat round with the running token tally
	// (cumulative Total + current Active window). Mirrors TurnResult.Usage.
	OnUsage func(TokenUsage)

	// OnToolCalls, if set, is called with the tool calls returned by the
	// model, before they are persisted or dispatched. The callback may add,
	// remove, or modify the slice. A returned nil or empty slice is treated
	// as "no tool calls" (the turn ends or checks for pending events).
	//
	// This is the seam for injecting host-initiated tool calls that appear
	// as if the model made them — e.g. a /ship command that forces the
	// assistant to call the ship tool, so the exchange is persisted as
	// assistant(tool_calls) → tool(result), not as a disembodied Aside.
	OnToolCalls func([]llm.ToolCall) []llm.ToolCall

	// OnOverflow, if set, fires when the provider ended a round with
	// finish_reason="length" — it ran out of room mid-response. The host decides
	// what to say and whether to retry; see overflow.go for why the policy
	// cannot live here.
	//
	// Nil means the previous behaviour: a cut tool call is still answered with
	// an error result (the model can retry smaller), and a cut REPLY still ends
	// the turn half-finished. The second of those is the one worth setting this
	// for.
	OnOverflow func(context.Context, Overflow) OverflowDecision

	// OnIdle, if set, is asked when the model ends a round with no tool calls
	// and nothing is pending: the point where the Turn would end. A non-empty
	// note is appended as a notification and the Turn runs another round, so
	// the host can make the model check its work before it stops. rounds is
	// how many rounds this Turn has run; asks counts earlier non-empty answers
	// in this Turn, so the host bounds itself (return "" to let the Turn end).
	OnIdle func(ctx context.Context, rounds, asks int) string

	// MaxOverflowRetries bounds consecutive length-cut rounds in one Turn before
	// the Turn fails with the evidence. 0 → 2. Negative → unbounded, which is
	// only sane if OnOverflow sheds context on every pass.
	MaxOverflowRetries int

	// Estimate counts tokens for the Active-window figure. Nil → Default()
	// (chars/4). Set to the same estimator the Shaper uses for consistency.
	Estimate TokenEstimator

	// MaxTurns caps the loop (default 100 — generous, since a role may chain
	// read tool calls before its terminal output; better to pay extra
	// round-trips than wedge the pipeline). Tests set this small.
	MaxTurns int

	// ForcedTerminalTool, when non-empty, names the single tool the caller
	// pinned via ChatOpts.ToolChoice as the session's only legitimate exit.
	// If MaxTurns elapses without the model ever invoking it, Turn returns a
	// diagnostic naming the tool — distinguishing "ran out of budget" from
	// "provider silently ignored tool_choice and never called the right
	// tool". Empty for roles where every tool is acceptable.
	ForcedTerminalTool string

	// MaxRepetitionRetries caps how many CONSECUTIVE rounds may be cut for
	// degenerate repetition (llm.RepetitionGuard) before Turn gives up. 0 → 2;
	// negative → unlimited (MaxTurns still bounds the loop).
	//
	// Each cut round costs a re-prompt, and a model that has collapsed twice
	// running usually collapses on the third: past that the retries reproduce
	// the very cost the cut exists to avoid, just in installments.
	MaxRepetitionRetries int

	// MaxRepeatedExchanges bounds the TURN-level loop: consecutive rounds whose
	// tool calls AND their results are byte-identical. At this many, the model
	// is told; at twice this many, Turn stops. 0 → 5; negative → off.
	//
	// The result is part of the comparison on purpose — see the check in Turn.
	// A poll whose answer keeps changing is progress and must never trip this.
	MaxRepeatedExchanges int

	// Preparer, if set, revalidates + clears stale pending notifications
	// before each iteration's context is built (the prepareNotifications-
	// BeforeSend seam). Nil = no preparation.
	Preparer NotificationPreparer

	// SpanPrefix names the span namespace (default "agent"): spans are
	// "<prefix>.Turn" and "<prefix>.streamChat". A host sets this to keep
	// its existing observability labels stable.
	SpanPrefix string

	// OmitSlotInstructions suppresses the automatic append of SlotSystemNote to
	// the system prompt (see transclude.go). By default, when Tools are attached
	// agent teaches the model the {OUTPUT}/{name} transclusion convention; set
	// this when the host writes those instructions itself or wants them gone.
	OmitSlotInstructions bool

	// MaxToolResultChars, if > 0, caps how much of each tool result the MODEL
	// sees: a longer result is truncated (head+tail, with a marker) in the
	// context sent this round. Storage keeps the COMPLETE result, and the
	// truncation is view-only — a reply can still surface the full bytes to the
	// user with {OUTPUT}/{name} (see transclude.go). The marker tells the model
	// the escape hatch exists. 0 = no truncation (default; no behavior change).
	MaxToolResultChars int

	// EncodeToolResult, if set, re-encodes a raw tool-result string BEFORE it is
	// stored + rendered into the model's context — e.g. JSON → YAML/TOON/CSV for a
	// terser, more token-efficient representation. nil = passthrough (the raw
	// result is stored unchanged). The transform must be information-preserving:
	// the model only READS the result, so a non-JSON representation is safe.
	EncodeToolResult func(raw string) string

	// Now is overridable in tests.
	Now func() int64

	// Tracer optionally captures spans. Nil = no tracing.
	Tracer Tracer
	// contains filtered or unexported fields
}

type SessionDoc struct {
	// Key names the document within the session ("fold-<id>", "recap-<id>").
	// The implementation places it under the session's own prefix.
	Key string
	// Kind is "fold" or "recap".
	Kind string
	// Name is a short title: the task the span was worked under, or its first
	// request.
	Name string
	// Summary is what replaced the span in context.
	Summary string
	// Body is the span itself, one event per line.
	Body string
}

type SessionHit struct {
	Key     string  `json:"key"`
	Name    string  `json:"name,omitempty"`
	Snippet string  `json:"snippet"`
	Score   float64 `json:"score,omitempty"`
}

type SessionIndex interface {
	// Put stores one document. It runs inside a turn, after a fold or a recap
	// has applied, so it must return quickly: queue the work, do not wait for
	// it. An error does not undo the fold.
	Put(ctx context.Context, d SessionDoc) error
	// Search returns the n best matches for q.
	Search(ctx context.Context, q string, n int) ([]SessionHit, error)
	// Close is the session's terminal end: remove what it put, or leave it to
	// expire, as the implementation was configured. A host calls it once, and
	// never for a session that pauses to be continued.
	Close(ctx context.Context) error
}

type ShapeHint struct {
	// Window is the endpoint's own context size, or 0 when it did not say.
	Window int
	// Scale is real tokens per estimated token, from the refused prompt, or 0
	// when unknown. Above 1 the estimator undercounts and limits shrink by it.
	Scale float64
}

type Shaper struct {
	Store    Store
	Runner   LLMRunner
	Estimate TokenEstimator
	Policy   ShaperPolicy
	// SpanPrefix names the span namespace (default "agent"): the build span
	// is "<prefix>.Shaper.Build". A host sets this to keep its labels stable.
	SpanPrefix string
	Tracer     Tracer // optional; nil = no spans
	// ToolLOD says which end of a truncated result each tool answers at.
	//
	// Keyed by tool name; absent means LODHead, which is right for the majority
	// (a file, a listing, a search). It is a property of the TOOL, known where
	// the tool is registered, so the shaper is told rather than guessing — and
	// it cannot ride on `llm.ToolDef`, which is the wire shape sent to the
	// provider.
	ToolLOD map[string]LODKeep

	// Pause, if set, is called before the compaction LLM call and returns the
	// resume func. A host uses it to STOP the turn's budget clock for the
	// duration of the summarize call: compaction is bookkeeping, not model
	// work, so it must not burn the turn's time budget. Without this, a slow
	// endpoint + a long compaction can run the turn past its budget MID-fold,
	// cancelling the compaction worker with a bare "context canceled" that
	// reads as a crash. nil = no pause (the call runs on the caller's context
	// and budget as-is).
	Pause func() (resume func())

	// SummaryOpts are the fold call's request options; nil sends none, and the
	// server's defaults decide. A host sets thinking off here: a summarizer that
	// thinks spends its budget before it writes, and on a server whose default
	// thinks, a fold cost thousands of reasoning tokens to write a few hundred.
	// The fold sends a copy with MaxTokens set from the summary budget.
	SummaryOpts *llm.ChatOpts

	// SummaryTokens sizes a fold's summary from the tokens being folded, the
	// tokens the prompt keeps beside the summary, and the build's target (0
	// for a fold that was asked for, not forced). nil = DefaultSummaryTokens.
	SummaryTokens func(folded, kept, target int) int

	// SummaryPrompt writes a fold's instructions from the task ("" when there
	// is none) and the budget in tokens; the numbered events follow it. nil =
	// DefaultSummaryPrompt. A host wraps the default to add to it, or writes
	// its own: what a summary must keep depends on what the host runs.
	SummaryPrompt func(task string, budget int) string
	// SummarySystem is the fold call's system message; "" =
	// DefaultSummarySystem.
	SummarySystem string

	// TaskFunc, when set, is the task at each fold and wins over Task: a
	// host's task changes during a session (a goal set, a plan revised, work
	// started), and a string set once goes stale.
	TaskFunc func() string

	// Task is what the session is FOR, shown to the summarizer on every fold.
	//
	// A fold sends only the oldest entries, and the summarizer was told nothing
	// else — so it judged what mattered by what was there, and one large early
	// tool result dominated the summary while the task it was read for went
	// unmentioned. The task is the measure of what to keep.
	//
	// Empty → Build falls back to the system prompt it was given, which is
	// where a host normally states the task. Compact has no system prompt, so
	// a host that forces folds sets this.
	Task string

	// Rehead, if set, is the host's own way to shrink the context, tried once
	// per Build just before a compaction fold — after the window has been
	// found over target even with LOD.
	//
	// It exists because a fold is the one moment the prompt prefix is
	// rewritten anyway: any other rewrite of earlier context breaks the
	// provider's prompt cache from that entry on, once per rewrite. A host that
	// knows some entries are redundant (a file read that a later, wider read
	// covers; a read made stale by an edit) replaces them here, through its
	// Store, and the cache is broken once for both. Rehead reports whether it
	// changed the context; when it did, Build re-reads the context and checks
	// the budget again, and the fold runs only if the window is still over.
	//
	// The host owns its errors: a re-heading that fails reports false and the
	// fold proceeds as it would have without one. nil = no re-heading, which is
	// the behavior before this field existed.
	Rehead func(ctx context.Context, sessionID string) (changed bool)

	// Index, if set, keeps each fold's subsumed entries searchable, with the
	// fold's summary as their description (see SessionIndex). A failed Put
	// does not undo the fold; it is reported in CompactionInfo.IndexErr.
	Index SessionIndex
}

type ShaperPolicy struct {
	// BudgetTokens is the model's usable context window in tokens.
	//
	// ZERO (or negative) means UNBUDGETED: no LOD, no compaction, the
	// conversation is rendered whole. It cannot mean "a budget of nothing" —
	// that reading cost a real session 45 compactions in 29 minutes, one per
	// turn, each spending a summarization call to fold history that had just
	// been summarized, leaving 5 surviving entries out of 50. A host that has
	// not been told the window size must not have its history destroyed on
	// that basis.
	BudgetTokens          int
	PreserveLastMessages  int
	PreserveLastToolCalls int

	// VerbatimToolResults passes tool-result content to the model byte for byte,
	// INCLUDING chat-template control tokens. Off by default.
	//
	// Set it only when the server's chat template neutralizes those tokens
	// itself, which is the right place for the fix: it costs nothing there and
	// covers every client. Left off against a stock template, `<|im_start|>` in a
	// file — a log, a README, a document about the template — tokenizes to the
	// real control token and opens a turn inside the prompt. Verified end to end:
	// the rendered turn sequence gains a SYSTEM message that came from disk.
	//
	// Probe a server before turning this on: ml-kit/templates/probe.py render
	// grades a template's tier-1 (frame-breaking) behavior, and llm.ProbeToolSurface
	// checks a live endpoint's tool-call round trip.
	VerbatimToolResults bool

	// ToolFormat must match the Session's, so replayed history is shown in the
	// same dialect the model writes.
	ToolFormat            ToolFormat
	LODTruncateAboveChars int
	// MaxToolResultChars bounds a single tool result REGARDLESS of age.
	//
	// LODTruncateAboveChars only reaches entries older than the preserved tail.
	// That exemption protects the result a session is about to act on, and it
	// means one oversized result rides in the window whole for as many turns as
	// the tail is long. This is the floor under that: the freshest result may be
	// large, but not unbounded. 0 → no limit.
	MaxToolResultChars int
	// LODHeadroomTokens is the runway kept below BudgetTokens. The Shaper
	// restructures (LOD, then compaction) once the estimated context would
	// exceed BudgetTokens-LODHeadroomTokens — NOT at the hard budget. Keeping
	// headroom means the prompt prefix is rewritten (and the KV cache
	// invalidated) in one decisive pass with room to spare, instead of eagerly
	// re-truncating a little more every turn. 0 → defaultLODHeadroom (10k);
	// negative → no headroom (restructure only at BudgetTokens).
	LODHeadroomTokens int
	// LODStep is how many entries the LOD boundary moves at a time. Entries
	// older than the pristine tail are stubbed, and the tail moves by one tool
	// call per turn; stubbing right up to it rewrites one already-sent result
	// from verbatim to stub on every turn, and a prompt cache keyed on the
	// prefix is invalid from that entry on. So the boundary is rounded down to a
	// multiple of LODStep: between steps history only grows at the end, and at a
	// step a whole batch is stubbed together. Entries between the rounded
	// boundary and the tail ride verbatim, at most LODStep-1 more than the
	// policy preserves; if that does not fit the budget the boundary steps
	// further (never back), up to the exact tail edge. 0 → defaultLODStep;
	// 1 → the exact edge every turn (the old behavior).
	LODStep int
	// PinFirstUser keeps the session's first user entry verbatim for the life
	// of the session. A host that states the session's subject in that message
	// (rather than in the system message, to keep the system message identical
	// across sessions) needs it to survive: older entries are otherwise
	// LOD-truncated once over budget and the oldest are folded into a
	// summary, and the subject is the oldest entry there is. A pinned entry is
	// never stubbed, never counted among the entries a fold subsumes, and
	// stays where it was.
	PinFirstUser bool
	// AlwaysLOD forces LOD (level-of-detail) truncation of oversized older
	// entries on EVERY Build, from Phase 0 on — skipping the "pristine, no-LOD"
	// fast path that otherwise leaves the context untouched while under budget.
	// Use it to force LOD every turn (e.g. a benchmark measuring recall over
	// truncated history). LOD is render-time and stateless — there is no
	// persisted-LOD op — so a policy flag, not a stored operation, is the right
	// shape for this knob.
	AlwaysLOD bool
}

type Span interface {
	Set(key string, value any) Span
	End()
	EndError(err error)
}

type Store interface {
	// ClaimPending marks the session's pending inbox arrivals as shown and
	// returns how many there were. The loop uses the count to decide whether
	// a re-prompt is warranted; the entries themselves surface via Context.
	ClaimPending(ctx context.Context, sessionID string, at int64) (int, error)
	// Append persists one entry (an assistant reply, a tool result, …).
	Append(ctx context.Context, sessionID string, e Entry) error
	// Context returns the session's non-subsumed entries (any order; the
	// engine sorts). The host merges whatever internal streams it has into
	// this single list.
	Context(ctx context.Context, sessionID string) ([]Entry, error)
	// Compact records a compaction marker + flags the subsumed entries, in
	// one transaction.
	Compact(ctx context.Context, sessionID string, c Compaction) error
}

type TokenEstimator interface {
	Estimate(s string) int
}

type TokenUsage struct {
	// Total is cumulative prompt+completion tokens billed across every chat
	// round of this Session's lifetime (what you paid). A host that reuses one
	// Session across a whole conversation sees the running total; one that makes
	// a fresh Session per Turn should persist + sum these itself.
	Total int
	// Active is the token count of the CURRENT live window — the built
	// (compacted + LOD) context the model sees now, INCLUDING any compaction
	// summary. This is the underlying-session size, distinct from Total.
	Active int

	// Cached, Processed and Generated split Total into the three channels that
	// actually price differently. Total alone is close to useless for judging
	// cost: it is dominated by the re-sent prefix, which is the CHEAPEST part.
	// Measured on one agent run, Total was 97% Cached — so ranking two runs by
	// Total ranks them by how much cache they read.
	//
	//   Cached    prompt tokens served from the provider's cache. Nearly free
	//             (llama.cpp reuses the KV slot; ~17x faster than generation).
	//   Processed prompt tokens the provider actually had to evaluate. In an
	//             agent loop this is mostly TOOL RESULTS — the honest per-turn
	//             input cost, and the thing a tool surface controls.
	//   Generated completion tokens. The most expensive per token, and usually
	//             the binding constraint, since output caps are hit long before
	//             context limits.
	//
	// A provider that reports no cache breakdown leaves Cached at 0 and puts the
	// whole prompt in Processed, which is the correct reading for that provider.
	Cached    int
	Processed int
	Generated int

	// Reasoning is the part of Generated known to be reasoning, summed over the
	// rounds whose reasoning is known. ReasoningReported and ReasoningEstimated
	// count those rounds by source; Turns minus both is the rounds whose
	// reasoning was not reported, which Reasoning does not include.
	Reasoning          int
	ReasoningReported  int
	ReasoningEstimated int

	// Turns counts chat round-trips accumulated into this tally — the divisor
	// for any per-turn figure.
	Turns int
}

type ToolDispatcher func(ctx context.Context, tc llm.ToolCall) (string, error)

type ToolFormat string

type Tracer interface {
	// Start opens a span named `name` and returns it plus a child context
	// carrying the span, so nested Starts chain into a tree.
	Start(ctx context.Context, name string) (Span, context.Context)
}

type TurnEnd struct {
	SessionID string
	ThreadID  string
	// Reason is why the loop stopped. Always set.
	Reason TurnEndReason
	// Err is the error Turn returned, nil on the clean exits.
	Err error
	// Rounds is how many chat rounds the loop ran, 1-based.
	Rounds int
	// Usage is the running tally as of the end of the turn.
	Usage TokenUsage
	// Duration is wall clock from OnTurnStart to here. See the type comment
	// before charging anyone for it.
	Duration time.Duration

	// ServerOverheadMS is what the proxy reported spending NOT running the
	// model — admission queueing plus cold loads — summed over the turn's
	// rounds. Subtract it from Duration to stop billing a caller for the queue
	// it waited in.
	ServerOverheadMS int64
	// ServerTimingSeen distinguishes "the proxy reported no overhead" from
	// "nothing reported". A plain OpenAI endpoint says nothing, and a host that
	// read a confident zero there would subtract an overhead it never measured.
	// False means ServerOverheadMS is unknown, not zero.
	ServerTimingSeen bool
}

type TurnEndReason string

type TurnResult struct {
	Reply       string
	Compactions []CompactionInfo // usually empty or one; more if a huge context folds in stages
	Usage       TokenUsage
}

type TurnStart struct {
	SessionID string
	ThreadID  string
	At        time.Time
}

type Validator interface {
	ValidateArgs(toolName, argsJSON string) error
}