agent

type CharsByFour 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
}

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 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.
	//
	// 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"`
	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"`
}

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 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 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

	// 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 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
	// 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())
}

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
	// 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
	// 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

	// 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
}

type ValidatorFunc func(toolName, argsJSON string) error