chat

type CachingChatClient interface {
	ChatClient

	// AddCached appends a user turn and asks the provider to cache it, so
	// later calls carrying the same prefix are billed at the cached rate.
	//
	// A hint, not a guarantee. Every provider declines to cache content below
	// a minimum size — 1024 tokens on Gemini and OpenAI, and between 512 and
	// 4096 on Claude depending on the model — and most do so silently. The
	// call still succeeds and the content is still sent; it is simply not
	// cached.
	//
	// Confirm the effect through Usage.CachedTokens rather than assuming it.
	// That is what the providers' own documentation recommends, and a number
	// that moves is worth more than a promise in this interface.
	AddCached(ctx context.Context, prompt string, media ...Media) error
}

type CachingSupport struct {
	// Explicit reports whether content can be marked for caching deliberately.
	Explicit Support
	// Implicit reports whether the provider caches eligible prefixes with no
	// action from the caller.
	Implicit Support
	// ImplicitMinTokens is the prefix size at which implicit caching begins to
	// engage. Zero means unknown.
	ImplicitMinTokens int
	// MinCacheableTokens is the smallest block a provider will cache at all.
	// Zero means unknown.
	MinCacheableTokens int
	// TTLs lists the retention periods the provider accepts. Empty means
	// unknown; providers offer discrete choices rather than arbitrary durations.
	TTLs []time.Duration
}

type Capabilities struct {
	// Supported maps each capability to its support level. A capability absent
	// from the map reports SupportUnknown, which is the zero value, so a
	// partially-populated map is always safe to read.
	Supported map[Capability]Support

	// Sampling, Effort and Caching carry specifics where a provider supplied
	// them. Nil means the provider said nothing.
	Sampling *SamplingSupport
	Effort   *EffortSupport
	Caching  *CachingSupport
}

type Capability string

type CapabilityResolver func(model string) ModelInfo

type ChatClient interface {
	// Add appends a user message to the conversation history without
	// triggering a completion. The message persists for subsequent
	// Chat() or Ask() calls.
	//
	// Under Config.Stateless the message is buffered rather than retained: it
	// is sent with the next Chat/Ask/StreamChat call and then cleared.
	Add(ctx context.Context, prompt string, media ...Media) error
	// Ask sends a question and unmarshals the structured response into
	// target. If Config.ResponseSchema was set during construction, the
	// provider enforces that schema. If no schema is set, the provider
	// returns the raw text content unmarshalled into target (which must
	// be a *string or implement json.Unmarshaler).
	//
	// The question and the answer are appended to the conversation, so a
	// subsequent call re-sends them. Callers making independent calls — batch
	// classification, extraction, judging — want Config.Stateless; without it,
	// each call carries every call before it.
	//
	// Ask is tool-free: tools registered with SetTools are not offered to the
	// model. Ask promises a structured answer, and a model that replies with a
	// tool call has not delivered one. Use Chat for tool use, then Ask to shape
	// the result — Chat commits its tool calls and their results to the
	// conversation, so a following Ask can read them:
	//
	//	client.SetTools(tools)
	//	_, _ = client.Chat(ctx, "research X with the tools")
	//	var out Report
	//	_ = client.Ask(ctx, "now give me that as JSON", &out)
	//
	// That idiom costs an extra round-trip, and it does not work under
	// Config.Stateless, where the session is dropped rather than committed.
	//
	// The contract is enforced by the shared conformance suite as each provider
	// module adopts a core release carrying it, so a provider pinned to an
	// earlier core may still offer tools to Ask.
	Ask(ctx context.Context, question string, target any, media ...Media) error
	// SetTools configures the tools available to the AI. This replaces
	// (not appends to) any previously set tools.
	SetTools(tools []Tool) error
	// Chat sends a message and returns the response content. If tools
	// are configured, the provider handles tool calls internally via a
	// ReAct loop bounded by Config.MaxSteps (default 20).
	//
	// Like Ask, the exchange is appended to the conversation and re-sent by the
	// next call unless Config.Stateless is set.
	Chat(ctx context.Context, prompt string, media ...Media) (string, error)
	// Usage returns the cumulative token usage across every provider
	// round-trip made by this client instance since construction. A single
	// Chat/Ask/StreamChat call may make multiple round-trips (one per ReAct
	// step) and all are summed. Providers that do not report token counts
	// (e.g. ProviderClaudeLocal) contribute a zero, Known == false Usage.
	// Wire Config.UsageObserver to observe usage per round-trip instead.
	Usage() Usage
	// History reports the conversation this client is carrying — how many turns
	// it will re-send on the next call, and the provider's own token count for
	// the last call it made.
	//
	// Every provider appends and re-sends, so a long-lived conversation grows
	// until it overflows the model's context window. This is what makes that
	// growth visible in time to do something about it: reset the client, or set
	// Config.Stateless if the calls were independent all along.
	//
	// Check History.Known before trusting Turns.
	History() History
}

type ClaudeLocal struct {
	UsageTracker
	// contains filtered or unexported fields
}

type ClaudeLocalOption func(*claudeLocalOptions)

type Command struct {
	// Name is the verb, without its leading slash.
	Name string
	// Summary is one line, shown by [HelpCommand].
	Summary string
	// Run performs it. A nil Run makes the command listable but inert, which is
	// useful for describing a command the consumer handles itself.
	Run CommandFunc
}

type CommandFunc func(ctx context.Context, req CommandRequest) (CommandResult, error)

type CommandRequest struct {
	// Client is the client the command acts on.
	Client ChatClient
	// Args is everything after the verb, trimmed. Empty when none was given.
	Args string
	// Set is the whole registered set, so a command can describe its siblings.
	// [HelpCommand] is the reason this is here.
	Set CommandSet
}

type CommandResult struct {
	// Name is the command that ran, without its leading slash.
	Name string
	// Text is human-readable output. It may be empty for a command that only
	// acts.
	Text string
	// Changed reports whether the conversation was altered.
	Changed bool
}

type CommandSet []Command

type CompactOption func(*compactOldest)

type Config struct {
	// Provider is the AI service provider to use.
	Provider Provider
	// Model is the specific model to use (e.g. "claude-opus-5", "gpt-5.6-sol").
	//
	// Empty selects the provider's default — see [DefaultModelClaude],
	// [DefaultModelOpenAI] and [DefaultModelGemini]. Those are chosen by one
	// rule applied to every provider: the most capable model the provider makes
	// generally available that supports the module's baseline capabilities.
	//
	// The defaults therefore favour capability over cost, because a default is
	// what a caller gets having expressed no preference. Set this field if cost
	// matters, if you need a particular model's behaviour, or if you want a
	// model pinned against vendor churn.
	Model string
	// Token is the API key or token for the service.
	Token string
	// Credentials carries provider-specific credential config resolved by the
	// host application. Token still wins when both are set.
	Credentials CredentialConfig `json:"-" mapstructure:"-" yaml:"-"`
	// Project is the cloud project a provider addresses. Required by
	// ProviderGeminiVertex, which falls back to GOOGLE_CLOUD_PROJECT when it is
	// empty and refuses to construct when both are. Ignored by every other
	// provider.
	//
	// It lives here rather than on a provider's constructor because this is the
	// only surface a config file decodes into, and an option is a function call.
	// See spec 0017 D7 and D10.
	Project string
	// Location is the region a provider addresses. Required by
	// ProviderGeminiVertex, which falls back to GOOGLE_CLOUD_LOCATION when it is
	// empty and refuses to construct when both are.
	//
	// Named for the concept rather than for one vendor: AWS Bedrock addresses by
	// region and means the same thing by it. See spec 0017 D7.
	Location string
	// BaseURL overrides the API endpoint. Required when using ProviderOpenAICompatible.
	// Example: "http://localhost:11434/v1" for Ollama, "https://api.groq.com/openai/v1" for Groq.
	BaseURL string
	// SystemPrompt is the initial system prompt to set the context for the AI.
	SystemPrompt string
	// ResponseSchema is the JSON schema used to force a structured output from
	// the AI. Build one with [GenerateSchema].
	//
	// Typed since v0.8.0; it was any beforehand, so the only statement of its
	// contract was a check in New that the compiler could not read.
	ResponseSchema *jsonschema.Schema
	// SchemaName is the name of the response schema (e.g., "error_analysis").
	SchemaName string
	// SchemaDescription is a description of the response schema.
	SchemaDescription string
	// MaxSteps limits the number of ReAct loop iterations in Chat().
	// Zero means use the default (DefaultMaxSteps = 20).
	MaxSteps int
	// MaxTokens sets the maximum tokens per response.
	// Zero means use the provider default (OpenAI: 4096, Claude: 8192, Gemini: 8192).
	MaxTokens int
	// RequestTimeout bounds a single HTTP request to the provider. Zero falls
	// back to the ai.request_timeout config key, then DefaultChatRequestTimeout.
	// Bounded on purpose so a stuck model fails rather than hanging forever.
	RequestTimeout time.Duration
	// HTTPClient, when non-nil, is used verbatim for provider API calls. The
	// host injects a hardened transport here (go-tool-base supplies one built on
	// the go/httpclient module);
	// nil ⇒ the module builds a plain bounded client from RequestTimeout.
	HTTPClient *http.Client `json:"-" mapstructure:"-" yaml:"-"`
	// HistoryPolicy bounds the conversation before each call. Nil leaves it
	// unbounded, which is the default and what every provider did before.
	//
	// Use it for a conversation that legitimately accumulates. For independent
	// calls that never needed history at all, Stateless is the cheaper answer.
	//
	// [TruncateOldest] is the policy the module ships. A policy never drops a
	// turn added with AddCached and never splits a tool request from its
	// results; [ApplyHistoryEdit] enforces both, so a policy that gets them
	// wrong fails loudly rather than corrupting a transcript.
	HistoryPolicy HistoryPolicy `json:"-" mapstructure:"-" yaml:"-"`

	// ParallelTools enables concurrent execution of multiple tool calls
	// within a single ReAct step. Disabled by default.
	ParallelTools bool
	// MaxParallelTools limits the number of tools executing concurrently.
	// Zero means use the default (5). Only effective when ParallelTools is true.
	MaxParallelTools int

	// Temperature, when non-nil, overrides the provider's default sampling
	// temperature. Nil samples at the provider's default.
	//
	// Passed through in the provider's own units and never rescaled: ranges
	// differ (Claude 0-1, OpenAI 0-2, Gemini 0-2) and quietly rescaling what
	// the caller asked for would be worse than making them read the range. The
	// value is validated against the selected provider's range before any
	// request is made.
	//
	// Support is narrowing sharply as vendors move to reasoning models, and
	// **none of the three default models accepts it**: it is deprecated on
	// claude-opus-5, rejected by gpt-5.6-sol (which permits only its default of
	// 1), and absent from claude-local entirely. Gemini still accepts it, as do
	// older models on every provider — but reaching them means setting [Model]
	// explicitly.
	//
	// Setting it against a provider that has no sampling concept is a
	// construction error; a model that refuses it yields
	// [ErrModelRejectedParameter] at request time. See [Effort], which is the
	// forward-looking control, is supported everywhere, and is what these
	// models expect to be steered with instead.
	//
	// Lower values reduce variance between runs. They do not make output
	// deterministic — see the sampling how-to.
	Temperature *float64

	// TopP, when non-nil, overrides the provider's default nucleus-sampling
	// threshold, on a 0-1 scale. Nil samples at the provider's default.
	//
	// Providers recommend adjusting temperature or top-p, not both.
	//
	// Its support is narrowing alongside [Temperature]: gpt-5.6-sol rejects it
	// outright, where gpt-5.4 accepted it. The same guidance applies — prefer
	// [Effort] on reasoning models, or set [Model] to one that still takes it.
	TopP *float64

	// Effort selects how much reasoning the model spends before answering.
	// Empty uses the provider's default.
	//
	// This is the forward-looking sibling of Temperature: every provider
	// supports it, including claude-local, and on reasoning models it is the
	// control that replaced temperature. It is also the most direct cost dial
	// in Config — observe its effect through Usage.ReasoningTokens.
	Effort Effort

	// CacheTTL requests how long a provider retains content marked with
	// CachingChatClient.AddCached. Zero uses the provider default.
	//
	// Providers offer discrete choices rather than arbitrary durations and
	// select the nearest they support: Claude offers 5 minutes or 1 hour,
	// Gemini takes a duration. The longer option costs more to write and is
	// what makes caching pay at moderate call rates, so it is a decision for
	// the caller rather than a default.
	CacheTTL time.Duration

	// MaxRetries bounds automatic retries of transient provider failures —
	// throttling, request timeouts, 5xx. Nil uses the provider's own default,
	// which is 2 on Claude and OpenAI and is matched by Gemini.
	//
	// Zero disables retry, for a caller who would rather fail fast than have a
	// call silently take tens of seconds. That is a coherent thing to want:
	// with a fallback composite configured, MaxRetries: 0 moves to the next
	// provider on the first throttle instead of waiting out the primary.
	//
	// Retries honour the provider's own Retry-After hint where one is given —
	// a delay guessed from outside is worse than the answer already supplied.
	//
	// Note that RequestTimeout bounds a single request and nothing bounds the
	// retry sequence as a whole, so a high MaxRetries against a provider
	// supplying long hints can take a while. Cancel the context to bound it.
	MaxRetries *int

	// Stateless makes every Chat, Ask and StreamChat call a one-shot: the
	// client neither seeds the request with prior turns nor retains the turns
	// from this call. One client then serves many independent calls with no
	// per-call construction cost and no cross-call contamination.
	//
	// The zero value keeps the conversational behaviour: history accumulates
	// across calls on a single client instance. That is right for a
	// conversation and wrong for batch work, where holding one client across N
	// independent calls re-sends the whole accumulated prefix every time —
	// quadratic input cost, and call N answered in the light of calls 1..N-1
	// without the caller ever asking for it.
	//
	// Tool calling is unaffected. Stateless means "no history across calls",
	// not "no messages within one": the ReAct loop keeps the assistant and tool
	// turns it needs to make progress, and discards them when the call returns.
	//
	// Add still works, and buffers a one-shot preamble — the buffered turns go
	// out with the next call and are then cleared rather than retained.
	//
	// Stateless provider clients are safe for concurrent use by multiple
	// goroutines; see [ChatClient] for the exceptions. Setting this against a
	// provider module that predates the flag is a construction error rather
	// than a silent miss — see [StatelessCapable].
	Stateless bool

	// UsageObserver, when non-nil, is invoked once per provider round-trip
	// with that round-trip's token usage. A ReAct tool-calling loop fires it
	// once per step. This is the opt-in hook for emitting a telemetry event,
	// metric, or log line; the chat client never depends on a telemetry
	// collector. Providers that do not report usage still fire the observer
	// with a Known == false Usage. The callback runs synchronously on the
	// calling goroutine, so keep it fast and non-blocking.
	UsageObserver func(Usage) `json:"-" mapstructure:"-" yaml:"-"`

	// AllowInsecureBaseURL permits HTTP (non-HTTPS) BaseURLs. This is
	// exclusively for tests that point at an httptest.Server. Production
	// callers must leave this false. The field is tagged json:"-" so
	// config files cannot enable it.
	AllowInsecureBaseURL bool `json:"-" mapstructure:"-" yaml:"-"`
}

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

type ConversationStore interface {
	// Save writes a snapshot to the store.
	Save(ctx context.Context, snapshot *Snapshot) error
	// Load retrieves a snapshot by ID.
	Load(ctx context.Context, id string) (*Snapshot, error)
	// List returns summaries of all stored snapshots.
	List(ctx context.Context) ([]SnapshotSummary, error)
	// Delete removes a snapshot by ID.
	Delete(ctx context.Context, id string) error
}

type CredentialConfig struct {
	Env      string `mapstructure:"env"`
	Keychain string `mapstructure:"keychain"`
	Key      string `mapstructure:"key"`
	// Lookup resolves the Keychain reference. Injected by the host (nil ⇒ the
	// keychain step is skipped); never decoded from config.
	Lookup KeychainLookup `mapstructure:"-" json:"-"`
}

type DroppedSetting struct {
	// Fields names the Config fields that were not applied, e.g. "Temperature".
	Fields []string
	// Capability is the capability the fields required.
	Capability Capability
	// Reason is a short human-readable explanation.
	Reason string
}

type Effort string

type EffortSupport struct {
	// Levels lists the rungs the model actually implements. Empty means the
	// ladder is not known, not that no levels exist.
	Levels []Effort
}

type FailoverDecision int

type FailoverPolicy interface {
	Classify(err error) FailoverDecision
}

type FallbackConfig struct {
	Enabled   bool       `mapstructure:"enabled"`
	Providers []Provider `mapstructure:"providers"`
}

type FallbackOption func(*fallbackConfig)

type FileStoreOption func(*fileStoreConfig)

type HTTPStatusExtractor func(err error) (status int, ok bool)

type History struct {
	// Turns is the number of conversation turns the client will re-send on its
	// next call, including any buffered by Add and not yet sent.
	Turns int

	// LastInputTokens is the provider-reported input-token count of the most
	// recent call — the measured size of everything that call sent. Zero before
	// the first call, and from providers that report no usage at all.
	//
	// It is a measurement rather than an estimate, and one call stale. See
	// [UsageTracker.LastUsage] for why the core does not compute it directly.
	LastInputTokens int

	// Known reports whether Turns is authoritative. False from a provider that
	// cannot count its own history — ProviderClaudeLocal delegates the
	// transcript to the claude CLI's own session, so it can only see what it has
	// buffered locally, not what the far side is carrying.
	Known bool
}

type HistoryEdit struct {
	// Keep lists the indices to retain, oldest first. An index absent from Keep
	// is dropped.
	Keep []int

	// Replace maps an index in Keep to text that supersedes that turn. It is
	// how a compacting policy substitutes a summary for the turns it folded up;
	// a truncating policy leaves it nil.
	//
	// A replaced turn becomes plain text of the same role, losing any structure
	// it had. That is why a tool group is replaced as a whole or not at all.
	Replace map[int]string
}

type HistoryPolicy interface {
	Bound(ctx context.Context, turns []TurnInfo) (HistoryEdit, error)
}

type KeychainLookup func(ctx context.Context, service, account string) (string, error)

type Limits struct {
	MaxInputTokens  int
	MaxOutputTokens int
}

type Media struct {
	MIMEType string
	Data     []byte
}

type ModelIdentifier interface {
	Provider() Provider
	Model() string
}

type ModelInfo struct {
	Capabilities Capabilities
	// Limits is nil when the ceilings are not known.
	Limits *Limits
}

type PersistentChatClient interface {
	ChatClient
	// Save captures the current conversation state as an immutable snapshot.
	// The snapshot includes provider-specific messages as opaque JSON, tool
	// metadata (without handlers), and configuration. Tokens are never saved.
	Save() (*Snapshot, error)
	// Restore replaces the current conversation state with a previously saved
	// snapshot. The snapshot's Provider must match the client's provider.
	// After restore, tools must be re-registered via SetTools with live handlers.
	Restore(snapshot *Snapshot) error
}

type Provider string

type ProviderCredentials func(provider Provider) (CredentialConfig, bool)

type ProviderFactory func(ctx context.Context, settings Settings) (ChatClient, error)

type ResolvedMedia struct {
	MIMEType string
	Data     []byte
}

type Role string

type RuntimeConfig struct {
	Provider       Provider       `mapstructure:"provider"`
	RequestTimeout time.Duration  `mapstructure:"request_timeout"`
	Fallback       FallbackConfig `mapstructure:"fallback"`
}

type SamplingSupport struct {
	// MinTemperature and MaxTemperature bound Config.Temperature in the
	// provider's own units. Both zero means the range is not known.
	MinTemperature float64
	MaxTemperature float64
	// TopP reports whether nucleus sampling is separately settable.
	TopP Support
}

type Settings struct {
	Config Config
	Logger *slog.Logger
}

type Snapshot struct {
	// ID uniquely identifies this snapshot.
	ID string `json:"id"`
	// Provider identifies which chat provider created this snapshot.
	Provider Provider `json:"provider"`
	// Model is the AI model used in the conversation.
	Model string `json:"model"`
	// SystemPrompt is the system instruction active at snapshot time.
	SystemPrompt string `json:"system_prompt,omitempty"`
	// Messages contains provider-specific message history as opaque JSON.
	// The format varies by provider — do not parse or modify directly.
	Messages json.RawMessage `json:"messages"`
	// Tools captures tool metadata (name, description, parameters) without
	// handlers. After restoring, call SetTools to re-register live handlers.
	Tools []ToolSnapshot `json:"tools,omitempty"`
	// Metadata holds arbitrary key-value pairs for consumer use.
	Metadata map[string]string `json:"metadata,omitempty"`
	// CreatedAt is when this snapshot was taken.
	CreatedAt time.Time `json:"created_at"`
	// Version is the snapshot format version for forward compatibility.
	Version int `json:"version"`
}

type SnapshotSummary struct {
	ID           string    `json:"id"`
	Provider     Provider  `json:"provider"`
	Model        string    `json:"model"`
	CreatedAt    time.Time `json:"created_at"`
	MessageCount int       `json:"message_count"`
}

type StatelessCapable interface {
	ChatClient

	// SupportsStateless is a compile-time marker. It is never called.
	SupportsStateless()
}

type StreamCallback func(event StreamEvent) error

type StreamEvent struct {
	// Type indicates the kind of event.
	Type StreamEventType

	// Delta contains the text fragment for EventTextDelta events.
	Delta string

	// ToolCall contains tool call information for EventToolCallStart/EventToolCallEnd events.
	ToolCall *StreamToolCall

	// Error contains error information for EventError events.
	Error error
}

type StreamEventType int

type StreamToolCall struct {
	// ID is the provider-assigned identifier for the tool call.
	ID string
	// Name is the tool name.
	Name string
	// Arguments is the complete JSON argument payload (only populated on EventToolCallEnd).
	Arguments string
	// Result is the tool execution result (only populated on EventToolCallEnd).
	Result string
}

type StreamingChatClient interface {
	ChatClient

	// StreamChat sends a message and streams the response via callback.
	// The callback is invoked for each event in the stream. If the callback
	// returns a non-nil error, the stream is cancelled and that error is returned.
	// The return value is the complete assembled response text (concatenation of
	// all EventTextDelta fragments) or an error if streaming failed.
	// Tool calls are handled internally via the same ReAct loop as Chat(). If
	// Config.ParallelTools is enabled, multiple tool calls are executed concurrently.
	StreamChat(ctx context.Context, prompt string, callback StreamCallback, media ...Media) (string, error)
}

type Support uint8

type Tool struct {
	Name        string                                                       `json:"name"`
	Description string                                                       `json:"description"`
	Parameters  *jsonschema.Schema                                           `json:"parameters"`
	Handler     func(ctx context.Context, args json.RawMessage) (any, error) `json:"-" mapstructure:"-" yaml:"-"`
}

type ToolCall struct {
	Name  string
	Input json.RawMessage
}

type ToolResult struct {
	Name   string
	Result string
}

type ToolSnapshot struct {
	Name        string             `json:"name"`
	Description string             `json:"description"`
	Parameters  *jsonschema.Schema `json:"parameters,omitempty"`
}

type TranscriptEditor interface {
	// ApplyPolicyNow bounds the retained conversation immediately, rather than
	// waiting for the next request to do it, and reports how many turns went.
	//
	// A nil policy means the one on [Config.HistoryPolicy]; with none configured
	// there is nothing to apply and it returns zero. Zero with a nil error means
	// the policy kept everything, which is a legitimate outcome rather than a
	// failure — a conversation inside its budget has nothing to do.
	//
	// Implementations run the policy through [BoundConversation], so an edit
	// that would drop a cached turn or split a tool group is refused rather than
	// applied.
	//
	// It returns [ErrTranscriptMoved] when another goroutine changed the
	// conversation while the policy was running, which a caller may retry.
	ApplyPolicyNow(ctx context.Context, policy HistoryPolicy) (removed int, err error)
}

type TurnInfo struct {
	// Index is the turn's position in the conversation, oldest first.
	Index int

	// Role is who produced the turn.
	Role Role

	// Text is the provider's best-effort rendering of the turn as plain text,
	// supplied so a policy can reason about content — a compacting policy
	// summarises from it. It is lossy by construction: a tool call rendered as
	// text is not the tool call. Nothing reconstructs a turn from it; it exists
	// to be read, and to be replaced wholesale via [HistoryEdit.Replace].
	Text string

	// Pinned marks a turn added via [CachingChatClient.AddCached]. A policy
	// must never drop one, and [ApplyHistoryEdit] refuses an edit that does.
	//
	// Caching bills a matching prefix at the cached rate, so dropping a cached
	// turn destroys every subsequent cache hit — a failure that shows up only
	// as a larger invoice.
	Pinned bool

	// ToolGroup ties a tool request to its results. Turns sharing a non-zero
	// ToolGroup are one indivisible unit; zero means the turn stands alone.
	//
	// Providers require a tool request and its result to travel together, so an
	// edit that keeps one without the other yields an API error rather than a
	// shorter conversation. [ApplyHistoryEdit] refuses to split a group.
	ToolGroup int
}

type Usage struct {
	// InputTokens is the number of prompt/input tokens consumed.
	InputTokens int
	// OutputTokens is the number of completion/output tokens produced.
	OutputTokens int
	// TotalTokens is the sum of input and output tokens. When a provider
	// supplies its own total it is preserved; otherwise it is computed as
	// InputTokens + OutputTokens.
	TotalTokens int
	// CachedTokens is the number of input tokens served from a provider-side
	// prompt cache, when reported. Zero when the provider does not expose it.
	CachedTokens int
	// ReasoningTokens is the number of tokens spent on internal reasoning
	// ("thinking") output, when reported. Zero when not exposed.
	ReasoningTokens int
	// Known reports whether the provider supplied token counts for this call.
	// False indicates the counts are not authoritative (e.g. ProviderClaudeLocal).
	Known bool
}

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