config

type AvailabilityProfile string

type CircuitBreakerConfig struct {
	FailureThreshold int      `yaml:"failure_threshold,omitempty" env:"FAILURE_THRESHOLD" env-default:"5"`
	RecoveryTimeout  Duration `yaml:"recovery_timeout,omitempty" env:"RECOVERY_TIMEOUT" env-default:"60s"`
}

type Config struct {
	// Servers maps server names to their configurations.
	Servers map[string]*ServerConfig `yaml:"servers"`

	// SlotGroups declaratively define pools of identical servers that may be
	// expanded into flat server entries at load time.
	SlotGroups map[string]*SlotGroupConfig `yaml:"slot_groups,omitempty"`

	// Security holds daemon-wide security settings for MCP endpoints.
	Security SecurityConfig `yaml:"security"`

	// Supervision holds global supervisor settings.
	Supervision SupervisionConfig `yaml:"supervision"`
}

type Duration time.Duration

type Instructions struct {
	// Servers maps server names to their instructions
	Servers map[string]*ServerInstructions `yaml:"servers,omitempty" json:"servers,omitempty"`

	// Tools maps tool names to their instructions (for cross-server tool guidance)
	Tools map[string]*ToolInstructions `yaml:"tools,omitempty" json:"tools,omitempty"`

	// GlobalGuidance is general guidance that applies to all tool selection
	GlobalGuidance string `yaml:"global_guidance,omitempty" json:"global_guidance,omitempty"`
}

type RestartPolicy string

type RetryConfig struct {
	MaxAttempts     int      `yaml:"max_attempts,omitempty" env:"MAX_ATTEMPTS" env-default:"1"`
	InitialDelay    Duration `yaml:"initial_delay,omitempty" env:"INITIAL_DELAY" env-default:"100ms"`
	MaxDelay        Duration `yaml:"max_delay,omitempty" env:"MAX_DELAY" env-default:"5s"`
	RetryableErrors []string `yaml:"retryable_errors,omitempty"`
}

type SecurityConfig struct {
	// BearerToken is the shared secret for Authorization header validation.
	// When empty, authentication is not enforced (open access).
	// Supports ${VAR} expansion from the environment.
	BearerToken string `yaml:"bearer_token,omitempty" env:"VISION_BEARER_TOKEN"`

	// AllowedOrigins is the list of permitted Origin header values.
	// When empty, origin checking is not enforced.
	// Wildcard ("*") is explicitly rejected and treated as disallowed.
	AllowedOrigins []string `yaml:"allowed_origins,omitempty"`
}

type ServerConfig struct {
	// Port is the HTTP port Vision exposes this server on (6276-6300).
	Port int `yaml:"port" env:"PORT"`

	// Transport is "stdio", "managed-http", "http", or "sse". Inferred if not set,
	// except managed-http which must be explicit because it owns command + URL.
	Transport TransportType `yaml:"transport,omitempty" env:"TRANSPORT"`

	// Command is the executable to run (for stdio transport).
	Command string `yaml:"command,omitempty" env:"COMMAND"`

	// Args are command-line arguments passed to Command.
	Args []string `yaml:"args,omitempty"`

	// Env are environment variables passed to the subprocess.
	// Values support ${VAR} expansion from the host environment.
	Env map[string]string `yaml:"env,omitempty"`

	// URL is the upstream MCP server URL (for http/sse transports).
	URL string `yaml:"url,omitempty" env:"URL"`

	// Headers are HTTP headers to forward (for http transport).
	Headers map[string]string `yaml:"headers,omitempty"`

	// Autostart determines if this server starts with the daemon.
	Autostart bool `yaml:"autostart,omitempty" env:"AUTOSTART" env-default:"false"`

	// RestartPolicy controls automatic restart behavior.
	RestartPolicy RestartPolicy `yaml:"restart_policy,omitempty" env:"RESTART_POLICY" env-default:"on-failure"`

	// MaxRestarts is the maximum restart attempts within a 5-minute window.
	MaxRestarts int `yaml:"max_restarts,omitempty" env:"MAX_RESTARTS" env-default:"5"`

	// Stateful enables process-per-session mode for isolated state.
	Stateful bool `yaml:"stateful,omitempty" env:"STATEFUL" env-default:"false"`

	// AvailabilityProfile selects opinionated resilience defaults for the server.
	AvailabilityProfile AvailabilityProfile `yaml:"availability_profile,omitempty" env:"AVAILABILITY_PROFILE"`

	// SessionTimeout is how long an idle session lives (for stateful servers).
	SessionTimeout Duration `yaml:"session_timeout,omitempty" env:"SESSION_TIMEOUT" env-default:"5m"`

	// MaxSessions limits concurrent sessions (for stateful servers, 0 = unlimited).
	MaxSessions int `yaml:"max_sessions,omitempty" env:"MAX_SESSIONS" env-default:"0"`

	// SessionTTL is the absolute maximum lifetime of a session regardless of activity.
	// 0 means no TTL (sessions only expire via idle timeout or explicit close).
	SessionTTL Duration `yaml:"session_ttl,omitempty" env:"SESSION_TTL" env-default:"0s"`

	// HealthCheckInterval is how often to probe idle downstream sessions for liveness.
	// When set, the proxy layer sends periodic tools/list calls to detect dead
	// subprocesses before a tool call hits the failure path. Must be >= 5s if set.
	// 0 means use default (30s).
	HealthCheckInterval Duration `yaml:"health_check_interval,omitempty" env:"HEALTH_CHECK_INTERVAL" env-default:"30s"`

	// RequestTimeout is the default deadline Vision applies to downstream tool calls
	// when the upstream request does not already specify one. 0 means use default (30s).
	RequestTimeout Duration `yaml:"request_timeout,omitempty" env:"REQUEST_TIMEOUT" env-default:"30s"`

	// Retry configures retry/backoff behavior for retryable downstream tool-call failures.
	Retry *RetryConfig `yaml:"retry,omitempty"`

	// CircuitBreaker configures fast-fail behavior after repeated downstream failures.
	CircuitBreaker *CircuitBreakerConfig `yaml:"circuit_breaker,omitempty"`

	// SharedReadOnlyTools lists tool names that are safe to coalesce/cache across
	// concurrent sessions for this server.
	SharedReadOnlyTools []string `yaml:"shared_read_only_tools,omitempty"`

	// SharedResultCacheTTL is how long successful shared read-only results stay cached.
	// 0 disables caching while still allowing in-flight coalescing.
	SharedResultCacheTTL Duration `yaml:"shared_result_cache_ttl,omitempty" env:"SHARED_RESULT_CACHE_TTL"`

	// SharedResultCacheSize caps cached shared read-only results per server.
	// 0 uses the default for the selected profile.
	SharedResultCacheSize int `yaml:"shared_result_cache_size,omitempty" env:"SHARED_RESULT_CACHE_SIZE"`

	// MaxInFlightRequests caps concurrent downstream tool calls per server.
	// 0 means unlimited.
	MaxInFlightRequests int `yaml:"max_in_flight_requests,omitempty" env:"MAX_IN_FLIGHT_REQUESTS"`

	// Required indicates the server MUST be running for Vision (and any
	// dependent agent) to function correctly. When both Autostart and
	// Required are true, initial-start failure is fatal to daemon startup
	// (daemon.StartAll returns a non-nil error). When Required is true but
	// Autostart is false, the field is informational only — external tools
	// such as OCA may surface it in doctor output.
	Required bool `yaml:"required,omitempty" env:"REQUIRED" env-default:"false"`

	// Source is an informational URL describing where this server comes
	// from (homepage, repo). Accepted and preserved on round-trip; not
	// interpreted by Vision. Populated by external configuration tools
	// such as OpenCode Advance.
	Source string `yaml:"source,omitempty"`

	// Description is a short human-readable summary of the server.
	// Accepted and preserved on round-trip; not interpreted by Vision.
	// Populated by external configuration tools.
	Description string `yaml:"description,omitempty"`

	// DisconnectGracePeriod controls how long to wait after the last HTTP connection
	// closes before removing a shared-mode upstream session. Only applies to
	// non-stateful servers using SharedSessionManager. 0 uses default (60s).
	// Negative values disable disconnect detection entirely.
	DisconnectGracePeriod Duration `yaml:"disconnect_grace_period,omitempty"`

	// IdleReapTimeout controls how long a shared-mode backend subprocess lives after
	// the last upstream session disconnects. Only applies to non-stateful servers
	// using SharedSessionManager. 0 uses default (5m). Negative values disable
	// idle reaping entirely (subprocess lives forever).
	IdleReapTimeout Duration `yaml:"idle_reap_timeout,omitempty"`

	// SlotGroup is internal metadata set when this server was synthesized from a
	// slot_groups entry. It is not persisted to YAML.
	SlotGroup string `yaml:"-"`

	// SlotIndex is the 1-based position of the synthesized server within its
	// slot group. It is not persisted to YAML.
	SlotIndex int `yaml:"-"`
}

type ServerInstructions struct {
	// Priority indicates how preferred this server is (high, medium, low)
	Priority string `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Guidance is extended usage instructions for AI agents
	Guidance string `yaml:"guidance,omitempty" json:"guidance,omitempty"`

	// PreferFor lists use cases where this server should be preferred
	PreferFor []string `yaml:"prefer_for,omitempty" json:"prefer_for,omitempty"`

	// AvoidFor lists use cases where this server should NOT be used
	AvoidFor []string `yaml:"avoid_for,omitempty" json:"avoid_for,omitempty"`

	// Examples are usage examples to help agents understand correct usage
	Examples []string `yaml:"examples,omitempty" json:"examples,omitempty"`
}

type SlotGroupConfig struct {
	Template  string        `yaml:"template"`
	BasePort  int           `yaml:"base_port"`
	Count     int           `yaml:"count"`
	GroupPort int           `yaml:"group_port"`
	Defaults  *ServerConfig `yaml:"defaults,omitempty"`
}

type SupervisionConfig struct {
	// HealthCheckInterval is how often to check server health.
	HealthCheckInterval Duration `yaml:"health_check_interval" env:"HEALTH_CHECK_INTERVAL" env-default:"30s"`

	// ShutdownTimeout is the grace period for graceful shutdown.
	ShutdownTimeout Duration `yaml:"shutdown_timeout" env:"SHUTDOWN_TIMEOUT" env-default:"10s"`

	// RestartDelay is the initial delay before restarting a crashed server.
	RestartDelay Duration `yaml:"restart_delay" env:"RESTART_DELAY" env-default:"1s"`

	// MaxRestartDelay is the maximum delay (for exponential backoff).
	MaxRestartDelay Duration `yaml:"max_restart_delay" env:"MAX_RESTART_DELAY" env-default:"60s"`
}

type ToolInstructions struct {
	// NamespacedName is the callable OpenCode Code Mode form, for example
	// tools.lgrep.search_semantic. When omitted, Vision may derive it from the
	// canonical tool name and configured server names.
	NamespacedName string `yaml:"namespaced_name,omitempty" json:"namespaced_name,omitempty"`

	// Priority indicates how preferred this tool is (high, medium, low)
	Priority string `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Guidance is extended usage instructions for AI agents
	Guidance string `yaml:"guidance,omitempty" json:"guidance,omitempty"`

	// PreferFor lists use cases where this tool should be preferred
	PreferFor []string `yaml:"prefer_for,omitempty" json:"prefer_for,omitempty"`

	// AvoidFor lists use cases where this tool should NOT be used
	AvoidFor []string `yaml:"avoid_for,omitempty" json:"avoid_for,omitempty"`

	// Examples are usage examples to help agents understand correct usage
	Examples []string `yaml:"examples,omitempty" json:"examples,omitempty"`
}

type TransportType string