configuration

type APIKeys map[string]string

type APITimeoutConfig struct {
	ConnectionTimeoutSec    int `json:"connection_timeout_sec,omitempty"`     // Time to establish connection (default: 300)
	FirstChunkTimeoutSec    int `json:"first_chunk_timeout_sec,omitempty"`    // Time to receive first response (default: 600)
	ChunkTimeoutSec         int `json:"chunk_timeout_sec,omitempty"`          // Max time between streaming chunks (default: 600)
	OverallTimeoutSec       int `json:"overall_timeout_sec,omitempty"`        // Total request timeout (default: 1800)
	CommitMessageTimeoutSec int `json:"commit_message_timeout_sec,omitempty"` // Timeout for commit message generation (default: 300)
}

type AutoApproveRules struct {
	LowRiskOps    []string `json:"low_risk,omitempty"`        // Operations auto-approved by EA
	MediumRiskOps []string `json:"medium_risk,omitempty"`     // Operations the EA reasons about
	HighRiskNever []string `json:"high_risk_never,omitempty"` // Pattern names always gated (rm_recursive, force_flag, ...)
	// DefaultRisk is the level returned for operations that don't
	// match any of the above. Default (empty) is "medium" — the
	// classic EA behavior. Cautious profiles set this to "high"
	// so unrecognized commands route to a prompt. Permissive /
	// unrestricted set it to "low" so common operations auto-approve.
	DefaultRisk RiskLevel `json:"default_risk,omitempty"`
}

type ChangeTrackingConfig struct {
	// Enabled controls whether the change tracking subsystem is active
	// at all. When false, no file changes are recorded, no revision
	// history is written, and the rollback/recover/view_history tools
	// are no-ops.
	//
	// Defaults to true. The git-awareness guards (IsRevertSafe) now
	// prevent the subsystem from reverting committed work, so tracking
	// stays on by default. Set to false to disable the entire subsystem.
	Enabled *bool `json:"enabled,omitempty"`

	// ShellWalkEnabled controls whether the per-shell_command snapshot
	// walk runs at all. Disable for workspaces where the walk cost is
	// unacceptable (e.g., very-large monorepos with novel bloat
	// directories) or for users who don't care about recovering
	// shell-deleted untracked files. Direct file-tool tracking is
	// unaffected. Default: true. Only meaningful when Enabled is true.
	ShellWalkEnabled *bool `json:"shell_walk_enabled,omitempty"`

	// MaxFiles caps the number of files visited in a single walk.
	// Larger workspaces hit the cap and yield partial coverage with a
	// truncation log. Default: 50000.
	MaxFiles int `json:"max_files,omitempty"`

	// MaxTotalBytes caps cumulative content bytes captured per walk.
	// Files past this cap get path-only entries (still appear in
	// list_changes / FilesModified, but report recoverable=false).
	// Default: 32 MiB (33554432).
	MaxTotalBytes int64 `json:"max_total_bytes,omitempty"`

	// MaxDurationMs is the wall-clock budget for a single walk, in
	// milliseconds. Exceeding it aborts the walk with a partial-
	// coverage log. Default: 500 ms.
	MaxDurationMs int `json:"max_duration_ms,omitempty"`

	// AutoSkipFileCountThreshold is the per-directory immediate child
	// file count that triggers adaptive auto-skip. Default: 1500.
	AutoSkipFileCountThreshold int `json:"auto_skip_file_count_threshold,omitempty"`

	// RevisionRetention controls how the persistent revision store
	// (.sprout/revisions/ + .sprout/changes/) is compacted. Quantity-
	// based tiering: most recent N revisions are kept verbatim, next M
	// drop the conversation transcript, next K collapse to a one-line
	// summary, the rest are dropped. Position is by directory mtime,
	// so accessing an old revision via view_history / recover_file
	// promotes it back toward "hot" automatically.
	RevisionRetention *RevisionRetentionConfig `json:"revision_retention,omitempty"`
}

type CombinedAssessment struct {
	ClassifierRisk     int    // SecurityRisk value (0=safe, 1=caution, 2=dangerous)
	ClassifierBlocked  bool   // ShouldBlock from the classifier
	ClassifierPrompt   bool   // ShouldPrompt from the classifier
	ClassifierCategory string // RiskCategory string
	PolicyAction       SecurityPolicyAction
	PolicyRule         *SecurityRule // the matched rule, if any
	PathAllowed        bool
	CommandDenied      bool
	OverrideAction     string // reason if policy overrides classifier
}

type CommandPolicies struct {
	Rules []CommandRule `json:"rules"`
}

type CommandPolicyAction string

type CommandRule struct {
	// Pattern is a glob pattern (Go path.Match syntax) to match against
	// shell commands. For example: "git push*", "rm -rf /tmp/*".
	Pattern string `json:"pattern"`
	// Action determines the behavior when a command matches this rule.
	Action CommandPolicyAction `json:"action"`
	// Reason is an optional user note explaining why this rule exists.
	Reason string `json:"reason,omitempty"`
}

type ComputerUseConfig struct {
	// Enabled is the master switch. When false (default) the computer_user
	// persona's mouse/keyboard/screenshot tools are never registered or
	// executed. Turning it on is a deliberate, one-time user choice.
	Enabled bool `json:"enabled,omitempty"`

	// MaxActionsPerMinute caps the action rate as a runaway-loop backstop.
	// Default: 60. Set to 0 to disable the cap (not recommended).
	MaxActionsPerMinute int `json:"max_actions_per_minute,omitempty"`

	// AuditLogDir is where per-session JSONL action logs are written.
	// Default: ~/.config/sprout/computer_use_log when empty.
	AuditLogDir string `json:"audit_log_dir,omitempty"`

	// WorkspaceAllowlist lists workspace roots where computer use is
	// auto-approved for the session without the per-session opt-in prompt.
	WorkspaceAllowlist []string `json:"workspace_allowlist,omitempty"`

	// PanicKeyChord is the key chord that triggers the panic key. Defaults
	// to "ctrl+shift+escape". Set to "disabled" to turn off the panic key
	// entirely.
	PanicKeyChord string `json:"panic_key_chord,omitempty"`

	// DestructiveAppGate controls whether the destructive-app denylist gate
	// is active. When true (default), actions targeting apps on the
	// denylist prompt the user for approval before proceeding.
	DestructiveAppGate bool `json:"destructive_app_gate,omitempty"`

	// OverrideFilePath is an optional override of the per-user denylist
	// override file location. When empty, the default path
	// (~/.config/sprout/computer_use_denylist_overrides.json) is used.
	OverrideFilePath string `json:"denylist_override_file,omitempty"`
}

type Config struct {
	Version string `json:"version"`

	// Provider and Model Configuration
	LastUsedProvider string            `json:"last_used_provider"`
	ProviderModels   map[string]string `json:"provider_models"`
	ProviderPriority []string          `json:"provider_priority"`

	// Language Server Override Configuration
	LanguageServers []LanguageServerOverride `json:"language_servers,omitempty"`

	// MCP Configuration
	MCP mcp.MCPConfig `json:"mcp"`

	// Preferences
	Preferences map[string]interface{} `json:"preferences,omitempty"`

	// DisableCoordinatorAutoActivate opts out of the automatic activation of the
	// coordinator persona (formerly Executive Assistant) when sprout starts in
	// the user's $HOME directory. When true, no persona is auto-activated and
	// the user must select one explicitly. Default false (auto-activate).
	DisableCoordinatorAutoActivate bool `json:"disable_coordinator_auto_activate,omitempty"`

	// AllowGitHistoryRewrite controls whether commands that can lose commit
	// history are accepted via shell_command without going through the git
	// tool's approval flow. Specifically: `git reset --hard <commit-ish>`,
	// `git rebase`, `git branch -D`, `git tag -d`.
	//
	// Working-tree-only destructive ops (`git checkout .`, `git restore`,
	// `git clean -fd`, `git reset --hard HEAD`, etc.) are always allowed
	// because the change tracker captures pre-mutation content and exposes
	// recover_file / recover_bulk for restoration. History rewrites can't
	// be recovered through the tracker — only via the reflog — so they
	// stay gated by default.
	//
	// Default: false (gated). Set true in environments where the agent
	// has tighter feedback loops (e.g. user-facing chat where every step
	// is confirmed) and the friction of going through the git tool isn't
	// worth it.
	AllowGitHistoryRewrite bool `json:"allow_git_history_rewrite,omitempty"`

	// UnifiedRiskResolver enables the unified risk resolver (SP-068 Phase 2).
	// When true (the default), gating decisions at call sites use a single
	// ResolveToolRisk assessment instead of the split Gate 1 (static
	// classifier) → Gate 2 (persona risk cascade) path. When false, the
	// legacy dual-gate code paths run (retained for compatibility). Set to
	// false explicitly to opt out of the unified resolver.
	UnifiedRiskResolver bool `json:"unified_risk_resolver,omitempty"`

	// DaemonMultiSession enables N concurrent browser windows per user
	// when the server runs in service/daemon mode (SPROUT_SERVICE=1).
	// When true, the WebSocket dispatcher routes new connections through
	// the multi-session path (handleWebSocket_Daemon); each connection
	// gets its own chat session and its own agent without colliding
	// with sibling windows. When false, the daemon falls back to the
	// single-active-session path (handleWebSocket_Agent) and the second
	// window triggers session_conflict + takeover — the pre-SP-118
	// behavior.
	//
	// Effective value at the dispatch site is
	//   effective = (agentEnforceSingleSession == false) && DaemonMultiSession
	// i.e. the agent path always uses Mode 1 regardless of this flag,
	// and the daemon path uses Mode 2 only when this flag is true.
	//
	// Default: true (the daemon opens with multi-session on, so three
	// browser windows on the same daemon each get their own chat
	// without a takeover prompt). Set to false to opt out without
	// editing code — useful for rolling forward / back during the
	// SP-118 rollout window. SP-118 Phase 4 will flip the rollout so
	// this default is the new normal.
	DaemonMultiSession bool `json:"daemon_multi_session,omitempty"`

	// ResourceDirectory stores captured web/vision resources relative to the current working directory.
	// This can be overridden at runtime with --resource-directory.
	ResourceDirectory string `json:"resource_directory,omitempty"`

	// ReasoningEffort sets a global default reasoning effort for chat requests.
	// Valid values: "low", "medium", "high". Empty means automatic selection.
	ReasoningEffort string `json:"reasoning_effort,omitempty"`

	// DisableThinking disables thinking/reasoning mode for thinking-capable models.
	// When true, models like Qwen3, Qwen3.5, GLM models, and Minimax models will
	// not use their thinking/reasoning mode. Note: GPT-OSS models do not support
	// disabling thinking (they use reasoning_effort instead).
	DisableThinking bool `json:"disable_thinking,omitempty"`

	// SystemPromptText overrides the main agent system prompt inline.
	// Empty means use the embedded default prompt.
	SystemPromptText string `json:"system_prompt_text,omitempty"`

	// RefreshSystemPromptOnModelChange (Spec B): when true, re-derive the
	// agent's system prompt on every provider/model swap instead of
	// freezing it at agent-creation time. Different models respond very
	// differently to the same prompt — a Claude-tuned prompt sent to
	// GPT-4 may be silently ignored. With this on, the agent re-runs
	// GetEmbeddedSystemPromptForProfile on each SetProvider / SelectProvider
	// so the prompt stays in sync with the active provider and context
	// window. Defaults to false so existing sessions are bit-identical.
	// Flip to true after observability shows the new behavior lands
	// cleanly. The agent's `SystemPromptText` override still wins — only
	// the embedded portion is re-derived, the configured override is
	// re-applied on top.
	RefreshSystemPromptOnModelChange bool `yaml:"refresh_system_prompt_on_model_change,omitempty" json:"refresh_system_prompt_on_model_change,omitempty"`

	// SkipPrompt - for non-interactive mode
	SkipPrompt bool `json:"skip_prompt,omitempty"`

	// RiskProfile selects a named preset for the shell-command risk
	// cascade: readonly / cautious / default / permissive /
	// unrestricted. Empty or unrecognized values resolve to "default"
	// via AutoApproveRulesForProfile. Per-persona AutoApproveRules
	// always win over the profile. The CLI's --risk-profile flag and
	// a workflow step's "risk_profile" field both override this
	// value.
	RiskProfile string `json:"risk_profile,omitempty"`

	// ContextMode selects a named context-engine preset: "" (full
	// default) | "full" | "low_context". Resolved into a ContextProfile
	// via ResolveContextProfile at agent creation; call sites read
	// fields off the resolved profile rather than this string directly.
	// Empty/unrecognized values fall through to auto-detection by the
	// resolver (which honors a small enough model window).
	ContextMode ContextMode `json:"context_mode,omitempty"`

	// RiskProfiles allows the user to override the baked-in rules
	// for any named profile. Keys are profile names (readonly,
	// cautious, default, permissive, unrestricted, or any
	// user-defined name); values replace the built-in rules entirely
	// for that name. Useful when the user wants a slightly different
	// definition of "cautious" or wants to add their own named
	// profile. See docs/SECURITY.md#risk-profiles.
	RiskProfiles map[string]AutoApproveRules `json:"risk_profiles,omitempty"`

	// ApprovedShellCommands is the user's persistent allowlist of
	// literal shell command strings that should auto-approve through
	// the high-risk cascade without prompting. Populated by the
	// "Always approve this command" choice on the approval dialog
	// (SP-058 follow-up). Stored as exact strings — matching is
	// command-literal equality, not pattern matching, so allow-listing
	// `rm -rf /tmp/build-cache` does NOT allow `rm -rf anything-else`.
	// The Critical tier still blocks regardless of this allowlist.
	// Users can edit this list directly in config.json to revoke an
	// entry, or remove all entries to reset.
	ApprovedShellCommands []string `json:"approved_shell_commands,omitempty"`

	// ApprovedShellCommandPatterns is the user's persistent allowlist of
	// glob patterns for shell commands that should auto-approve through
	// the high-risk cascade without prompting. Patterns use Go's path.Match
	// syntax: `*` matches any sequence of characters (but NOT `/`),
	// `?` matches any single character, `[abc]` matches a character class.
	// For example, `rm -rf /tmp/*` matches `rm -rf /tmp/build` but NOT
	// `rm -rf /home/x`. The Critical tier still blocks regardless of
	// pattern matches — patterns cannot override critical-tier gating,
	// which is enforced at the call site before this allowlist is consulted.
	// Users can edit this list directly in config.json to revoke an entry,
	// or remove all entries to reset.
	ApprovedShellCommandPatterns []string `json:"approved_shell_command_patterns,omitempty"`

	// CommandPolicies is the unified command policy layer (SP-123) with
	// three actions: allow (auto-approve), ask (force prompt), deny
	// (hard block). Rules are evaluated before the classifier and risk
	// profile, first-match-wins. Replaces the fragmented
	// approved_shell_commands / approved_shell_command_patterns /
	// security_policy.denied_commands surfaces. Legacy fields remain for
	// backward compatibility; MigrateCommandPolicies converts them on load.
	CommandPolicies *CommandPolicies `json:"command_policies,omitempty"`

	// DismissedPrompts tracks which one-time prompts the user has dismissed.
	DismissedPrompts map[string]bool `json:"dismissed_prompts,omitempty"`

	// API Timeout Configuration (in seconds)
	APITimeouts *APITimeoutConfig `json:"api_timeouts,omitempty"`

	// Custom Providers Configuration
	CustomProviders map[string]CustomProviderConfig `json:"custom_providers,omitempty"`

	// Command History Configuration
	CommandHistoryByPath map[string][]string `json:"command_history_by_path,omitempty"`
	HistoryIndexByPath   map[string]int      `json:"history_index_by_path,omitempty"`

	// Change History Configuration
	HistoryScope string `json:"history_scope,omitempty"` // "project" or "global"

	// Subagent Configuration
	SubagentProvider string `json:"subagent_provider,omitempty"` // Provider for subagents (defaults to LastUsedProvider)
	SubagentModel    string `json:"subagent_model,omitempty"`    // Model for subagents (defaults to provider's default model)
	// SubagentTypes is hydrated from the embedded catalog at config load time.
	// It is NOT persisted (json:"-"): personas are catalog-fixed and user
	// customization is intentionally not supported. Use DisabledPersonas to
	// hide specific personas from /persona list and from subagent spawning.
	SubagentTypes map[string]SubagentType `json:"-"`
	// DisabledPersonas holds canonical persona IDs the user has hidden via
	// `/persona <id> disable`. The catalog entries themselves are never
	// mutated; resolution checks this list and treats disabled IDs as absent.
	DisabledPersonas []string `json:"disabled_personas,omitempty"`
	// DefaultSubagentPersona is the persona ID used when run_subagent is called
	// without a persona argument. Defaults to "general" if unset. Setting this
	// lets users redirect default spawns without editing the catalog.
	DefaultSubagentPersona  string `json:"default_subagent_persona,omitempty"`
	SubagentMaxParallel     int    `json:"subagent_max_parallel,omitempty"`     // Maximum number of parallel subagents (default: 2)
	SubagentParallelEnabled *bool  `json:"subagent_parallel_enabled,omitempty"` // Enable/disable parallel subagent execution (default: true)
	SubagentMaxDepth        int    `json:"subagent_max_depth,omitempty"`        // Maximum subagent nesting depth (default: 2)

	// Commit Configuration
	CommitProvider string `json:"commit_provider,omitempty"` // Provider for commit message generation (defaults to LastUsedProvider)
	CommitModel    string `json:"commit_model,omitempty"`    // Model for commit message generation (defaults to provider's default model)

	// Review Configuration
	ReviewProvider string `json:"review_provider,omitempty"` // Provider for review commands (defaults to LastUsedProvider)
	ReviewModel    string `json:"review_model,omitempty"`    // Model for review commands (defaults to provider's default model)

	// Vision Fallback Configuration
	// VisionFallbackToOCR enables transparent fallback to the OCR model
	// when the primary vision model fails after retries. When true and
	// PDFOCRModel is configured, a single OCR attempt is made as a last
	// resort. Default: true (enabled). Controlled by VISION_FALLBACK_TO_OCR
	// env var (SPROUT_ / LEDIT_ prefixes).
	VisionFallbackToOCR bool `json:"vision_fallback_to_ocr,omitempty"`

	// PDF OCR Configuration
	PDFOCREnabled    bool   `json:"pdf_ocr_enabled,omitempty"`    // Enable PDF OCR processing
	PDFOCRProvider   string `json:"pdf_ocr_provider,omitempty"`   // Provider for PDF OCR (e.g., "ollama", "openai", "deepinfra")
	PDFOCRModel      string `json:"pdf_ocr_model,omitempty"`      // Model for PDF OCR (e.g., "glm-ocr", "llama3.2-vision")
	PDFOCRDownloaded bool   `json:"pdf_ocr_downloaded,omitempty"` // Whether the model has been downloaded

	// Embedding Index Configuration
	EmbeddingIndex *EmbeddingIndexConfig `json:"embedding_index,omitempty"`

	// Persistent Context Configuration
	PersistentContext *PersistentContextConfig `json:"persistent_context,omitempty"`

	// Computer Use Configuration (SP-063) — gates the computer_user persona's
	// mouse/keyboard/screenshot tools. Off by default; the tools are never
	// available unless this is explicitly enabled.
	ComputerUse *ComputerUseConfig `json:"computer_use,omitempty"`

	// Vision Configuration (SP-103-C3) — controls vision-pipeline runtime
	// behavior: parallel worker pool size, global concurrency cap, and
	// multi-image batching. All fields have safe defaults via Resolve().
	Vision *VisionConfig `json:"vision,omitempty"`

	// Change Tracking Configuration — controls the shell-mutation
	// snapshot pass. Direct file-tool hooks (write_file, edit_file,
	// patch_structured_file) are always tracked; this struct only
	// gates the walker that detects shell_command mutations.
	ChangeTracking *ChangeTrackingConfig `json:"change_tracking,omitempty"`

	// Skills Configuration
	Skills map[string]Skill `json:"skills,omitempty"` // Agent Skills that can be loaded into context

	// Zsh Command Execution
	EnableZshCommandDetection   bool `json:"enable_zsh_command_detection"`   // Enable zsh-aware command detection (default: true)
	AutoExecuteDetectedCommands bool `json:"auto_execute_detected_commands"` // Auto-execute detected commands without prompting (default: true)

	// Security Policy Configuration
	SecurityPolicy *SecurityPolicy `json:"security_policy,omitempty"`

	// Shell Configuration — user-configurable shell permission policy
	// (SP-049 Phase 2). Lets users define safe/dangerous command patterns
	// and a workspace-overlay mode.
	Shell ShellConfig `json:"shell,omitempty"`

	// MaxContextTokens caps the effective context window used when building
	// requests. When set, the agent acts as if the model has at most this
	// many tokens of context, limiting how large an input (and therefore
	// completion budget) a single request can claim. Useful as a cost-control
	// measure when using models with very large native context windows
	// (e.g. 1M-token models billed per input token). Nil or 0 means no cap.
	MaxContextTokens *int `json:"max_context_tokens,omitempty"`

	// Notifications Configuration (SP-070) — controls how the agent
	// notifies the user when long-running turns complete.
	Notifications *NotificationsConfig `json:"notifications,omitempty"`

	// Edit Approval Configuration (SP-072) — controls the per-hunk
	// diff approval gate for agent file writes.
	EditApproval *EditApprovalConfig `json:"edit_approval,omitempty"`

	// OutputVerbosity controls how much inter-tool-call narration and
	// streaming detail the UI shows. Valid values: "compact" (hide
	// interim model messages, show only tool results and final text),
	// "default" (show tool calls with results, show streaming final
	// text), "verbose" (show everything including interim narration).
	// Empty defaults to "default".
	OutputVerbosity string `json:"output_verbosity,omitempty"`

	// ShowToolInvocations controls whether the UI expands per-tool
	// invocation details in the conversation output. When false, tool
	// calls are collapsed/hidden. Defaults to true.
	ShowToolInvocations bool `json:"show_tool_invocations,omitempty"`

	// Wakeup controls auto-resume behavior for background task completions
	// (SP-108). When enabled, the daemon automatically processes pending
	// notifications by calling ProcessQueryWithContinuity so the agent can
	// act on completed background tasks without the user sending a manual
	// message. Budget controls prevent unattended token burn loops.
	Wakeup WakeupConfig `json:"wakeup,omitempty"`

	// Training controls opt-in session recording for training data
	// collection. When enabled, each saved session is PII-redacted and
	// pushed to the configured endpoint as JSON. OFF by default — must
	// be explicitly enabled via --train flag, SPROUT_TRAIN_ENABLED env,
	// or config.json.
	Training TrainingConfig `json:"training,omitempty"`

	// Other flags
	FromAgent bool `json:"-"` // Internal flag, not persisted
	// contains filtered or unexported fields
}

type ConfigConflictError struct {
	// Path is the absolute path of the config file.
	Path string
	// LoadedModTime / LoadedSize is what the in-memory Config remembers
	// from when it was last loaded.
	LoadedModTime time.Time
	LoadedSize    int64
	// CurrentModTime / CurrentSize is what's on disk right now.
	CurrentModTime time.Time
	CurrentSize    int64
}

type ContextMode string

type ContextProfile struct {
	Mode                      ContextMode `json:"mode,omitempty"`
	ToolAllowlist             []string    `json:"tool_allowlist,omitempty"`
	SystemPromptPath          string      `json:"system_prompt_path,omitempty"`
	SkipProactiveContext      bool        `json:"skip_proactive_context,omitempty"`
	CompactionTriggerFraction float64     `json:"compaction_trigger_fraction,omitempty"`
	RecentTurnsToPreserve     int         `json:"recent_turns_to_preserve,omitempty"`
	RepoMapDefaultDepth       int         `json:"repo_map_default_depth,omitempty"`
}

type CustomProviderConfig struct {
	Name                   string                      `json:"name"`
	Endpoint               string                      `json:"endpoint"`
	ModelName              string                      `json:"model_name"`
	ContextSize            int                         `json:"context_size"`                  // Default context size for provider
	ModelContextSizes      map[string]int              `json:"model_context_sizes,omitempty"` // Per-model context sizes (e.g., "my-model": 131072)
	ReasoningEffort        string                      `json:"reasoning_effort,omitempty"`    // Optional provider-specific reasoning effort override
	Temperature            *float64                    `json:"temperature,omitempty"`         // Optional default temperature
	TopP                   *float64                    `json:"top_p,omitempty"`               // Optional default top_p
	Parameters             map[string]interface{}      `json:"parameters,omitempty"`          // Optional provider-specific default parameters
	RequiresAPIKey         bool                        `json:"requires_api_key"`
	ToolCalls              []string                    `json:"tool_calls,omitempty"`               // Optional explicit tool allowlist; when set, only these tools are exposed
	EnvVar                 string                      `json:"env_var,omitempty"`                  // Environment variable name for API key
	ChunkTimeoutMs         int                         `json:"chunk_timeout_ms,omitempty"`         // Streaming chunk timeout in milliseconds
	Conversion             providers.MessageConversion `json:"message_conversion,omitempty"`       // Message conversion configuration
	SupportsVision         bool                        `json:"supports_vision,omitempty"`          // Whether this provider supports vision requests
	VisionModel            string                      `json:"vision_model,omitempty"`             // Vision-capable model for this provider
	VisionFallbackProvider string                      `json:"vision_fallback_provider,omitempty"` // Optional fallback provider for vision
	VisionFallbackModel    string                      `json:"vision_fallback_model,omitempty"`    // Optional fallback model for vision provider
	BillingType            string                      `json:"billing_type,omitempty"`             // Billing model: pay_per_token (default), subscription, free
}

type EditApprovalConfig struct {
	Mode  string   `json:"mode,omitempty"`
	Paths []string `json:"paths,omitempty"`

	// ShellCommand enables per-part shell approval prompts (SP-093-2).
	// When true, a multi-part shell command is split and each part is
	// approved individually via Agent.RequestShellApproval. Default: false,
	// which preserves the existing 4-option prompt for the whole command.
	ShellCommand bool `json:"shell_command,omitempty" yaml:"shell_command,omitempty"`
}

type EmbeddingIndexConfig struct {
	// Enabled controls whether the embedding index is active.
	Enabled bool `json:"enabled,omitempty"`

	// IndexDir is the directory where the embedding index JSONL files are stored.
	// If empty, uses ~/.config/sprout/embeddings/
	IndexDir string `json:"index_dir,omitempty"`

	// SimilarityThreshold is the cosine similarity threshold for duplicate detection.
	// Range: 0.0 to 1.0. Default: 0.90
	SimilarityThreshold float32 `json:"similarity_threshold,omitempty"`

	// MaxResults is the maximum number of duplicate candidates to return.
	// Default: 3
	MaxResults int `json:"max_results,omitempty"`

	// AutoIndex controls whether the index is built automatically on first use.
	// Default: true
	AutoIndex bool `json:"auto_index,omitempty"`

	// ExcludePaths is a list of additional paths to exclude from indexing.
	ExcludePaths []string `json:"exclude_paths,omitempty"`
}

type KnownProviderInfo struct {
	// Source identifies where the metadata came from.
	// "custom" = user's ~/.config/sprout/providers/<name>.json
	// "factory" = embedded config in pkg/agent_providers/configs/
	//            or upserted via refreshFromRemote
	Source string

	// Name is the canonical provider name (lowercase, trimmed).
	Name string

	// DisplayName is the friendly label shown in UI surfaces.
	DisplayName string

	// EnvVar is the environment variable the provider expects for
	// authentication (e.g. "OPENAI_API_KEY"). Empty when no auth
	// is required.
	EnvVar string

	// RequiresAPIKey reports whether the provider needs an API key.
	RequiresAPIKey bool

	// Endpoint is the chat endpoint URL when known.
	Endpoint string

	// DefaultModel is the configured default model when known.
	DefaultModel string

	// ContextSize is the configured default context size in tokens.
	ContextSize int
}

type LanguageServerOverride struct {
	ID          string   `json:"id" yaml:"id"`                                         // Unique server ID (e.g. "go", "typescript")
	Binary      string   `json:"binary" yaml:"binary"`                                 // Path to the binary (e.g. "gopls", "typescript-language-server")
	Args        []string `json:"args,omitempty" yaml:"args,omitempty"`                 // Command-line arguments (e.g. ["--stdio"])
	LanguageIDs []string `json:"language_ids,omitempty" yaml:"language_ids,omitempty"` // Language IDs this server handles (e.g. ["go"])
	InstallHint string   `json:"install_hint,omitempty" yaml:"install_hint,omitempty"` // Installation instructions
}

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

type MigrationFunc func(raw map[string]interface{}) error

type NotificationsConfig struct {
	// CLIBell emits a terminal bell (\a) on completion.
	CLIBell bool `json:"cli_bell,omitempty"`
	// OSNotify fires an OS-level desktop notification on completion.
	OSNotify bool `json:"os_notify,omitempty"`
	// Browser fires a browser notification (used by WebUI, SP-070-4).
	Browser bool `json:"browser,omitempty"`
	// MinSeconds is the minimum turn duration (in seconds) before a
	// notification is sent.  Default: 10.0.  Turns completing in less
	// than this are considered too brief to warrant a notification.
	MinSeconds float64 `json:"min_seconds,omitempty"`
}

type PersistentContextConfig struct {
	// ProactiveContextEnabled controls whether the system primes new sessions with
	// relevant past work via semantic retrieval from conversation history.
	// Default: true
	ProactiveContextEnabled bool `json:"proactiveContextEnabled,omitempty"`

	// MaxContextualResults is the maximum number of past turns to retrieve for context.
	// Default: 5
	MaxContextualResults int `json:"maxContextualResults,omitempty"`

	// MinRelevanceScore is the minimum time-decayed cosine similarity score for retrieval.
	// Range: 0.0 to 1.0. Results below this score are filtered out.
	// Default: 0.50
	MinRelevanceScore float64 `json:"minRelevanceScore,omitempty"`

	// MaxContextChars is the hard cap on total injected character count for context.
	// Default: 4000
	MaxContextChars int `json:"maxContextChars,omitempty"`

	// WorkspaceScopedRetrieval restricts retrieval to turns from the current workspace only.
	// When false (default), retrieval searches across all workspaces.
	// Default: false
	WorkspaceScopedRetrieval bool `json:"workspaceScopedRetrieval,omitempty"`

	// DriftDetectionEnabled controls whether conversational drift detection is active.
	// When enabled, the system checks if the conversation has drifted from its original intent.
	// Default: true
	DriftDetectionEnabled bool `json:"driftDetectionEnabled,omitempty"`

	// DriftThreshold is the cosine similarity threshold below which drift is flagged.
	// Range: 0.0 to 1.0. Lower values require more divergence before flagging.
	// Default: 0.60
	DriftThreshold float64 `json:"driftThreshold,omitempty"`

	// DriftCheckInterval is the number of turns between drift checks.
	// For example, 5 means drift is checked on turns 5, 10, 15, etc.
	// Default: 5
	DriftCheckInterval int `json:"driftCheckInterval,omitempty"`

	// RetentionDays controls how many days to keep persistent context entries.
	// Default: 0 (never expire). Set to a positive value to automatically clean
	// up entries older than the specified number of days at agent startup.
	RetentionDays int `json:"retentionDays,omitempty"`
}

type ProviderAuthMetadata struct {
	Provider       string
	DisplayName    string
	RequiresAPIKey bool
	EnvVar         string
	AuthType       string
}

type ProviderConfigLookupFunc func(name string) (envVar, authType string, ok bool)

type ProviderDiscoveryModel struct {
	ID            string   `json:"id"`
	Name          string   `json:"name,omitempty"`
	Description   string   `json:"description,omitempty"`
	ContextLength int      `json:"context_length,omitempty"`
	Tags          []string `json:"tags,omitempty"`
}

type ProviderDisplayNameLookupFunc func(name string) (displayName string, ok bool)

type ProviderNamesLookupFunc func() []string

type RevisionRetentionConfig struct {
	// HotCount: most recent N revisions kept verbatim (full
	// conversation.json + instructions + llm_response + all change
	// payloads). Fast view_history + full recovery. Default: 200.
	HotCount int `json:"hot_count,omitempty"`

	// WarmCount: next M revisions after the hot tier. conversation.json
	// dropped; instructions + response + change payloads kept. Recovery
	// still works; conversation context lost. Default: 500.
	WarmCount int `json:"warm_count,omitempty"`

	// MaxDirBytes is the long-stop cap on total revisions+changes
	// disk usage per workspace. If the count-based tiering still
	// leaves the directory over this size, trim oldest warm entries
	// until under cap. Default: 1 GiB (1073741824).
	MaxDirBytes int64 `json:"max_dir_bytes,omitempty"`

	// ArchiveFrozen: if true, dropped revisions are moved to
	// .sprout/revisions/_frozen/ instead of being deleted outright.
	// Opt-in safety net for users who want a recoverable record of
	// long-tail history at the cost of unbounded growth. Default: false.
	ArchiveFrozen bool `json:"archive_frozen,omitempty"`

	// MaxChangesPerRevision caps the number of change records kept per
	// revision in .sprout/changes/. A single runaway session (e.g. an
	// agent that `cd`'d into $HOME so a shell walk classified
	// pre-existing files as creates) can produce tens of thousands of
	// records; without this cap, count bloat persists even when total
	// bytes are under MaxDirBytes. Default: 10000.
	MaxChangesPerRevision int `json:"max_changes_per_revision,omitempty"`

	// MaxChangesAgeDays drops change records older than this number of
	// days regardless of their parent revision's tier. Belt-and-
	// suspenders against changes/ accumulating inside the hot window.
	// Default: 30. Set to a negative value to disable.
	MaxChangesAgeDays int `json:"max_changes_age_days,omitempty"`
}

type RiskLevel string

type RiskProfile string

type SecurityPolicy struct {
	DefaultAction  string         `json:"default_action,omitempty"`
	Rules          []SecurityRule `json:"rules,omitempty"`
	AllowedPaths   []string       `json:"allowed_paths,omitempty"`
	DeniedPaths    []string       `json:"denied_paths,omitempty"`
	DeniedCommands []string       `json:"denied_commands,omitempty"`
	MaxRiskLevel   string         `json:"max_risk_level,omitempty"`
}

type SecurityPolicyAction string

type SecurityRule struct {
	Pattern string `json:"pattern"`
	Action  string `json:"action"`
	Reason  string `json:"reason,omitempty"`
}

type ShellConfig struct {
	UserSafePatterns      []ShellPattern         `json:"user_safe_patterns,omitempty"`
	UserDangerousPatterns []ShellPattern         `json:"user_dangerous_patterns,omitempty"`
	WorkspaceOverlay      WorkspaceOverlayConfig `json:"workspace_overlay,omitempty"`
}

type ShellPattern struct {
	Match  string `json:"match"`            // prefix string or regex pattern
	Kind   string `json:"kind"`             // "prefix" or "regex"
	Reason string `json:"reason,omitempty"` // optional human-readable note
}

type Skill struct {
	ID           string            `json:"id"`            // Unique identifier (e.g., "go-best-practices")
	Name         string            `json:"name"`          // Human-readable name
	Description  string            `json:"description"`   // What this skill provides and when to use it
	Path         string            `json:"path"`          // Relative path to skill directory
	Enabled      bool              `json:"enabled"`       // Whether this skill is available
	Metadata     map[string]string `json:"metadata"`      // Optional metadata (author, version, etc.)
	AllowedTools string            `json:"allowed_tools"` // Optional space-delimited list of pre-approved tools
}

type SubagentType struct {
	ID                 string            `json:"id"`                             // Unique identifier (e.g., "coder", "tester", "debugger")
	Name               string            `json:"name"`                           // Human-readable name (e.g., "Coder", "Tester")
	Description        string            `json:"description"`                    // What this subagent specializes in
	Provider           string            `json:"provider"`                       // Provider for this subagent type (optional, falls back to SubagentProvider)
	Model              string            `json:"model"`                          // Model for this subagent type (optional, falls back to SubagentModel)
	SystemPrompt       string            `json:"system_prompt"`                  // Relative path to system prompt file (e.g., "subagent_prompts/coder.md")
	SystemPromptText   string            `json:"system_prompt_text,omitempty"`   // Optional inline system prompt text (replaces base prompt entirely)
	SystemPromptAppend string            `json:"system_prompt_append,omitempty"` // Optional inline text appended to the base or loaded system prompt (for composition)
	AllowedTools       []string          `json:"allowed_tools,omitempty"`        // Optional explicit tool allowlist for focused persona behavior
	Aliases            []string          `json:"aliases,omitempty"`              // Optional aliases (e.g., "web-scraper")
	Enabled            bool              `json:"enabled"`                        // Catalog-only: every shipped persona sets this true. Runtime "is this persona usable?" is determined by Config.DisabledPersonas (user) + LocalOnly (env). Kept for catalog hygiene + defense-in-depth in case a future variant ships with a deliberately-disabled entry.
	LocalOnly          bool              `json:"local_only,omitempty"`           // Only available in local mode (not cloud)
	Delegatable        bool              `json:"delegatable,omitempty"`          // Whether this persona can be used as a subagent (default: true for worker personas, false for orchestrator personas)
	AutoApproveRules   *AutoApproveRules `json:"auto_approve_rules,omitempty"`   // Risk cascade rules for the runtime auto-approve check
	// Capabilities is an explicit list of agency grants this persona holds
	// (e.g. "git_write"). Replaces sniffing AutoApproveRules to infer what a
	// persona is allowed to do. Use HasCapability to query.
	Capabilities []string `json:"capabilities,omitempty"`
	// CanSpawnNonDelegatable lists otherwise-undelegatable persona IDs that
	// this persona may spawn. Replaces the hardcoded EA-spawn-authority
	// special-case. The coordinator carries ["orchestrator"] to enable the
	// canonical coordinator→orchestrator→specialist chain.
	CanSpawnNonDelegatable []string `json:"can_spawn_non_delegatable,omitempty"`
}

type TrainingConfig struct {
	// Endpoint is the URL to push training data to (e.g. http://localhost:8190).
	// Sessions are POSTed to {Endpoint}/sessions as JSON.
	Endpoint string `json:"endpoint,omitempty"`

	// Enabled controls whether training data is collected and pushed.
	// ALWAYS false by default — must be explicitly enabled.
	Enabled bool `json:"enabled,omitempty"`

	// ExcludePaths is a list of working directory prefixes to exclude from
	// training data. Sessions whose working directory starts with any of
	// these paths are silently skipped.
	ExcludePaths []string `json:"exclude_paths,omitempty"`
}

type VisionConfig struct {
	// ParallelWorkers caps concurrent in-flight vision requests per
	// session. Vision requests are heavyweight (large payloads, slow
	// provider round-trips) so this defaults to 3 — independent of the
	// generic request_parallelism setting.
	//
	// Range: 1..32. Values outside this range are clamped in Resolve().
	// Set to 0 to fall back to the default (3).
	ParallelWorkers int `json:"parallel_workers,omitempty"`

	// MaxParallelRequests caps the global number of in-flight vision
	// API calls across the entire process. This is independent of
	// ParallelWorkers (which is per-session). Default: 8.
	MaxParallelRequests int `json:"max_parallel_requests,omitempty"`

	// EnableBatchProcessing toggles the multi-image batching layer
	// (VISION-4). Default: true.
	EnableBatchProcessing bool `json:"enable_batch_processing,omitempty"`

	// MaxBatchSize is the maximum number of images sent to the provider
	// in a single batched call. Default: 4. Range: 1..8.
	MaxBatchSize int `json:"max_batch_size,omitempty"`
}

type WakeupConfig struct {
	Enabled              bool `json:"enabled"`                 // Master switch; default false
	MaxTokensPerSession  int  `json:"max_tokens_per_session"`  // Hard cap on auto-resume token spend; default 5000
	MaxResumesPerSession int  `json:"max_resumes_per_session"` // Max auto-resumes before requiring user input; default 10
}

type WorkspaceOverlayConfig struct {
	// Mode: "tighten_only" (default — only user_dangerous_patterns honored),
	// "trusted" (full overlay honored after `sprout policy trust`), or
	// "ignore" (workspace policy never loaded).
	Mode string `json:"mode,omitempty"`
}