harnesses

type AccountInfo struct {
	Email    string `json:"email,omitempty"`
	PlanType string `json:"plan_type,omitempty"`
	OrgName  string `json:"org_name,omitempty"`
}

type ClaudeQuotaRoutingDecision struct {
	Fresh        bool   `json:"fresh"`
	PreferClaude bool   `json:"prefer_claude"`
	Reason       string `json:"reason,omitempty"`
}

type Event struct {
	Type     EventType         `json:"type"`
	Sequence int64             `json:"sequence"`
	Time     time.Time         `json:"time"`
	Metadata map[string]string `json:"metadata,omitempty"`
	Data     json.RawMessage   `json:"data"`
}

type EventType string

type ExecuteRequest struct {
	// Prompt is the resolved user prompt sent to the model.
	Prompt string

	// SystemPrompt is the resolved system prompt; empty means harness default.
	SystemPrompt string

	// Provider is the resolved provider identifier when applicable. May be
	// empty for harnesses that have no provider concept (e.g. claude CLI).
	Provider string

	// Model is the resolved model identifier; empty means harness default.
	Model string

	// WorkDir is the working directory for tool operations. Required when
	// the chosen harness uses tools.
	WorkDir string

	// Permissions is "safe" | "supervised" | "unrestricted". Empty defaults to "safe".
	Permissions string

	// Temperature is the model sampling temperature requested by the caller.
	// Harness adapters may ignore it when their CLI has no equivalent control.
	Temperature float32

	// Seed is the requested sampling seed. Zero means unset/provider chooses.
	// Harness adapters may ignore it when their CLI has no equivalent control.
	Seed int64

	// Reasoning is the normalized public reasoning scalar. Empty/off means no
	// adapter flag should be emitted.
	Reasoning string

	// Timeout is the wall-clock cap for the entire request. 0 disables.
	Timeout time.Duration

	// IdleTimeout is the streaming-quiet cap. 0 uses harness default.
	IdleTimeout time.Duration

	// SessionLogDir overrides the per-run session-log directory; harness
	// uses this to direct progress traces into a per-bundle evidence dir.
	SessionLogDir string

	// SessionID is a stable identifier for the run, used in progress log
	// filenames and event metadata. Empty means the harness generates one.
	SessionID string

	// Metadata is echoed back into Event.Metadata (e.g. bead_id, attempt_id).
	Metadata map[string]string
}

type FinalData struct {
	Status         string            `json:"status"` // success|iteration_limit|failed|stalled|timed_out|cancelled
	ExitCode       int               `json:"exit_code"`
	Error          string            `json:"error,omitempty"`
	FinalText      string            `json:"final_text,omitempty"`
	DurationMS     int64             `json:"duration_ms"`
	Usage          *FinalUsage       `json:"usage,omitempty"`
	Warnings       []FinalWarning    `json:"warnings,omitempty"`
	CostUSD        float64           `json:"cost_usd,omitempty"`
	SessionLogPath string            `json:"session_log_path,omitempty"`
	RoutingActual  *RoutingActual    `json:"routing_actual,omitempty"`
	Extra          map[string]string `json:"-"`
}

type FinalUsage struct {
	InputTokens      *int                  `json:"input_tokens,omitempty"`
	OutputTokens     *int                  `json:"output_tokens,omitempty"`
	CacheReadTokens  *int                  `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int                  `json:"cache_write_tokens,omitempty"`
	CacheTokens      *int                  `json:"cache_tokens,omitempty"`
	ReasoningTokens  *int                  `json:"reasoning_tokens,omitempty"`
	TotalTokens      *int                  `json:"total_tokens,omitempty"`
	Source           string                `json:"source,omitempty"`
	Fresh            *bool                 `json:"fresh,omitempty"`
	CapturedAt       string                `json:"captured_at,omitempty"`
	Sources          []UsageSourceEvidence `json:"sources,omitempty"`
}

type FinalWarning struct {
	Code    string                `json:"code"`
	Message string                `json:"message,omitempty"`
	Sources []UsageSourceEvidence `json:"sources,omitempty"`
}

type Harness interface {
	// Info returns identity + capability metadata for this harness.
	Info() HarnessInfo

	// HealthCheck triggers a fresh probe (binary present, auth ok, etc.)
	// and returns nil if the harness is ready to execute.
	HealthCheck(ctx context.Context) error

	// Execute runs one resolved request. Events stream on the returned
	// channel; a single final event closes the stream. The first error
	// return is reserved for setup failures (binary missing, etc.) — once
	// the channel is returned, all per-run failures are reported via a
	// final event with Status != "success".
	Execute(ctx context.Context, req ExecuteRequest) (<-chan Event, error)
}

type HarnessConfig struct {
	Name                string              // e.g. "codex", "claude", "gemini"
	Binary              string              // binary name to exec
	BaseArgs            []string            // args always included regardless of permission level
	PermissionArgs      map[string][]string // extra args keyed by permission level: "safe", "supervised", "unrestricted"
	PromptMode          string              // "arg" (final arg), "stdin" (pipe)
	DefaultModel        string              // built-in model choice when no config override exists
	Models              []string            // known valid models for this harness
	ReasoningLevels     []string            // supported reasoning levels in preference order
	MaxReasoningTokens  int                 // numeric reasoning budget max; 0 = unsupported/unknown
	ModelFlag           string              // flag for model override (e.g. "-m", "--model"), empty if unsupported
	WorkDirFlag         string              // flag for working directory (e.g. "-C", "--cwd"), empty if unsupported
	ReasoningFlag       string              // adapter flag for reasoning control, empty if unsupported
	ReasoningFormat     string              // format string for adapter reasoning value, empty = use value directly
	TokenPattern        string              // regex to extract token count from output, must have one capture group
	Surface             string              // catalog surface identifier: "codex", "claude", "embedded-openai", "embedded-anthropic"
	CostClass           string              // local, cheap, medium, expensive
	IsLocal             bool                // true for embedded/local harnesses (no cloud cost)
	ExactPinSupport     bool                // true if harness can accept an exact concrete model pin
	QuotaCommand        string              // CLI args for non-interactive quota introspection; empty = skip probe
	TUIQuotaCommand     string              // Slash command to send as a prompt when native quota signal is unavailable
	IsHTTPProvider      bool                // true for API-only providers (openrouter, lmstudio) that have no CLI binary
	IsSubscription      bool                // true for fixed-subscription harnesses (codex, claude)
	AutoRoutingEligible bool                // true when this harness has full coverage and may be selected by unattended profile routing
	TestOnly            bool                // true for sentinel/test harnesses that must never be selected by production tier routing
}

type HarnessInfo struct {
	Name                 string
	Type                 string // "native" | "subprocess"
	Available            bool
	Path                 string
	Error                string
	IsLocal              bool
	IsSubscription       bool
	AutoRoutingEligible  bool
	ExactPinSupport      bool
	DefaultModel         string
	SupportedPermissions []string
	SupportedReasoning   []string
	CostClass            string
}

type HarnessState struct {
	Installed           bool                        `json:"installed"`
	Reachable           bool                        `json:"reachable"`
	Authenticated       bool                        `json:"authenticated"`
	QuotaOK             bool                        `json:"quota_ok"`
	QuotaState          string                      `json:"quota_state,omitempty"` // ok, blocked, unknown
	Degraded            bool                        `json:"degraded"`
	PolicyOK            bool                        `json:"policy_ok"`
	LastCheckedUnix     int64                       `json:"last_checked_unix,omitempty"`
	Error               string                      `json:"error,omitempty"`
	Quota               *QuotaInfo                  `json:"quota,omitempty"`
	ClaudeQuotaDecision *ClaudeQuotaRoutingDecision `json:"claude_quota_decision,omitempty"`
}

type HarnessStatus struct {
	Name      string `json:"name"`
	Available bool   `json:"available"`
	Binary    string `json:"binary"`
	Path      string `json:"path,omitempty"` // resolved binary path
	Error     string `json:"error,omitempty"`
}

type LookPathFunc func(file string) (string, error)

type ModelDiscoverySnapshot struct {
	CapturedAt      time.Time `json:"captured_at"`
	Models          []string  `json:"models,omitempty"`
	ReasoningLevels []string  `json:"reasoning_levels,omitempty"`
	Source          string    `json:"source"`
	FreshnessWindow string    `json:"freshness_window,omitempty"`
	Detail          string    `json:"detail,omitempty"`
}

type QuotaInfo struct {
	PercentUsed int    `json:"percent_used"`
	LimitWindow string `json:"limit_window,omitempty"` // e.g. "5h", "7 day"
	ResetDate   string `json:"reset_date,omitempty"`   // e.g. "April 12"
}

type QuotaWindow struct {
	Name          string  `json:"name"`               // e.g. "5h", "7d", "spark"
	LimitID       string  `json:"limit_id,omitempty"` // provider limit_id
	LimitName     string  `json:"limit_name,omitempty"`
	WindowMinutes int     `json:"window_minutes"`
	UsedPercent   float64 `json:"used_percent"`
	ResetsAt      string  `json:"resets_at,omitempty"`      // human-readable
	ResetsAtUnix  int64   `json:"resets_at_unix,omitempty"` // unix timestamp
	State         string  `json:"state"`
}

type Registry struct {
	LookPath LookPathFunc
	// contains filtered or unexported fields
}

type RoutingActual struct {
	Harness            string   `json:"harness"`
	Provider           string   `json:"provider,omitempty"`
	Model              string   `json:"model"`
	FallbackChainFired []string `json:"fallback_chain_fired,omitempty"`
	FailureClass       string   `json:"failure_class,omitempty"`
	// Power is the catalog-projected power of the actually-dispatched
	// Model. 0 means unknown/exact-pin-only/no catalog entry.
	Power int `json:"power,omitempty"`
}

type TextDeltaData struct {
	Text string `json:"text"`
}

type ToolCallData struct {
	ID    string          `json:"id"`
	Name  string          `json:"name"`
	Input json.RawMessage `json:"input,omitempty"`
}

type ToolResultData struct {
	ID         string `json:"id"`
	Output     string `json:"output,omitempty"`
	Error      string `json:"error,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
}

type UsageCandidate struct {
	Source     string
	Fresh      *bool
	CapturedAt string
	Counts     UsageTokenCounts
	Warning    string
}

type UsageSourceEvidence struct {
	Source     string            `json:"source"`
	Fresh      *bool             `json:"fresh,omitempty"`
	CapturedAt string            `json:"captured_at,omitempty"`
	Usage      *UsageTokenCounts `json:"usage,omitempty"`
	Warning    string            `json:"warning,omitempty"`
}

type UsageTokenCounts struct {
	InputTokens      *int `json:"input_tokens,omitempty"`
	OutputTokens     *int `json:"output_tokens,omitempty"`
	CacheReadTokens  *int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int `json:"cache_write_tokens,omitempty"`
	CacheTokens      *int `json:"cache_tokens,omitempty"`
	ReasoningTokens  *int `json:"reasoning_tokens,omitempty"`
	TotalTokens      *int `json:"total_tokens,omitempty"`
}