provider

type Capabilities struct {
	// Streaming indicates if the provider supports streaming responses.
	Streaming bool `json:"streaming"`

	// Tools indicates if the provider supports tool/function calling.
	Tools bool `json:"tools"`

	// MCP indicates if the provider supports MCP (Model Context Protocol) servers.
	// If true, custom tools can be added via MCP regardless of native tool support.
	MCP bool `json:"mcp"`

	// Sessions indicates if the provider supports multi-turn conversation sessions.
	Sessions bool `json:"sessions"`

	// Images indicates if the provider supports image inputs.
	Images bool `json:"images"`

	// NativeTools lists the provider's built-in tools by name.
	// Tool names are provider-specific (e.g., "Read" for Claude, "read_file" for Gemini).
	NativeTools []string `json:"native_tools"`

	// ContextFile is the filename for project-specific context (e.g., "CLAUDE.md", "GEMINI.md").
	// Empty string if the provider doesn't support context files.
	ContextFile string `json:"context_file,omitempty"`
}

type Client interface {
	// Complete sends a request and returns the full response.
	// The context controls cancellation and timeouts.
	Complete(ctx context.Context, req Request) (*Response, error)

	// Stream sends a request and returns a channel of response chunks.
	// The channel is closed when streaming completes (check chunk.Done).
	// Errors during streaming are returned via chunk.Error.
	Stream(ctx context.Context, req Request) (<-chan StreamChunk, error)

	// Provider returns the provider name (e.g., "claude", "gemini", "codex").
	Provider() string

	// Capabilities returns what this provider natively supports.
	// Use this to check for specific tools before attempting to use them.
	Capabilities() Capabilities

	// Close releases any resources held by the client.
	// For CLI-based providers, this may terminate any running sessions.
	Close() error
}

type Config struct {

	// Provider is the name of the provider to use.
	// Required. Values: "claude", "gemini", "codex", "opencode", "local"
	Provider string `json:"provider" yaml:"provider" mapstructure:"provider"`

	// Model is the model to use (provider-specific name).
	// Examples: "claude-sonnet-4-20250514", "gemini-2.5-pro", "gpt-5-codex"
	Model string `json:"model" yaml:"model" mapstructure:"model"`

	// FallbackModel is used when the primary model is unavailable.
	// Optional.
	FallbackModel string `json:"fallback_model" yaml:"fallback_model" mapstructure:"fallback_model"`

	// SystemPrompt is the system message prepended to all requests.
	// Optional.
	SystemPrompt string `json:"system_prompt" yaml:"system_prompt" mapstructure:"system_prompt"`

	// MaxTurns limits conversation turns (tool calls + responses).
	// 0 means no limit. Default varies by provider.
	MaxTurns int `json:"max_turns" yaml:"max_turns" mapstructure:"max_turns"`

	// Timeout is the maximum duration for a completion request.
	// 0 uses the provider default.
	Timeout time.Duration `json:"timeout" yaml:"timeout" mapstructure:"timeout"`

	// MaxBudgetUSD limits spending per request.
	// 0 means no limit. Not all providers support this.
	MaxBudgetUSD float64 `json:"max_budget_usd" yaml:"max_budget_usd" mapstructure:"max_budget_usd"`

	// WorkDir is the working directory for file operations.
	// Default: current directory.
	WorkDir string `json:"work_dir" yaml:"work_dir" mapstructure:"work_dir"`

	// AllowedTools limits which tools the model can use.
	// Empty means all tools allowed. Tool names are provider-specific.
	AllowedTools []string `json:"allowed_tools" yaml:"allowed_tools" mapstructure:"allowed_tools"`

	// DisallowedTools explicitly blocks certain tools.
	// Takes precedence over AllowedTools.
	DisallowedTools []string `json:"disallowed_tools" yaml:"disallowed_tools" mapstructure:"disallowed_tools"`

	// MCP configures MCP servers to enable.
	// MCP is the universal tool extension mechanism supported by all providers.
	MCP *claudeconfig.MCPConfig `json:"mcp" yaml:"mcp" mapstructure:"mcp"`

	// Env provides additional environment variables for CLI execution.
	Env map[string]string `json:"env" yaml:"env" mapstructure:"env"`

	// Options holds provider-specific configuration.
	// See each provider's documentation for available options.
	//
	// Common options by provider:
	//
	// Claude:
	//   - "permission_mode": "acceptEdits" | "bypassPermissions"
	//   - "skip_permissions": bool (dangerously skip all permission prompts)
	//   - "session_id": string
	//   - "home_dir": string (for containers)
	//   - "config_dir": string
	//   - "output_format": "json" | "stream-json" | "text"
	//   - "claude_path": string (path to claude binary)
	//   - "continue": bool (continue most recent session)
	//   - "resume": string (resume specific session ID)
	//   - "no_session_persistence": bool
	//   - "json_schema": string (JSON schema for structured output)
	//   - "tools": []string (exact tool set, different from allowed_tools)
	//   - "setting_sources": []string (e.g., ["project", "local", "user"])
	//   - "add_dirs": []string (additional directories for file access)
	//   - "append_system_prompt": string (append to system prompt)
	//   - "mcp_config": string (MCP config file path or JSON)
	//   - "mcp_config_paths": []string (multiple MCP config paths)
	//   - "strict_mcp_config": bool
	//
	// Gemini:
	//   - "include_directories": []string
	//   - "yolo": bool (auto-approve all actions)
	//   - "sandbox": string (docker/podman/custom, via GEMINI_SANDBOX env)
	//
	// Codex:
	//   - "sandbox": "read-only" | "workspace-write" | "danger-full-access"
	//   - "ask_for_approval": "untrusted" | "on-failure" | "on-request" | "never"
	//   - "search": bool
	//   - "full_auto": bool
	//
	// OpenCode:
	//   - "quiet": bool
	//   - "agent": "build" | "plan"
	//   - "debug": bool
	//
	// Local:
	//   - "backend": "ollama" | "llama.cpp" | "vllm"
	//   - "sidecar_path": string
	//
	// Continue (Continue.dev CLI):
	//   - "path": string (path to cn binary)
	//   - "config_path": string (path to config.yaml)
	//   - "api_key": string (CONTINUE_API_KEY)
	//   - "rule": string (rule from Mission Control)
	//   - "verbose": bool (enable logging)
	//   - "resume": bool (resume previous session)
	//   - "allowed_tools": []string (--allow patterns)
	//   - "ask_tools": []string (--ask patterns)
	//   - "excluded_tools": []string (--exclude tools)
	//
	// Aider:
	//   - "path": string (path to aider binary)
	//   - "ollama_api_base": string (OLLAMA_API_BASE)
	//   - "edit_format": string (diff, whole, etc.)
	//   - "no_git": bool (disable git)
	//   - "no_auto_commits": bool (disable auto-commits)
	//   - "no_stream": bool (disable streaming)
	//   - "dry_run": bool (preview without modifying)
	//   - "yes_always": bool (auto-confirm all prompts)
	//   - "editable_files": []string (--file flags)
	//   - "read_only_files": []string (--read flags)
	Options map[string]any `json:"options" yaml:"options" mapstructure:"options"`
}

type ContentPart struct {
	// Type indicates the content type: "text", "image", "file"
	Type string `json:"type"`

	// Text content (when Type == "text")
	Text string `json:"text,omitempty"`

	// ImageURL for remote images (when Type == "image")
	ImageURL string `json:"image_url,omitempty"`

	// ImageBase64 for inline images (when Type == "image")
	// Format: base64-encoded image data
	ImageBase64 string `json:"image_base64,omitempty"`

	// MediaType specifies the MIME type (e.g., "image/png", "image/jpeg")
	MediaType string `json:"media_type,omitempty"`

	// FilePath for local file references (when Type == "file")
	FilePath string `json:"file_path,omitempty"`
}

type Error struct {
	Provider  string // Provider name ("claude", "gemini", etc.)
	Op        string // Operation that failed ("complete", "stream")
	Err       error  // Underlying error
	Retryable bool   // Whether the error is likely transient
}

type Factory func(cfg Config) (Client, error)

type Message struct {
	Role    Role   `json:"role"`
	Content string `json:"content"`
	Name    string `json:"name,omitempty"` // For tool results

	// ContentParts enables multimodal content (text + images).
	// If set, takes precedence over Content for providers that support images.
	// Each part can be text, image (base64 or URL), or other media types.
	ContentParts []ContentPart `json:"content_parts,omitempty"`
}

type Request struct {
	// SystemPrompt sets the system message that guides the model's behavior.
	SystemPrompt string `json:"system_prompt,omitempty"`

	// Messages is the conversation history to send to the model.
	Messages []Message `json:"messages"`

	// Model specifies which model to use (provider-specific name).
	// Examples: "claude-sonnet-4-20250514", "gemini-2.5-pro", "gpt-5-codex"
	Model string `json:"model,omitempty"`

	// MaxTokens limits the response length.
	MaxTokens int `json:"max_tokens,omitempty"`

	// Temperature controls response randomness (0.0 = deterministic, 1.0 = creative).
	Temperature float64 `json:"temperature,omitempty"`

	// Tools lists available tools the model can invoke.
	Tools []Tool `json:"tools,omitempty"`

	// MCP configures MCP servers to enable for this request.
	// MCP is the universal tool extension mechanism supported by all providers.
	MCP *claudeconfig.MCPConfig `json:"mcp,omitempty"`

	// Options holds provider-specific configuration not covered by standard fields.
	// See each provider's documentation for available options.
	Options map[string]any `json:"options,omitempty"`
}

type Response struct {
	// Content is the text response from the model.
	Content string `json:"content"`

	// ToolCalls contains any tool invocations requested by the model.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// Usage tracks token consumption for this request.
	Usage TokenUsage `json:"usage"`

	// Model is the actual model used (may differ from requested).
	Model string `json:"model"`

	// FinishReason indicates why the model stopped generating.
	// Common values: "stop", "length", "tool_calls"
	FinishReason string `json:"finish_reason"`

	// Duration is the time taken for the completion.
	Duration time.Duration `json:"duration"`

	// SessionID is the session identifier (for providers that support sessions).
	// Empty if the provider doesn't support sessions.
	SessionID string `json:"session_id,omitempty"`

	// CostUSD is the estimated cost in USD (for providers that track cost).
	// Zero if cost tracking is not available.
	CostUSD float64 `json:"cost_usd,omitempty"`

	// NumTurns is the number of conversation turns (for multi-turn sessions).
	NumTurns int `json:"num_turns,omitempty"`

	// Metadata holds provider-specific response data.
	// See each provider's documentation for available fields.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Role string

type StreamChunk struct {
	// Content is the text content in this chunk.
	Content string `json:"content,omitempty"`

	// ToolCalls contains tool invocations (usually only in final chunks).
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// Usage is the token usage (only set in final chunk).
	Usage *TokenUsage `json:"usage,omitempty"`

	// Done indicates this is the final chunk.
	Done bool `json:"done"`

	// Error is non-nil if streaming failed.
	Error error `json:"-"`
}

type TokenUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`

	// Cache-related tokens (provider-specific, may be zero)
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
}

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

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