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, DelegationMode, FocusConfig, GoalConfig, ModelSpec,
119    ParentContextPolicy, SubAgentConfig, SubAgentLifecycleHooks, TaskSupervisorConfig,
120    ToolFilterConfig,
121};
122pub use channels::{
123    A2aClientConfig, A2aServerConfig, CardTrustPolicy, ChannelSkillsConfig, DiscordConfig,
124    IbctKeyConfig, McpConfig, McpMediaConfig, McpOAuthConfig, McpPolicy, McpServerConfig,
125    McpTrustLevel, OAuthTokenStorage, RateLimit, SlackConfig, TelegramConfig, ToolDiscoveryConfig,
126    ToolDiscoveryStrategyConfig, ToolPruningConfig, TrustCalibrationConfig, TrustedAgentKey,
127    is_skill_allowed,
128};
129pub use cli::{CliConfig, LoopConfig};
130pub use cocoon::CocoonConfig;
131pub use defaults::{
132    DEFAULT_DEBUG_DIR, DEFAULT_LOG_FILE, DEFAULT_SKILLS_DIR, DEFAULT_SQLITE_PATH,
133    default_debug_dir, default_integrity_registry_path, default_log_file_path, default_skills_dir,
134    default_sqlite_path, is_legacy_default_debug_dir, is_legacy_default_log_file,
135    is_legacy_default_skills_path, is_legacy_default_sqlite_path,
136};
137pub use dump_format::DumpFormat;
138pub use durable::{DurableBackend, DurableConfig, RetentionPolicy};
139pub use execution::{EnvironmentConfig, ExecutionConfig};
140pub use experiment::{
141    AdaptOrchConfig, AssetSensitivity, CommandConfig, EnsembleConfig, ExperimentConfig,
142    ExperimentSchedule, FailureStrategy, OrchestrationConfig, PlanCacheConfig,
143};
144pub use features::{
145    CavemanConfig, CompressionSpectrumConfig, CostConfig, DaemonConfig, DebugConfig, GatewayConfig,
146    IndexConfig, ProactiveExplorationConfig, RegistryBackendKind, RegistryConfig,
147    ScheduledTaskConfig, ScheduledTaskKind, SchedulerConfig, SchedulerDaemonConfig,
148    SchedulerSecurityConfig, SkillEvaluationConfig, SkillMiningConfig, SkillPromptMode,
149    SkillsConfig, TraceConfig, VaultBackend, VaultConfig, default_subagent_skill_token_budget,
150};
151pub use fidelity::FidelityConfig;
152pub use hooks::{FileChangedConfig, HooksConfig};
153pub use integrity::{AnchorMode, IntegrityConfig};
154pub use knowledge::KnowledgeConfig;
155pub use learning::{DetectorMode, LearningConfig};
156pub use logging::{LogRotation, LoggingConfig};
157pub use mcp_security::{CapabilityClass, DataSensitivity, FlaggedParameter, ToolSecurityMeta};
158pub use memory::{
159    AconConfig, AdmissionConfig, AdmissionStrategy, AdmissionWeights, ArcCompactionConfig,
160    AutoDreamConfig, BeliefRevisionConfig, CategoryConfig, CompressionConfig, CompressionStrategy,
161    ConflictResolutionStrategy, ConsentGateConfig, ConsolidationDaemonConfig, ContextFormat,
162    ContextStrategy, CrossThreadStoreConfig, DigestConfig, DocumentConfig, EmGraphConfig,
163    FiveSignalConfig, FiveSignalConsolidationConfig, ForgettingConfig, GraphConfig, HebbianConfig,
164    ImplicitConflictConfig, MagicDocsConfig, MemCotConfig, MemoryConfig, MicrocompactConfig,
165    NoteLinkingConfig, OpticalForgettingConfig, PersonaConfig, PruningStrategy, ReasoningConfig,
166    RecallViewConfig, RetrievalConfig, RetrievalFailuresConfig, RpeConfig, SemanticConfig,
167    SessionsConfig, SidequestConfig, SimilarityMethod, StoreRoutingConfig, StoreRoutingStrategy,
168    TierConfig, TieredRetrievalConfig, TrajectoryConfig, TrajectoryRiskAccumulatorConfig,
169    TrajectorySeverityMultipliers, TrajectorySignalWeights, TreeConfig, TypedPagesConfig,
170    TypedPagesEnforcement, VectorBackend,
171};
172pub use metrics::MetricsConfig;
173pub use notifications::NotificationsConfig;
174pub use plugins::{PluginsConfig, ReputationConfig, ReputationEnforcement};
175pub use providers::default_stt_language;
176pub use providers::{
177    BanditConfig, CacheTtl, CandleConfig, CandleDevice, CandleInlineConfig, CandleSource,
178    CascadeClassifierMode, CascadeConfig, CocoonPricing, CoeConfig, ComplexityRoutingConfig,
179    FAST_TIER_MODEL_HINTS, GeminiThinkingLevel, GenerationParams, GonkaNode, LlmConfig,
180    LlmRoutingStrategy, MAX_TOKENS_CAP, ProviderEntry, ProviderKind, ProviderName,
181    ProviderOverrides, RouterConfig, RouterStrategyConfig, StreamLimits, SttConfig, ThinkingConfig,
182    ThinkingEffort, TierMapping, validate_pool,
183};
184pub use quality::{QualityConfig, TriggerPolicy};
185pub use rate_limit::RateLimitConfig;
186pub use sanitizer::{
187    CausalIpiConfig, ContentIsolationConfig, CustomPiiPattern, EmbeddingGuardConfig,
188    ExfiltrationGuardConfig, MemoryWriteValidationConfig, NliConfig, PiiFilterConfig,
189    QuarantineConfig, ResponseVerificationConfig, SecretMaskingConfig, ShadowMemoryConfig,
190};
191pub use sanitizer::{GuardrailAction, GuardrailConfig, GuardrailFailStrategy};
192pub use security::{
193    CapabilityScopesConfig, PatternStrictness, ScannerConfig, ScopeConfig, SecurityConfig,
194    ShadowSentinelConfig, TimeoutConfig, TrajectorySentinelConfig, TrustConfig,
195};
196pub use serve::ServeConfig;
197pub use session::{RecapConfig, ResumeConfig, SessionConfig};
198pub use subagent::{
199    HookAction, HookDef, HookMatcher, MemoryScope, PermissionMode, SkillFilter, SubagentHooks,
200    ToolPolicy,
201};
202pub use telemetry::{TelemetryBackend, TelemetryConfig};
203pub use tools::{AuditDestination, SandboxBackend, ToolCompressionConfig};
204pub use ui::{
205    ACP_AUTH_CLIENT_ID_DEFAULT, ACP_AUTH_CLIENT_ID_LOCAL, AcpAuthClient, AcpAuthMethod, AcpConfig,
206    AcpLspConfig, AcpModelConfigConfig, AcpSubagentsConfig, AcpTemperaturePreset,
207    AcpTimeoutsConfig, AcpTransport, AdditionalDir, AdditionalDirError, ColorMode, DelightsConfig,
208    FleetConfig, Motion, PanelSizingMode, SubagentPresetConfig, ThemeConfig, ToolDensity,
209    TuiConfig,
210};
211pub use ui::{DiagnosticSeverity, DiagnosticsConfig, HoverConfig, LspConfig};
212pub use vigil::VigilConfig;
213pub use worktree::{BgIsolation, WorktreeBaseRef, WorktreeConfig};
214
215// Top-level config struct, error type, and resolved secrets — moved from zeph-core.
216pub use classifiers::{ClassifiersConfig, InjectionEnforcementMode};
217#[cfg(feature = "deep-link")]
218pub use deep_link::{AcpPreference, DeepLinkConfig};
219pub use error::ConfigError;
220pub use root::{Config, ResolvedSecrets};
zeph_config/lib.rs

zeph_config/
lib.rs
