provider

type BackgroundActivity struct {
	// Detected is how many processes were still running once the harness had
	// exited and a short grace window had passed.
	Detected int
	// Commands names what was running, for operator diagnosis. Bounded, and
	// truncated to the kernel's 15-character process names.
	Commands []string
	// Waited is how long cloop blocked waiting for the work to finish.
	Waited time.Duration
	// Drained is true when the background work finished on its own within the
	// budget. The task's output can then be trusted: the work it started is
	// genuinely complete.
	Drained bool
	// Terminated is how many processes were killed after outliving the
	// budget. Zero when Drained, or when the operator opted to keep orphans.
	Terminated int
}

type BackgroundPolicyConfig struct {
	Disabled     bool
	GraceSeconds int
	WaitMinutes  int
	KeepOrphans  bool
}

type BreakerConfig struct {
	// FailureThreshold is the number of failures within FailureWindow that
	// trigger a transition from closed to open. Default: 5.
	FailureThreshold int
	// FailureWindow is the rolling window in which failures are counted.
	// Default: 60s.
	FailureWindow time.Duration
	// Cooldown is the duration the breaker stays open before transitioning
	// to half-open and admitting a probe request. Default: 30s.
	Cooldown time.Duration
}

type BreakerStatus struct {
	Key               string        `json:"key"`
	State             string        `json:"state"`
	ConsecutiveFails  int           `json:"consecutive_failures"`
	RecentFailures    int           `json:"recent_failures"`
	OpenedAt          time.Time     `json:"opened_at,omitempty"`
	CooldownRemaining time.Duration `json:"cooldown_remaining"`
	LastFailure       time.Time     `json:"last_failure,omitempty"`
	LastError         string        `json:"last_error,omitempty"`
}

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

type CircuitState int

type Options struct {
	Model        string
	MaxTokens    int
	Timeout      time.Duration
	SystemPrompt string
	WorkDir      string
	// OnToken, if set, is called for each token chunk as it streams in.
	// When set, the provider should use streaming mode.
	// The full output is still returned in Result.Output.
	OnToken func(token string)

	// OnBackgroundWait, if set, is called once when the provider starts
	// waiting for work an agent harness left running after it exited. The
	// activity passed in is provisional: Waited and Drained are not yet known.
	//
	// It exists so a caller can surface the wait as it happens. Without it a
	// task blocked for twenty minutes on a training run the agent forgot to
	// wait for is indistinguishable, from the outside, from a task that is
	// simply slow — which is the confusion this whole mechanism exists to end.
	OnBackgroundWait func(activity BackgroundActivity)

	// Inference parameters — nil means "use provider default".
	// Temperature controls randomness (0 = deterministic, higher = more creative).
	// TopP is nucleus sampling threshold (0–1).
	// FrequencyPenalty reduces repetition (OpenAI only, 0–2).
	Temperature      *float64
	TopP             *float64
	FrequencyPenalty *float64

	// ExtendedThinking enables reasoning/thinking mode.
	// For Anthropic: sends the "thinking" block with budget_tokens=ThinkingBudget.
	// For OpenAI o1/o3/o4-mini: sets reasoning_effort based on ThinkingBudget.
	ExtendedThinking bool

	// ThinkingBudget is the token budget for reasoning/thinking content.
	// Anthropic: budget_tokens for the thinking block (default 8000).
	// OpenAI: maps to reasoning_effort ("low"/<4000, "medium"/<12000, "high"/>=12000).
	ThinkingBudget int

	// Effort is the model reasoning-effort level for providers that support
	// it. Valid values: "low", "medium", "high", "xhigh", "max"; empty means
	// provider default. Currently honored by claudecode (passed as the claude
	// CLI's --effort flag); other providers ignore it.
	Effort string

	// ResumeSession asks a provider that keeps a conversation to continue the
	// one a previous Result.SessionID named instead of starting a new one; the
	// prompt is then the next message in it. Providers that keep none ignore
	// it. Honoured by claudecode (the CLI's --resume), which is how a task
	// whose agent ended its turn mid-work is given the turn back with its
	// context intact (Task 20349).
	ResumeSession string

	// ReadOnly asks a provider that runs an agent harness to give it only
	// tools that read — no edit, no write, no shell. The review gate sets it
	// (Task 20357): a reviewer that could rewrite the work it is judging
	// would not be reviewing it. Honoured by claudecode (--tools); HTTP
	// providers run no tools and ignore it.
	ReadOnly bool

	// Env adds variables to the environment of an agent harness process, on
	// top of the one it inherits. The review gate uses it to hold the agent's
	// pushes (Task 20357). Honoured by claudecode; HTTP providers spawn no
	// process and ignore it.
	Env []string
}

type Provider interface {
	Complete(ctx context.Context, prompt string, opts Options) (*Result, error)
	Name() string
	DefaultModel() string
}

type ProviderConfig struct {
	// Which provider to use
	Name string

	// Anthropic settings
	AnthropicAPIKey  string
	AnthropicBaseURL string

	// OpenAI settings
	OpenAIAPIKey  string
	OpenAIBaseURL string

	// Ollama settings
	OllamaBaseURL string

	// Mock settings
	MockResponsesFile string

	// ClaudeCodeBackground tunes the handling of work the claude CLI leaves
	// running after it exits (Task 20205). The zero value detects it, waits
	// for it, and terminates whatever outlives the wait.
	ClaudeCodeBackground BackgroundPolicyConfig
}

type ProviderFactory func(cfg ProviderConfig) (Provider, error)

type Result struct {
	Output       string
	Duration     time.Duration
	Provider     string
	Model        string
	InputTokens  int // tokens in the prompt/input
	OutputTokens int // tokens in the completion/output
	// ThinkingTokens is the number of tokens used for reasoning/thinking content
	// (Anthropic extended thinking, OpenAI reasoning tokens). Estimated from output.
	ThinkingTokens int

	// Background reports work the harness left running after it exited, for
	// providers that spawn one. nil means none was detected — which is also
	// what the HTTP providers report, since they spawn no processes at all.
	//
	// A non-nil value with Drained false means the output above cannot be
	// trusted as a finished result: the harness described work it had only
	// started. Callers that gate other work on this one must treat that as
	// incomplete rather than as success.
	Background *BackgroundActivity

	// SessionID names the conversation this call ran in, for a provider that
	// can continue it through Options.ResumeSession. Empty when it cannot.
	SessionID string
}

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

type RetryConfig struct {
	MaxAttempts  int           // total attempts including the first (default: 3)
	InitialDelay time.Duration // base delay before the first retry (default: 1s)
	MaxDelay     time.Duration // cap on delay between retries (default: 30s)

	// BreakerKey, if non-empty, gates the call through a circuit breaker
	// looked up from the global registry (or created with default config).
	// When the breaker is open the call short-circuits with ErrCircuitOpen
	// without consuming an attempt or contacting the upstream.
	BreakerKey string
}