config

type Agent struct {
	ID                  string        `json:"id"`
	Name                string        `json:"name"`
	Model               string        `json:"model"`
	ModelThinking       string        `json:"model_thinking"`
	ModelStrong         string        `json:"model_strong"`
	ModelStrongThinking string        `json:"model_strong_thinking"`
	ModelFast           string        `json:"model_fast"`
	ModelFastThinking   string        `json:"model_fast_thinking"`
	SystemPrompt        string        `json:"system_prompt"`
	Soul                string        `json:"soul"`
	Workspace           string        `json:"workspace"`
	Sandbox             SandboxConfig `json:"sandbox"`
	Scope               string        `json:"scope"`
	CreatorID           string        `json:"creator_id"`
	Enabled             bool          `json:"enabled"`
	LastActive          *time.Time    `json:"last_active,omitempty"`
}

type BlobS3Config struct {
	Endpoint  string
	Bucket    string
	AccessKey string
	SecretKey string
	Region    string
	UseSSL    string
}

type BuiltinPlugin struct {
	ID             string
	Kind           string
	Name           string
	DefaultEnabled bool
}

type CachedModel struct {
	Provider     string `json:"provider"`
	ProviderName string `json:"provider_name,omitempty"`
	Model        string `json:"model"`
}

type Channel struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Type    string `json:"type"`
	AgentID string `json:"agent_id,omitempty"`
	Enabled bool   `json:"enabled"`
	Config  string `json:"config"`
}

type ChannelBindingConflictError struct {
	AgentID   string
	Type      string
	ChannelID string
}

type CompactionConfig struct {
	// MaxTokens triggers compaction when the estimated token count exceeds this.
	// 0 (or omitted) uses the default of 80000. Negative values disable
	// automatic compaction. Manual /compact still works.
	MaxTokens int `json:"max_tokens"`
	// KeepTail is the number of recent user turns to preserve verbatim
	// after compaction. Default: 6.
	KeepTail int `json:"keep_tail"`
}

type DatabaseConfig struct {
	// RequireExternalDB forbids the embedded-PostgreSQL fallback. The embedded
	// cluster is a single-node local convenience: in a container it lands on an
	// ephemeral filesystem, and with multiple replicas each process would create
	// its own database. The Docker image sets this by default; set it to 0 to
	// deliberately run embedded PostgreSQL inside a container (e.g. a single
	// container with a persistent volume). Unset or empty is false; any other
	// value is parsed as a boolean and an unparseable value fails fast.
	RequireExternalDB bool
	// URL is an explicitly configured PostgreSQL DSN (STELLA_DATABASE_URL), or ""
	// when none is set. An empty result tells the server to start and manage its
	// own embedded PostgreSQL — the zero-config default, so a fresh install needs
	// no separately installed or running database.
	URL string
}

type DiagnosticsConfig struct {
	// PprofAddr is the listen address for the net/http/pprof debug server
	// (STELLA_PPROF_ADDR). Empty (unset) leaves the debug server disabled. Raw
	// (os.Getenv semantics) so the disabled-when-empty check is unchanged.
	PprofAddr string
}

type EmbeddingSettings struct {
	Enabled   bool   `json:"enabled"`
	Model     string `json:"model"`
	Dim       int    `json:"dim"`
	APIKey    string `json:"api_key"`
	BaseURL   string `json:"base_url"`
	Normalize bool   `json:"normalize"`
}

type Lifecycle struct {
	// HTTPShutdownTimeout is the drain budget for in-flight HTTP requests. When
	// the budget is spent the server force-closes any still-open connections.
	HTTPShutdownTimeout time.Duration
	// RiverSoftStopTimeout is the drain budget for in-flight background jobs
	// (goal/scheduler agent runs) before River cancels their work contexts and
	// escalates to a hard stop.
	RiverSoftStopTimeout time.Duration
}

type ManifestPluginOverride struct {
	PluginID           string
	Enabled            *bool  // nil = fallback to manifest default; non-nil = override
	SessionEnvVaultKey string // empty = fallback; non-empty = vault blob with session_env override map
	Config             string // JSON manifest plugin definition override; empty = fallback to builtin
	UpdatedAt          string
}

type OIDCConfig struct {
	ProviderName string
	IssuerURL    string
	ClientID     string
	ClientSecret string
	RedirectURL  string
	Scopes       string
}

type ObservabilityConfig struct {
	// RecordToolIO records tool input/output payloads on spans
	// (OTEL_STELLA_RECORD_TOOL_IO). Preserves the exact ==\"true\" opt-in: any
	// other value, including unset, leaves it off.
	RecordToolIO bool
	// RiverLogLevel is the raw LOG_LEVEL_RIVER value ("" for unset). The River
	// job queue heartbeats at DEBUG/INFO, so its logger is capped at WARN unless
	// this opens it up; internal/cli.ParseLogLevel owns the level dialect.
	RiverLogLevel string
}

type Plugin struct {
	ID      string         `json:"id"`
	Kind    string         `json:"kind"`
	Name    string         `json:"name"`
	Enabled bool           `json:"enabled"`
	Config  map[string]any `json:"config"`
}

type Provider struct {
	ID      string                   `json:"id"`
	Type    string                   `json:"type"`
	Name    string                   `json:"name"`
	Enabled bool                     `json:"enabled"`
	APIKey  string                   `json:"api_key"`
	BaseURL string                   `json:"base_url"`
	Models  map[string]ProviderModel `json:"models,omitempty"`
}

type ProviderCreds struct {
	Type    string
	APIKey  string
	BaseURL string
}

type ProviderModel struct {
	ID            string            `json:"id,omitempty"`
	Name          string            `json:"name,omitempty"`
	Enabled       bool              `json:"enabled"`
	Reasoning     bool              `json:"reasoning,omitempty"`
	Input         []string          `json:"input,omitempty"`
	Output        []string          `json:"output,omitempty"`
	ContextWindow int               `json:"contextWindow,omitempty"`
	MaxTokens     int               `json:"maxTokens,omitempty"`
	Cost          ProviderModelCost `json:"cost,omitzero"`
}

type ProviderModelCost struct {
	Input      float64 `json:"input,omitempty"`
	Output     float64 `json:"output,omitempty"`
	CacheRead  float64 `json:"cacheRead,omitempty"`
	CacheWrite float64 `json:"cacheWrite,omitempty"`
}

type ReflectConfig struct {
	Interval    string
	Mode        string
	CuratorMode string
}

type RunnerConfig struct {
	System          string           `json:"system"`
	IdleTimeout     int              `json:"idle_timeout"`
	DelegateTimeout int              `json:"delegate_timeout"` // minutes; 0 = use default (15m)
	Compaction      CompactionConfig `json:"compaction"`
}

type SandboxConfig struct {
	Network SandboxNetworkConfig `json:"network"`
}

type SandboxNetworkConfig struct {
	Mode      string   `json:"mode"`
	Allowlist []string `json:"allowlist"`
}

type SchedulerConfig struct {
	Enabled *bool  `json:"enabled"`
	DataDir string `json:"data_dir"`
}

type ServerConfig struct {
	// Database selects between the embedded PostgreSQL convenience cluster and an
	// external server.
	Database DatabaseConfig
	// Lifecycle bounds the two-phase graceful-shutdown drain. It is the same type
	// injected since #700; keep it a nested group so that injection path is
	// unchanged.
	Lifecycle Lifecycle
	// ServerURL is the URL CLI commands use to reach the local stella server.
	// It has no Go consumer today (the sandbox injects STELLA_SERVER_URL into the
	// container itself); the field is carried so a future CLI client threads it
	// from here instead of reading the environment directly.
	ServerURL string
	// BaseURL is the externally reachable base URL of the deployment
	// (STELLA_BASE_URL), raw and un-normalized: "" means "derive from the bind
	// host". The gateway trims a trailing slash where it builds absolute URLs;
	// the raw value is carried so that trimming stays at the use site.
	BaseURL string
	// Vault carries the master key used to seal per-user secrets.
	Vault VaultConfig
	// OIDC is the static single-provider OIDC block. It is read raw (no trim) so
	// the external-vs-local mode decision, the provider config, and the
	// dependent-feature check all observe one snapshot with no os.Getenv/config
	// generation split.
	OIDC OIDCConfig
	// Blob holds the raw S3-compatible blob-store settings. The group constraint
	// (any set => the four core fields required) and the USE_SSL bool dialect stay
	// in the blob package, which consumes these raw strings.
	Blob BlobS3Config
	// Reflect carries the raw reflect-scheduler tuning strings. Parsing stays in
	// the reflect setup so its lenient-warn-and-clamp interval behavior and
	// fail-fast curator-mode enum are preserved exactly.
	Reflect ReflectConfig
	// Diagnostics holds optional debug-server settings.
	Diagnostics DiagnosticsConfig
	// Observability holds tracing/telemetry toggles owned by this server (the
	// standard OTEL SDK variables stay with the SDK and are not mirrored here).
	Observability ObservabilityConfig
}

type SettingStore interface {
	GetSetting(ctx context.Context, key string) (string, error)
	SetSetting(ctx context.Context, key, value string) error
}

type Snapshot struct {
	AgentID string // the agent ID this snapshot belongs to

	// Provider, APIKey, BaseURL are the default provider credentials derived
	// from the Model field's provider prefix. Kept for backward compatibility.
	Provider            string
	Model               string
	ModelThinking       string
	ModelStrong         string
	ModelStrongThinking string
	ModelFast           string
	ModelFastThinking   string
	Workspace           string
	Sandbox             SandboxConfig
	APIKey              string
	BaseURL             string
	SystemPrompt        string // agent's base system prompt from DB
	Soul                string // agent's default soul from DB (fallback for all users)

	Runner     RunnerConfig
	Compaction CompactionConfig
	Scheduler  SchedulerConfig
	Plugins    []Plugin

	// Providers maps provider ID to credentials, enabling per-tier provider
	// resolution when model_strong or model_fast use a different provider.
	Providers map[string]ProviderCreds
}

type Store interface {
	// Providers
	ListProviders(ctx context.Context) ([]Provider, error)
	GetProvider(ctx context.Context, id string) (Provider, error)
	CreateProvider(ctx context.Context, p Provider) error
	UpdateProvider(ctx context.Context, p Provider) error
	DeleteProvider(ctx context.Context, id string) error

	// Fetched-model cache — the model IDs an admin pulled from each provider's
	// API. ListCachedModels returns a flat list across providers; ReplaceCachedModels
	// replaces the fetched set for one provider only, leaving others untouched.
	ListCachedModels(ctx context.Context) ([]CachedModel, error)
	ReplaceCachedModels(ctx context.Context, providerID string, modelIDs []string) error

	// Agents
	ListAgents(ctx context.Context) ([]Agent, error)
	ListEnabledAgents(ctx context.Context) ([]Agent, error)
	ListAccessibleAgents(ctx context.Context, userID string) ([]Agent, error)
	GetAgent(ctx context.Context, id string) (Agent, error)
	CreateAgent(ctx context.Context, a Agent) error
	UpdateAgent(ctx context.Context, a Agent) error
	DeleteAgent(ctx context.Context, id string) error

	// Channels
	ListChannels(ctx context.Context) ([]Channel, error)
	ListChannelsByType(ctx context.Context, channelType string) ([]Channel, error)
	GetChannel(ctx context.Context, id string) (Channel, error)
	UpsertChannel(ctx context.Context, ch Channel) error
	DeleteChannel(ctx context.Context, id string) error

	// Manifest plugin overrides — tunables for manifest-declared plugins.
	// Reads merge the builtin manifest defaults with these rows.
	GetManifestPluginOverride(ctx context.Context, pluginID string) (ManifestPluginOverride, bool, error)
	ListManifestPluginOverrides(ctx context.Context) ([]ManifestPluginOverride, error)
	UpsertManifestPluginOverride(ctx context.Context, override ManifestPluginOverride) error
	DeleteManifestPluginOverride(ctx context.Context, pluginID string) error

	// Plugins — read paths merge BuiltinPlugins() with DB override rows.
	ListPlugins(ctx context.Context) ([]Plugin, error)
	ListPluginOverrides(ctx context.Context) ([]Plugin, error)
	ListPluginsByKind(ctx context.Context, kind string) ([]Plugin, error)
	ListEnabledPlugins(ctx context.Context) ([]Plugin, error)
	GetPlugin(ctx context.Context, id string) (Plugin, error)
	UpsertPlugin(ctx context.Context, p Plugin) error
	SetPluginEnabled(ctx context.Context, id string, enabled bool) error
	SetPluginConfig(ctx context.Context, id string, config map[string]any) error
	DeletePlugin(ctx context.Context, id string) error

	// Chat Agents (group -> agent mapping)
	GetChatAgent(ctx context.Context, channelID, platform, chatID string) (string, error) // returns agentID
	SetChatAgent(ctx context.Context, channelID, platform, chatID, agentID string) error
	DeleteChatAgent(ctx context.Context, channelID, platform, chatID string) error

	// Settings (key-value JSON)
	GetSetting(ctx context.Context, key string) (string, error) // returns JSON string
	SetSetting(ctx context.Context, key, value string) error

	// Snapshot assembles a read-only config snapshot for an agent.
	Snapshot(ctx context.Context, agentID string) (*Snapshot, error)

	// Bootstrap seeds default config for a fresh install.
	Seed(ctx context.Context) error
}

type VaultConfig struct {
	Key string
}