fizeau

type AccountStatus struct {
	Authenticated   bool
	Unauthenticated bool
	Email           string
	PlanType        string
	OrgName         string
	Source          string
	CapturedAt      time.Time
	Fresh           bool
	Detail          string
}

type AnchorStore = anchorstore.AnchorStore

type BashOutputFilterConfig = tool.BashOutputFilterConfig

type CatalogProbeFunc func(ctx context.Context) (ids []string, err error)

type CatalogResult struct {
	IDs                []string  // server-order model IDs; empty when discovery unsupported or never fetched successfully
	FetchedAt          time.Time // zero when no successful fetch has occurred
	DiscoverySupported bool      // false when /v1/models returned 404; callers passthrough
	LastErr            error     // last probe's error if any; may be a ReachabilityError
	FromCache          bool      // true when served from cache (fresh or stale)
	Stale              bool      // true when served from a stale cache entry (async refresh kicked)
}

type CompactionConfig = compaction.Config

type CooldownState struct {
	Reason      string    // "consecutive_failures" | "route_attempt_failure" | "manual" | etc.
	Until       time.Time // when the cooldown expires
	FailCount   int       // number of consecutive failures that triggered the cooldown
	LastError   string    // last recorded error message, if available
	LastAttempt time.Time // when the feedback was recorded
}

type CorrelationIDNormalizationError struct {
	CorrelationID string
	Reason        string
}

type CostInfo struct {
	InputPerMTok  float64 // USD per 1M input tokens; 0 = unknown/free
	OutputPerMTok float64 // USD per 1M output tokens; 0 = unknown/free
}

type DecisionWithCandidates interface {
	error
	// RouteCandidates returns the evaluated candidates that led to the error.
	RouteCandidates() []RouteCandidate
}

type DrainExecuteResult struct {
	Events           []ServiceDecodedEvent
	TextDeltas       []ServiceTextDeltaData
	ToolCalls        []ServiceToolCallData
	ToolResults      []ServiceToolResultData
	Compactions      []ServiceCompactionData
	Progresses       []ServiceProgressData
	Stalls           []ServiceStallData
	RoutingDecision  *ServiceRoutingDecisionData
	Override         *ServiceOverrideData
	RejectedOverride *ServiceOverrideData
	Final            *ServiceFinalData

	FinalStatus    string
	FinalText      string
	Usage          *ServiceFinalUsage
	Warnings       []ServiceFinalWarning
	CostUSD        float64
	SessionLogPath string
	RoutingActual  *ServiceRoutingActual
	TerminalError  string
}

type EndpointStatus struct {
	Name          string
	BaseURL       string
	ProbeURL      string
	Status        string // connected|unreachable|unauthenticated|error|unknown
	Source        string
	CapturedAt    time.Time
	Fresh         bool
	LastSuccessAt time.Time
	ModelCount    int
	LastError     *StatusError
}

type ErrHarnessModelIncompatible struct {
	// Harness is the canonical harness name supplied by the caller.
	Harness string
	// Model is the exact concrete model pin supplied by the caller.
	Model string
	// SupportedModels is the harness allow-list that rejected Model.
	SupportedModels []string
}

type ErrNoLiveProvider struct {
	PromptTokens  int
	RequiresTools bool
	StartingTier  string
}

type ErrNoProfileCandidate struct {
	Profile           string
	MissingCapability string
	Rejected          int
}

type ErrProfilePinConflict struct {
	// Profile is the explicit profile requested by the caller.
	Profile string
	// ConflictingPin names the explicit pin that violates the profile, such as
	// "Harness=claude" or "Model=local-model".
	ConflictingPin string
	// ProfileConstraint is a short description of the profile placement rule,
	// such as "local-only" or "subscription-only".
	ProfileConstraint string
}

type ErrRejectedOverride struct {
	// Inner is the underlying pin error (e.g., *ErrHarnessModelIncompatible).
	Inner error
	// Event is the rejected_override payload (no outcome).
	Event ServiceOverrideData
}

type ErrUnknownProfile struct {
	Profile string
}

type ErrUnknownProvider struct {
	// Provider is the provider name supplied by the caller.
	Provider string
	// KnownProviders is the set of provider names the service knows about
	// (empty when no ServiceConfig is configured).
	KnownProviders []string
}

type FizeauService interface {
	Execute(ctx context.Context, req ServiceExecuteRequest) (<-chan ServiceEvent, error)
	TailSessionLog(ctx context.Context, sessionID string) (<-chan ServiceEvent, error)
	ListHarnesses(ctx context.Context) ([]HarnessInfo, error)
	ListProviders(ctx context.Context) ([]ProviderInfo, error)
	ListModels(ctx context.Context, filter ModelFilter) ([]ModelInfo, error)
	ListProfiles(ctx context.Context) ([]ProfileInfo, error)
	ResolveProfile(ctx context.Context, name string) (*ResolvedProfile, error)
	ProfileAliases(ctx context.Context) (map[string]string, error)
	HealthCheck(ctx context.Context, target HealthTarget) error
	ResolveRoute(ctx context.Context, req RouteRequest) (*RouteDecision, error)
	RecordRouteAttempt(ctx context.Context, attempt RouteAttempt) error
	RouteStatus(ctx context.Context) (*RouteStatusReport, error)

	// Historical session-log projections. CONTRACT-003 owns these so CLI
	// subcommands such as log/replay/usage do not need to read the
	// internal session-log JSONL schema.
	UsageReport(ctx context.Context, opts UsageReportOptions) (*UsageReport, error)
	ListSessionLogs(ctx context.Context) ([]SessionLogEntry, error)
	WriteSessionLog(ctx context.Context, sessionID string, w io.Writer) error
	ReplaySession(ctx context.Context, sessionID string, w io.Writer) error
}

type HarnessCapability struct {
	Status HarnessCapabilityStatus
	Detail string
}

type HarnessCapabilityMatrix struct {
	ExecutePrompt   HarnessCapability
	ModelDiscovery  HarnessCapability
	ModelPinning    HarnessCapability
	WorkdirContext  HarnessCapability
	ReasoningLevels HarnessCapability
	PermissionModes HarnessCapability
	ProgressEvents  HarnessCapability
	UsageCapture    HarnessCapability
	FinalText       HarnessCapability
	ToolEvents      HarnessCapability
	QuotaStatus     HarnessCapability
	RecordReplay    HarnessCapability
}

type HarnessCapabilityStatus string

type HarnessInfo struct {
	Name                 string
	Type                 string // "native" | "subprocess"
	Available            bool
	Path                 string
	Error                string
	IsLocal              bool
	IsSubscription       bool
	AutoRoutingEligible  bool
	TestOnly             bool
	ExactPinSupport      bool
	DefaultModel         string   // built-in default model when no override is supplied
	SupportedPermissions []string // subset of {"safe","supervised","unrestricted"}
	SupportedReasoning   []string // values such as {"low","medium","high","xhigh","max"}
	CostClass            string   // "local" | "cheap" | "medium" | "expensive"
	Quota                *QuotaState
	Account              *AccountStatus
	UsageWindows         []UsageWindow
	LastError            *StatusError
	CapabilityMatrix     HarnessCapabilityMatrix
}

type HealthTarget struct {
	Type string // "harness" | "provider"
	Name string
}

type ModelFilter struct {
	Harness  string
	Provider string
}

type ModelInfo struct {
	ID              string
	Provider        string
	ProviderType    string
	Harness         string
	EndpointName    string
	EndpointBaseURL string
	ContextLength   int
	Capabilities    []string
	Cost            CostInfo
	PerfSignal      PerfSignal
	Power           int
	AutoRoutable    bool
	ExactPinOnly    bool
	Available       bool
	IsConfigured    bool   // matches an explicit model_routes entry
	IsDefault       bool   // matches the configured default model
	CatalogRef      string // canonical catalog reference if recognized
	RankPosition    int    // ordinal in latest discovery rank; -1 if unranked
}

type NoViableProviderForNow struct {
	// RetryAfter is the earliest expected provider-recovery time across the
	// exhausted set. Callers should not retry before this instant.
	RetryAfter time.Time
	// ExhaustedProviders is the set of provider names currently in the
	// quota_exhausted state that would otherwise have served the request.
	ExhaustedProviders []string
}

type OverrideClassBucket struct {
	PromptFeatureBucket string `json:"prompt_feature_bucket"`
	Axis                string `json:"axis"`
	Match               bool   `json:"match"`
	Count               int    `json:"count"`

	SuccessOutcomes   int `json:"success_outcomes"`
	StalledOutcomes   int `json:"stalled_outcomes"`
	FailedOutcomes    int `json:"failed_outcomes"`
	CancelledOutcomes int `json:"cancelled_outcomes"`
	UnknownOutcomes   int `json:"unknown_outcomes"`
}

type PerfSignal struct {
	SpeedTokensPerSec float64 // 0 = unknown
	SWEBenchVerified  float64 // 0 = unknown
}

type ProfileInfo struct {
	Name               string
	Target             string
	AliasOf            string
	ProviderPreference string
	Deprecated         bool
	Replacement        string
	CatalogVersion     string
	ManifestSource     string
	ManifestVersion    int
}

type ProfileSurface struct {
	Name                    string
	Harness                 string
	ProviderSystem          string
	Model                   string
	Candidates              []string
	PlacementOrder          []string
	CostCeilingInputPerMTok *float64
	ReasoningDefault        Reasoning
	FailurePolicy           string
}

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

type ProviderInfo struct {
	Name           string
	Type           string // "openai" | "openrouter" | "lmstudio" | "omlx" | "ollama" | "anthropic" | "virtual"
	BaseURL        string
	Endpoints      []ServiceProviderEndpoint
	Status         string // "connected" | "unreachable" | "error: <msg>"
	ModelCount     int
	Capabilities   []string       // e.g. {"tool_use","streaming","json_mode"}
	IsDefault      bool           // matches the configured default_provider
	DefaultModel   string         // per-provider configured default model, if any
	CooldownState  *CooldownState // nil if not in cooldown
	Auth           AccountStatus
	EndpointStatus []EndpointStatus
	Quota          *QuotaState
	UsageWindows   []UsageWindow
	LastError      *StatusError
}

type ProviderQuotaState string

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

type QuotaRecoveryProber func(ctx context.Context, provider string) error

type QuotaState struct {
	Windows    []harnesses.QuotaWindow `json:"windows"`
	CapturedAt time.Time               `json:"captured_at"`
	Fresh      bool                    `json:"fresh"`
	Source     string                  `json:"source,omitempty"`
	Status     string                  `json:"status,omitempty"` // ok|stale|unavailable|unauthenticated|unknown
	LastError  *StatusError            `json:"last_error,omitempty"`
}

type ReadTool = tool.ReadTool

type Reasoning = reasoning.Reasoning

type ResolvedProfile struct {
	Name            string
	Target          string
	Deprecated      bool
	Replacement     string
	CatalogVersion  string
	ManifestSource  string
	ManifestVersion int
	Surfaces        []ProfileSurface
}

type RoleNormalizationError struct {
	// Role is the value that failed normalization.
	Role string
	// Reason is a short human-readable reason (e.g. "too long",
	// "contains invalid character").
	Reason string
}

type RouteAttempt struct {
	Harness   string
	Provider  string
	Model     string
	Endpoint  string
	Status    string
	Reason    string
	Error     string
	Duration  time.Duration
	Timestamp time.Time // zero = time.Now()
}

type RouteCandidate struct {
	// Harness is the candidate harness name.
	Harness string
	// Provider is the candidate provider name for native agent routes.
	Provider string
	// Endpoint is the provider endpoint name when applicable.
	Endpoint string
	// Model is the candidate concrete model.
	Model string
	// Score is the routing score assigned before final ordering.
	Score float64
	// CostUSDPer1kTokens is the estimated blended USD cost per 1,000 tokens.
	CostUSDPer1kTokens float64
	// CostSource indicates whether cost came from catalog, subscription,
	// user-config, or is unknown.
	CostSource string
	// Eligible reports whether the candidate passed all routing gates.
	Eligible bool
	// Reason is the scoring reason for eligible candidates or the rejection
	// reason for ineligible candidates.
	Reason string
	// FilterReason names the gate that disqualified an ineligible candidate.
	// Empty when Eligible. See the FilterReason* constants.
	FilterReason string
	// Components carries the per-axis score inputs (power, cost, latency,
	// success rate, quota, capability) that fed the final Score. Consumers use these to
	// explain rankings without parsing the free-form Reason.
	Components RouteCandidateComponents
}

type RouteCandidateComponents struct {
	// Power is the catalog model power used by automatic routing. Zero means
	// unknown or not contributing.
	Power int
	// Cost is the per-1k-token cost expressed as a numeric component (USD).
	// Mirrors RouteCandidate.CostUSDPer1kTokens; surfaced here so the event
	// payload carries a single component bundle.
	Cost float64
	// CostClass is the candidate cost class used by the router.
	CostClass string
	// LatencyMS is the observed median latency for this candidate, in
	// milliseconds. Zero when no observations are available.
	LatencyMS float64
	// SpeedTPS is the observed output speed in tokens per second. Zero when
	// no observations are available.
	SpeedTPS float64
	// SuccessRate is the observed success rate (0–1) for this candidate.
	// Negative means insufficient data; zero means unknown.
	SuccessRate float64
	// QuotaOK/QuotaPercentUsed/QuotaTrend are subscription quota inputs used
	// by routing. They are zero values for non-subscription candidates.
	QuotaOK          bool
	QuotaPercentUsed int
	QuotaTrend       string
	// Capability is a coarse capability score derived from the candidate's
	// cost class / surface (higher = more capable).
	Capability float64
}

type RouteCandidateStatus struct {
	Provider                string
	Model                   string
	Priority                int
	Healthy                 bool
	Cooldown                *CooldownState
	RecentLatencyMS         float64 // observation-derived; 0 when unavailable
	ProviderReliabilityRate float64 // 0-1; 0 when unavailable. Legacy success-rate field, relabeled per ADR-006 §5 to disambiguate from routing-quality.
}

type RouteDecision struct {
	// Harness is the selected harness name.
	Harness string
	// Provider is the selected provider for native agent routes.
	Provider string
	// Endpoint is the selected named endpoint when the provider exposes more
	// than one endpoint.
	Endpoint string
	// Model is the selected concrete model.
	Model string
	// Reason summarizes why the selected candidate won.
	Reason string
	// Power is the catalog-projected power of the selected Model
	// (per CONTRACT-003 § Catalog Power Projection). 0 means
	// unknown/exact-pin-only/no catalog entry. DDx callers read this
	// to compute next-attempt MinPower without importing catalog code.
	Power int
	// Candidates is the full ranked decision trace, including rejected
	// candidates and their rejection reasons.
	Candidates []RouteCandidate
}

type RouteRequest struct {
	Profile     string // optional named policy bundle: cheap|standard|smart|custom
	Model       string
	Provider    string
	Harness     string
	ModelRef    string
	Reasoning   Reasoning
	Permissions string
	MinPower    int
	MaxPower    int

	// EstimatedPromptTokens, when > 0, filters out candidates whose context
	// window cannot accommodate the prompt (with a safety margin).
	EstimatedPromptTokens int

	// RequiresTools, when true, filters out candidates that do not support
	// tool calling.
	RequiresTools bool

	// CachePolicy mirrors ServiceExecuteRequest.CachePolicy. Routing decisions
	// today do not act on it; it is carried through so callers using
	// ResolveRoute as a public surface can plumb the same opt-out the
	// Execute path honors.
	CachePolicy string

	// Role tags the kind of work this call performs (e.g. "implementer",
	// "reviewer", "decomposer"). Observational only — it does NOT enter the
	// routing precedence chain. Mirrors ServiceExecuteRequest.Role so
	// ResolveRoute previews don't diverge from Execute.
	Role string

	// CorrelationID joins calls that share work context (e.g.
	// "bead_123:attempt_4"). Observational only — it does NOT enter the
	// routing precedence chain. Mirrors ServiceExecuteRequest.CorrelationID.
	CorrelationID string
}

type RouteStatusEntry struct {
	Model          string // route key
	Strategy       string // "priority-round-robin" | "first-available" | etc.
	Candidates     []RouteCandidateStatus
	LastDecision   *RouteDecision // most recent ResolveRoute result for this key (cached)
	LastDecisionAt time.Time
}

type RouteStatusReport struct {
	Routes          []RouteStatusEntry
	GeneratedAt     time.Time
	GlobalCooldowns []CooldownState
	// RoutingQuality holds the three first-class routing-quality metrics
	// over a recent window (last RouteStatusRoutingQualityWindow requests).
	RoutingQuality RoutingQualityMetrics
}

type RoutingQualityMetrics struct {
	// AutoAcceptanceRate = no-override requests / total requests. Higher is
	// better. The headline number for routing health.
	AutoAcceptanceRate float64 `json:"auto_acceptance_rate"`

	// OverrideDisagreementRate = overrides where the user pin differs from
	// auto on at least one overridden axis / total overrides. Lower is
	// better. Coincidental-agreement overrides land in the denominator but
	// not the numerator.
	OverrideDisagreementRate float64 `json:"override_disagreement_rate"`

	// OverrideClassBreakdown is a pivot of (prompt_features bucket,
	// axis_overridden, match_per_axis) → count + outcome aggregates.
	// Sorted deterministically by (PromptFeatureBucket, Axis, Match) so
	// snapshot tests remain stable across runs.
	OverrideClassBreakdown []OverrideClassBucket `json:"override_class_breakdown,omitempty"`

	// TotalRequests is the total Execute count over the metric window
	// (including overridden requests). Surface for operator UIs that want
	// to display "k out of N" alongside the rate.
	TotalRequests int `json:"total_requests"`

	// TotalOverrides is the total override count over the metric window.
	// Equal to TotalRequests-(no-override requests).
	TotalOverrides int `json:"total_overrides"`
}

type ScoredModel = oaiProvider.ScoredModel

type ServiceCompactionData struct {
	MessagesBefore int `json:"messages_before"`
	MessagesAfter  int `json:"messages_after"`
	TokensFreed    int `json:"tokens_freed"`
}

type ServiceConfig interface {
	// ProviderNames returns provider names in stable order (default first).
	ProviderNames() []string
	// DefaultProviderName returns the name of the configured default provider.
	DefaultProviderName() string
	// Provider returns the raw config values for a named provider.
	Provider(name string) (ServiceProviderEntry, bool)
	// ModelRouteNames returns configured model-route names.
	ModelRouteNames() []string
	// ModelRouteCandidates returns the provider names referenced by a route.
	ModelRouteCandidates(routeName string) []string
	// ModelRouteConfig returns the full route config for a named route.
	// Returns zero value when the route is not found.
	ModelRouteConfig(routeName string) ServiceModelRouteConfig
	// HealthCooldown returns the configured cooldown duration (0 = use default 30s).
	HealthCooldown() time.Duration
	// WorkDir is the base directory for file-backed health state.
	WorkDir() string
	// SessionLogDir returns the configured sessions directory.
	SessionLogDir() string
	// RouteHealthPath returns the path to the route health file for a given route key.
	RouteHealthPath(routeKey string) string
}

type ServiceDecodedEvent struct {
	Type     string
	Sequence int64
	Time     time.Time
	Metadata map[string]string

	TextDelta        *ServiceTextDeltaData
	ToolCall         *ServiceToolCallData
	ToolResult       *ServiceToolResultData
	Compaction       *ServiceCompactionData
	Progress         *ServiceProgressData
	RoutingDecision  *ServiceRoutingDecisionData
	Stall            *ServiceStallData
	Final            *ServiceFinalData
	Override         *ServiceOverrideData
	RejectedOverride *ServiceOverrideData
}

type ServiceEvent = harnesses.Event

type ServiceExecuteRequest struct {
	Prompt            string
	SystemPrompt      string
	Model             string
	Provider          string
	Harness           string
	ModelRef          string
	Profile           string
	WorkDir           string
	Temperature       *float32
	TopP              *float64
	TopK              *int
	MinP              *float64
	RepetitionPenalty *float64
	Seed              *int64
	// SamplingSource is the comma-separated layer attribution produced by
	// internal/sampling.Resolve. Plumbed through to the llm.request
	// telemetry event for ADR-007 override-tracking; never on the wire.
	SamplingSource string
	Reasoning      Reasoning
	NoStream       bool
	Permissions    string
	// Tools overrides the built-in native agent tool set when Harness is
	// "agent". Nil uses the native built-ins for ToolPreset and WorkDir.
	Tools []Tool
	// ToolPreset is passed through to BuiltinToolsForPreset when Tools is nil.
	// Empty uses the default tool set.
	ToolPreset string

	// PlanningMode, when true, performs one no-tool LLM "planning" call
	// before the main native agent loop and injects the response as an
	// assistant message wrapped in <plan> tags. The benchmark tool preset
	// auto-enables planning; this flag is the per-request opt-in for other
	// callers (e.g. the CLI --plan flag). Only honored when Harness=="agent"
	// (the native loop). See internal/core.Request.PlanningMode.
	PlanningMode bool

	// EstimatedPromptTokens, when > 0, drives auto-selection's
	// context-window gate (filter out candidates whose context window is
	// too small for the prompt + safety margin).
	EstimatedPromptTokens int
	// RequiresTools, when true, drives auto-selection's tool-support gate
	// (filter out candidates that cannot invoke tools).
	RequiresTools bool
	MinPower      int
	MaxPower      int

	// CachePolicy is the public opt-out for prompt caching. Empty (the zero
	// value) and "default" both request the per-provider default caching
	// behavior; "off" disables caching for this request. Any other value is
	// rejected at the service boundary (see ValidateCachePolicy). Providers
	// that do not implement caching ignore the field; this field is read by
	// the Anthropic cache_control writer (bead C) and the cache-aware cost
	// attribution path (bead D).
	CachePolicy string

	// Three independent timeout knobs:
	//   Timeout         — wall-clock cap on the entire request.
	//   IdleTimeout     — streaming-quiet cap; per-stream gap.
	//   ProviderTimeout — per-HTTP-request cap to the provider.
	Timeout         time.Duration
	IdleTimeout     time.Duration
	ProviderTimeout time.Duration

	// Optional native-loop overrides used when Harness == "agent". These let
	// the CLI and other callers route fully-resolved execution settings through
	// the service path instead of maintaining a divergent direct loop path.
	MaxIterations           int
	MaxTokens               int
	ReasoningByteLimit      int
	CompactionContextWindow int
	CompactionReserveTokens int

	// Optional stall policy. When non-nil agent enforces and ends with
	// Status="stalled" if any limit hits. Default policy applies when nil.
	StallPolicy *StallPolicy

	// SessionLogDir overrides the default session-log directory for this
	// request (e.g. an execute-bead per-bundle evidence directory).
	SessionLogDir string

	// SelectedRoute is the configured model-route name the caller picked
	// (e.g. "code-pool"). Recorded into the service-owned session log so
	// post-hoc routing analytics can correlate logs to route keys without
	// reconstructing attribution from the event stream.
	SelectedRoute string

	// ResolvedModelRef is the profile/model reference (e.g. "code-medium")
	// that was mapped onto the concrete Model for this request. Paired with
	// ModelRef (the caller-requested reference) in the session log.
	ResolvedModelRef string

	// Metadata is bidirectional: echoed back in every Event AND stamped
	// onto every line of the session log so external consumers correlate.
	Metadata map[string]string

	// Role tags the kind of work this call performs (e.g. "implementer",
	// "reviewer", "decomposer", "summarizer"). Observational: echoed into
	// the routing_decision and final event Metadata, plus the session-log
	// header. Per CONTRACT-003 it is NOT part of the selection precedence
	// chain (Day 1) and does NOT affect routing. Empty means unset.
	//
	// Normalization: lowercased, alphanumeric + hyphen only, max 64 chars;
	// invalid values are rejected pre-dispatch with RoleNormalizationError.
	Role string
	// CorrelationID links calls that share work context (e.g.
	// "bead_123:attempt_4") so reviewer/implementer/retry attempts can be
	// joined in logs and aggregations. Observational: echoed into
	// routing_decision and final event Metadata, plus the session-log
	// header. Per CONTRACT-003 it is NOT part of the selection precedence
	// chain (Day 1) and does NOT affect routing. Empty means unset.
	//
	// Normalization: printable ASCII (no control chars, no whitespace
	// except hyphen, colon, underscore), max 256 chars; invalid values
	// are rejected pre-dispatch with CorrelationIDNormalizationError.
	CorrelationID string
}

type ServiceFinalData struct {
	Status         string                `json:"status"`
	ExitCode       int                   `json:"exit_code"`
	Error          string                `json:"error,omitempty"`
	FinalText      string                `json:"final_text,omitempty"`
	DurationMS     int64                 `json:"duration_ms"`
	Usage          *ServiceFinalUsage    `json:"usage,omitempty"`
	Warnings       []ServiceFinalWarning `json:"warnings,omitempty"`
	CostUSD        float64               `json:"cost_usd,omitempty"`
	SessionLogPath string                `json:"session_log_path,omitempty"`
	RoutingActual  *ServiceRoutingActual `json:"routing_actual,omitempty"`
}

type ServiceFinalUsage 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          []ServiceUsageSourceEvidence `json:"sources,omitempty"`
}

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

type ServiceModelRouteConfig struct {
	Strategy   string                       // "priority-round-robin" | "ordered-failover" | "smart" | ""
	Candidates []ServiceRouteCandidateEntry // ordered candidate list
}

type ServiceOptions struct {
	ConfigPath string    // optional override; default $XDG_CONFIG_HOME/fizeau/config.yaml
	Logger     io.Writer // optional; agent writes structured session logs internally regardless

	// ServiceConfig, when non-nil, supplies provider and routing data for
	// ListProviders and HealthCheck. Pass a value wrapping the loaded config.
	// When nil, those methods return an error.
	ServiceConfig ServiceConfig

	// QuotaRefreshDebounce is the minimum interval between live quota probes for
	// a primary subscription harness. Zero uses the service default.
	QuotaRefreshDebounce time.Duration
	// QuotaRefreshStartupWait bounds startup waiting when the durable quota
	// cache is missing, stale, or incomplete. Zero uses the service default.
	QuotaRefreshStartupWait time.Duration
	// QuotaRefreshInterval enables periodic refresh for long-running server
	// processes. Zero disables the timer; cache refresh still happens on startup
	// and service activity.
	QuotaRefreshInterval time.Duration
	// QuotaRefreshContext optionally cancels the periodic server refresh worker.
	// When nil, the worker uses context.Background().
	QuotaRefreshContext context.Context

	// CatalogProbeTimeout bounds live /v1/models discovery during routing.
	// Zero uses the service default of 2s.
	CatalogProbeTimeout time.Duration
	// CatalogRefreshTimeout bounds stale-while-revalidate catalog refreshes.
	// Zero uses the service default of 30s.
	CatalogRefreshTimeout time.Duration

	// LocalCostUSDPer1kTokens is the operator-supplied electricity/operations
	// estimate for local endpoint providers under the embedded agent harness.
	// Zero means local endpoint cost is unknown.
	LocalCostUSDPer1kTokens float64
	// SubscriptionCostCurve optionally overrides the default subscription
	// effective-cost curve used by routing.
	SubscriptionCostCurve *SubscriptionCostCurve

	// SessionLogDir overrides the directory used by historical session-log
	// projections (UsageReport, ListSessionLogs, WriteSessionLog,
	// ReplaySession). Empty falls back to ServiceConfig.SessionLogDir().
	// Per-Execute requests still set their own
	// ServiceExecuteRequest.SessionLogDir.
	SessionLogDir string

	// StaleHarnessReaperGrace is the minimum age before a startup reaper may
	// terminate an owned subprocess record. Zero uses the default grace window.
	StaleHarnessReaperGrace time.Duration
	// contains filtered or unexported fields
}

type ServiceOverrideAutoComponents struct {
	Power            int     `json:"power"`
	Cost             float64 `json:"cost"`
	CostClass        string  `json:"cost_class,omitempty"`
	LatencyMS        float64 `json:"latency_ms"`
	SpeedTPS         float64 `json:"speed_tps"`
	SuccessRate      float64 `json:"success_rate"`
	QuotaOK          bool    `json:"quota_ok"`
	QuotaPercentUsed int     `json:"quota_percent_used"`
	QuotaTrend       string  `json:"quota_trend,omitempty"`
	Capability       float64 `json:"capability"`
}

type ServiceOverrideData struct {
	SessionID      string                        `json:"session_id,omitempty"`
	UserPin        ServiceOverridePin            `json:"user_pin"`
	AutoDecision   ServiceOverridePin            `json:"auto_decision"`
	AxesOverridden []string                      `json:"axes_overridden"`
	MatchPerAxis   map[string]bool               `json:"match_per_axis"`
	AutoScore      float64                       `json:"auto_score"`
	AutoComponents ServiceOverrideAutoComponents `json:"auto_components"`
	PromptFeatures ServiceOverridePromptFeatures `json:"prompt_features"`
	ReasonHint     string                        `json:"reason_hint,omitempty"`
	Outcome        *ServiceOverrideOutcome       `json:"outcome,omitempty"`
	RejectionError string                        `json:"rejection_error,omitempty"`
}

type ServiceOverrideOutcome struct {
	Status     string  `json:"status"`
	CostUSD    float64 `json:"cost_usd,omitempty"`
	DurationMS int64   `json:"duration_ms"`
}

type ServiceOverridePin struct {
	Harness  string `json:"harness"`
	Provider string `json:"provider"`
	Model    string `json:"model"`
}

type ServiceOverridePromptFeatures struct {
	EstimatedTokens *int   `json:"estimated_tokens,omitempty"`
	RequiresTools   bool   `json:"requires_tools"`
	Reasoning       string `json:"reasoning,omitempty"`
}

type ServiceProgressData struct {
	Phase                 string `json:"phase"`
	State                 string `json:"state"`
	Message               string `json:"message,omitempty"`
	TurnIndex             int    `json:"turn_index,omitempty"`
	ToolName              string `json:"tool_name,omitempty"`
	Command               string `json:"command,omitempty"`
	DurationMS            int64  `json:"duration_ms,omitempty"`
	InputTokens           *int   `json:"input_tokens,omitempty"`
	OutputTokens          *int   `json:"output_tokens,omitempty"`
	TotalTokens           *int   `json:"total_tokens,omitempty"`
	ContextMessages       int    `json:"context_messages,omitempty"`
	ContextTokensEstimate int    `json:"context_tokens_estimate,omitempty"`
	SessionSummary        string `json:"session_summary,omitempty"`
}

type ServiceProviderEndpoint struct {
	Name    string
	BaseURL string
}

type ServiceProviderEntry struct {
	Type      string // "openai" | "openrouter" | "lmstudio" | "omlx" | "ollama" | "anthropic"
	BaseURL   string
	Endpoints []ServiceProviderEndpoint
	APIKey    string
	Model     string // configured default model (may be empty)
	// DailyTokenBudget is the operator-configured per-UTC-day token budget
	// (request + response) for this provider. Zero means no local burn-rate
	// prediction; the provider's own quota signal still applies.
	DailyTokenBudget int
}

type ServiceRouteCandidateEntry struct {
	Provider string
	Model    string // may be empty (provider default)
	Priority int
}

type ServiceRoutingActual 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 (CONTRACT-003 § Catalog Power Projection). 0 means
	// unknown/exact-pin-only/no catalog entry.
	Power int `json:"power,omitempty"`
}

type ServiceRoutingDecisionCandidate struct {
	Harness            string                           `json:"harness"`
	Provider           string                           `json:"provider,omitempty"`
	Endpoint           string                           `json:"endpoint,omitempty"`
	Model              string                           `json:"model,omitempty"`
	Score              float64                          `json:"score"`
	CostUSDPer1kTokens float64                          `json:"cost_usd_per_1k_tokens,omitempty"`
	CostSource         string                           `json:"cost_source,omitempty"`
	Eligible           bool                             `json:"eligible"`
	Reason             string                           `json:"reason,omitempty"`
	FilterReason       string                           `json:"filter_reason,omitempty"`
	Components         ServiceRoutingDecisionComponents `json:"components"`
}

type ServiceRoutingDecisionComponents struct {
	Power            int     `json:"power"`
	Cost             float64 `json:"cost"`
	CostClass        string  `json:"cost_class,omitempty"`
	LatencyMS        float64 `json:"latency_ms"`
	SpeedTPS         float64 `json:"speed_tps"`
	SuccessRate      float64 `json:"success_rate"`
	QuotaOK          bool    `json:"quota_ok"`
	QuotaPercentUsed int     `json:"quota_percent_used"`
	QuotaTrend       string  `json:"quota_trend,omitempty"`
	Capability       float64 `json:"capability"`
}

type ServiceRoutingDecisionData struct {
	Harness          string   `json:"harness"`
	Provider         string   `json:"provider,omitempty"`
	Endpoint         string   `json:"endpoint,omitempty"`
	Model            string   `json:"model"`
	Reason           string   `json:"reason"`
	RequestedHarness string   `json:"requested_harness,omitempty"`
	HarnessSource    string   `json:"harness_source,omitempty"`
	FallbackChain    []string `json:"fallback_chain,omitempty"`
	SessionID        string   `json:"session_id,omitempty"`

	// Candidates exposes the full ranked decision trace. Each candidate
	// carries per-axis component scores (cost / latency / success rate /
	// capability) plus an explicit filter_reason for rejected entries.
	Candidates []ServiceRoutingDecisionCandidate `json:"candidates,omitempty"`
}

type ServiceStallData struct {
	Reason string `json:"reason"`
	Count  int64  `json:"count"`
}

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

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

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

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

type ServiceUsageTokenCounts 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"`
}

type SessionEndData = session.SessionEndData

type SessionEvent = agentcore.Event

type SessionEventType = agentcore.EventType

type SessionLogEntry struct {
	SessionID string    `json:"session_id"`
	ModTime   time.Time `json:"mod_time"`
	Size      int64     `json:"size"`
}

type SessionLogger = session.Logger

type SessionStartData = session.SessionStartData

type SessionStatus = agentcore.Status

type SkillCatalog = skill.Catalog

type StallPolicy struct {
	MaxReadOnlyToolIterations int // 0 = disabled
	MaxNoopCompactions        int // 0 = disabled
}

type StatusError struct {
	Type      string    // unavailable|unauthenticated|error
	Detail    string    // human-readable detail, safe for diagnostics
	Source    string    // config path, endpoint, cache path, or probe name
	Timestamp time.Time // zero when the source did not include a timestamp
}

type SubscriptionCostCurve struct {
	FreeUntilPercent   int
	LowUntilPercent    int
	MediumUntilPercent int
	LowMultiplier      float64
	MediumMultiplier   float64
	HighMultiplier     float64
}

type TokenUsage = agentcore.TokenUsage

type Tool = agentcore.Tool

type UsageReport struct {
	Window         *UsageReportWindow    `json:"window,omitempty"`
	Rows           []UsageReportRow      `json:"rows"`
	Totals         UsageReportRow        `json:"totals"`
	RoutingQuality RoutingQualityMetrics `json:"routing_quality"`
}

type UsageReportOptions struct {
	// Since limits the report window. Supported values include "today", "7d",
	// "30d", a date range "YYYY-MM-DD..YYYY-MM-DD", or a single start date.
	// Empty means no window filter (all sessions).
	Since string
	// Now is the reference time for relative windows. Zero means time.Now().
	Now time.Time
}

type UsageReportRow struct {
	Provider            string   `json:"provider"`
	Model               string   `json:"model"`
	Sessions            int      `json:"sessions"`
	SuccessSessions     int      `json:"success_sessions"`
	FailedSessions      int      `json:"failed_sessions"`
	InputTokens         int      `json:"input_tokens"`
	OutputTokens        int      `json:"output_tokens"`
	TotalTokens         int      `json:"total_tokens"`
	DurationMs          int64    `json:"duration_ms"`
	KnownCostUSD        *float64 `json:"known_cost_usd"`
	UnknownCostSessions int      `json:"unknown_cost_sessions"`
	CacheReadTokens     int      `json:"cache_read_tokens"`
	CacheWriteTokens    int      `json:"cache_write_tokens"`
}

type UsageReportWindow struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

type UsageWindow struct {
	Name                string
	Source              string
	CapturedAt          time.Time
	Fresh               bool
	InputTokens         int
	OutputTokens        int
	TotalTokens         int
	CacheReadTokens     int
	CacheWriteTokens    int
	ReasoningTokens     int
	CostUSD             float64
	KnownCostUSD        *float64
	UnknownCostSessions int
}