config

Documentation

Overview

Package config is the thin root composite read by every cmd/aura subcommand. Per CONTEXT.md D-row "Composition": per-subsystem configs (db, knowledge, llm) live in their owning packages; this file only wires the top-level fields and composes credentials from POSTGRES_* primitives.

Slice 0.5 form: DB only. Slice 0.7 added `Neo4j knowledge.Config`; Phase 3 (Slice 1) adds `LLM llm.Config` + the AURA_OTEL_* tracing knobs. No new fields land here without an owning slice plan.

Index

• type Config
  • func Load() (*Config, error)
  • func LoadDB() *Config
  • func LoadServe() (*Config, error)
  • func (c *Config) Validate() error

Types

type Config

type Config struct {
	DB             db.Config
	Neo4j          knowledge.Config // Slice 0.7 — graph + vector + embed sidecar wiring
	LLM            llm.Config       // Slice 1 — OpenAI-compat client + load-order chain (D-22)
	MCPServers     map[string]mcp.ServerConfig
	MCPPolicies    map[string]mcp.ManagedServer
	MCPServersErr  error
	RunDir         string
	ToolPreviewCap int
	OtelExporter   string // AURA_OTEL_EXPORTER ∈ {stdout,otlp,none} (D-06)
	OtelEndpoint   string // AURA_OTEL_ENDPOINT — OTLP/gRPC target (D-06)

	// Phase 4 (Slice 1.8) conversation + context-management tuning knobs.
	// Non-fatal envIntDefault fallbacks (an ad-hoc tweak typo falls back, not boots-fatal).
	ConversationTurnCapBytes   int // AURA_CONVERSATION_TURN_CAP_BYTES — content > this spills to a sidecar file
	ContextToolEvictAfterTurns int // AURA_CONTEXT_TOOL_EVICT_AFTER_TURNS — L1 microcompact eviction age
	HistoryHardCapTurns        int // AURA_HISTORY_HARD_CAP_TURNS — L2.5 picobot hard rolling buffer cap
	RunDirWarnThresholdBytes   int // AURA_RUN_DIR_WARN_THRESHOLD_BYTES — boot du WARN threshold (audit-only)
	RunDirSweepIntervalSec     int // AURA_RUN_DIR_SWEEP_INTERVAL_SEC — periodic sidecar-sweep cadence in `serve` (M-06); <=0 disables the worker (boot sweep still runs)

	// Phase 7 (Slice 5) web_search/web_fetch knobs. SearxngURL is the upstream-
	// canonical name (NO AURA_ prefix); an empty value is NOT boot-fatal — it is
	// surfaced as web_search_unavailable{searxng_not_configured} at call time
	// (D-05/D-06) so `aura db migrate` and every non-web subcommand keep working.
	// No allowlist/loopback escape hatch lands here (D-30).
	SearxngURL           string // SEARXNG_URL — local SearXNG /search endpoint; empty default, fail-closed at call time
	WebDNSPinTTLSec      int    // AURA_WEB_DNS_PIN_TTL_SEC — per-conversation DNS pin TTL (D-25)
	WebFetchMaxBodyBytes int    // AURA_WEB_FETCH_MAX_BODY_BYTES — raw HTTP response body download ceiling (DoS guard); the LLM-facing markdown preview/spillover is governed by the agent tool-result preview cap (tools.NewResult), NOT this field
	WebCachePersistent   bool   // AURA_WEB_CACHE_PERSISTENT — opt-in disk cache; default false = in-memory (D-32)
	WebSearchTimeoutSec  int    // AURA_WEB_SEARCH_TIMEOUT_SEC — search wall-clock deadline (D-14)
	WebFetchTimeoutSec   int    // AURA_WEB_FETCH_TIMEOUT_SEC — fetch wall-clock deadline (D-23)
	WebUserAgent         string // AURA_WEB_USER_AGENT — Aura-specific UA, no browser spoof (D-34/D-35)

	// Phase 9 (Slice 3) swarm knobs (D-11/D-12/D-13). All non-fatal
	// envIntDefault fallbacks — a typo falls back rather than booting fatal.
	MaxSwarmGoals        int // AURA_SWARM_MAX_GOALS — hard cap on goals per swarm_spawn call (D-13)
	SwarmChildTimeoutSec int // AURA_SWARM_CHILD_TIMEOUT_SEC — per-child wall-clock deadline (D-11)
	MaxSwarmConcurrent   int // AURA_SWARM_MAX_CONCURRENT — wave width; goals beyond this run in sequential waves (D-12)

	// Scheduler agent_job wall-clock (#53/D-42). The 120s swarm-child analog starved
	// real artifact jobs (a North-Star-class xlsx run measures 150-360s live); the
	// serve composition root passes this into AgentDeps.MaxDuration.
	AgentJobMaxDurationSec int // AURA_AGENT_JOB_MAX_DURATION_SEC — agent_job end-to-end wall-clock deadline

	// SchedulerPreferOriginChannel is the default-on kill-switch (Phase 20 R5/D-03):
	// when on, a scheduled notification with an owning identity prefers the origin
	// channel (a Telegram reminder lands back in that DM) over the per-task route. The
	// composition root injects it as cron.DispatchDeps.PreferOriginChannel; false →
	// byte-identical legacy route-only behavior. Unset/malformed → on.
	SchedulerPreferOriginChannel bool // AURA_SCHEDULER_PREFER_ORIGIN_CHANNEL — prefer the origin channel over the route (default true)

	// Phase 11 (Slice 7) skills knobs (D-34). SkillsDir is the active skill root the
	// loader scans + builtins materialize into; ExportDir is the ro `/skills` mount
	// source. Cap knobs bound the per-skill body and the model-visible manifest.
	SkillsDir             string // AURA_SKILLS_DIR — active skill root (loader scan + builtin materialization)
	SkillBodyCapBytes     int    // AURA_SKILL_BODY_CAP_BYTES — per-skill body size cap at load (DoS guard, D-34)
	SkillManifestCapBytes int    // AURA_SKILL_MANIFEST_CAP_BYTES — manifest-in-Description byte budget; overflow → BM25 list (D-09/D-34)
	SkillExportDir        string // AURA_SKILL_EXPORT_DIR — activation→host export dir (the ro /skills mount source, D-17)
	SkillSnippetTTLDays   int    // AURA_SKILL_SNIPPET_TTL_DAYS — TTL sweep archives snippets unused this long (D-16/D-34)

	// Write-boundary injection blocklist (D-27/D-34). The NFKC-normalize-then-
	// match literal sequence list the skills validator enforces at write time
	// (model-authored create/update/install), NEVER on load (D-28). Defaults to
	// the prd.md §Slice 7 builtin list; a comma-separated AURA_SKILL_INJECTION_BLOCKLIST
	// replaces it wholesale.
	SkillInjectionBlocklist []string // AURA_SKILL_INJECTION_BLOCKLIST — prompt-injection literal blocklist (D-27/D-34)

	// Phase 12 (Slice 8) AG-UI gateway knobs. AGUIBind is hardcoded loopback this
	// phase (auth deferred; the loopback bind IS the compensating control, Pitfall 6
	// / amendment #35 — no --bind flag, no non-loopback escape). AGUICORSPermissive
	// gates the `Access-Control-Allow-Origin: *` header (default restrictive, dev-only).
	// AGUIBufferCap caps the per-connection SSE pump channel (drop-on-full, never
	// blocks the Loop). All non-fatal envDefault fallbacks.
	AGUIBind           string // AURA_AGUI_BIND — loopback-only HTTP bind (Pitfall 6)
	AGUICORSPermissive bool   // AURA_AGUI_CORS_PERMISSIVE — dev-only permissive CORS (default restrictive)
	AGUIBufferCap      int    // AURA_AGUI_BUFFER_CAP — SSE/fanout subscriber buffer cap (default 64)

	// ServeShutdownGraceSec bounds the in-flight turn drain on a SIGTERM/SIGINT
	// (audit O-06 / AP-17): on the signal the daemon stops accepting new work, then
	// gives in-flight turns up to this window to reach a terminal frame before the
	// work ctx is hard-cancelled as the final backstop. Default 25s — a real turn
	// rarely exceeds it; a misconfigured non-positive value degrades to immediate
	// hard-cancel (no wedge).
	ServeShutdownGraceSec int // AURA_SERVE_SHUTDOWN_GRACE_SEC — bounded in-flight turn drain window on shutdown (default 25)

	// Phase 13 (Slice 9) channels + setup-wizard + multimodal knobs. Aura-native
	// knobs use the AURA_<DOMAIN>_<UNIT> convention; third-party sidecars keep
	// upstream naming (MULTIMODAL_*/STT_*/TTS_*) per the CLAUDE.md exception. All
	// non-fatal silent-fallback loads — a typo falls back, never boots fatal.
	//
	// SetupBind is a loopback default on a port DISTINCT from the AG-UI :9080
	// (T-13-04-SetupExposure: the loopback bind IS the compensating control; the
	// override exists only for a deliberate remote-QR scan, token gate is plan
	// 13-07). SetupToken empty default → a random UUIDv4 is generated and printed
	// to stdout on first boot (plan 13-07), never read from disk here.
	SetupBind  string // AURA_SETUP_BIND — loopback setup-wizard HTTP bind, distinct from :9080
	SetupToken string // AURA_SETUP_TOKEN — setup-API gate; empty → generated at boot (13-07)

	// VisionCloud routes image understanding: false (default) → local aura-ocr-vl
	// sidecar; true → OpenRouter/minimax-m3 cloud (no GPU). One env branch, zero
	// code dup (#60 / Pitfall 6).
	VisionCloud bool // AURA_VISION_CLOUD — false=local GLM-OCR sidecar, true=cloud vision

	// Multimodal sidecar URLs/models (upstream naming, CLAUDE.md third-party
	// exception). MultimodalFallbackModel is the cloud vision model used when
	// VisionCloud is true and the primary model lacks SupportsVision.
	MultimodalBaseURL       string // MULTIMODAL_BASE_URL — aura-ocr-vl OpenAI-compat base
	MultimodalModel         string // MULTIMODAL_MODEL — local vision model id
	MultimodalFallbackModel string // MULTIMODAL_FALLBACK_MODEL — cloud vision fallback (default minimax/minimax-m3)
	STTBaseURL              string // STT_BASE_URL — aura-stt OpenAI-compat base
	STTModel                string // STT_MODEL — speech-to-text model id
	STTLanguage             string // STT_LANGUAGE — transcription language hint (default "it"; "" = whisper auto-detect, unreliable on short clips — spike-027)
	TTSBaseURL              string // TTS_BASE_URL — aura-tts OpenAI-compat base
	TTSVoice                string // TTS_VOICE — Kokoro voice id (default if_sara)
	TTSFormat               string // TTS_FORMAT — voice-note audio format (default opus)
	DocumentsBaseURL        string // DOCUMENTS_BASE_URL — markitdown /convert base (UX-04 documents leg)
	MultimodalTimeoutSec    int    // MULTIMODAL_TIMEOUT_SEC — per-request sidecar ceiling (default 120s; CPU OCR on a downscaled photo is well under, but vision needs more headroom than STT/TTS)

	// Phase 14 (Slice 10) Agent.md profile knobs.
	ProfileDir        string // AURA_PROFILE_DIR — per-identity Agent.md root, default ~/.aura/agents
	ProfileCertaintyN int    // AURA_PROFILE_CERTAINTY_N — observation threshold for auto-add, default 3
}

Config is the root composite. Subsystem configs live in their packages.

func Load

func Load() (*Config, error)

Load reads .env (best-effort) then populates a Config from environment variables. A missing .env file is not an error — production deployments rely on real environment variables, not on the .env shim.

Postgres DSN composition: AURA_DB_URL / AURA_DB_MIGRATE_URL overrides take precedence (production managed Postgres). Otherwise URLs are composed from POSTGRES_* primitives + AURA_DB_*_ROLE role names. Single POSTGRES_PASSWORD fans out to both runtime + DDL roles for local-dev ergonomics.

func LoadDB

func LoadDB() *Config

LoadDB loads the non-LLM configuration only. DB-admin commands (aura db migrate/ping/status/reset) must NOT require an LLM API key — migration is a pure DB operation, and Load's fail-fast empty-key (D-22) would otherwise block `aura db migrate` wherever OPENROUTER_API_KEY is unset (notably CI's migrate step). LLM is left zero-value; DB commands never read it.

func LoadServe

func LoadServe() (*Config, error)

LoadServe reads the full daemon config but permits an empty LLM API key so the setup wizard and channels can boot. LLM turns still fail closed at call time.

func (*Config) Validate

func (c *Config) Validate() error

Validate fails fast on an empty REQUIRED infrastructure secret so a misconfigured deploy errors at boot with a named cause instead of a late, cryptic DB auth failure or a silently degraded graph (O-04). The LLM API key has its own fail-fast in llm.Load (D-22); this covers the composed DB DSN and the Neo4j password. The daemon/REPL boot wires it in; the DB-only commands (LoadDB) skip it.