provider

type CacheAttribution struct {
	// ReadTokens is the count of tokens the provider says were
	// served from prompt cache. 0 if the provider doesn't report it.
	ReadTokens int
	// WriteTokens is the count of tokens the provider says were
	// freshly added to its cache. Non-zero only on Anthropic-shape.
	WriteTokens int
	// Quality categorizes how reliable the attribution is:
	//   - "explicit"     — provider returned a structured cache breakdown
	//   - "midstream"    — markers parsed mid-stream (Anthropic-shape on partial)
	//   - "estimate"     — heuristic when the provider doesn't surface cache info
	//   - "none"         — the provider doesn't support prompt caching
	Quality string
}

type CacheBreakpoint struct {
	MessageIndex int    // 0-based index into Request.Messages
	Marker       string // optional opaque marker
}

type Capabilities struct {
	Vision      bool
	Thinking    bool
	ToolUse     bool
	PromptCache bool
}

type Message struct {
	Role    Role
	Content []control.ContentBlock
}

type Model struct {
	ID            string
	Name          string
	ContextWindow int
	MaxOutput     int
	Pricing       Pricing
	Capabilities  Capabilities
}

type Pricing struct {
	InputPerMTok      float64
	OutputPerMTok     float64
	CacheReadPerMTok  float64 // discounted cache hit rate
	CacheWritePerMTok float64 // cache-write surcharge
}

type Provider interface {
	// Name returns the provider's identifier (e.g., "openrouter", "zai").
	Name() string

	// Chat starts a streaming chat completion. The returned channel
	// is closed when the stream terminates (success or error).
	//
	// The engine consumes events from this channel and re-emits them
	// onto the per-session Bus.
	Chat(ctx context.Context, req *Request) (<-chan StreamEvent, error)

	// Models returns the model catalog this provider can serve. The
	// engine surfaces this through /v1/providers/{name}/models.
	Models(ctx context.Context) ([]Model, error)

	// TokenCount estimates how many tokens the given messages will
	// consume against the named model. Used by the compaction
	// trigger middleware.
	TokenCount(ctx context.Context, model string, msgs []Message) (int, error)
}

type Request struct {
	Model       string
	System      string                 // system prompt (already assembled by middleware)
	Messages    []Message              // canonical history
	Tools       []ToolSchema           // available tools for tool_use
	Temperature float64                // 0.0 = deterministic
	MaxTokens   int                    // 0 = provider default
	CacheHints  []CacheBreakpoint      // provider-aware cache placement
	Extra       map[string]interface{} // provider-specific knobs (rarely used)
}

type Role string

type StreamEvent struct {
	Kind         StreamEventKind
	Text         string           // for KindTextDelta
	Thinking     []byte           // for KindThinkingDelta (opaque, provider-stamped)
	ToolUse      *control.ToolUse // for KindToolUseStart (Input filled in on Stop)
	ToolUseID    string           // for KindToolUseDelta / KindToolUseStop
	InputDelta   string           // for KindToolUseDelta (concatenates to ToolUse.Input on Stop)
	Usage        *Usage           // for KindUsage
	FinishReason string           // for KindStop ("stop", "tool_use", "length", "yield")
	Err          error            // for KindError
}

type StreamEventKind int

type ToolSchema struct {
	Name        string
	Description string
	InputSchema []byte // JSON Schema bytes
}

type Usage struct {
	InputTokens      int
	OutputTokens     int
	CacheReadTokens  int
	CacheWriteTokens int
}