provider

type AssistantMessage struct {
	ID      string         `json:"id,omitempty"`
	Type    string         `json:"type,omitempty"`
	Role    string         `json:"role,omitempty"`
	Content []ContentBlock `json:"content,omitempty"`
}

type ClaudeCodeProvider struct {
	ProviderBase
	// contains filtered or unexported fields
}

type ContentBlock struct {
	Type      string         `json:"type"`
	Text      string         `json:"text,omitempty"`
	Name      string         `json:"name,omitempty"`
	ID        string         `json:"id,omitempty"`
	ToolUseID string         `json:"tool_use_id,omitempty"`
	Input     map[string]any `json:"input,omitempty"`
	Content   string         `json:"content,omitempty"`
	IsError   bool           `json:"is_error,omitempty"`
}

type DecisionDetail struct {
	Type    string `json:"type"` // "ask", "allow", "deny"
	Reason  string `json:"reason,omitempty"`
	Options []struct {
		Name string `json:"name"`
	} `json:"options,omitempty"`
}

type EventMeta struct {
	DurationMs       int64  `json:"duration_ms,omitempty"`
	TotalDurationMs  int64  `json:"total_duration_ms,omitempty"`
	ToolName         string `json:"tool_name,omitempty"`
	ToolID           string `json:"tool_id,omitempty"`
	Status           string `json:"status,omitempty"`
	ErrorMsg         string `json:"error_msg,omitempty"`
	InputTokens      int32  `json:"input_tokens,omitempty"`
	OutputTokens     int32  `json:"output_tokens,omitempty"`
	CacheWriteTokens int32  `json:"cache_write_tokens,omitempty"`
	CacheReadTokens  int32  `json:"cache_read_tokens,omitempty"`
	InputSummary     string `json:"input_summary,omitempty"`
	OutputSummary    string `json:"output_summary,omitempty"`
	FilePath         string `json:"file_path,omitempty"`
	LineCount        int32  `json:"line_count,omitempty"`
	Progress         int32  `json:"progress,omitempty"`
	TotalSteps       int32  `json:"total_steps,omitempty"`
	CurrentStep      int32  `json:"current_step,omitempty"`
}

type EventWithMeta struct {
	EventType string     `json:"event_type"`
	EventData string     `json:"event_data"`
	Meta      *EventMeta `json:"meta,omitempty"`
}

type FinishReason string

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

type HTTPTransportConfig struct {
	Endpoint string
	Password string
	Logger   *slog.Logger
	Timeout  time.Duration
	WorkDir  string // Working directory for OpenCode Server context
}

type ModelUsageStats struct {
	InputTokens              int32   `json:"inputTokens"`
	OutputTokens             int32   `json:"outputTokens"`
	CacheReadInputTokens     int32   `json:"cacheReadInputTokens"`
	CacheCreationInputTokens int32   `json:"cacheCreationInputTokens"`
	WebSearchRequests        int32   `json:"webSearchRequests"` // WebSearchRequests is the count of tool-level web search operations.
	CostUSD                  float64 `json:"costUSD"`
	ContextWindow            int32   `json:"contextWindow"`   // ContextWindow is the model's total context capacity (tokens). Used for utilization calculation.
	MaxOutputTokens          int32   `json:"maxOutputTokens"` // MaxOutputTokens is the model's maximum output limit.
}

type OCAssistantMessage struct {
	ID        string   `json:"id,omitempty"`
	SessionID string   `json:"sessionID,omitempty"`
	Role      string   `json:"role,omitempty"`
	ModelID   string   `json:"modelID,omitempty"`
	Cost      float64  `json:"cost,omitempty"`
	Tokens    OCUsage  `json:"tokens"`
	Finish    string   `json:"finish,omitempty"`
	Error     *OCError `json:"error,omitempty"`
}

type OCCacheUsage struct {
	Read  int32 `json:"read,omitempty"`
	Write int32 `json:"write,omitempty"`
}

type OCError struct {
	Name    string         `json:"name"`
	Message string         `json:"message,omitempty"`
	Data    map[string]any `json:"data,omitempty"`
}

type OCMessage struct {
	ID      string   `json:"id,omitempty"`
	Role    string   `json:"role,omitempty"`
	Parts   []OCPart `json:"parts,omitempty"`
	Content string   `json:"content,omitempty"`
	Status  string   `json:"status,omitempty"`
	Error   string   `json:"error,omitempty"`
}

type OCPart struct {
	ID   string `json:"id,omitempty"`
	Type string `json:"type"`

	// text / reasoning
	Text string `json:"text,omitempty"`

	// tool (v1.3.2+ uses nested state and tool field)
	Tool   string         `json:"tool,omitempty"`
	Input  map[string]any `json:"input,omitempty"`
	Output string         `json:"output,omitempty"`
	Error  string         `json:"error,omitempty"`
	State  *OCPartState   `json:"state,omitempty"`

	// step
	StepNumber int    `json:"step_number,omitempty"`
	TotalSteps int    `json:"total_steps,omitempty"`
	Reason     string `json:"reason,omitempty"`

	// token usage
	Usage *OCUsage `json:"usage,omitempty"`

	// Legacy compatibility (fallback for older versions)
	Status string `json:"status,omitempty"`
	Name   string `json:"name,omitempty"`
}

type OCPartState struct {
	Status string `json:"status,omitempty"` // pending, running, completed, error
}

type OCPartUpdateProps struct {
	Part  OCPart `json:"part"`
	Delta string `json:"delta,omitempty"`
}

type OCPermissionProps struct {
	ID        string `json:"id"`
	Type      string `json:"type"`
	SessionID string `json:"sessionID,omitempty"`
	Title     string `json:"title,omitempty"`
}

type OCSSEEvent struct {
	Type       string          `json:"type"`
	Properties json.RawMessage `json:"properties,omitempty"`
}

type OCSession struct {
	ID        string `json:"id"`
	ProjectID string `json:"projectID,omitempty"`
	Directory string `json:"directory,omitempty"`
	Title     string `json:"title"`
	Version   string `json:"version,omitempty"`
}

type OCSessionErrorProps struct {
	Error OCError `json:"error"`
}

type OCSessionState struct {
	Type    string `json:"type"`
	Attempt int    `json:"attempt,omitempty"`
}

type OCSessionStatusProps struct {
	Status OCSessionState `json:"status"`
}

type OCTimeStamp struct {
	Created int64 `json:"created,omitempty"`
	Updated int64 `json:"updated,omitempty"`
}

type OCUsage struct {
	InputTokens  int32         `json:"input_tokens,omitempty"`
	OutputTokens int32         `json:"output_tokens,omitempty"`
	Cache        *OCCacheUsage `json:"cache,omitempty"`
}

type OpenCodeConfig struct {
	// UseHTTPAPI enables HTTP API mode instead of CLI mode
	UseHTTPAPI bool `json:"use_http_api,omitempty" koanf:"use_http_api"`

	// Port for HTTP API server
	Port int `json:"port,omitempty" koanf:"port"`

	// PlanMode enables planning mode
	PlanMode bool `json:"plan_mode,omitempty" koanf:"plan_mode"`

	// Provider is the LLM provider to use
	Provider string `json:"provider,omitempty" koanf:"provider"`

	// Model is the model ID
	Model string `json:"model,omitempty" koanf:"model"`

	// ServerURL is the HTTP endpoint for opencode serve (e.g., "http://127.0.0.1:4096").
	// Used by OpenCodeServerProvider (opencode-server type).
	ServerURL string `json:"server_url,omitempty" koanf:"server_url"`

	// Agent is the opencode serve --agent flag (e.g., "build", "plan").
	Agent string `json:"agent,omitempty" koanf:"agent"`

	// Password is the Basic Auth password for opencode serve.
	Password string `json:"password,omitempty" koanf:"password"`

	// WorkDir is the working directory for OpenCode Server context.
	// This is passed via x-opencode-directory HTTP header to specify project directory.
	WorkDir string `json:"work_dir,omitempty" koanf:"work_dir"`
}

type OpenCodeServerProvider struct {
	ProviderBase
	// contains filtered or unexported fields
}

type PendingPermissionRequest struct {
	ID             string // Unique ID (messageID or generated)
	SessionID      string // Claude Code session ID
	Request        *PermissionRequest
	ChannelID      string           // Slack channel ID
	MessageTS      string           // Slack message timestamp for update
	UserID         string           // Slack user who triggered the request
	CreatedAt      time.Time        // When the request was created
	ExpiresAt      time.Time        // When the request expires (timeout)
	SlackMessageTS string           // TS of the Slack message with buttons
	Status         PermissionStatus // Current status
}

type PermissionBehavior string

type PermissionDeniedDetail struct {
	ToolName  string         `json:"tool_name"`            // Name of the denied tool (e.g., "Edit", "Bash")
	ToolUseID string         `json:"tool_use_id"`          // Unique ID for correlating with tool_use event
	ToolInput map[string]any `json:"tool_input,omitempty"` // The tool input that was denied
}

type PermissionDetail struct {
	Name  string `json:"name"`            // Tool name (e.g., "bash", "Read", "Edit")
	Input string `json:"input,omitempty"` // Tool input (e.g., command to execute)
}

type PermissionRequest struct {
	Type       string            `json:"type"`
	SessionID  string            `json:"session_id,omitempty"`
	MessageID  string            `json:"message_id,omitempty"`
	Decision   *DecisionDetail   `json:"decision,omitempty"`
	Permission *PermissionDetail `json:"permission,omitempty"` // Legacy format
}

type PermissionResponse struct {
	Behavior string `json:"behavior"`
	Message  string `json:"message,omitempty"`
}

type PermissionStatus string

type PermissionTool string

type PiAgentEvent struct {
	Type     string           `json:"type"`
	Messages []PiAgentMessage `json:"messages,omitempty"`
	Message  *PiAgentMessage  `json:"message,omitempty"`
}

type PiAgentMessage struct {
	Role         string           `json:"role"`
	Content      []PiContentBlock `json:"content,omitempty"`
	Timestamp    int64            `json:"timestamp,omitempty"`
	Provider     string           `json:"provider,omitempty"`
	Model        string           `json:"model,omitempty"`
	API          string           `json:"api,omitempty"`
	Usage        *PiUsage         `json:"usage,omitempty"`
	StopReason   string           `json:"stopReason,omitempty"`
	ErrorMessage string           `json:"errorMessage,omitempty"`
}

type PiAssistantMessageEvent struct {
	Type  string `json:"type"`
	Delta string `json:"delta,omitempty"`
}

type PiConfig struct {
	// Provider is the LLM provider to use (anthropic, openai, google, etc.)
	Provider string `json:"provider,omitempty" koanf:"provider"`

	// Model is the model ID or pattern (supports provider/id format)
	Model string `json:"model,omitempty" koanf:"model"`

	// Thinking level: off, minimal, low, medium, high, xhigh
	Thinking string `json:"thinking,omitempty" koanf:"thinking"`

	// UseRPC enables RPC mode for process integration (stdin/stdout)
	UseRPC bool `json:"use_rpc,omitempty" koanf:"use_rpc"`

	// SessionDir custom session storage directory
	SessionDir string `json:"session_dir,omitempty" koanf:"session_dir"`

	// NoSession enables ephemeral mode (don't save session)
	NoSession bool `json:"no_session,omitempty" koanf:"no_session"`
}

type PiContentBlock struct {
	Type      string         `json:"type"`
	Text      string         `json:"text,omitempty"`
	Thinking  string         `json:"thinking,omitempty"`
	ID        string         `json:"id,omitempty"`
	Name      string         `json:"name,omitempty"`
	Arguments map[string]any `json:"arguments,omitempty"`
	Data      string         `json:"data,omitempty"`
	MimeType  string         `json:"mimeType,omitempty"`
}

type PiMessageUpdateEvent struct {
	Type                  string                   `json:"type"`
	Message               *PiAgentMessage          `json:"message"`
	AssistantMessageEvent *PiAssistantMessageEvent `json:"assistantMessageEvent,omitempty"`
}

type PiProvider struct {
	ProviderBase
	// contains filtered or unexported fields
}

type PiSessionEvent struct {
	Type      string `json:"type"`
	Version   int    `json:"version"`
	ID        string `json:"id"`
	Timestamp string `json:"timestamp"`
	Cwd       string `json:"cwd"`
}

type PiToolExecutionEvent struct {
	Type          string         `json:"type"`
	ToolCallID    string         `json:"toolCallId"`
	ToolName      string         `json:"toolName"`
	Args          map[string]any `json:"args,omitempty"`
	Result        any            `json:"result,omitempty"`
	PartialResult any            `json:"partialResult,omitempty"`
	IsError       bool           `json:"isError,omitempty"`
}

type PiUsage struct {
	InputTokens  int32 `json:"input_tokens"`
	OutputTokens int32 `json:"output_tokens"`
}

type PluginMetadataError struct {
	Type    ProviderType
	Message string
}

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

type Provider interface {
	// Metadata returns the provider's identity and capabilities.
	Metadata() ProviderMeta

	// BuildCLIArgs constructs the command-line arguments for starting the CLI process.
	// The sessionID is the internal SDK identifier, providerSessionID is the
	// provider-specific persistent session identifier (e.g., Claude's --session-id).
	BuildCLIArgs(providerSessionID string, opts *ProviderSessionOptions) []string

	// BuildInputMessage constructs the stdin message payload for sending user input.
	// This handles provider-specific input formatting (e.g., stream-json for Claude).
	BuildInputMessage(prompt string, taskInstructions string) (map[string]any, error)

	// ParseEvent parses a raw output line into one or more normalized ProviderEvents.
	// Returns empty slice if the line should be ignored (e.g., system messages).
	// Returns an error if parsing fails critically.
	ParseEvent(line string) ([]*ProviderEvent, error)

	// DetectTurnEnd checks if the event indicates the end of a turn.
	// Different providers signal turn completion differently:
	// - Claude Code: type="result"
	// - OpenCode: step-finish or specific completion marker
	DetectTurnEnd(event *ProviderEvent) bool

	// ValidateBinary checks if the CLI binary is available and returns its path.
	ValidateBinary() (string, error)

	// CleanupSession cleans up provider-specific session files from disk (e.g. for /reset).
	CleanupSession(providerSessionID string, workDir string) error

	// VerifySession checks if a session can be resumed (i.e., session data exists on disk).
	// This is called before attempting to resume a session to avoid "No conversation found" errors.
	// Returns true if the session exists and can be resumed, false otherwise.
	VerifySession(providerSessionID string, workDir string) bool

	// Name returns the provider name for logging and identification.
	Name() string
}

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

type ProviderConfig struct {
	// Type identifies the provider (required)
	Type ProviderType `json:"type" yaml:"type" koanf:"type"`

	// Enabled controls whether this provider is available
	Enabled *bool `json:"enabled" yaml:"enabled" koanf:"enabled"`

	// ExplicitDisable explicitly disables the provider, overriding base config's Enabled=true.
	// This is needed because bool zero value (false) cannot be distinguished from "not set"
	// in config merging. Use this when you want to disable a provider in overlay config.
	ExplicitDisable bool `json:"explicit_disable,omitempty" yaml:"explicit_disable,omitempty" koanf:"explicit_disable"`

	// BinaryPath overrides the default binary lookup path
	BinaryPath string `json:"binary_path,omitempty" yaml:"binary_path,omitempty" koanf:"binary_path"`

	// DefaultModel is the default model to use
	DefaultModel string `json:"default_model,omitempty" yaml:"default_model,omitempty" koanf:"default_model"`

	// DefaultPermissionMode is the default permission mode
	DefaultPermissionMode string `json:"default_permission_mode,omitempty" yaml:"default_permission_mode,omitempty" koanf:"default_permission_mode"`

	// DangerouslySkipPermissions bypasses all permission checks.
	// Equivalent to --permission-mode bypassPermissions but skips permission prompts entirely.
	// Recommended only for sandboxes with no internet access.
	DangerouslySkipPermissions *bool `` /* 128-byte string literal not displayed */

	// AllowedTools restricts available tools (provider-level override)
	AllowedTools []string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty" koanf:"allowed_tools"`

	// DisallowedTools blocks specific tools (provider-level override)
	DisallowedTools []string `json:"disallowed_tools,omitempty" yaml:"disallowed_tools,omitempty" koanf:"disallowed_tools"`

	// ExtraArgs are additional CLI arguments
	ExtraArgs []string `json:"extra_args,omitempty" yaml:"extra_args,omitempty" koanf:"extra_args"`

	// ExtraEnv are additional environment variables
	ExtraEnv map[string]string `json:"extra_env,omitempty" yaml:"extra_env,omitempty" koanf:"extra_env"`

	// Timeout overrides the default execution timeout
	Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty" koanf:"timeout"`

	// OpenCode-specific options
	OpenCode *OpenCodeConfig `json:"opencode,omitempty" yaml:"opencode,omitempty" koanf:"opencode"`

	// Pi-specific options
	Pi *PiConfig `json:"pi,omitempty" yaml:"pi,omitempty" koanf:"pi"`
}

type ProviderContentBlock struct {
	Type      string         `json:"type"`
	Text      string         `json:"text,omitempty"`
	Name      string         `json:"name,omitempty"`
	ID        string         `json:"id,omitempty"`
	ToolUseID string         `json:"tool_use_id,omitempty"`
	Input     map[string]any `json:"input,omitempty"`
	Content   string         `json:"content,omitempty"`
	IsError   bool           `json:"is_error,omitempty"`
}

type ProviderCreator func(cfg ProviderConfig, logger *slog.Logger) (Provider, error)

type ProviderEvent struct {
	// Type is the normalized event type
	Type ProviderEventType `json:"type"`

	// RawType is the original type string from the provider (for debugging)
	RawType string `json:"raw_type,omitempty"`

	// Timestamp of the event
	Timestamp time.Time `json:"timestamp,omitempty"`

	// SessionID is the provider-specific session identifier
	SessionID string `json:"session_id,omitempty"`

	// Content contains the main event payload
	Content string `json:"content,omitempty"`

	// Blocks contains structured content blocks (if applicable)
	Blocks []ProviderContentBlock `json:"blocks,omitempty"`

	// Tool information (for tool_use and tool_result events)
	ToolName  string         `json:"tool_name,omitempty"`
	ToolID    string         `json:"tool_id,omitempty"`
	ToolInput map[string]any `json:"tool_input,omitempty"`

	// Status indicates operation status ("running", "success", "error")
	Status string `json:"status,omitempty"`

	// Error contains error message if applicable
	Error   string `json:"error,omitempty"`
	IsError bool   `json:"is_error,omitempty"`

	// Metadata contains additional provider-specific information
	Metadata *ProviderEventMeta `json:"metadata,omitempty"`

	// RawLine preserves the original JSON line for debugging
	RawLine string `json:"-"`
}

type ProviderEventMeta struct {
	// Timing information
	DurationMs      int64 `json:"duration_ms,omitempty"`
	TotalDurationMs int64 `json:"total_duration_ms,omitempty"`

	// Token usage
	InputTokens      int32 `json:"input_tokens,omitempty"`
	OutputTokens     int32 `json:"output_tokens,omitempty"`
	CacheWriteTokens int32 `json:"cache_write_tokens,omitempty"`
	CacheReadTokens  int32 `json:"cache_read_tokens,omitempty"`

	// Cost information
	TotalCostUSD float64 `json:"total_cost_usd,omitempty"`

	// Model information
	Model           string `json:"model,omitempty"`
	ModelName       string `json:"model_name,omitempty"`        // ModelName is the primary model name from modelUsage (the most active model).
	ContextWindow   int32  `json:"context_window,omitempty"`    // ContextWindow is the model's total context capacity (tokens).
	MaxOutputTokens int32  `json:"max_output_tokens,omitempty"` // MaxOutputTokens is the model's maximum output limit.

	// Context usage percentage (priority over manual calculation)
	ContextUsedPercent *float64 `json:"context_used_percent,omitempty"` // ContextUsedPercent is the direct percentage from provider (e.g., Claude Code provides this).

	// Progress tracking
	Progress    int32 `json:"progress,omitempty"`
	TotalSteps  int32 `json:"total_steps,omitempty"`
	CurrentStep int32 `json:"current_step,omitempty"`
}

type ProviderEventParser interface {
	// Parse converts a raw output line to a normalized ProviderEvent.
	Parse(line string) (*ProviderEvent, error)

	// IsTurnEnd returns true if the event signals turn completion.
	IsTurnEnd(event *ProviderEvent) bool

	// ExtractSessionID extracts the provider session ID from an event.
	ExtractSessionID(event *ProviderEvent) string
}

type ProviderEventType string

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

type ProviderFeatures struct {
	SupportsResume             bool // Can resume existing sessions (e.g., --resume)
	SupportsStreamJSON         bool // Supports stream-json input/output format
	SupportsSSE                bool // Supports Server-Sent Events output
	SupportsHTTPAPI            bool // Has HTTP API mode
	SupportsSessionID          bool // Supports explicit session ID assignment
	SupportsPermissions        bool // Supports permission modes
	MultiTurnReady             bool // Can handle multiple turns in one session
	RequiresInitialPromptAsArg bool // Requires first prompt to be passed via CLI args instead of stdin
}

type ProviderMeta struct {
	Type        ProviderType // Provider type identifier
	DisplayName string       // Human-readable name (e.g., "Claude Code")
	BinaryName  string       // CLI binary name (e.g., "claude", "opencode")
	InstallHint string       // Installation hint (e.g., "npm install -g @anthropic-ai/claude-code")
	Version     string       // CLI version (if available)
	Features    ProviderFeatures
}

type ProviderPlugin interface {
	// Type returns the unique provider type identifier.
	Type() ProviderType

	// New creates a new Provider instance with the given configuration.
	// The logger may be nil, in which case the default logger should be used.
	New(cfg ProviderConfig, logger *slog.Logger) (Provider, error)

	// Meta returns the provider's metadata including capabilities.
	Meta() ProviderMeta
}

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

type ProviderSessionOptions struct {
	// Working directory for the CLI process
	WorkDir string

	// Permission mode (e.g., "bypassPermissions", "acceptEdits", "default")
	PermissionMode string

	// DangerouslySkipPermissions bypasses all permission checks
	DangerouslySkipPermissions bool

	// Tool restrictions
	AllowedTools    []string
	DisallowedTools []string

	// System prompts
	BaseSystemPrompt string // Engine-level foundational prompt
	TaskInstructions string // Per-task instructions (persisted per session)
	InitialPrompt    string // First prompt for cold start (sent as CLI arg if needed)

	// Session management
	SessionID         string // Internal SDK session ID
	ProviderSessionID string // Provider-specific persistent session ID
	ResumeSession     bool   // Whether to resume an existing session

	// Provider-specific flags
	// Claude Code specific
	Model string // Model override (e.g., "claude-3-5-sonnet")

	// OpenCode specific
	PlanMode bool // Use planning mode instead of build mode
	Port     int  // Port for HTTP API mode (if applicable)
}

type ProviderType string

type StreamMessage struct {
	Message      *AssistantMessage `json:"message,omitempty"`
	Input        map[string]any    `json:"input,omitempty"`
	Type         string            `json:"type"`
	Timestamp    string            `json:"timestamp,omitempty"`
	SessionID    string            `json:"session_id,omitempty"`
	MessageID    string            `json:"message_id,omitempty"`
	Role         string            `json:"role,omitempty"`
	Name         string            `json:"name,omitempty"`
	Output       string            `json:"output,omitempty"`
	Status       string            `json:"status,omitempty"`
	Error        string            `json:"error,omitempty"`
	Content      []ContentBlock    `json:"content,omitempty"`
	Duration     int               `json:"duration,omitempty"`    // Claude Code often uses "duration"
	DurationMs   int               `json:"duration_ms,omitempty"` // Some versions/providers use "duration_ms"
	Subtype      string            `json:"subtype,omitempty"`
	IsError      bool              `json:"is_error,omitempty"`
	TotalCostUSD float64           `json:"total_cost_usd,omitempty"`
	Usage        *UsageStats       `json:"usage,omitempty"`
	Result       string            `json:"result,omitempty"`
	// Permission request fields (Issue #39)
	Permission *PermissionDetail          `json:"permission,omitempty"`
	Decision   *DecisionDetail            `json:"decision,omitempty"`
	ModelUsage map[string]ModelUsageStats `json:"modelUsage,omitempty"`
	// PermissionDenials contains tools that were denied by user (Claude Code stop_reason="tool_disallowed")
	PermissionDenials []PermissionDeniedDetail `json:"permission_denials,omitempty"`
}

type Transport interface {
	// Connect establishes the connection to the agent server.
	// It is called once during transport initialization.
	Connect(ctx context.Context, cfg TransportConfig) error

	// Send delivers a message to an existing session.
	Send(ctx context.Context, sessionID string, message map[string]any) error

	// Events returns a channel that emits raw SSE event payloads (JSON strings).
	// The channel is closed when the transport is closed.
	// Multiple goroutines may read from the channel concurrently.
	Events() <-chan string

	// CreateSession creates a new session on the server and returns its ID.
	CreateSession(ctx context.Context, title string) (string, error)

	// DeleteSession terminates a session on the server.
	DeleteSession(ctx context.Context, sessionID string) error

	// RespondPermission sends a permission response to the server.
	RespondPermission(ctx context.Context, sessionID, permissionID, response string) error

	// Health checks if the server is reachable.
	Health(ctx context.Context) error

	// Close releases all resources held by the transport.
	// Close is idempotent and goroutine-safe.
	Close() error
}

type TransportConfig struct {
	// Endpoint is the base URL of the agent server (e.g., "http://127.0.0.1:4096").
	Endpoint string

	// Env contains environment variables to pass to the server.
	Env map[string]string

	// WorkDir is the working directory for the session.
	WorkDir string

	// Password is the Basic Auth password for the server.
	Password string
}

type UsageStats struct {
	InputTokens           int32 `json:"input_tokens"`
	OutputTokens          int32 `json:"output_tokens"`
	CacheWriteInputTokens int32 `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens  int32 `json:"cache_read_input_tokens,omitempty"`
}