provider

type AgenticProvider interface {
	Provider
	CompleteWithTools(
		ctx context.Context,
		conversation []ConversationTurn,
		tools []ToolSpec,
		systemPrompt string,
	) (*AgenticResponse, error)
}

type AgenticResponse struct {
	TextBlocks     []TextBlock       // text content blocks
	ToolCalls      []ToolCallRequest // tool_use blocks
	ThinkingBlocks []ThinkingBlock   // extended-thinking content blocks (Phase 3 F)
	StopReason     StopReason        // why the model stopped
	Usage          Usage             // token accounting for this response
}

type Block struct {
	Kind BlockKind `json:"kind"`

	// Text carries BlockKindText content.
	Text string `json:"text,omitempty"`
	// Thinking carries BlockKindThinking content (hidden reasoning + the
	// opaque provenance signature some providers require on replay).
	Thinking *ThinkingBlock `json:"thinking,omitempty"`
	// ToolCall carries BlockKindToolCall content.
	ToolCall *ToolCall `json:"tool_call,omitempty"`
	// ToolResult carries BlockKindToolResult content.
	ToolResult *ToolResult `json:"tool_result,omitempty"`
	// Image carries BlockKindImage content. May be nil for a degenerate
	// image block with no source (preserved as-is for round-tripping).
	Image *ImageSource `json:"image,omitempty"`
}

type BlockKind string

type ChatProvider interface {
	Name() string
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
	ChatStream(ctx context.Context, req ChatRequest, cb StreamCallback) (*ChatResponse, error)
}

type ChatRequest struct {
	// System is the system prompt ("" for none).
	System string
	// Turns is the neutral conversation history, oldest first.
	Turns []Turn
	// Tools are the tool definitions offered to the model (nil for none).
	Tools []ToolSpec
	// Model optionally overrides the provider's configured model for this
	// request. Routed through ModelEffortOverridable; providers without that
	// seam return an error rather than silently ignoring the override.
	Model string
	// MaxTokens optionally caps the response size (max_tokens on the wire)
	// for this request. Routed through MaxTokensOverridable; 0 keeps the
	// provider's construction-time cap, and providers without that seam
	// return an error rather than silently ignoring the cap.
	MaxTokens int
}

type ChatResponse struct {
	Blocks     []Block
	StopReason StopReason
	Usage      Usage
}

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

type ContentBlock struct {
	Type   string       `json:"type"`             // "text" | "image"
	Text   string       `json:"text,omitempty"`   // when Type == "text"
	Source *ImageSource `json:"source,omitempty"` // when Type == "image"
}

type ConversationTurn struct {
	Role          string            // "user", "assistant", or "tool"
	Content       string            // text content (for user messages or assistant text)
	ContentBlocks []ContentBlock    // structured content (e.g. text + image); when non-empty for a user turn, supersedes Content. Follow-up item 1.
	ToolCalls     []ToolCallRequest // tool_use blocks produced by assistant
	ToolCallID    string            // for role "tool": the tool_use id this result corresponds to
	IsError       bool              // for role "tool": whether this result is an error

	// Category classifies the turn's origin (TurnCategory* constants above):
	// shell / ai / rysh / chat for pane-mode parity, tool for tool results,
	// subagent for sub-agent summaries, system for synthetic turns. Serialized
	// into the session JSON so downstream consumers (Slack flow, history tools)
	// respect the pane categorisation.
	Category string `json:"category,omitempty"`
	// Origin identifies the producer within the category: the tool name for
	// Category "tool", the child orchestrator id for "subagent", the pane /
	// agent / humanoid name for "shell"/"chat" injections.
	Origin string `json:"origin,omitempty"`
	// Summary is a short human-readable digest of the turn (a step title for
	// tool calls, an LLM/deterministic summary for sub-agent results). Used by
	// low-bandwidth renderers (Slack step flow) instead of full Content.
	Summary string `json:"summary,omitempty"`
	// TimestampMs records when the turn was appended (unix milliseconds).
	TimestampMs int64 `json:"timestamp_ms,omitempty"`
	// Thinking carries the assistant turn's extended-thinking blocks so they
	// can be replayed on the next request (the Messages API requires thinking
	// blocks to precede tool_use blocks in replayed assistant turns when
	// extended thinking is enabled).
	Thinking []ThinkingBlock `json:"thinking,omitempty"`

	// ProviderName / Model record WHICH model produced an assistant turn.
	//
	// A conversation outlives the model that started it: `##llm select` swaps
	// the provider on a live orchestrator, so the next model inherits a
	// transcript of assistant turns it did not write. Without attribution it
	// reads them as its own — one model answered "I'm ChatGPT", the next was
	// asked the same question, saw that answer in its own voice, and
	// "corrected" itself. Role alone cannot express this: every assistant turn
	// is role "assistant" no matter who wrote it.
	//
	// Empty on user/tool turns, and on assistant turns recorded before this
	// existed — treat empty as "unknown", never as "mine".
	ProviderName string `json:"provider_name,omitempty"`
	Model        string `json:"model,omitempty"`

	// SubAgentCalls is set only on the tool-result turn of a sub_agent call:
	// the tool calls the child orchestrator made, in order, each nested call
	// carrying its own children. It is an AUDIT record for consumers that
	// account for every tool call of a turn (the meeting audit ledger) — the
	// child's steps otherwise reach them only over the asynchronous step
	// stream. It is never rendered into a provider request: the model sees
	// exactly the Content it saw before this field existed.
	//
	// In-process only (json:"-"), like MsgOrchestratorDone.Conversation: the
	// audit reconciles from the orchestrator's in-process result, so the
	// field is never persisted (session KV), restored, or sent over NATS
	// (##hop fork) — the child calls' titles carry tool targets that none of
	// those flows carried before.
	SubAgentCalls []SubAgentCall `json:"-"`
}

type ImageSource struct {
	Type      string `json:"type"`                 // "base64" | "url" | "file_id"
	MediaType string `json:"media_type,omitempty"` // e.g. "image/png"
	Data      string `json:"data,omitempty"`       // base64-encoded when Type=="base64"
	URL       string `json:"url,omitempty"`        // when Type=="url"
	FileID    string `json:"file_id,omitempty"`    // when Type=="file_id"
}

type MaxTokensOverridable interface {
	// WithMaxTokens returns a provider identical to the receiver except for
	// its max_tokens output cap; maxTokens <= 0 keeps the receiver's cap.
	// The receiver is not mutated. Wrappers that forward the seam return nil
	// when the wrapped provider cannot honor the cap, so callers can fail
	// loudly instead of silently sending an uncapped request.
	WithMaxTokens(maxTokens int) AgenticProvider
}

type ModelEffortOverridable interface {
	// WithModelEffort returns a provider identical to the receiver except for
	// the non-empty overrides. The receiver is not mutated.
	WithModelEffort(model, effort string) AgenticProvider
}

type ModelFallback struct {
	Secondary string // e.g. "claude-3-5-haiku-20241022"
}

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

type Provider interface {
	Name() string
	Complete(ctx context.Context, prompt string) (string, error)
}

type RetryPolicy struct {
	// MaxAttempts is the upper bound on total attempts (including the first).
	// 1 means "try once, no retries". Default 5.
	MaxAttempts int

	// BaseDelay is the starting backoff window. Each subsequent attempt
	// doubles up to MaxDelay. Default 1 second.
	BaseDelay time.Duration

	// MaxDelay caps the backoff between attempts. Default 30 seconds.
	MaxDelay time.Duration

	// Jitter adds randomised fuzz to each backoff so synchronised clients
	// don't herd. Expressed as a fraction of the computed delay; 0.2 means
	// ±20%. Default 0.2.
	Jitter float64

	// HonourRetryAfter, when true, overrides the computed backoff with the
	// server-sent Retry-After header (if shorter than MaxDelay). Default true.
	HonourRetryAfter bool
}

type StaticAgenticProvider struct {
	Response string
}

type StopReason string

type StreamCallback func(StreamEvent)

type StreamEvent struct {
	Type        StreamEventType
	Index       int        // for *content_block_* events
	Text        string     // text_delta
	ToolUseID   string     // content_block_start (tool_use)
	ToolUseName string     // content_block_start (tool_use)
	PartialJSON string     // tool_use_delta
	Thinking    string     // thinking_delta (Phase 3 F)
	StopReason  StopReason // message_delta
	Usage       Usage      // message_start / message_delta
}

type StreamEventType string

type StreamingProvider interface {
	CompleteWithToolsStream(
		ctx context.Context,
		conversation []ConversationTurn,
		tools []ToolSpec,
		systemPrompt string,
		cb StreamCallback,
	) (*AgenticResponse, error)
}

type SubAgentCall struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Title          string         `json:"title"`
	IsError        bool           `json:"is_error"`
	Ended          bool           `json:"ended"`
	Interrupted    bool           `json:"interrupted,omitempty"`
	OrchestratorID string         `json:"orchestrator_id,omitempty"`
	Calls          []SubAgentCall `json:"calls,omitempty"`
}

type TextBlock struct {
	Text string
}

type ThinkingBlock struct {
	Text      string `json:"thinking,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type ThinkingConfig struct {
	// Type is "adaptive" (recommended, 4.6+ models) or "enabled" (legacy).
	Type string `json:"type"`

	// BudgetTokens is the legacy fixed thinking budget. Only set with
	// Type == "enabled" on pre-4.6 models; omitted from the wire form
	// otherwise (adaptive mode has no budget field).
	BudgetTokens int `json:"budget_tokens,omitempty"`
}

type ToolCall struct {
	// ID is the provider-assigned call identifier; the matching ToolResult
	// echoes it as CallID.
	ID string `json:"id,omitempty"`
	// Name is the tool name.
	Name string `json:"name,omitempty"`
	// ParamsJSON is the raw JSON arguments object.
	ParamsJSON json.RawMessage `json:"params_json,omitempty"`
}

type ToolCallRequest struct {
	ID    string          // unique id assigned by the API
	Name  string          // tool name
	Input json.RawMessage // raw JSON input arguments
}

type ToolResult struct {
	// CallID references the ToolCall.ID this result answers.
	CallID string `json:"call_id,omitempty"`
	// Content is the textual result payload.
	Content string `json:"content,omitempty"`
	// IsError marks the result as a failure the model should read as such.
	IsError bool `json:"is_error,omitempty"`
}

type ToolSpec struct {
	Name        string          // tool name
	Description string          // human-readable description
	Parameters  json.RawMessage // JSON Schema for the tool input
}

type Turn struct {
	Role   TurnRole `json:"role"`
	Blocks []Block  `json:"blocks,omitempty"`

	// Category classifies the turn's origin (TurnCategory* constants).
	Category string `json:"category,omitempty"`
	// Origin identifies the producer within the category.
	Origin string `json:"origin,omitempty"`
	// Summary is a short human-readable digest of the turn.
	Summary string `json:"summary,omitempty"`
	// TimestampMs records when the turn was appended (unix milliseconds).
	TimestampMs int64 `json:"timestamp_ms,omitempty"`
}

type TurnRole string

type Usage struct {
	InputTokens              int // non-cached input tokens billed at full rate
	OutputTokens             int // generated output tokens
	CacheReadInputTokens     int // input tokens served from the prompt cache
	CacheCreationInputTokens int // input tokens written to the prompt cache
}