zeph_config/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Configuration types and loaders for Zeph.
5//!
6//! This crate contains configuration struct and enum definitions, the TOML loader,
7//! environment variable overrides, validation, and migration helpers.
8//! Vault secret resolution is handled in `zeph-core` through the `SecretResolver` trait.
9//!
10//! # TODO (D4 — deferred: typed config presets)
11//!
12//! This crate currently has 131 config structs across 30 files (~19K LOC). Many subsystem
13//! configs duplicate the same optional/default patterns and there is no compile-time guarantee
14//! that a feature's config section is consistent with its runtime behaviour.
15//!
16//! Planned: typed preset newtype wrappers (e.g., `MemoryConfig<Minimal>`, `MemoryConfig<Full>`)
17//! so callers can use a named preset instead of setting 20+ individual fields, avoiding silent
18//! config drift when new fields are added.
19//!
20//! **Blocked by:** requires a clear preset taxonomy and a backwards-compatible TOML migration
21//! strategy. Must be a standalone epic with its own SDD spec. Do NOT bundle with other refactors.
22//!
23//! # Loading configuration
24//!
25//! ```no_run
26//! use std::path::Path;
27//! use zeph_config::Config;
28//!
29//! // Load from file (falls back to defaults when the file does not exist)
30//! let config = Config::load(Path::new("/etc/zeph/config.toml"))
31//!     .expect("failed to load config");
32//!
33//! // Validate numeric bounds and cross-references
34//! config.validate().expect("config validation failed");
35//!
36//! println!("Agent name: {}", config.agent.name);
37//! println!("History limit: {}", config.memory.history_limit);
38//! ```
39//!
40//! # Environment variable overrides
41//!
42//! After loading from TOML, `Config::load` automatically applies env-var overrides.
43//! Key variables:
44//!
45//! | Variable | Field overridden |
46//! |---|---|
47//! | `ZEPH_LLM_PROVIDER` | `llm.providers[0].provider_type` |
48//! | `ZEPH_LLM_MODEL` | `llm.providers[0].model` |
49//! | `ZEPH_SQLITE_PATH` | `memory.sqlite_path` |
50//! | `ZEPH_QDRANT_URL` | `memory.qdrant_url` |
51//!
52//! The Qdrant API key is vault-only (not an env-var override):
53//! `zeph vault set ZEPH_QDRANT_API_KEY "<key>"` → `memory.qdrant_api_key`.
54//!
55//! # Config migration
56//!
57//! Use [`migrate::ConfigMigrator`] to upgrade existing TOML configs with newly-added
58//! parameters added as commented-out entries:
59//!
60//! ```no_run
61//! use zeph_config::migrate::ConfigMigrator;
62//!
63//! let user_toml = std::fs::read_to_string("config.toml").unwrap();
64//! let migrator = ConfigMigrator::new();
65//! let result = migrator.migrate(&user_toml).expect("migration failed");
66//! println!("Added {} new parameters", result.changed_count);
67//! std::fs::write("config.toml", &result.output).unwrap();
68//! ```
69
70// TODO(critic): post-v1.0 — re-evaluate ConfigSection derive macro for the 131 config structs.
71
72pub mod agent;
73pub mod autonomous;
74pub mod channels;
75pub mod classifiers;
76pub mod cli;
77pub mod cocoon;
78mod de_helpers;
79#[cfg(feature = "deep-link")]
80pub mod deep_link;
81pub mod defaults;
82pub mod dump_format;
83pub mod durable;
84mod env;
85pub mod error;
86pub mod execution;
87pub mod experiment;
88pub mod features;
89pub mod fidelity;
90pub mod hooks;
91pub mod integrity;
92pub mod knowledge;
93pub mod learning;
94mod loader;
95pub mod logging;
96pub mod mcp_security;
97pub mod memory;
98pub mod metrics;
99pub mod migrate;
100pub mod notifications;
101pub mod plugins;
102pub mod providers;
103pub mod quality;
104pub mod rate_limit;
105pub mod root;
106pub mod sanitizer;
107pub mod security;
108pub mod serve;
109pub mod session;
110pub mod subagent;
111pub mod telemetry;
112pub mod tools;
113pub mod ui;
114pub mod vigil;
115pub mod worktree;
116
117pub use agent::{
118    AgentConfig, ContextInjectionMode, FocusConfig, GoalConfig, ModelSpec, ParentContextPolicy,
119    SubAgentConfig, SubAgentLifecycleHooks, TaskSupervisorConfig, ToolFilterConfig,
120};
121pub use channels::{
122    A2aClientConfig, A2aServerConfig, CardTrustPolicy, ChannelSkillsConfig, DiscordConfig,
123    IbctKeyConfig, McpConfig, McpMediaConfig, McpOAuthConfig, McpPolicy, McpServerConfig,
124    McpTrustLevel, OAuthTokenStorage, RateLimit, SlackConfig, TelegramConfig, ToolDiscoveryConfig,
125    ToolDiscoveryStrategyConfig, ToolPruningConfig, TrustCalibrationConfig, TrustedAgentKey,
126    is_skill_allowed,
127};
128pub use cli::{CliConfig, LoopConfig};
129pub use cocoon::CocoonConfig;
130pub use defaults::{
131    DEFAULT_DEBUG_DIR, DEFAULT_LOG_FILE, DEFAULT_SKILLS_DIR, DEFAULT_SQLITE_PATH,
132    default_debug_dir, default_integrity_registry_path, default_log_file_path, default_skills_dir,
133    default_sqlite_path, is_legacy_default_debug_dir, is_legacy_default_log_file,
134    is_legacy_default_skills_path, is_legacy_default_sqlite_path,
135};
136pub use dump_format::DumpFormat;
137pub use durable::{DurableBackend, DurableConfig, RetentionPolicy};
138pub use execution::{EnvironmentConfig, ExecutionConfig};
139pub use experiment::{
140    AdaptOrchConfig, AssetSensitivity, CommandConfig, EnsembleConfig, ExperimentConfig,
141    ExperimentSchedule, FailureStrategy, OrchestrationConfig, PlanCacheConfig,
142};
143pub use features::{
144    CavemanConfig, CompressionSpectrumConfig, CostConfig, DaemonConfig, DebugConfig, GatewayConfig,
145    IndexConfig, ProactiveExplorationConfig, RegistryBackendKind, RegistryConfig,
146    ScheduledTaskConfig, ScheduledTaskKind, SchedulerConfig, SchedulerDaemonConfig,
147    SchedulerSecurityConfig, SkillEvaluationConfig, SkillMiningConfig, SkillPromptMode,
148    SkillsConfig, TraceConfig, VaultBackend, VaultConfig, default_subagent_skill_token_budget,
149};
150pub use fidelity::FidelityConfig;
151pub use hooks::{FileChangedConfig, HooksConfig};
152pub use integrity::{AnchorMode, IntegrityConfig};
153pub use knowledge::KnowledgeConfig;
154pub use learning::{DetectorMode, LearningConfig};
155pub use logging::{LogRotation, LoggingConfig};
156pub use mcp_security::{CapabilityClass, DataSensitivity, FlaggedParameter, ToolSecurityMeta};
157pub use memory::{
158    AconConfig, AdmissionConfig, AdmissionStrategy, AdmissionWeights, ArcCompactionConfig,
159    AutoDreamConfig, BeliefRevisionConfig, CategoryConfig, CompressionConfig, CompressionStrategy,
160    ConflictResolutionStrategy, ConsolidationDaemonConfig, ContextFormat, ContextStrategy,
161    CrossThreadStoreConfig, DigestConfig, DocumentConfig, EmGraphConfig, FiveSignalConfig,
162    FiveSignalConsolidationConfig, ForgettingConfig, GraphConfig, HebbianConfig,
163    ImplicitConflictConfig, MagicDocsConfig, MemCotConfig, MemoryConfig, MicrocompactConfig,
164    NoteLinkingConfig, OpticalForgettingConfig, PersonaConfig, PruningStrategy, ReasoningConfig,
165    RecallViewConfig, RetrievalConfig, RetrievalFailuresConfig, RpeConfig, SemanticConfig,
166    SessionsConfig, SidequestConfig, SimilarityMethod, StoreRoutingConfig, StoreRoutingStrategy,
167    TierConfig, TieredRetrievalConfig, TrajectoryConfig, TrajectoryRiskAccumulatorConfig,
168    TrajectorySeverityMultipliers, TrajectorySignalWeights, TreeConfig, TypedPagesConfig,
169    TypedPagesEnforcement, VectorBackend,
170};
171pub use metrics::MetricsConfig;
172pub use notifications::NotificationsConfig;
173pub use plugins::{PluginsConfig, ReputationConfig, ReputationEnforcement};
174pub use providers::default_stt_language;
175pub use providers::{
176    BanditConfig, CacheTtl, CandleConfig, CandleDevice, CandleInlineConfig, CandleSource,
177    CascadeClassifierMode, CascadeConfig, CocoonPricing, CoeConfig, ComplexityRoutingConfig,
178    FAST_TIER_MODEL_HINTS, GeminiThinkingLevel, GenerationParams, GonkaNode, LlmConfig,
179    LlmRoutingStrategy, MAX_TOKENS_CAP, ProviderEntry, ProviderKind, ProviderName,
180    ProviderOverrides, RouterConfig, RouterStrategyConfig, StreamLimits, SttConfig, ThinkingConfig,
181    ThinkingEffort, TierMapping, validate_pool,
182};
183pub use quality::{QualityConfig, TriggerPolicy};
184pub use rate_limit::RateLimitConfig;
185pub use sanitizer::{
186    CausalIpiConfig, ContentIsolationConfig, CustomPiiPattern, EmbeddingGuardConfig,
187    ExfiltrationGuardConfig, MemoryWriteValidationConfig, NliConfig, PiiFilterConfig,
188    QuarantineConfig, ResponseVerificationConfig, SecretMaskingConfig, ShadowMemoryConfig,
189};
190pub use sanitizer::{GuardrailAction, GuardrailConfig, GuardrailFailStrategy};
191pub use security::{
192    CapabilityScopesConfig, PatternStrictness, ScannerConfig, ScopeConfig, SecurityConfig,
193    ShadowSentinelConfig, TimeoutConfig, TrajectorySentinelConfig, TrustConfig,
194};
195pub use serve::ServeConfig;
196pub use session::{RecapConfig, ResumeConfig, SessionConfig};
197pub use subagent::{
198    HookAction, HookDef, HookMatcher, MemoryScope, PermissionMode, SkillFilter, SubagentHooks,
199    ToolPolicy,
200};
201pub use telemetry::{TelemetryBackend, TelemetryConfig};
202pub use tools::{AuditDestination, SandboxBackend, ToolCompressionConfig};
203pub use ui::{
204    ACP_AUTH_CLIENT_ID_DEFAULT, ACP_AUTH_CLIENT_ID_LOCAL, AcpAuthClient, AcpAuthMethod, AcpConfig,
205    AcpLspConfig, AcpModelConfigConfig, AcpSubagentsConfig, AcpTemperaturePreset,
206    AcpTimeoutsConfig, AcpTransport, AdditionalDir, AdditionalDirError, ColorMode, DelightsConfig,
207    FleetConfig, Motion, SubagentPresetConfig, ThemeConfig, ToolDensity, TuiConfig,
208};
209pub use ui::{DiagnosticSeverity, DiagnosticsConfig, HoverConfig, LspConfig};
210pub use vigil::VigilConfig;
211pub use worktree::{BgIsolation, WorktreeBaseRef, WorktreeConfig};
212
213// Top-level config struct, error type, and resolved secrets — moved from zeph-core.
214pub use classifiers::{ClassifiersConfig, InjectionEnforcementMode};
215#[cfg(feature = "deep-link")]
216pub use deep_link::{AcpPreference, DeepLinkConfig};
217pub use error::ConfigError;
218pub use root::{Config, ResolvedSecrets};
zeph_config/lib.rs

zeph_config/
lib.rs
