config

Documentation

Overview

Package config holds the koanf-backed daemon configuration. The `defaults.go` file is the canonical source for every Phase 1+ default value in the 4-layer precedence chain (CLI > project > user > profile).

Phase 57 added the `semantic_index.*` family per SPEC-DRAFT.md §25; see `internal/semantic/config.go` for the typed mirror. The `SerenaConfig.SemanticIndex` field's `koanf:"semantic_index"` binding tag was added by P03 atop the stub field landed in P02.

Float defaults MUST be wrapped `float64(...)` — koanf's confmap provider decodes untyped Go literals as `int`, which then fails to bind to a float64 struct field (the resulting value is the zero float). The observability tracing-ratio default below is the canonical precedent.

Slice defaults MUST be declared as `[]string{...}` (or the appropriate concrete slice type) — a bare `[]any{...}` does not bind cleanly to a `[]string` struct field through koanf's mapstructure decoder.

Index

• func DefaultConfig() map[string]interface{}
• func DefaultSocketPath() string
• func ResolveProfile(cfg *SerenaConfig, globalDir string) (*profile.ProfileStore, *profile.Profile, error)
• type ContextConfig
• type DaemonConfig
• type DegradationConfig
• type LoggingConfig
• type ModeConfig
• type ObservabilityConfig
• type ProjectDefaults
• type SerenaConfig
  • func Load(globalPath, projectPath string, cliOverrides map[string]interface{}) (*SerenaConfig, error)
• type WorkerPoolConfig

Functions

func DefaultConfig

func DefaultConfig() map[string]interface{}

DefaultConfig returns built-in default values.

func DefaultSocketPath

func DefaultSocketPath() string

DefaultSocketPath returns the default Unix socket path for the daemon.

func ResolveProfile

func ResolveProfile(cfg *SerenaConfig, globalDir string) (*profile.ProfileStore, *profile.Profile, error)

ResolveProfile loads the ProfileStore and returns the active profile based on the config's Profile field. The profile name flows through koanf precedence (CLI > project > global > default "full"); the profile content comes from the ProfileStore (embedded + overrides from globalDir).

Types

type ContextConfig

type ContextConfig struct {
	// Tools lists tool names available in this context
	Tools []string `koanf:"tools"`
	// Description of this context
	Description string `koanf:"description"`
}

ContextConfig defines a tool context.

type DaemonConfig

type DaemonConfig struct {
	// SocketPath overrides default /tmp/helix-$UID/daemon.sock (D-14)
	SocketPath string `koanf:"socket_path"`
	// HTTPAddr is the listen address for Streamable HTTP (default ":8080")
	HTTPAddr string `koanf:"http_addr"`
	// ShutdownTimeout in seconds for graceful shutdown
	ShutdownTimeout int `koanf:"shutdown_timeout"`
}

DaemonConfig holds daemon-specific settings.

type DegradationConfig

type DegradationConfig struct {
	TimeoutRead        int `koanf:"timeout_read"`        // seconds, default 5
	TimeoutSearch      int `koanf:"timeout_search"`      // seconds, default 15
	TimeoutEdit        int `koanf:"timeout_edit"`        // seconds, default 10
	TimeoutIndex       int `koanf:"timeout_index"`       // seconds, default 120
	TimeoutDiagnostics int `koanf:"timeout_diagnostics"` // seconds, default 20
	MemoryLimitMB      int `koanf:"memory_limit_mb"`     // 0 = don't set (use GOMEMLIMIT env if present)
	RestartBudget      int `koanf:"restart_budget"`      // default 3, consecutive crashes before circuit stays open
}

DegradationConfig holds timeout budgets and resilience settings (Phase 13).

type LoggingConfig

type LoggingConfig struct {
	// Format: "text" (default) or "json" (D-16)
	Format string `koanf:"format"`
	// Level: "debug", "info", "warn", "error" (default: "info")
	Level string `koanf:"level"`
	// Dir: log file directory (default: ~/.helix/logs/) (D-17)
	Dir string `koanf:"dir"`
}

LoggingConfig holds logging settings.

type ModeConfig

type ModeConfig struct {
	// Tools lists tool names available in this mode
	Tools []string `koanf:"tools"`
	// Description of this mode
	Description string `koanf:"description"`
}

ModeConfig defines an operational mode.

type ObservabilityConfig

type ObservabilityConfig struct {
	// AdminAddr is the loopback bind address for the admin listener.
	// Empty string disables the listener (D-02, D-05).
	AdminAddr string `koanf:"admin_addr"`
	// EnablePprof registers /debug/pprof/* handlers on the admin listener when true (D-10).
	// Default false: zero attack surface when disabled (D-12).
	EnablePprof bool `koanf:"enable_pprof"`

	// Phase 12: Tracing
	// TracingEndpoint is the OTLP/gRPC collector endpoint.
	// Empty string disables tracing entirely (D-11).
	TracingEndpoint string `koanf:"tracing_endpoint"`
	// TracingSampleRatio is the TraceIDRatioBased fraction.
	// 0.0 = off (default), 1.0 = sample everything (D-11).
	TracingSampleRatio float64 `koanf:"tracing_sample_ratio"`
	// ServiceName is the OTel resource service.name attribute.
	// Default: "helix" (D-11).
	ServiceName string `koanf:"service_name"`
}

ObservabilityConfig holds admin listener, pprof gating, and tracing settings. AdminAddr empty = disabled. Must be loopback (127.0.0.1/localhost/::1) — v1.3 adds auth.

type ProjectDefaults

type ProjectDefaults struct {
	// Contexts define tool sets for different environments
	Contexts map[string]ContextConfig `koanf:"contexts"`
	// Modes define operational patterns
	Modes map[string]ModeConfig `koanf:"modes"`
}

ProjectDefaults holds default project settings.

type SerenaConfig

type SerenaConfig struct {
	// Daemon settings
	Daemon DaemonConfig `koanf:"daemon"`
	// Logging settings
	Logging LoggingConfig `koanf:"logging"`
	// Default project settings (overridden per-project)
	Defaults ProjectDefaults `koanf:"defaults"`
	// Worker pool settings for LS process management
	WorkerPool WorkerPoolConfig `koanf:"worker_pool"`
	// Profile is the active agent profile name (default: "full").
	// Precedence: CLI --profile > project config > user config > default (D-10, PRF-05).
	Profile string `koanf:"profile"`
	// Mode is the initial operational mode override.
	// Empty means use the profile's DefaultMode.
	Mode string `koanf:"mode"`
	// Observability holds admin listener + pprof gating settings (Phase 10).
	Observability ObservabilityConfig `koanf:"observability"`
	// Degradation holds timeout budgets and resilience settings (Phase 13).
	Degradation DegradationConfig `koanf:"degradation"`
	// SemanticIndex holds Phase 57+ semantic graph settings (SPEC §25).
	//
	// Phase 57 plan P02 landed this field as a stub (zero values, no koanf
	// tag); Phase 57 plan P03 (this commit) attaches the
	// `koanf:"semantic_index"` binding tag so the SPEC §25 defaults from
	// internal/config/defaults.go and any user/project YAML files actually
	// populate the field through the standard 4-layer precedence.
	SemanticIndex semantic.Config `koanf:"semantic_index"`
}

SerenaConfig is the top-level configuration for the Serena daemon. Mirrors the Python Helix config schema (D-11) with Go types.

func Load

func Load(globalPath, projectPath string, cliOverrides map[string]interface{}) (*SerenaConfig, error)

Load builds a SerenaConfig from layered sources in precedence order: 1. Built-in defaults 2. Global config (~/.helix/helix_config.yml) 3. Project config (.helix/project.yml) (D-09) 4. CLI flag overrides

type WorkerPoolConfig

type WorkerPoolConfig struct {
	// BaseTTL is the base idle timeout in seconds (default 300).
	BaseTTL int `koanf:"base_ttl"`
	// CeilingTTL is the maximum idle timeout in seconds (default 3600).
	CeilingTTL int `koanf:"ceiling_ttl"`
	// MaxWorkers is the maximum number of concurrent LS workers (default 10).
	MaxWorkers int `koanf:"max_workers"`
	// RSSHardCapMB is the per-worker RSS hard cap in MB for pressure eviction (default 2048).
	RSSHardCapMB int `koanf:"rss_hard_cap_mb"`
	// PressureCheckInterval is the interval in seconds between pressure checks (default 10).
	PressureCheckInterval int `koanf:"pressure_check_interval"`
}

WorkerPoolConfig holds configuration for the LS worker pool.