core

type AttemptMetadata struct {
	AttemptIndex   int              `json:"attempt_index,omitempty"`
	ProviderName   string           `json:"provider_name,omitempty"`
	ProviderSystem string           `json:"provider_system,omitempty"`
	Route          string           `json:"route,omitempty"`
	ServerAddress  string           `json:"server_address,omitempty"`
	ServerPort     int              `json:"server_port,omitempty"`
	RequestedModel string           `json:"requested_model,omitempty"`
	ResponseModel  string           `json:"response_model,omitempty"`
	ResolvedModel  string           `json:"resolved_model,omitempty"`
	Cost           *CostAttribution `json:"cost,omitempty"`
	Timing         *TimingBreakdown `json:"timing,omitempty"`
}

type CompactionResult struct {
	// Summary is the generated summary text.
	Summary string `json:"summary"`
	// FileOps tracks files read and modified.
	FileOps map[string]any `json:"file_ops,omitempty"`
	// TokensBefore is the estimated token count before compaction.
	TokensBefore int `json:"tokens_before"`
	// TokensAfter is the estimated token count after compaction.
	TokensAfter int `json:"tokens_after"`
	// Warning is a degradation warning, if any.
	Warning string `json:"warning,omitempty"`
}

type Compactor func(ctx context.Context, messages []Message, provider Provider, toolCalls []ToolCallLog) ([]Message, *CompactionResult, error)

type CostAttribution struct {
	Source           CostSource      `json:"source,omitempty"`
	Currency         string          `json:"currency,omitempty"`
	Amount           *float64        `json:"amount,omitempty"`
	InputAmount      *float64        `json:"input_amount,omitempty"`
	OutputAmount     *float64        `json:"output_amount,omitempty"`
	CacheReadAmount  *float64        `json:"cache_read_amount,omitempty"`
	CacheWriteAmount *float64        `json:"cache_write_amount,omitempty"`
	ReasoningAmount  *float64        `json:"reasoning_amount,omitempty"`
	PricingRef       string          `json:"pricing_ref,omitempty"`
	Raw              json.RawMessage `json:"raw,omitempty"`
}

type CostSource string

type Event struct {
	SessionID string          `json:"session_id"`
	Seq       int             `json:"seq"`
	Type      EventType       `json:"type"`
	Timestamp time.Time       `json:"ts"`
	Data      json.RawMessage `json:"data"`
}

type EventCallback func(Event)

type EventType string

type Message struct {
	Role       Role       `json:"role"`
	Content    string     `json:"content,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

type ModelPricing struct {
	InputPerMTok   float64 `json:"input_per_mtok"`
	OutputPerMTok  float64 `json:"output_per_mtok"`
	CacheReadPerM  float64 `json:"cache_read_per_m,omitempty"`
	CacheWritePerM float64 `json:"cache_write_per_m,omitempty"`
}

type Options struct {
	SeamOptions

	Model       string   `json:"model,omitempty"`
	Temperature *float64 `json:"temperature,omitempty"`
	TopP        *float64 `json:"top_p,omitempty"`
	TopK        *int     `json:"top_k,omitempty"`
	MinP        *float64 `json:"min_p,omitempty"`
	// RepetitionPenalty is the OpenAI-compat field name; openai-compat
	// servers (omlx, lmstudio, vLLM, OpenRouter) accept it as a top-level
	// extra. >1.0 discourages exact repeats; 1.05–1.1 is typical for Qwen.
	RepetitionPenalty *float64 `json:"repetition_penalty,omitempty"`
	Seed              int64    `json:"seed,omitempty"`
	MaxTokens         int      `json:"max_tokens,omitempty"`
	Stop              []string `json:"stop,omitempty"`
	// SamplingSource is a comma-separated record of which resolution layers
	// supplied non-nil sampler fields, e.g. "catalog" or
	// "catalog,provider_config". Used only for the llm.request telemetry
	// event; never sent on the provider wire. See ADR-007 §5.
	SamplingSource string `json:"sampling_source,omitempty"`
	// Reasoning controls model-side reasoning with one scalar value. Empty means
	// unset; use ReasoningOff or ReasoningTokens(0) for explicit off.
	Reasoning Reasoning `json:"reasoning,omitempty"`

	// CachePolicy is the public prompt-caching opt-out plumbed from
	// ServiceExecuteRequest. Valid values: "" / "default" / "off". Providers
	// that implement caching (currently Anthropic, via cache_control writes
	// in a follow-up bead) consult this field; providers without caching
	// ignore it.
	CachePolicy string `json:"cache_policy,omitempty"`
}

type PricingTable map[string]ModelPricing

type Provider interface {
	Chat(ctx context.Context, messages []Message, tools []ToolDef, opts Options) (Response, error)
}

type ProviderCapabilityMissingError struct {
	// Code is the stable error code; always equals ProviderCapabilityMissingErrorCode.
	Code string
	// Capability is the missing capability name extracted from the server
	// message (e.g. "RotatingKVCache Quantization"). Empty when the upstream
	// message did not name a recognizable capability.
	Capability string
	// ServerMessage is the raw error message returned by the upstream server.
	ServerMessage string
	// Cause is the underlying transport error, preserved for chained Unwrap
	// callers that want the original SDK error.
	Cause error
}

type Reasoning = reasoning.Reasoning

type ReasoningStallError struct {
	// Model is the resolved/concrete model ID that stalled.
	Model string
	// Timeout is the stall threshold that was exceeded.
	Timeout time.Duration
	// ReasoningTail is the last N bytes of reasoning_content seen on the
	// stream prior to the stall. May be empty if the stall fired before any
	// reasoning bytes accumulated.
	ReasoningTail string
	// PromptID is a caller-supplied identifier correlating this stall to the
	// prompt or turn that produced it. Empty when not provided.
	PromptID string
}

type Request struct {
	// Prompt is the user's task description.
	Prompt string

	// SystemPrompt is prepended to the conversation as a system message.
	SystemPrompt string

	// History carries prior conversation messages into this run.
	// Use Result.Messages from a previous Run call to continue a session.
	History []Message

	// Provider is the configured LLM backend.
	Provider Provider

	// Tools are the tools available to the agent.
	Tools []Tool

	// MaxIterations limits the number of tool-call rounds. Zero means no limit.
	MaxIterations int

	// ReasoningByteLimit is the maximum bytes of pure reasoning_content
	// allowed before the stream is aborted. Zero means unlimited (no limit).
	ReasoningByteLimit int

	// ReasoningStallTimeout overrides the stall deadline for this request.
	// Zero means use DefaultReasoningStallTimeout. Not exposed through config
	// or the service layer — use programmatically or in tests only.
	ReasoningStallTimeout time.Duration

	// WorkDir is the working directory for file operations and bash commands.
	WorkDir string

	// Callback receives events in real time. May be nil.
	Callback EventCallback

	// Metadata is correlation data (e.g., bead_id) stored on session events.
	Metadata map[string]string

	// SelectedProvider is the concrete provider chosen by the CLI/config layer.
	SelectedProvider string

	// SelectedRoute is the routing key used to choose the provider (for example
	// a backend pool name or direct provider name).
	SelectedRoute string

	// RequestedModel is the route key or canonical target that drove selection.
	RequestedModel string

	// RequestedModelRef is the caller-supplied model catalog reference.
	RequestedModelRef string

	// ResolvedModelRef is the resolved catalog target reference when model
	// selection came from a model_ref.
	ResolvedModelRef string

	// ResolvedModel is the resolved concrete model selected before the run.
	ResolvedModel string

	// MaxTokens is the maximum number of tokens the model may generate per turn.
	// Zero means no explicit limit (provider default applies).
	MaxTokens int

	// Temperature is the model sampling temperature for each provider call.
	// Nil means no explicit setting (provider default applies).
	Temperature *float64

	// TopP, TopK, MinP, RepetitionPenalty are model sampling fields that
	// most OpenAI-compat servers (omlx, lmstudio, vLLM, OpenRouter) accept
	// as top-level extras. Nil means no explicit setting (server default
	// applies). Setting RepetitionPenalty > 1.0 prevents exact-token loops.
	TopP              *float64
	TopK              *int
	MinP              *float64
	RepetitionPenalty *float64

	// Seed is an optional model sampling seed. Zero means unset/provider chooses.
	Seed int64

	// SamplingSource is the resolved sampling-layer attribution, plumbed
	// through to the llm.request telemetry event. See ADR-007 §5.
	SamplingSource string

	// Reasoning controls model-side reasoning with one scalar value. Empty means
	// unset; use ReasoningOff or ReasoningTokens(0) for explicit off.
	Reasoning Reasoning

	// NoStream disables streaming even if the provider supports it.
	NoStream bool

	// CachePolicy is the prompt-caching opt-out, threaded into per-call
	// Options. Valid values: "" / "default" / "off". See agent.CachePolicy*.
	CachePolicy string

	// Telemetry carries the runtime telemetry implementation. If nil, the
	// agent loop falls back to a no-op runtime.
	Telemetry telemetry.Telemetry

	// PlanningMode, when true, performs one no-tool LLM call before the main
	// tool loop. The plan response is injected as an assistant message wrapped
	// in <plan> tags so the subsequent tool loop has it as context. Failure of
	// the planning call is non-fatal: the run continues without a plan.
	PlanningMode bool

	// Compactor is called before each agent loop iteration (and after tool
	// results). If non-nil, it may compact the message history to fit within
	// the context window. Returns the (possibly compacted) messages and result.
	// The compaction package provides a ready-made implementation.
	Compactor Compactor
}

type Response struct {
	Content      string           `json:"content"`
	ToolCalls    []ToolCall       `json:"tool_calls,omitempty"`
	Usage        TokenUsage       `json:"usage"`
	Model        string           `json:"model"`
	FinishReason string           `json:"finish_reason"`
	Attempt      *AttemptMetadata `json:"attempt,omitempty"`
}

type Result struct {
	// Status indicates whether the run succeeded.
	Status Status `json:"status"`

	// Output is the final text response from the model.
	Output string `json:"output"`

	// ToolCalls logs every tool execution during the run.
	ToolCalls []ToolCallLog `json:"tool_calls,omitempty"`

	// Messages is the conversation history for this run, excluding the
	// system prompt. Feed this back into Request.History to continue a session.
	Messages []Message `json:"messages,omitempty"`

	// Tokens is the accumulated token usage across all iterations.
	Tokens TokenUsage `json:"tokens"`

	// Duration is the total wall-clock time of the run.
	Duration time.Duration `json:"duration_ms"`

	// CostUSD is the estimated cost. -1 means unknown (model not in pricing table).
	// 0 means free (local model with $0 pricing entry).
	CostUSD float64 `json:"cost_usd"`

	// Model is the model that was used.
	Model string `json:"model"`

	// SelectedProvider is the concrete provider chosen before the run.
	SelectedProvider string `json:"selected_provider,omitempty"`

	// SelectedRoute is the routing key used to choose the provider.
	SelectedRoute string `json:"selected_route,omitempty"`

	// RequestedModel is the route key or canonical target that drove selection.
	RequestedModel string `json:"requested_model,omitempty"`

	// RequestedModelRef is the caller-supplied model catalog reference.
	RequestedModelRef string `json:"requested_model_ref,omitempty"`

	// ResolvedModelRef is the resolved catalog target reference.
	ResolvedModelRef string `json:"resolved_model_ref,omitempty"`

	// ResolvedModel is the resolved concrete model selected before the run.
	ResolvedModel string `json:"resolved_model,omitempty"`

	// Reasoning is the resolved model-side reasoning control for this run.
	Reasoning Reasoning `json:"reasoning,omitempty"`

	// AttemptedProviders records providers tried in order by any routing wrapper.
	AttemptedProviders []string `json:"attempted_providers,omitempty"`

	// FailoverCount records how many times routing advanced to another candidate.
	FailoverCount int `json:"failover_count,omitempty"`

	// Error is non-nil when Status is StatusError.
	Error error `json:"-"`

	// SessionID identifies the session log for this run.
	SessionID string `json:"session_id"`
}

type Role string

type RoutingReport struct {
	SelectedProvider   string   `json:"selected_provider,omitempty"`
	SelectedRoute      string   `json:"selected_route,omitempty"`
	AttemptedProviders []string `json:"attempted_providers,omitempty"`
	FailoverCount      int      `json:"failover_count,omitempty"`
}

type RoutingReporter interface {
	RoutingReport() RoutingReport
}

type SeamOptions struct{}

type Status string

type StreamDelta struct {
	// ArrivedAt records when the provider produced the delta.
	// It is omitted from JSON and used only for local timing measurements.
	ArrivedAt time.Time `json:"-"`

	// Content is a text fragment (may be empty for tool call chunks).
	Content string `json:"content,omitempty"`

	// ReasoningContent holds thinking/reasoning tokens emitted by models that
	// separate their internal reasoning from the final response (e.g. Qwen3,
	// DeepSeek-R1). Captured from choices[0].delta.reasoning_content in the
	// OpenAI-compatible streaming format.
	ReasoningContent string `json:"reasoning_content,omitempty"`

	// ToolCallID is set when a new tool call starts.
	ToolCallID string `json:"tool_call_id,omitempty"`
	// ToolCallName is set on the first delta of a tool call.
	ToolCallName string `json:"tool_call_name,omitempty"`
	// ToolCallArgs is a fragment of the tool call's JSON arguments.
	ToolCallArgs string `json:"tool_call_args,omitempty"`

	// Usage may be set on any delta, including before Done.
	// Providers can emit incremental usage updates; consumers should merge them.
	Usage *TokenUsage `json:"usage,omitempty"`

	// FinishReason is set on the final delta.
	FinishReason string `json:"finish_reason,omitempty"`

	// Model is set on the first or final delta.
	Model string `json:"model,omitempty"`

	// Attempt carries provider identity and attribution metadata when known.
	Attempt *AttemptMetadata `json:"attempt,omitempty"`

	// Done signals the end of the stream.
	Done bool `json:"done,omitempty"`

	// Err is set when the stream terminated with an error.
	// consumeStream returns this error and discards any partial content.
	Err error `json:"err,omitempty"`
}

type StreamingProvider interface {
	Provider
	ChatStream(ctx context.Context, messages []Message, tools []ToolDef, opts Options) (<-chan StreamDelta, error)
}

type TimingBreakdown struct {
	FirstToken *time.Duration `json:"first_token,omitempty"`
	Queue      *time.Duration `json:"queue,omitempty"`
	Prefill    *time.Duration `json:"prefill,omitempty"`
	Generation *time.Duration `json:"generation,omitempty"`
	CacheRead  *time.Duration `json:"cache_read,omitempty"`
	CacheWrite *time.Duration `json:"cache_write,omitempty"`
}

type TokenUsage struct {
	Input      int `json:"input"`
	Output     int `json:"output"`
	CacheRead  int `json:"cache_read,omitempty"`
	CacheWrite int `json:"cache_write,omitempty"`
	Total      int `json:"total"`
}

type Tool interface {
	// Name returns the tool's identifier.
	Name() string
	// Description returns a human-readable description for the LLM.
	Description() string
	// Schema returns the JSON Schema for the tool's parameters.
	Schema() json.RawMessage
	// Execute runs the tool with the given parameters and returns the result.
	Execute(ctx context.Context, params json.RawMessage) (string, error)
	// Parallel reports whether this tool is safe to execute concurrently with
	// other parallel-flagged tools. Read-only tools return true; tools with
	// side effects (writes, shell commands, sub-agents) return false.
	Parallel() bool
}

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

type ToolCallLog struct {
	Tool     string          `json:"tool"`
	Input    json.RawMessage `json:"input"`
	Output   string          `json:"output"`
	Duration time.Duration   `json:"duration_ms"`
	Error    string          `json:"error,omitempty"`
}

type ToolDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"` // JSON Schema
}