Skip to main content

microclaw_engine/config/
core.rs

1use super::*;
2
3pub fn normalize_model_name(value: &str) -> Option<String> {
4    let trimmed = value.trim();
5    if trimmed.is_empty() || trimmed == "*" {
6        None
7    } else {
8        Some(trimmed.to_string())
9    }
10}
11
12pub(crate) fn normalize_string_list(values: &mut Vec<String>, lowercase: bool) {
13    *values = values
14        .drain(..)
15        .map(|value| {
16            let value = value.trim();
17            if lowercase {
18                value.to_ascii_lowercase()
19            } else {
20                value.to_string()
21            }
22        })
23        .filter(|value| !value.is_empty())
24        .collect();
25    values.sort();
26    values.dedup();
27}
28
29pub fn resolve_model_name_with_fallback(
30    provider: &str,
31    candidate: Option<&str>,
32    fallback: Option<&str>,
33) -> String {
34    candidate
35        .and_then(normalize_model_name)
36        .or_else(|| fallback.and_then(normalize_model_name))
37        .unwrap_or_else(|| default_model_for_provider_name(provider).to_string())
38}
39
40/// Expands a path string, replacing `~` with the user's home directory.
41pub(crate) fn expand_path(path: &str) -> PathBuf {
42    match shellexpand::tilde(path) {
43        std::borrow::Cow::Borrowed(p) => PathBuf::from(p),
44        std::borrow::Cow::Owned(p) => PathBuf::from(p),
45    }
46}
47
48pub(crate) fn detect_system_timezone() -> String {
49    match iana_time_zone::get_timezone() {
50        Ok(tz_name) => tz_name,
51        Err(e) => {
52            warn!("Failed to detect system timezone automatically: {e}. Falling back to UTC.");
53            "UTC".into()
54        }
55    }
56}
57
58/// Language for user-facing runtime messages (refusals, approval prompts,
59/// recovery notices). `en` preserves historical output; approval reply
60/// keywords are recognized in both languages regardless.
61#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
62#[serde(rename_all = "lowercase")]
63pub enum UserMessageLanguage {
64    #[default]
65    En,
66    Zh,
67    Bilingual,
68}
69
70/// How much time detail the runtime injects into the prompt for the current
71/// turn. Lower values keep the cached prompt prefix stable across turns, which
72/// is what prompt caching requires: anything that changes every turn must live
73/// in the transient turn-context block instead of the system prompt.
74#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(rename_all = "lowercase")]
76pub enum SystemPromptTimeDetail {
77    /// No clock in the system prompt. The live time is only available through
78    /// the `get_current_time` tool and the transient turn-context block.
79    None,
80    /// Date only (`YYYY-MM-DD`) in the configured timezone. Stable for a whole
81    /// local day, so the prefix still survives within a day.
82    #[default]
83    Date,
84    /// Full local and UTC timestamps. Changes on every turn, so the system
85    /// prompt prefix is invalidated continuously.
86    Full,
87}
88
89#[derive(Clone, Debug, Serialize, Deserialize)]
90pub struct Config {
91    // --- LLM / API ---
92    #[serde(default = "default_llm_provider")]
93    pub llm_provider: String,
94    #[serde(default = "default_api_key")]
95    pub api_key: String,
96    /// Additional API keys forming a rotation pool with `api_key`: on
97    /// auth (401/403) or rate-limit (429) errors the provider advances to
98    /// the next key before retrying.
99    #[serde(default)]
100    pub api_keys: Vec<String>,
101    #[serde(default = "default_model")]
102    pub model: String,
103    #[serde(default)]
104    pub provider_presets: HashMap<String, LlmProviderProfile>,
105    #[serde(default)]
106    pub llm_providers: HashMap<String, LlmProviderProfile>,
107    #[serde(default)]
108    pub llm_base_url: Option<String>,
109    #[serde(default = "default_llm_user_agent")]
110    pub llm_user_agent: String,
111    #[serde(default = "default_max_tokens")]
112    pub max_tokens: u32,
113    #[serde(default = "default_max_tool_iterations")]
114    pub max_tool_iterations: usize,
115    #[serde(default = "default_compaction_timeout_secs")]
116    pub compaction_timeout_secs: u64,
117    /// Optional per-task auxiliary model overrides (e.g. a cheaper model for
118    /// compaction). Empty by default, in which case the main model is used.
119    #[serde(default)]
120    pub aux_models: AuxModels,
121    /// Optional fallback model used when the primary model's provider keeps
122    /// failing (after retries) or its circuit breaker is open. None disables
123    /// fallback (and the breaker wrapper) entirely — behaviour is then
124    /// identical to the primary provider alone.
125    #[serde(default)]
126    pub fallback_model: Option<String>,
127    #[serde(default = "default_max_history_messages")]
128    pub max_history_messages: usize,
129    #[serde(default = "default_max_document_size_mb")]
130    pub max_document_size_mb: u64,
131    #[serde(default = "default_memory_token_budget")]
132    pub memory_token_budget: usize,
133    /// Percentage of memory_token_budget reserved for L0 Identity (PROFILE) memories. Default: 20.
134    #[serde(default = "default_memory_l0_identity_pct")]
135    pub memory_l0_identity_pct: usize,
136    /// Percentage of memory_token_budget reserved for L1 Essential (high-confidence) memories. Default: 30.
137    #[serde(default = "default_memory_l1_essential_pct")]
138    pub memory_l1_essential_pct: usize,
139    #[serde(default = "default_memory_max_entries_per_chat")]
140    pub memory_max_entries_per_chat: usize,
141    #[serde(default = "default_memory_max_global_entries")]
142    pub memory_max_global_entries: usize,
143    /// Maximum active triples per chat in the knowledge graph. 0 = unlimited. Default: 1000.
144    #[serde(default = "default_kg_max_triples_per_chat")]
145    pub kg_max_triples_per_chat: usize,
146    /// Tool-result content over this many Unicode characters is truncated in
147    /// the message history and the full body is stored as an artifact the
148    /// agent can read via `fetch_artifact`. Set to 0 to disable. Default: 4000.
149    #[serde(default = "default_tool_result_truncation_threshold_chars")]
150    pub tool_result_truncation_threshold_chars: usize,
151    /// When truncating, keep this many leading characters of the original
152    /// content in the message history. Default: 1500.
153    #[serde(default = "default_tool_result_truncation_head_chars")]
154    pub tool_result_truncation_head_chars: usize,
155    /// When truncating, keep this many trailing characters (so the agent
156    /// still sees errors/summaries that often live at the end). Default: 500.
157    #[serde(default = "default_tool_result_truncation_tail_chars")]
158    pub tool_result_truncation_tail_chars: usize,
159    /// Lifetime for stashed tool-result artifacts before they're pruned.
160    /// Long enough to span a typical multi-turn task. Default: 24 hours.
161    #[serde(default = "default_tool_result_artifact_ttl_hours")]
162    pub tool_result_artifact_ttl_hours: u64,
163    /// Half-life (in days) of the recency-decay multiplier applied to
164    /// non-PROFILE memories during L1/L2 ranking. After `half_life_days`,
165    /// a memory's effective score is half of its raw confidence; PROFILE
166    /// memories never decay. Set to 0 to disable decay. Default: 30.
167    #[serde(default = "default_memory_recency_half_life_days")]
168    pub memory_recency_half_life_days: f64,
169    /// Graph-augmented memory recall: after the flat L0-L2 layers are built,
170    /// seed the temporal knowledge graph from entities the query mentions and
171    /// pull in connected facts a few hops out (a "# Connected" block). Surfaces
172    /// multi-hop context the flat layers miss, using the graph the reflector
173    /// already builds — local-only, no embeddings or extra LLM calls. Default: true.
174    #[serde(default = "default_memory_graph_recall_enabled")]
175    pub memory_graph_recall_enabled: bool,
176    /// Maximum hops to expand outward from query-seeded entities during
177    /// graph-augmented recall. Clamped to 1-3. Default: 2.
178    #[serde(default = "default_memory_graph_max_hops")]
179    pub memory_graph_max_hops: usize,
180    /// Maximum number of connected triples injected by graph-augmented recall
181    /// (also bounded by the overall memory token budget). Set to 0 to disable.
182    /// Default: 10.
183    #[serde(default = "default_memory_graph_max_triples")]
184    pub memory_graph_max_triples: usize,
185    /// Sliding-window size (in past tool calls) used by the duplicate-call
186    /// circuit breaker. When the same `(tool_name, args)` shows up
187    /// `tool_repeat_limit` times within this many recent calls, the next
188    /// invocation is short-circuited with an error so the agent picks a
189    /// different approach. Set to 0 to disable. Default: 10.
190    #[serde(default = "default_tool_repeat_window")]
191    pub tool_repeat_window: usize,
192    /// Repeat threshold for the duplicate-call circuit breaker. Default: 3.
193    #[serde(default = "default_tool_repeat_limit")]
194    pub tool_repeat_limit: usize,
195    /// Enable Anthropic prompt-cache breakpoints (system + last 3 messages).
196    /// Cuts repeat-turn input cost ~75% for multi-turn chats. Anthropic-only;
197    /// no effect on OpenAI-compatible providers. Default: true.
198    #[serde(default = "default_anthropic_prompt_cache_enabled")]
199    pub anthropic_prompt_cache_enabled: bool,
200    /// Let Anthropic clear old tool results on the server (context editing,
201    /// beta) in addition to MicroClaw's own compaction. Default: false.
202    #[serde(default)]
203    pub anthropic_context_editing: bool,
204    /// Cache TTL for Anthropic prompt cache. "5m" (default) or "1h".
205    /// "1h" requires extended-cache opt-in on the API key.
206    #[serde(default = "default_anthropic_prompt_cache_ttl")]
207    pub anthropic_prompt_cache_ttl: String,
208    /// Enable transparent filesystem checkpoints via a shadow git repo.
209    /// When on, microclaw snapshots each chat's working directory at the
210    /// start of every agent turn so users can `/rewind` to a prior state.
211    /// Off by default — opt in per chat or via global config. Requires `git`
212    /// on PATH.
213    #[serde(default = "default_checkpoints_enabled")]
214    pub checkpoints_enabled: bool,
215    /// Auto-archive `agent-created` skills that haven't been activated in
216    /// this many days and are themselves at least this old. The skill dir
217    /// is moved under `<skills_dir>/.archived/` (recoverable). Set to 0
218    /// to disable. Default: 30 days.
219    #[serde(default = "default_skill_archive_after_days")]
220    pub skill_archive_after_days: u64,
221    /// When building the skills section of the system prompt, inline the
222    /// full body of the top-K skills whose descriptions match the user
223    /// query and list the rest as `name: description` only. Cuts prompt
224    /// cost as the skill library grows. Set to 0 to fall back to the
225    /// flat catalog. Default: 3.
226    #[serde(default = "default_skills_catalog_top_k")]
227    pub skills_catalog_top_k: usize,
228    /// How much live time detail the system prompt carries. The default `date`
229    /// keeps the cached prefix stable within a local day; the live clock and
230    /// query-scoped context are injected per turn instead. Set to `full` to
231    /// restore the previous always-current timestamps in the system prompt.
232    #[serde(default)]
233    pub system_prompt_time_detail: SystemPromptTimeDetail,
234    #[serde(default = "default_max_session_messages")]
235    pub max_session_messages: usize,
236    /// Cap on rendered unified-diff lines attached by file-modifying tools
237    /// (edit_file / write_file). Default: 120.
238    #[serde(default = "default_diff_max_lines")]
239    pub diff_max_lines: usize,
240    /// Deliver file-edit diffs as chat messages on channels that opted into
241    /// progress updates. The web UI always receives diff events. Default: true.
242    #[serde(default = "default_file_diffs_in_chat")]
243    pub file_diffs_in_chat: bool,
244    /// Let write_file / edit_file modify MicroClaw's own governance files
245    /// (the config file, AGENTS.md / SOUL.md / USER.md under data_dir, soul
246    /// and context directories, the path allowlist). Off by default: those
247    /// files are injected into every chat's prompt or define access policy,
248    /// so only scoped tools such as write_memory may change them.
249    #[serde(default)]
250    pub allow_governance_file_writes: bool,
251    /// Approximate context window (tokens) of the configured model, used by
252    /// the mid-turn context-pressure check. Default: 200000.
253    #[serde(default = "default_model_context_window")]
254    pub model_context_window: usize,
255    /// Compact the session mid-turn once a request consumes this percentage
256    /// of `model_context_window`. 0 disables the pressure check (the
257    /// overflow-error retry still applies). Default: 85.
258    #[serde(default = "default_context_pressure_compact_pct")]
259    pub context_pressure_compact_pct: usize,
260    /// Per-model context windows (tokens), overriding `model_context_window`
261    /// and the built-in model table, e.g. `{"my-local-model": 32768}`.
262    #[serde(default)]
263    pub model_context_windows: HashMap<String, usize>,
264    /// Compact automatically when the conversation approaches the model's
265    /// context window (`context_pressure_compact_pct`, at most 90%). Manual
266    /// compaction keeps working when this is off. Default: true.
267    #[serde(default = "default_true")]
268    pub auto_compact: bool,
269    /// Before summarizing, older tool outputs are cleared; the most recent
270    /// this many tokens of tool output are always kept. Default: 40000.
271    #[serde(default = "default_prune_protect_tokens")]
272    pub prune_protect_tokens: usize,
273    /// Clear older tool outputs only when that frees at least this many
274    /// tokens (smaller savings are not worth invalidating the prompt cache).
275    /// Default: 20000.
276    #[serde(default = "default_prune_minimum_tokens")]
277    pub prune_minimum_tokens: usize,
278    /// Keep roughly the last this many tokens of conversation verbatim when
279    /// summarizing. 0 keeps the last `compact_keep_recent` messages instead.
280    /// Default: 0.
281    #[serde(default)]
282    pub compact_keep_recent_tokens: usize,
283    /// Extra instructions for compaction summaries (what to preserve).
284    #[serde(default)]
285    pub compact_instructions: Option<String>,
286    /// Directory of project agent definitions (`<name>.md`) offered to the
287    /// `explore` tool. Set by embedders for trusted workspaces.
288    #[serde(default)]
289    pub project_agents_dir: Option<String>,
290    /// Embedder-supplied gate consulted before every tool call (permission
291    /// rules, user hooks). Never read from or written to the file.
292    #[serde(skip)]
293    pub tool_gate: crate::tool_gate::ToolGateHandle,
294    /// Offer the model the context tools `context_note` and
295    /// `rewind_context`. Default: false.
296    #[serde(default)]
297    pub context_tools: bool,
298    /// Tell the model how full its context is on every request. Default:
299    /// false (on in coding workspaces).
300    #[serde(default)]
301    pub context_budget_hint: bool,
302    /// Offer the read-only `explore` helper. Default: false (on in coding
303    /// workspaces).
304    #[serde(default)]
305    pub explore_tool: bool,
306    /// Opt-in post-edit quality pass: after a turn that ran edit_file /
307    /// write_file, one extra review iteration runs before the reply is
308    /// finalized.
309    #[serde(default)]
310    pub self_recheck: SelfRecheckConfig,
311    #[serde(default = "default_compact_keep_recent")]
312    pub compact_keep_recent: usize,
313    #[serde(default = "default_tool_timeout_secs")]
314    pub default_tool_timeout_secs: u64,
315    #[serde(default)]
316    pub tool_timeout_overrides: HashMap<String, u64>,
317    #[serde(default = "default_mcp_request_timeout_secs")]
318    pub default_mcp_request_timeout_secs: u64,
319    #[serde(default)]
320    pub show_thinking: bool,
321    #[serde(default)]
322    pub subagents: SubagentConfig,
323    #[serde(default)]
324    pub idle_checkin: IdleCheckinConfig,
325    #[serde(default)]
326    pub heartbeat: HeartbeatConfig,
327    #[serde(default)]
328    pub token_budget: TokenBudgetConfig,
329    #[serde(default)]
330    pub alerts: AlertsConfig,
331    #[serde(default)]
332    pub trust_report: TrustReportConfig,
333    /// Language for user-facing refusals/approval prompts/notices.
334    #[serde(default)]
335    pub user_message_language: UserMessageLanguage,
336    #[serde(default)]
337    pub sleep_time: SleepTimeConfig,
338    #[serde(default)]
339    pub interjection: InterjectionConfig,
340    #[serde(default)]
341    pub a2a: A2AConfig,
342
343    // --- Concurrency ---
344    /// Maximum number of pending messages per chat before oldest are dropped.
345    #[serde(default = "default_chat_turn_queue_max_pending")]
346    pub chat_turn_queue_max_pending: usize,
347    /// Inject pending messages into the active agent loop between iterations,
348    /// rather than queuing them for a separate re-run. Default: true.
349    #[serde(default = "default_true")]
350    pub enable_mid_turn_injection: bool,
351    /// On non-web channels (Telegram/Discord/Slack), send a small ack message
352    /// when a follow-up arrives mid-turn and is folded into the active loop.
353    /// Default: true. Has no effect when `enable_mid_turn_injection` is false.
354    #[serde(default = "default_true")]
355    pub mid_turn_injection_echo: bool,
356    /// Maximum number of tools to execute concurrently in a single wave.
357    #[serde(default = "default_parallel_tool_max_concurrency")]
358    pub parallel_tool_max_concurrency: usize,
359    /// Override concurrency class for specific tools (e.g., promote safe MCP tools).
360    /// Keys are tool names, values are "read_only", "side_effect", or "exclusive".
361    #[serde(default)]
362    pub tool_concurrency_overrides: HashMap<String, String>,
363    /// OpenAI-compatible request-body overrides applied for all models/providers.
364    /// Set a key to `null` to remove that field from the outgoing JSON body.
365    #[serde(default)]
366    pub openai_compat_body_overrides: HashMap<String, serde_json::Value>,
367    /// OpenAI-compatible request-body overrides keyed by provider name.
368    /// Provider keys are normalized to lowercase.
369    #[serde(default)]
370    pub openai_compat_body_overrides_by_provider:
371        HashMap<String, HashMap<String, serde_json::Value>>,
372    /// OpenAI-compatible request-body overrides keyed by model name.
373    #[serde(default)]
374    pub openai_compat_body_overrides_by_model: HashMap<String, HashMap<String, serde_json::Value>>,
375
376    // --- Paths & environment ---
377    #[serde(default = "default_data_dir")]
378    pub data_dir: String,
379    #[serde(default)]
380    pub skills_dir: Option<String>,
381    #[serde(default = "default_working_dir")]
382    pub working_dir: String,
383    #[serde(default = "default_working_dir_isolation")]
384    pub working_dir_isolation: WorkingDirIsolation,
385    #[serde(default = "default_high_risk_tool_user_confirmation_required")]
386    pub high_risk_tool_user_confirmation_required: bool,
387    /// Caller channels whose high-risk tool calls (shell commands) need an
388    /// explicit human approval. Control chats always do. Default:
389    /// `["web", "code"]` — the interactive operator surfaces.
390    #[serde(default = "default_approval_channels")]
391    pub approval_channels: Vec<String>,
392    /// Caller channels whose sub-agents may only use read-only tools, so
393    /// workspace writes stay with the main agent. Default: `["code"]`.
394    #[serde(default = "default_read_only_subagent_channels")]
395    pub read_only_subagent_channels: Vec<String>,
396    /// Regex patterns that always require operator approval before bash will
397    /// run, even in non-control chats. Extends the per-chat risk policy with
398    /// command-content inspection so destructive shell snippets cannot slip
399    /// through just because the caller happens to be in a permissive chat.
400    /// Patterns are matched case-insensitively against the full command
401    /// string. Set to an empty list to disable command-content gating.
402    #[serde(default = "default_bash_dangerous_patterns")]
403    pub bash_dangerous_patterns: Vec<String>,
404    /// RTK (Rust Token Killer) bash-output compression. Off by default.
405    #[serde(default)]
406    pub rtk: RtkConfig,
407    #[serde(default)]
408    pub sandbox: SandboxConfig,
409    #[serde(default, skip_serializing_if = "Option::is_none")]
410    pub override_timezone: Option<String>,
411    #[serde(default = "default_timezone", skip_serializing)]
412    pub timezone: String,
413    #[serde(default = "default_control_chat_ids")]
414    pub control_chat_ids: Vec<i64>,
415    #[serde(default)]
416    pub discord_bot_token: Option<String>,
417    #[serde(default)]
418    pub discord_allowed_channels: Vec<u64>,
419    #[serde(default)]
420    pub discord_no_mention: bool,
421    #[serde(default = "default_allow_group_slash_without_mention")]
422    pub allow_group_slash_without_mention: bool,
423
424    // --- Web UI ---
425    #[serde(default = "default_web_enabled")]
426    pub web_enabled: bool,
427    #[serde(default = "default_web_host")]
428    pub web_host: String,
429    #[serde(default = "default_web_port")]
430    pub web_port: u16,
431    #[serde(default = "default_web_max_inflight_per_session")]
432    pub web_max_inflight_per_session: usize,
433    #[serde(default = "default_web_max_requests_per_window")]
434    pub web_max_requests_per_window: usize,
435    #[serde(default = "default_web_rate_window_seconds")]
436    pub web_rate_window_seconds: u64,
437    #[serde(default = "default_web_run_history_limit")]
438    pub web_run_history_limit: usize,
439    #[serde(default = "default_web_session_idle_ttl_seconds")]
440    pub web_session_idle_ttl_seconds: u64,
441    #[serde(default)]
442    pub web_fetch_validation: WebContentValidationConfig,
443    #[serde(default)]
444    pub web_fetch_url_validation: WebFetchUrlValidationConfig,
445    /// Pluggable web-search backend (duckduckgo | searxng | brave | tavily | keenable).
446    /// Defaults to DuckDuckGo, preserving historical behavior.
447    #[serde(default)]
448    pub web_search: SearchProviderConfig,
449    /// Outbound message guardrail (off | redact | block). Off by default;
450    /// scans delivered bot messages for credential-like strings.
451    #[serde(default)]
452    pub output_guardrail: OutputGuardrailConfig,
453    /// Pre-tool-call policy (mode off | warn | block, deny_tools, max_risk,
454    /// allow_tools). Off by default; violations are sealed into the audit log.
455    #[serde(default)]
456    pub tool_policy: crate::tool_guardrails::ToolPolicyConfig,
457    /// Process policy for configured HTTP(S) endpoints and every URL exposed
458    /// through the shared tool registry. Off by default for compatibility.
459    #[serde(default)]
460    pub egress_policy: EgressPolicyConfig,
461
462    // --- Embedding ---
463    #[serde(default)]
464    pub embedding_provider: Option<String>,
465    #[serde(default)]
466    pub embedding_api_key: Option<String>,
467    #[serde(default)]
468    pub embedding_base_url: Option<String>,
469    #[serde(default)]
470    pub embedding_model: Option<String>,
471    #[serde(default)]
472    pub embedding_dim: Option<usize>,
473    #[serde(default)]
474    pub openai_api_key: Option<String>,
475
476    // --- Pricing ---
477    #[serde(default = "default_model_prices")]
478    pub model_prices: Vec<ModelPrice>,
479
480    // --- Reflector ---
481    #[serde(default = "default_reflector_enabled")]
482    pub reflector_enabled: bool,
483    #[serde(default = "default_reflector_interval_mins")]
484    pub reflector_interval_mins: u64,
485    // --- Scheduled-task DLQ auto-replay ---
486    /// Automatically retry scheduled tasks that landed in the dead-letter
487    /// queue (e.g. a one-shot task that hit a transient failure), up to
488    /// `dlq_max_replay_attempts` times. Default: true.
489    #[serde(default = "default_dlq_replay_enabled")]
490    pub dlq_replay_enabled: bool,
491    /// How often the DLQ auto-replay sweep runs, in seconds. Default: 300.
492    #[serde(default = "default_dlq_replay_interval_secs")]
493    pub dlq_replay_interval_secs: u64,
494    /// Maximum automatic replay attempts per task before it is left in the
495    /// DLQ for manual inspection. Default: 3.
496    #[serde(default = "default_dlq_max_replay_attempts")]
497    pub dlq_max_replay_attempts: u32,
498    /// Minimum tool_use blocks in a turn before the end-of-turn skill
499    /// review fires. Autonomous skill creation is on by default; set to
500    /// 0 to disable entirely. Default: 5.
501    #[serde(default = "default_skill_review_min_tool_calls")]
502    pub skill_review_min_tool_calls: usize,
503
504    // --- Soul ---
505    /// Path to a SOUL.md file that defines the bot's personality, voice, and values.
506    /// If not set, looks for SOUL.md in data_dir root, then current directory.
507    #[serde(default = "default_soul_path")]
508    pub soul_path: Option<String>,
509    /// Directory for per-bot SOUL files. Defaults to <data_dir>/souls when unset.
510    #[serde(default = "default_souls_dir")]
511    pub souls_dir: Option<String>,
512
513    // --- Project context files ---
514    /// Directory of project-level context Markdown files injected into the
515    /// system prompt for every chat. Use this for workspace-wide facts that
516    /// belong above per-chat memory but are not personality (which lives in
517    /// SOUL.md). Defaults to `<data_dir>/context/` when unset; missing
518    /// directories are silently skipped.
519    #[serde(default)]
520    pub context_dir: Option<String>,
521    /// Hard cap (in characters) on the combined size of all loaded context
522    /// files, to keep prefix-cache friendly system prompts from blowing up.
523    /// Set to 0 to disable the project-context layer entirely.
524    #[serde(default = "default_context_max_chars")]
525    pub context_max_chars: usize,
526
527    // --- Per-chat user model (USER.md) ---
528    /// When a turn was triggered by an inbound voice message and this is
529    /// true, the bot's text reply is also rendered to audio via the TTS
530    /// layer and sent back through the same channel. Off by default — opt
531    /// in explicitly because each round trip burns one extra TTS call.
532    /// Has no effect unless `media.tts.enabled` is also true.
533    #[serde(default)]
534    pub voice_round_trip: bool,
535
536    /// Hard cap on USER.md size. Hermes ships a 1375-char limit on its
537    /// equivalent file to force the curator to summarize rather than append.
538    /// Set to 0 to disable the user-model layer entirely; the chat falls
539    /// back to PROFILE memories alone. Curation is folded into the
540    /// reflector LLM call (see scheduler.rs), so there is no per-tick
541    /// amortization knob: the LLM itself returns null when no rewrite is
542    /// warranted.
543    #[serde(default = "default_user_model_max_chars")]
544    pub user_model_max_chars: usize,
545
546    // --- ClawHub ---
547    #[serde(flatten)]
548    pub clawhub: ClawHubConfig,
549
550    // --- Plugins ---
551    #[serde(default)]
552    pub plugins: PluginsConfig,
553
554    // --- Media tools (OpenAI-compatible) ---
555    /// Multimedia tool configuration (image generation / vision / TTS / STT).
556    /// When unset, each tool defaults to `enabled: false`. API key and base URL
557    /// fall back to `openai_api_key` / `openai_base_url`, so users who already
558    /// have their OpenAI credential wired up get zero-config.
559    #[serde(default)]
560    pub media: MediaConfig,
561
562    /// Override for the OpenAI-compatible base URL used by media tools. When
563    /// unset, media tools use `https://api.openai.com/v1`.
564    #[serde(default)]
565    pub openai_base_url: Option<String>,
566
567    // --- Voice / Speech-to-text ---
568    /// Voice transcription provider: "openai" uses OpenAI Whisper API, "local" uses voice_transcription_command
569    #[serde(default = "default_voice_provider", rename = "voice_provider")]
570    pub voice_provider: String,
571    /// Command template for local voice transcription. Use {file} as placeholder for audio file path.
572    /// Example: "whisper-mlx --file {file}" or "/usr/local/bin/whisper {file}"
573    #[serde(default, rename = "voice_transcription_command")]
574    pub voice_transcription_command: Option<String>,
575
576    // --- Observability ---
577    #[serde(default)]
578    pub observability: Option<serde_yaml::Value>,
579
580    // --- Channel registry (new dynamic config) ---
581    /// Per-channel configuration. Keys are channel names (e.g. "telegram", "discord", "slack", "irc", "web").
582    /// Each value is channel-specific config deserialized by the adapter.
583    /// If empty, synthesized from legacy flat fields below in post_deserialize().
584    #[serde(default)]
585    pub channels: HashMap<String, serde_yaml::Value>,
586
587    // --- Legacy channel fields (deprecated, use `channels:` instead) ---
588    #[serde(default = "default_telegram_bot_token")]
589    pub telegram_bot_token: String,
590    #[serde(default = "default_bot_username")]
591    pub bot_username: String,
592    #[serde(default)]
593    pub allowed_groups: Vec<i64>,
594}
595
596pub(crate) fn collect_enabled_channel_endpoints(value: &serde_yaml::Value, out: &mut Vec<String>) {
597    let Some(mapping) = value.as_mapping() else {
598        return;
599    };
600    if mapping
601        .get(serde_yaml::Value::String("enabled".into()))
602        .and_then(serde_yaml::Value::as_bool)
603        == Some(false)
604    {
605        return;
606    }
607
608    for (key, value) in mapping {
609        let Some(key) = key.as_str() else {
610            continue;
611        };
612        let key = key.to_ascii_lowercase();
613        let is_endpoint_key = key.contains("url")
614            || key.contains("endpoint")
615            || key == "homeserver"
616            || key == "homeserver_url";
617        if is_endpoint_key {
618            if let Some(endpoint) = value
619                .as_str()
620                .map(str::trim)
621                .filter(|endpoint| !endpoint.is_empty())
622            {
623                out.push(endpoint.to_string());
624            }
625        }
626        match value {
627            serde_yaml::Value::Mapping(_) => collect_enabled_channel_endpoints(value, out),
628            serde_yaml::Value::Sequence(values) => {
629                for value in values {
630                    collect_enabled_channel_endpoints(value, out);
631                }
632            }
633            _ => {}
634        }
635    }
636}
637
638impl Config {
639    /// Whether `chat_id` is a control chat. An empty `control_chat_ids` list
640    /// means NO chat has control privileges (default deny) — every privileged
641    /// surface (skill management, /learn, /log, ...) must route through this
642    /// so that rule stays in one place.
643    pub fn is_control_chat(&self, chat_id: i64) -> bool {
644        self.control_chat_ids.contains(&chat_id)
645    }
646
647    fn ensure_mapping_mut(value: &mut serde_yaml::Value) -> &mut serde_yaml::Mapping {
648        if !matches!(value, serde_yaml::Value::Mapping(_)) {
649            *value = serde_yaml::Value::Mapping(serde_yaml::Mapping::new());
650        }
651        value
652            .as_mapping_mut()
653            .expect("value should be a mapping after initialization")
654    }
655
656    fn channel_default_account_id(&self, channel: &str) -> Option<String> {
657        let channel_cfg = self.channels.get(channel)?;
658        let mut account_ids: Vec<String> = channel_cfg
659            .get("accounts")
660            .and_then(|v| v.as_mapping())
661            .map(|m| {
662                m.keys()
663                    .filter_map(|k| k.as_str().map(ToOwned::to_owned))
664                    .collect()
665            })
666            .unwrap_or_default();
667        account_ids.sort();
668        channel_cfg
669            .get("default_account")
670            .and_then(|v| v.as_str())
671            .map(str::trim)
672            .filter(|v| !v.is_empty())
673            .map(ToOwned::to_owned)
674            .or_else(|| {
675                if channel_cfg
676                    .get("accounts")
677                    .and_then(|v| v.get("default"))
678                    .is_some()
679                {
680                    Some("default".to_string())
681                } else {
682                    account_ids.first().cloned()
683                }
684            })
685    }
686
687    fn llm_override_target(&self, channel: &str) -> Option<(String, Option<String>)> {
688        let channel = channel.trim();
689        if channel.is_empty() {
690            return None;
691        }
692        if let Some((base_channel, account_id)) = channel.split_once('.') {
693            let base_channel = base_channel.trim();
694            let account_id = account_id.trim();
695            if base_channel.is_empty() || account_id.is_empty() {
696                return None;
697            }
698            return Some((base_channel.to_string(), Some(account_id.to_string())));
699        }
700
701        Some((
702            channel.to_string(),
703            self.channel_default_account_id(channel),
704        ))
705    }
706
707    fn llm_override_mapping_mut(&mut self, channel: &str) -> Option<&mut serde_yaml::Mapping> {
708        let (base_channel, account_id) = self.llm_override_target(channel)?;
709        let channel_value = self
710            .channels
711            .entry(base_channel)
712            .or_insert_with(|| serde_yaml::Value::Mapping(serde_yaml::Mapping::new()));
713        let channel_map = Self::ensure_mapping_mut(channel_value);
714        if let Some(account_id) = account_id {
715            let accounts_key = serde_yaml::Value::String("accounts".to_string());
716            let accounts_value = channel_map
717                .entry(accounts_key)
718                .or_insert_with(|| serde_yaml::Value::Mapping(serde_yaml::Mapping::new()));
719            let accounts_map = Self::ensure_mapping_mut(accounts_value);
720            let account_value = accounts_map
721                .entry(serde_yaml::Value::String(account_id))
722                .or_insert_with(|| serde_yaml::Value::Mapping(serde_yaml::Mapping::new()));
723            return Some(Self::ensure_mapping_mut(account_value));
724        }
725        Some(channel_map)
726    }
727
728    pub fn set_provider_override_for_channel(&mut self, channel: &str, provider: Option<&str>) {
729        let Some(target) = self.llm_override_mapping_mut(channel) else {
730            return;
731        };
732        let provider_preset_key = serde_yaml::Value::String("provider_preset".to_string());
733        let llm_provider_key = serde_yaml::Value::String("llm_provider".to_string());
734        target.remove(&provider_preset_key);
735        target.remove(&llm_provider_key);
736        if let Some(provider) = provider
737            .map(str::trim)
738            .filter(|provider| !provider.is_empty())
739            .map(|provider| provider.to_ascii_lowercase())
740        {
741            target.insert(
742                provider_preset_key,
743                serde_yaml::Value::String(provider.to_string()),
744            );
745        }
746    }
747
748    pub fn set_model_override_for_channel(&mut self, channel: &str, model: Option<&str>) {
749        let Some(target) = self.llm_override_mapping_mut(channel) else {
750            return;
751        };
752        let model_key = serde_yaml::Value::String("model".to_string());
753        target.remove(&model_key);
754        if let Some(model) = model.and_then(normalize_model_name) {
755            target.insert(model_key, serde_yaml::Value::String(model.to_string()));
756        }
757    }
758
759    fn channel_account_bot_username(&self, channel: &str, account_id: &str) -> Option<String> {
760        self.channels
761            .get(channel)
762            .and_then(|v| v.get("accounts"))
763            .and_then(|v| v.get(account_id))
764            .and_then(|v| v.get("bot_username"))
765            .and_then(|v| v.as_str())
766            .map(str::trim)
767            .filter(|v| !v.is_empty())
768            .map(ToOwned::to_owned)
769    }
770
771    fn channel_account_soul_path(&self, channel: &str, account_id: &str) -> Option<String> {
772        self.channels
773            .get(channel)
774            .and_then(|v| v.get("accounts"))
775            .and_then(|v| v.get(account_id))
776            .and_then(|v| v.get("soul_path"))
777            .and_then(|v| v.as_str())
778            .map(str::trim)
779            .filter(|v| !v.is_empty())
780            .map(ToOwned::to_owned)
781    }
782
783    fn provider_override_from_value(value: &serde_yaml::Value) -> Option<String> {
784        value
785            .get("provider_preset")
786            .and_then(|v| v.as_str())
787            .or_else(|| value.get("llm_provider").and_then(|v| v.as_str()))
788            .map(str::trim)
789            .filter(|v| !v.is_empty())
790            .map(|v| v.to_ascii_lowercase())
791    }
792
793    fn channel_account_provider_override(&self, channel: &str, account_id: &str) -> Option<String> {
794        self.channels
795            .get(channel)
796            .and_then(|v| v.get("accounts"))
797            .and_then(|v| v.get(account_id))
798            .and_then(Self::provider_override_from_value)
799    }
800
801    fn model_override_from_value(value: &serde_yaml::Value) -> Option<String> {
802        value
803            .get("model")
804            .and_then(|v| v.as_str())
805            .and_then(normalize_model_name)
806    }
807
808    fn channel_account_model_override(&self, channel: &str, account_id: &str) -> Option<String> {
809        self.channels
810            .get(channel)
811            .and_then(|v| v.get("accounts"))
812            .and_then(|v| v.get(account_id))
813            .and_then(Self::model_override_from_value)
814    }
815
816    pub fn provider_override_for_channel(&self, channel: &str) -> Option<String> {
817        if let Some((base_channel, account_id)) = channel.split_once('.') {
818            if let Some(v) = self.channel_account_provider_override(base_channel, account_id) {
819                return Some(v);
820            }
821            return self
822                .channels
823                .get(base_channel)
824                .and_then(Self::provider_override_from_value);
825        }
826
827        if let Some(default_account) = self.channel_default_account_id(channel) {
828            if let Some(v) = self.channel_account_provider_override(channel, &default_account) {
829                return Some(v);
830            }
831        }
832
833        self.channels
834            .get(channel)
835            .and_then(Self::provider_override_from_value)
836    }
837
838    pub fn model_override_for_channel(&self, channel: &str) -> Option<String> {
839        if let Some((base_channel, account_id)) = channel.split_once('.') {
840            if let Some(v) = self.channel_account_model_override(base_channel, account_id) {
841                return Some(v);
842            }
843            return self
844                .channels
845                .get(base_channel)
846                .and_then(Self::model_override_from_value);
847        }
848
849        if let Some(default_account) = self.channel_default_account_id(channel) {
850            if let Some(v) = self.channel_account_model_override(channel, &default_account) {
851                return Some(v);
852            }
853        }
854
855        self.channels
856            .get(channel)
857            .and_then(Self::model_override_from_value)
858    }
859
860    pub fn soul_path_for_channel(&self, channel: &str) -> Option<String> {
861        let channel_override = self
862            .channels
863            .get(channel)
864            .and_then(|v| v.get("soul_path"))
865            .and_then(|v| v.as_str())
866            .map(str::trim)
867            .filter(|v| !v.is_empty())
868            .map(ToOwned::to_owned);
869        if channel_override.is_some() {
870            return channel_override;
871        }
872
873        if let Some((base_channel, account_id)) = channel.split_once('.') {
874            if let Some(v) = self.channel_account_soul_path(base_channel, account_id) {
875                return Some(v);
876            }
877            return self
878                .channels
879                .get(base_channel)
880                .and_then(|v| v.get("soul_path"))
881                .and_then(|v| v.as_str())
882                .map(str::trim)
883                .filter(|v| !v.is_empty())
884                .map(ToOwned::to_owned);
885        }
886
887        if let Some(default_account) = self.channel_default_account_id(channel) {
888            if let Some(v) = self.channel_account_soul_path(channel, &default_account) {
889                return Some(v);
890            }
891        }
892
893        self.channels
894            .get(channel)
895            .and_then(|v| v.get("soul_path"))
896            .and_then(|v| v.as_str())
897            .map(str::trim)
898            .filter(|v| !v.is_empty())
899            .map(ToOwned::to_owned)
900    }
901
902    pub fn bot_username_for_channel(&self, channel: &str) -> String {
903        let channel_override = self
904            .channels
905            .get(channel)
906            .and_then(|v| v.get("bot_username"))
907            .and_then(|v| v.as_str())
908            .map(str::trim)
909            .filter(|v| !v.is_empty());
910        if let Some(v) = channel_override {
911            return v.to_string();
912        }
913
914        if let Some((base_channel, account_id)) = channel.split_once('.') {
915            if let Some(v) = self.channel_account_bot_username(base_channel, account_id) {
916                return v;
917            }
918        } else if let Some(default_account) = self.channel_default_account_id(channel) {
919            if let Some(v) = self.channel_account_bot_username(channel, &default_account) {
920                return v;
921            }
922        }
923
924        let global = self.bot_username.trim();
925        if !global.is_empty() {
926            global.to_string()
927        } else {
928            default_bot_username()
929        }
930    }
931
932    pub fn bot_username_overrides(&self) -> HashMap<String, String> {
933        let mut overrides: HashMap<String, String> = self
934            .channels
935            .iter()
936            .filter_map(|(channel, cfg)| {
937                cfg.get("bot_username")
938                    .and_then(|v| v.as_str())
939                    .map(str::trim)
940                    .filter(|v| !v.is_empty())
941                    .map(|v| (channel.clone(), v.to_string()))
942            })
943            .collect();
944
945        for (channel, channel_cfg) in &self.channels {
946            let accounts = channel_cfg.get("accounts").and_then(|v| v.as_mapping());
947            let Some(accounts) = accounts else {
948                continue;
949            };
950            let default_account = self.channel_default_account_id(channel);
951            for (key, value) in accounts {
952                let Some(account_id) = key.as_str() else {
953                    continue;
954                };
955                let username = value
956                    .get("bot_username")
957                    .and_then(|v| v.as_str())
958                    .map(str::trim)
959                    .filter(|v| !v.is_empty());
960                let Some(username) = username else {
961                    continue;
962                };
963                if default_account
964                    .as_deref()
965                    .map(|v| v == account_id)
966                    .unwrap_or(false)
967                {
968                    overrides.insert(channel.clone(), username.to_string());
969                } else {
970                    overrides.insert(format!("{channel}.{account_id}"), username.to_string());
971                }
972            }
973        }
974
975        overrides
976    }
977
978    pub fn llm_provider_overrides(&self) -> HashMap<String, String> {
979        let mut overrides: HashMap<String, String> = self
980            .channels
981            .iter()
982            .filter_map(|(channel, cfg)| {
983                Self::provider_override_from_value(cfg).map(|provider| (channel.clone(), provider))
984            })
985            .collect();
986
987        for (channel, channel_cfg) in &self.channels {
988            let accounts = channel_cfg.get("accounts").and_then(|v| v.as_mapping());
989            let Some(accounts) = accounts else {
990                continue;
991            };
992            let default_account = self.channel_default_account_id(channel);
993            for (key, value) in accounts {
994                let Some(account_id) = key.as_str() else {
995                    continue;
996                };
997                let Some(provider) = Self::provider_override_from_value(value) else {
998                    continue;
999                };
1000                if default_account
1001                    .as_deref()
1002                    .map(|v| v == account_id)
1003                    .unwrap_or(false)
1004                {
1005                    overrides.insert(channel.clone(), provider);
1006                } else {
1007                    overrides.insert(format!("{channel}.{account_id}"), provider);
1008                }
1009            }
1010        }
1011
1012        overrides
1013    }
1014
1015    #[cfg(any(test, feature = "test-support"))]
1016    pub fn test_defaults() -> Self {
1017        Self {
1018            telegram_bot_token: "tok".into(),
1019            bot_username: "bot".into(),
1020            llm_provider: "anthropic".into(),
1021            api_key: "key".into(),
1022            api_keys: Vec::new(),
1023            model: "claude-sonnet-4-5-20250929".into(),
1024            provider_presets: HashMap::new(),
1025            llm_providers: HashMap::new(),
1026            llm_base_url: None,
1027            llm_user_agent: default_llm_user_agent(),
1028            max_tokens: 8192,
1029            max_tool_iterations: 100,
1030            compaction_timeout_secs: 180,
1031            aux_models: AuxModels::default(),
1032            fallback_model: None,
1033            max_history_messages: 50,
1034            max_document_size_mb: 100,
1035            memory_token_budget: 1500,
1036            memory_l0_identity_pct: 20,
1037            memory_l1_essential_pct: 30,
1038            memory_max_entries_per_chat: 200,
1039            memory_max_global_entries: 500,
1040            kg_max_triples_per_chat: 1000,
1041            tool_result_truncation_threshold_chars: 4000,
1042            tool_result_truncation_head_chars: 1500,
1043            tool_result_truncation_tail_chars: 500,
1044            tool_result_artifact_ttl_hours: 24,
1045            memory_recency_half_life_days: 30.0,
1046            memory_graph_recall_enabled: true,
1047            memory_graph_max_hops: 2,
1048            memory_graph_max_triples: 10,
1049            tool_repeat_window: 10,
1050            tool_repeat_limit: 3,
1051            anthropic_prompt_cache_enabled: true,
1052            anthropic_context_editing: false,
1053            anthropic_prompt_cache_ttl: "5m".into(),
1054            checkpoints_enabled: false,
1055            skill_archive_after_days: 30,
1056            skills_catalog_top_k: 3,
1057            system_prompt_time_detail: SystemPromptTimeDetail::default(),
1058            data_dir: default_data_dir(),
1059            skills_dir: None,
1060            working_dir: default_working_dir(),
1061            working_dir_isolation: WorkingDirIsolation::Chat,
1062            high_risk_tool_user_confirmation_required: true,
1063            approval_channels: default_approval_channels(),
1064            read_only_subagent_channels: default_read_only_subagent_channels(),
1065            bash_dangerous_patterns: default_bash_dangerous_patterns(),
1066            rtk: RtkConfig::default(),
1067            sandbox: SandboxConfig::default(),
1068            openai_api_key: None,
1069            override_timezone: None,
1070            timezone: "UTC".into(),
1071            allowed_groups: vec![],
1072            control_chat_ids: vec![],
1073            max_session_messages: 40,
1074            diff_max_lines: default_diff_max_lines(),
1075            file_diffs_in_chat: default_file_diffs_in_chat(),
1076            allow_governance_file_writes: false,
1077            model_context_window: default_model_context_window(),
1078            context_pressure_compact_pct: default_context_pressure_compact_pct(),
1079            model_context_windows: HashMap::new(),
1080            auto_compact: true,
1081            prune_protect_tokens: default_prune_protect_tokens(),
1082            prune_minimum_tokens: default_prune_minimum_tokens(),
1083            compact_keep_recent_tokens: 0,
1084            compact_instructions: None,
1085            project_agents_dir: None,
1086            tool_gate: Default::default(),
1087            context_tools: false,
1088            context_budget_hint: false,
1089            explore_tool: false,
1090            self_recheck: SelfRecheckConfig::default(),
1091            compact_keep_recent: 20,
1092            default_tool_timeout_secs: default_tool_timeout_secs(),
1093            tool_timeout_overrides: HashMap::new(),
1094            default_mcp_request_timeout_secs: default_mcp_request_timeout_secs(),
1095            discord_bot_token: None,
1096            discord_allowed_channels: vec![],
1097            discord_no_mention: false,
1098            allow_group_slash_without_mention: false,
1099            show_thinking: false,
1100            subagents: SubagentConfig::default(),
1101            idle_checkin: IdleCheckinConfig::default(),
1102            heartbeat: HeartbeatConfig::default(),
1103            token_budget: TokenBudgetConfig::default(),
1104            alerts: AlertsConfig::default(),
1105            trust_report: TrustReportConfig::default(),
1106            user_message_language: UserMessageLanguage::default(),
1107            sleep_time: SleepTimeConfig::default(),
1108            interjection: InterjectionConfig::default(),
1109            a2a: A2AConfig::default(),
1110            openai_compat_body_overrides: HashMap::new(),
1111            openai_compat_body_overrides_by_provider: HashMap::new(),
1112            openai_compat_body_overrides_by_model: HashMap::new(),
1113            web_enabled: true,
1114            web_host: "127.0.0.1".into(),
1115            web_port: 10961,
1116            web_max_inflight_per_session: 10,
1117            web_max_requests_per_window: 8,
1118            web_rate_window_seconds: 10,
1119            web_run_history_limit: 512,
1120            web_session_idle_ttl_seconds: 300,
1121            web_fetch_validation: WebContentValidationConfig::default(),
1122            web_fetch_url_validation: WebFetchUrlValidationConfig::default(),
1123            web_search: SearchProviderConfig::default(),
1124            output_guardrail: OutputGuardrailConfig::default(),
1125            tool_policy: crate::tool_guardrails::ToolPolicyConfig::default(),
1126            egress_policy: EgressPolicyConfig::default(),
1127            model_prices: vec![],
1128            embedding_provider: None,
1129            embedding_api_key: None,
1130            embedding_base_url: None,
1131            embedding_model: None,
1132            embedding_dim: None,
1133            reflector_enabled: true,
1134            reflector_interval_mins: 15,
1135            dlq_replay_enabled: true,
1136            dlq_replay_interval_secs: 300,
1137            dlq_max_replay_attempts: 3,
1138            skill_review_min_tool_calls: 5,
1139            soul_path: None,
1140            souls_dir: None,
1141            context_dir: None,
1142            context_max_chars: 8000,
1143            user_model_max_chars: 1500,
1144            voice_round_trip: false,
1145            clawhub: ClawHubConfig::default(),
1146            plugins: PluginsConfig::default(),
1147            media: MediaConfig::default(),
1148            openai_base_url: None,
1149            voice_provider: "openai".into(),
1150            voice_transcription_command: None,
1151            observability: None,
1152            channels: HashMap::new(),
1153            chat_turn_queue_max_pending: 20,
1154            enable_mid_turn_injection: true,
1155            mid_turn_injection_echo: true,
1156            parallel_tool_max_concurrency: 8,
1157            tool_concurrency_overrides: HashMap::new(),
1158        }
1159    }
1160
1161    /// Data root directory from config.
1162    pub fn data_root_dir(&self) -> PathBuf {
1163        expand_path(&self.data_dir)
1164    }
1165
1166    /// Runtime data directory (db, memory, exports, etc.).
1167    pub fn runtime_data_dir(&self) -> String {
1168        let root = self.data_root_dir();
1169        // Avoid nested runtime/runtime if data_dir is already runtime
1170        if root.file_name().and_then(|n| n.to_str()) == Some("runtime") {
1171            return root.to_string_lossy().to_string();
1172        }
1173        root.join("runtime").to_string_lossy().to_string()
1174    }
1175
1176    /// Skills directory. Priority: MICROCLAW_SKILLS_DIR env var > skills_dir config > <data_dir>/skills
1177    pub fn skills_data_dir(&self) -> String {
1178        // 1. Check env var first
1179        if let Ok(explicit_dir) = std::env::var("MICROCLAW_SKILLS_DIR") {
1180            let trimmed = explicit_dir.trim();
1181            if !trimmed.is_empty() {
1182                return expand_path(trimmed).to_string_lossy().to_string();
1183            }
1184        }
1185        // 2. Check config file
1186        if let Some(configured) = &self.skills_dir {
1187            let trimmed = configured.trim();
1188            if !trimmed.is_empty() {
1189                return expand_path(trimmed).to_string_lossy().to_string();
1190            }
1191        }
1192        // 3. Default to <data_dir>/skills
1193        self.data_root_dir()
1194            .join("skills")
1195            .to_string_lossy()
1196            .to_string()
1197    }
1198
1199    /// Souls directory. Priority: souls_dir config > <data_dir>/souls
1200    pub fn souls_data_dir(&self) -> String {
1201        if let Some(configured) = &self.souls_dir {
1202            let trimmed = configured.trim();
1203            if !trimmed.is_empty() {
1204                return expand_path(trimmed).to_string_lossy().to_string();
1205            }
1206        }
1207        self.data_root_dir()
1208            .join("souls")
1209            .to_string_lossy()
1210            .to_string()
1211    }
1212
1213    pub fn clawhub_lockfile_path(&self) -> PathBuf {
1214        self.data_root_dir().join("clawhub.lock.json")
1215    }
1216
1217    /// Lockfile path plus block flag for load-time skill verification,
1218    /// or `None` when `clawhub_verify_on_load: off`.
1219    pub fn clawhub_load_verification(&self) -> Option<(PathBuf, bool)> {
1220        match self.clawhub.verify_on_load {
1221            ClawHubVerifyMode::Off => None,
1222            ClawHubVerifyMode::Warn => Some((self.clawhub_lockfile_path(), false)),
1223            ClawHubVerifyMode::Block => Some((self.clawhub_lockfile_path(), true)),
1224        }
1225    }
1226
1227    pub fn config_path_for_setup() -> PathBuf {
1228        if let Ok(custom) = std::env::var("MICROCLAW_CONFIG") {
1229            return expand_path(&custom);
1230        }
1231        if std::path::Path::new("./microclaw.config.yaml").exists() {
1232            return PathBuf::from("./microclaw.config.yaml");
1233        }
1234        if std::path::Path::new("./microclaw.config.yml").exists() {
1235            return PathBuf::from("./microclaw.config.yml");
1236        }
1237        if std::env::var("SNAP").is_ok() {
1238            if let Ok(snap_user_common) = std::env::var("SNAP_USER_COMMON") {
1239                return PathBuf::from(snap_user_common).join("config.yaml");
1240            }
1241        }
1242        PathBuf::from("microclaw.config.yaml")
1243    }
1244
1245    pub fn resolve_config_path() -> Result<Option<PathBuf>, MicroClawError> {
1246        // 1. Check MICROCLAW_CONFIG env var for custom path
1247        if let Ok(custom) = std::env::var("MICROCLAW_CONFIG") {
1248            let expanded = expand_path(&custom);
1249            if expanded.exists() {
1250                return Ok(Some(expanded));
1251            }
1252            return Err(MicroClawError::Config(format!(
1253                "MICROCLAW_CONFIG points to non-existent file: {custom}"
1254            )));
1255        }
1256
1257        if std::path::Path::new("./microclaw.config.yaml").exists() {
1258            return Ok(Some(PathBuf::from("./microclaw.config.yaml")));
1259        }
1260        if std::path::Path::new("./microclaw.config.yml").exists() {
1261            return Ok(Some(PathBuf::from("./microclaw.config.yml")));
1262        }
1263        Ok(None)
1264    }
1265
1266    fn inferred_channel_enabled(&self, channel: &str) -> bool {
1267        match channel {
1268            "telegram" => {
1269                !self.telegram_bot_token.trim().is_empty() || self.channels.contains_key("telegram")
1270            }
1271            "discord" => {
1272                self.discord_bot_token
1273                    .as_deref()
1274                    .map(|v| !v.trim().is_empty())
1275                    .unwrap_or(false)
1276                    || self.channels.contains_key("discord")
1277            }
1278            "web" => self.web_enabled || self.channels.contains_key("web"),
1279            _ => self.channels.contains_key(channel),
1280        }
1281    }
1282
1283    fn explicit_channel_enabled(&self, channel: &str) -> Option<bool> {
1284        self.channels
1285            .get(channel)
1286            .and_then(|v| v.get("enabled"))
1287            .and_then(|v| v.as_bool())
1288    }
1289
1290    pub fn channel_enabled(&self, channel: &str) -> bool {
1291        let needle = channel.trim().to_lowercase();
1292        if let Some(explicit) = self.explicit_channel_enabled(&needle) {
1293            return explicit;
1294        }
1295        self.inferred_channel_enabled(&needle)
1296    }
1297
1298    /// Classify every known channel into `(enabled, configured_but_disabled)`.
1299    /// A channel is "configured" when it has credentials/config present (a
1300    /// `channels.<name>` block or a legacy top-level token); it is "enabled"
1301    /// per [`channel_enabled`]. Used both for the no-channel config error and
1302    /// for `microclaw doctor`, so the two stay consistent.
1303    pub fn channel_status(&self) -> (Vec<&'static str>, Vec<&'static str>) {
1304        let configured = [
1305            (
1306                "telegram",
1307                !self.telegram_bot_token.trim().is_empty()
1308                    || self.channels.contains_key("telegram"),
1309            ),
1310            (
1311                "discord",
1312                self.discord_bot_token
1313                    .as_deref()
1314                    .map(|v| !v.trim().is_empty())
1315                    .unwrap_or(false)
1316                    || self.channels.contains_key("discord"),
1317            ),
1318            ("slack", self.channels.contains_key("slack")),
1319            ("feishu", self.channels.contains_key("feishu")),
1320            ("matrix", self.channels.contains_key("matrix")),
1321            ("irc", self.channels.contains_key("irc")),
1322            ("web", self.web_enabled || self.channels.contains_key("web")),
1323        ];
1324        let mut enabled = Vec::new();
1325        let mut configured_but_disabled = Vec::new();
1326        for (name, is_configured) in configured {
1327            if !is_configured {
1328                continue;
1329            }
1330            if self.channel_enabled(name) {
1331                enabled.push(name);
1332            } else {
1333                configured_but_disabled.push(name);
1334            }
1335        }
1336        (enabled, configured_but_disabled)
1337    }
1338
1339    /// Load config from YAML file.
1340    pub fn load() -> Result<Self, MicroClawError> {
1341        let yaml_path = Self::resolve_config_path()?;
1342
1343        if let Some(path) = yaml_path {
1344            return Self::load_from_path(&path);
1345        }
1346
1347        // No config file found at all
1348        Err(MicroClawError::Config(
1349            "No microclaw.config.yaml found. Run `microclaw setup` to create one.".into(),
1350        ))
1351    }
1352
1353    /// Load and validate a specific YAML configuration file.
1354    pub fn load_from_path(path: &Path) -> Result<Self, MicroClawError> {
1355        Self::load_from_path_inner(path, false)
1356    }
1357
1358    /// Load a specific configuration for a channel-free foreground runtime.
1359    ///
1360    /// All provider, tool, path, and security validation is retained. Only the
1361    /// Server requirement that at least one delivery channel be enabled is
1362    /// waived, because MicroClaw Code and other headless callers deliver results through
1363    /// their own application boundary.
1364    pub fn load_from_path_for_headless(path: &Path) -> Result<Self, MicroClawError> {
1365        Self::load_from_path_inner(path, true)
1366    }
1367
1368    /// Build and validate a channel-free configuration for an embedded caller.
1369    pub fn for_embedded(
1370        provider: impl Into<String>,
1371        model: impl Into<String>,
1372        api_key: impl Into<String>,
1373        base_url: Option<String>,
1374    ) -> Result<Self, MicroClawError> {
1375        let mut config: Config = serde_yaml::from_str("{}")
1376            .map_err(|error| MicroClawError::Config(error.to_string()))?;
1377        config.llm_provider = provider.into();
1378        config.model = model.into();
1379        config.api_key = api_key.into();
1380        config.llm_base_url = base_url;
1381        config.web_enabled = true;
1382        config.post_deserialize()?;
1383        config.web_enabled = false;
1384        config.channels.remove("web");
1385        Ok(config)
1386    }
1387
1388    fn load_from_path_inner(path: &Path, allow_no_channels: bool) -> Result<Self, MicroClawError> {
1389        let path_str = path.to_string_lossy().to_string();
1390        let content = std::fs::read_to_string(path)
1391            .map_err(|e| MicroClawError::Config(format!("Failed to read {path_str}: {e}")))?;
1392        if let Ok(raw) = serde_yaml::from_str::<serde_yaml::Value>(&content) {
1393            if let Some(map) = raw.as_mapping() {
1394                let old_top_level = map
1395                    .get(serde_yaml::Value::String("web_auth_token".to_string()))
1396                    .is_some();
1397                let old_channel_level = map
1398                    .get(serde_yaml::Value::String("channels".to_string()))
1399                    .and_then(|v| v.as_mapping())
1400                    .and_then(|channels| channels.get(serde_yaml::Value::String("web".to_string())))
1401                    .and_then(|v| v.as_mapping())
1402                    .map(|web| {
1403                        web.contains_key(serde_yaml::Value::String("auth_token".to_string()))
1404                    })
1405                    .unwrap_or(false);
1406                if old_top_level || old_channel_level {
1407                    warn!(
1408                        "Deprecated web auth token config detected in {}. \
1409`web_auth_token` / `channels.web.auth_token` are ignored; migrate to operator password + API keys.",
1410                        path_str
1411                    );
1412                }
1413                for warning in unknown_top_level_key_warnings(map) {
1414                    warn!("{warning} (in {path_str})");
1415                }
1416            }
1417        }
1418        let mut config: Config = serde_yaml::from_str(&content)
1419            .map_err(|error| MicroClawError::Config(friendly_yaml_error(&path_str, &error)))?;
1420        let synthesized_channel = allow_no_channels && config.channel_status().0.is_empty();
1421        if synthesized_channel {
1422            config.web_enabled = true;
1423        }
1424        config.post_deserialize()?;
1425        if crate::tool_guardrails::global_policy_has_no_rules(&config.tool_policy) {
1426            tracing::warn!(
1427                "tool_policy.mode is on but allow_tools, deny_tools and max_risk are all empty: \
1428                 every tool is still permitted. Add an allowlist, a deny list or a max_risk ceiling."
1429            );
1430        }
1431        if synthesized_channel {
1432            config.web_enabled = false;
1433            config.channels.remove("web");
1434        }
1435        Ok(config)
1436    }
1437
1438    /// Apply post-deserialization normalization and validation.
1439    pub fn post_deserialize(&mut self) -> Result<(), MicroClawError> {
1440        self.llm_provider = self.llm_provider.trim().to_lowercase();
1441
1442        self.model = resolve_model_name_with_fallback(&self.llm_provider, Some(&self.model), None);
1443        self.provider_presets =
1444            normalize_provider_profiles(std::mem::take(&mut self.provider_presets));
1445        self.llm_providers = normalize_provider_profiles(std::mem::take(&mut self.llm_providers));
1446        for (alias, preset) in self.provider_presets.clone() {
1447            self.llm_providers
1448                .entry(alias)
1449                .and_modify(|existing| {
1450                    *existing = merge_provider_profile(preset.clone(), existing.clone());
1451                })
1452                .or_insert(preset);
1453        }
1454        for channel_cfg in self.channels.values_mut() {
1455            migrate_model_override_alias_to_provider_preset(channel_cfg, &self.provider_presets);
1456        }
1457
1458        self.override_timezone = self
1459            .override_timezone
1460            .as_ref()
1461            .map(|v| v.trim().to_string())
1462            .filter(|v| !v.is_empty());
1463        if self
1464            .override_timezone
1465            .as_deref()
1466            .is_some_and(|v| v.eq_ignore_ascii_case("auto"))
1467        {
1468            self.override_timezone = None;
1469        }
1470
1471        // Normalize and validate timezone.
1472        // Priority: override_timezone > system auto-detect.
1473        let tz_raw = self
1474            .override_timezone
1475            .clone()
1476            .unwrap_or_else(|| "auto".to_string());
1477
1478        if tz_raw.eq_ignore_ascii_case("auto") {
1479            let detected = detect_system_timezone();
1480            if detected.parse::<chrono_tz::Tz>().is_ok() {
1481                self.timezone = detected;
1482            } else {
1483                warn!(
1484                    "Detected system timezone '{}' is not recognized by chrono-tz. Falling back to UTC.",
1485                    detected
1486                );
1487                self.timezone = "UTC".into();
1488            }
1489        } else {
1490            tz_raw
1491                .parse::<chrono_tz::Tz>()
1492                .map_err(|_| MicroClawError::Config(format!("Invalid timezone: {tz_raw}")))?;
1493            self.timezone = tz_raw;
1494        }
1495
1496        // Filter empty llm_base_url
1497        if let Some(ref url) = self.llm_base_url {
1498            if url.trim().is_empty() {
1499                self.llm_base_url = None;
1500            }
1501        }
1502        self.llm_user_agent = self.llm_user_agent.trim().to_string();
1503        if self.llm_user_agent.is_empty() {
1504            self.llm_user_agent = default_llm_user_agent();
1505        }
1506        if let Some(dir) = &self.skills_dir {
1507            let trimmed = dir.trim().to_string();
1508            self.skills_dir = if trimmed.is_empty() {
1509                None
1510            } else {
1511                Some(expand_path(&trimmed).to_string_lossy().to_string())
1512            };
1513        }
1514        if let Some(dir) = &self.souls_dir {
1515            let trimmed = dir.trim().to_string();
1516            self.souls_dir = if trimmed.is_empty() {
1517                None
1518            } else {
1519                Some(expand_path(&trimmed).to_string_lossy().to_string())
1520            };
1521        }
1522        if let Some(dir) = &self.plugins.dir {
1523            let trimmed = dir.trim().to_string();
1524            self.plugins.dir = if trimmed.is_empty() {
1525                None
1526            } else {
1527                Some(expand_path(&trimmed).to_string_lossy().to_string())
1528            };
1529        }
1530        if self.working_dir.trim().is_empty() {
1531            self.working_dir = default_working_dir();
1532        } else {
1533            self.working_dir = expand_path(&self.working_dir).to_string_lossy().to_string();
1534        }
1535        self.data_dir = expand_path(&self.data_dir).to_string_lossy().to_string();
1536        self.sandbox.image = self.sandbox.image.trim().to_string();
1537        if self.sandbox.image.is_empty() {
1538            self.sandbox.image = default_sandbox_image();
1539        }
1540        self.sandbox.container_prefix = self.sandbox.container_prefix.trim().to_string();
1541        if self.sandbox.container_prefix.is_empty() {
1542            self.sandbox.container_prefix = default_sandbox_container_prefix();
1543        }
1544        normalize_string_list(&mut self.sandbox.credential_env_allowlist, false);
1545        normalize_string_list(&mut self.egress_policy.allow_hosts, true);
1546        normalize_string_list(&mut self.egress_policy.deny_hosts, true);
1547        normalize_string_list(&mut self.tool_policy.allow_tools, false);
1548        normalize_string_list(&mut self.tool_policy.deny_tools, false);
1549        for grant in &mut self.tool_policy.grants {
1550            grant.channel = grant
1551                .channel
1552                .take()
1553                .map(|value| value.trim().to_ascii_lowercase())
1554                .filter(|value| !value.is_empty());
1555            grant.principal = grant
1556                .principal
1557                .take()
1558                .map(|value| value.trim().to_ascii_lowercase())
1559                .filter(|value| !value.is_empty());
1560            normalize_string_list(&mut grant.allow_tools, false);
1561            normalize_string_list(&mut grant.deny_tools, false);
1562        }
1563        if self.web_host.trim().is_empty() {
1564            self.web_host = default_web_host();
1565        }
1566        self.a2a.public_base_url = self
1567            .a2a
1568            .public_base_url
1569            .as_ref()
1570            .map(|v| v.trim().trim_end_matches('/').to_string())
1571            .filter(|v| !v.is_empty());
1572        self.a2a.agent_name = self
1573            .a2a
1574            .agent_name
1575            .as_ref()
1576            .map(|v| v.trim().to_string())
1577            .filter(|v| !v.is_empty());
1578        self.a2a.agent_description = self
1579            .a2a
1580            .agent_description
1581            .as_ref()
1582            .map(|v| v.trim().to_string())
1583            .filter(|v| !v.is_empty());
1584        self.a2a.shared_tokens = self
1585            .a2a
1586            .shared_tokens
1587            .drain(..)
1588            .map(|v| v.trim().to_string())
1589            .filter(|v| !v.is_empty())
1590            .collect();
1591        self.a2a.peers = self
1592            .a2a
1593            .peers
1594            .drain()
1595            .filter_map(|(name, mut peer)| {
1596                let normalized = name.trim().to_ascii_lowercase();
1597                if normalized.is_empty() {
1598                    return None;
1599                }
1600                peer.base_url = peer.base_url.trim().trim_end_matches('/').to_string();
1601                if peer.base_url.is_empty() {
1602                    return None;
1603                }
1604                peer.bearer_token = peer
1605                    .bearer_token
1606                    .as_ref()
1607                    .map(|v| v.trim().to_string())
1608                    .filter(|v| !v.is_empty());
1609                peer.description = peer
1610                    .description
1611                    .as_ref()
1612                    .map(|v| v.trim().to_string())
1613                    .filter(|v| !v.is_empty());
1614                peer.default_session_key = peer
1615                    .default_session_key
1616                    .as_ref()
1617                    .map(|v| v.trim().to_string())
1618                    .filter(|v| !v.is_empty());
1619                Some((normalized, peer))
1620            })
1621            .collect();
1622        if let Some(provider) = &self.embedding_provider {
1623            let p = provider.trim().to_lowercase();
1624            self.embedding_provider = if p.is_empty() { None } else { Some(p) };
1625        }
1626        if let Some(v) = &self.embedding_api_key {
1627            if v.trim().is_empty() {
1628                self.embedding_api_key = None;
1629            }
1630        }
1631        if let Some(v) = &self.embedding_base_url {
1632            if v.trim().is_empty() {
1633                self.embedding_base_url = None;
1634            }
1635        }
1636        if let Some(v) = &self.embedding_model {
1637            let m = v.trim().to_string();
1638            self.embedding_model = if m.is_empty() { None } else { Some(m) };
1639        }
1640        if let Some(v) = self.embedding_dim {
1641            if v == 0 {
1642                self.embedding_dim = None;
1643            }
1644        }
1645        if let Some(web_cfg) = self
1646            .channels
1647            .get_mut("web")
1648            .and_then(|v| v.as_mapping_mut())
1649        {
1650            if web_cfg
1651                .remove(serde_yaml::Value::String("auth_token".to_string()))
1652                .is_some()
1653            {
1654                warn!(
1655                    "Deprecated `channels.web.auth_token` detected and ignored. \
1656Use operator password + API keys for Web auth."
1657                );
1658            }
1659        }
1660        if self.web_max_inflight_per_session == 0 {
1661            self.web_max_inflight_per_session = default_web_max_inflight_per_session();
1662        }
1663        if self.web_max_requests_per_window == 0 {
1664            self.web_max_requests_per_window = default_web_max_requests_per_window();
1665        }
1666        if self.web_rate_window_seconds == 0 {
1667            self.web_rate_window_seconds = default_web_rate_window_seconds();
1668        }
1669        if self.web_run_history_limit == 0 {
1670            self.web_run_history_limit = default_web_run_history_limit();
1671        }
1672        if self.web_session_idle_ttl_seconds == 0 {
1673            self.web_session_idle_ttl_seconds = default_web_session_idle_ttl_seconds();
1674        }
1675        self.web_fetch_validation.normalize();
1676        self.web_fetch_url_validation.normalize();
1677        self.web_search.normalize();
1678        if self.max_document_size_mb == 0 {
1679            self.max_document_size_mb = default_max_document_size_mb();
1680        }
1681        if self.default_tool_timeout_secs == 0 {
1682            self.default_tool_timeout_secs = default_tool_timeout_secs();
1683        }
1684        if self.default_mcp_request_timeout_secs == 0 {
1685            self.default_mcp_request_timeout_secs = default_mcp_request_timeout_secs();
1686        }
1687        if self.subagents.max_concurrent == 0 {
1688            self.subagents.max_concurrent = default_subagent_max_concurrent();
1689        }
1690        if self.subagents.max_active_per_chat == 0 {
1691            self.subagents.max_active_per_chat = default_subagent_max_active_per_chat();
1692        }
1693        if self.subagents.run_timeout_secs == 0 {
1694            self.subagents.run_timeout_secs = default_subagent_run_timeout_secs();
1695        }
1696        if self.subagents.max_spawn_depth == 0 {
1697            self.subagents.max_spawn_depth = default_subagent_max_spawn_depth();
1698        }
1699        self.subagents.max_spawn_depth = self.subagents.max_spawn_depth.min(5);
1700        if self.subagents.max_children_per_run == 0 {
1701            self.subagents.max_children_per_run = default_subagent_max_children_per_run();
1702        }
1703        if self.subagents.announce_relay_interval_secs == 0 {
1704            self.subagents.announce_relay_interval_secs =
1705                default_subagent_announce_relay_interval_secs();
1706        }
1707        self.subagents.announce_relay_interval_secs =
1708            self.subagents.announce_relay_interval_secs.clamp(1, 300);
1709        if self.subagents.max_tokens_per_run <= 0 {
1710            self.subagents.max_tokens_per_run = default_subagent_max_tokens_per_run();
1711        }
1712        self.subagents.max_tokens_per_run =
1713            self.subagents.max_tokens_per_run.clamp(2_000, 2_000_000);
1714        if self.subagents.orchestrate_max_workers == 0 {
1715            self.subagents.orchestrate_max_workers = default_subagent_orchestrate_max_workers();
1716        }
1717        self.subagents.orchestrate_max_workers =
1718            self.subagents.orchestrate_max_workers.clamp(1, 12);
1719        self.subagents.acp.normalize();
1720        self.tool_timeout_overrides = self
1721            .tool_timeout_overrides
1722            .drain()
1723            .filter_map(|(name, timeout_secs)| {
1724                let normalized = name.trim().to_ascii_lowercase();
1725                if normalized.is_empty() || timeout_secs == 0 {
1726                    None
1727                } else {
1728                    Some((normalized, timeout_secs))
1729                }
1730            })
1731            .collect();
1732        self.openai_compat_body_overrides =
1733            normalize_body_override_params(std::mem::take(&mut self.openai_compat_body_overrides));
1734        self.openai_compat_body_overrides_by_provider = self
1735            .openai_compat_body_overrides_by_provider
1736            .drain()
1737            .filter_map(|(provider, params)| {
1738                let provider = provider.trim().to_ascii_lowercase();
1739                if provider.is_empty() {
1740                    return None;
1741                }
1742                let params = normalize_body_override_params(params);
1743                if params.is_empty() {
1744                    None
1745                } else {
1746                    Some((provider, params))
1747                }
1748            })
1749            .collect();
1750        self.openai_compat_body_overrides_by_model = self
1751            .openai_compat_body_overrides_by_model
1752            .drain()
1753            .filter_map(|(model, params)| {
1754                let model = model.trim().to_string();
1755                if model.is_empty() {
1756                    return None;
1757                }
1758                let params = normalize_body_override_params(params);
1759                if params.is_empty() {
1760                    None
1761                } else {
1762                    Some((model, params))
1763                }
1764            })
1765            .collect();
1766        if self.memory_token_budget == 0 {
1767            self.memory_token_budget = default_memory_token_budget();
1768        }
1769        for price in &mut self.model_prices {
1770            price.model = price.model.trim().to_string();
1771            if price.model.is_empty() {
1772                return Err(MicroClawError::Config(
1773                    "model_prices entries must include non-empty model".into(),
1774                ));
1775            }
1776            if !(price.input_per_million_usd.is_finite() && price.input_per_million_usd >= 0.0) {
1777                return Err(MicroClawError::Config(format!(
1778                    "model_prices[{}].input_per_million_usd must be >= 0",
1779                    price.model
1780                )));
1781            }
1782            if !(price.output_per_million_usd.is_finite() && price.output_per_million_usd >= 0.0) {
1783                return Err(MicroClawError::Config(format!(
1784                    "model_prices[{}].output_per_million_usd must be >= 0",
1785                    price.model
1786                )));
1787            }
1788        }
1789
1790        // Synthesize `channels` map from legacy flat fields if empty
1791        if self.channels.is_empty() {
1792            if !self.telegram_bot_token.trim().is_empty() {
1793                self.channels.insert(
1794                    "telegram".into(),
1795                    serde_yaml::to_value(serde_json::json!({
1796                        "enabled": true,
1797                        "bot_token": self.telegram_bot_token,
1798                        "bot_username": self.bot_username,
1799                        "allowed_groups": self.allowed_groups,
1800                    }))
1801                    .unwrap(),
1802                );
1803            }
1804            if let Some(ref token) = self.discord_bot_token {
1805                if !token.trim().is_empty() {
1806                    self.channels.insert(
1807                        "discord".into(),
1808                        serde_yaml::to_value(serde_json::json!({
1809                            "enabled": true,
1810                            "bot_token": token,
1811                            "allowed_channels": self.discord_allowed_channels,
1812                            "no_mention": self.discord_no_mention,
1813                        }))
1814                        .unwrap(),
1815                    );
1816                }
1817            }
1818            if self.web_enabled {
1819                self.channels.insert(
1820                    "web".into(),
1821                    serde_yaml::to_value(serde_json::json!({
1822                        "enabled": true,
1823                        "host": self.web_host,
1824                        "port": self.web_port,
1825                    }))
1826                    .unwrap(),
1827                );
1828            }
1829        }
1830
1831        // Validate required fields
1832        let (enabled_channels, configured_but_disabled) = self.channel_status();
1833        if enabled_channels.is_empty() {
1834            let hint = if configured_but_disabled.is_empty() {
1835                String::new()
1836            } else {
1837                format!(
1838                    " These channels are configured but not enabled: {}. \
1839                     Set `channels.<name>.enabled: true` (or run `microclaw setup`).",
1840                    configured_but_disabled.join(", ")
1841                )
1842            };
1843            return Err(MicroClawError::Config(format!(
1844                "At least one channel must be enabled and configured (via channels.<name>.enabled or legacy channel settings).{hint}"
1845            )));
1846        }
1847        if self.api_key.is_empty() && !provider_allows_empty_api_key(&self.llm_provider) {
1848            return Err(MicroClawError::Config("api_key is required".into()));
1849        }
1850        if is_openai_codex_provider(&self.llm_provider) {
1851            if !self.api_key.trim().is_empty() {
1852                return Err(MicroClawError::Config(
1853                    "openai-codex ignores microclaw.config.yaml api_key. Configure ~/.codex/auth.json or run `codex login` instead.".into(),
1854                ));
1855            }
1856            if self
1857                .llm_base_url
1858                .as_ref()
1859                .map(|v| !v.trim().is_empty())
1860                .unwrap_or(false)
1861            {
1862                return Err(MicroClawError::Config(
1863                    "openai-codex ignores microclaw.config.yaml llm_base_url. Configure ~/.codex/config.toml instead.".into(),
1864                ));
1865            }
1866            let has_codex_auth = codex_auth_file_has_access_token()?;
1867            if !has_codex_auth {
1868                return Err(MicroClawError::Config(
1869                    "openai-codex requires ~/.codex/auth.json (access token or OPENAI_API_KEY), or OPENAI_CODEX_ACCESS_TOKEN. Run `codex login` or update Codex config files.".into(),
1870                ));
1871            }
1872        }
1873        if is_qwen_portal_provider(&self.llm_provider) && self.api_key.trim().is_empty() {
1874            let has_qwen_auth = qwen_oauth_file_has_access_token()?;
1875            if !has_qwen_auth {
1876                return Err(MicroClawError::Config(
1877                    "qwen-portal requires api_key, or ~/.qwen/oauth_creds.json (access_token), or QWEN_PORTAL_ACCESS_TOKEN.".into(),
1878                ));
1879            }
1880        }
1881
1882        self.validate_configured_egress()?;
1883
1884        Ok(())
1885    }
1886
1887    fn validate_configured_egress(&self) -> Result<(), MicroClawError> {
1888        if self.egress_policy.mode == EgressPolicyMode::Off {
1889            return Ok(());
1890        }
1891        for url in self.configured_egress_endpoints() {
1892            let decision =
1893                crate::internal::tool_runtime::egress::evaluate_url(&self.egress_policy, &url);
1894            match decision {
1895                crate::internal::tool_runtime::egress::EgressDecision::Warn(reason) => {
1896                    warn!(url = %url, reason = %reason, "configured endpoint violates egress policy");
1897                }
1898                crate::internal::tool_runtime::egress::EgressDecision::Block(reason) => {
1899                    return Err(MicroClawError::Config(format!(
1900                        "configured endpoint `{url}` blocked by egress policy: {reason}"
1901                    )));
1902                }
1903                crate::internal::tool_runtime::egress::EgressDecision::Allow => {}
1904            }
1905        }
1906        Ok(())
1907    }
1908
1909    fn configured_egress_endpoints(&self) -> Vec<String> {
1910        let mut urls = Vec::new();
1911        {
1912            let mut add = |value: Option<&str>| {
1913                if let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) {
1914                    urls.push(value.to_string());
1915                }
1916            };
1917
1918            add(self.llm_base_url.as_deref());
1919            for profile in self
1920                .provider_presets
1921                .values()
1922                .chain(self.llm_providers.values())
1923            {
1924                add(profile.llm_base_url.as_deref());
1925            }
1926            add(self.embedding_base_url.as_deref());
1927            add(self.openai_base_url.as_deref());
1928
1929            let media_enabled = self.media.image_gen.enabled
1930                || self.media.vision.enabled
1931                || self.media.tts.enabled
1932                || self.media.stt.enabled
1933                || self.media.podcast.enabled;
1934            if media_enabled {
1935                add(self.media.base_url.as_deref());
1936            }
1937            if self.media.tts.enabled || self.media.podcast.enabled {
1938                add(self.media.tts.base_url.as_deref());
1939            }
1940            if self.media.podcast.enabled {
1941                add(self.media.podcast.base_url.as_deref());
1942            }
1943
1944            if self.web_search.effective_backend()
1945                == crate::internal::tool_runtime::web_search::SearchBackend::Searxng
1946            {
1947                add(Some(&self.web_search.searxng_base_url));
1948            }
1949            for peer in self.a2a.peers.values().filter(|peer| peer.enabled) {
1950                add(Some(&peer.base_url));
1951            }
1952            if self.clawhub.agent_tools_enabled {
1953                add(Some(&self.clawhub.registry));
1954            }
1955            if self.alerts.enabled {
1956                add(Some(&self.alerts.webhook_url));
1957            }
1958        }
1959
1960        for channel in self.channels.values() {
1961            collect_enabled_channel_endpoints(channel, &mut urls);
1962        }
1963
1964        urls.sort();
1965        urls.dedup();
1966        urls
1967    }
1968
1969    fn merged_profile_from_alias(&self, alias: &str) -> Option<ResolvedLlmProviderProfile> {
1970        let alias = alias.trim().to_ascii_lowercase();
1971        if alias.is_empty() {
1972            return None;
1973        }
1974        if alias == self.llm_provider {
1975            let mut provider = self.llm_provider.clone();
1976            let mut api_key = self.api_key.clone();
1977            let mut api_keys = self.api_keys.clone();
1978            let mut llm_base_url = self.llm_base_url.clone();
1979            let mut llm_user_agent = self.llm_user_agent.clone();
1980            let mut default_model = self.model.clone();
1981            let mut models = vec![default_model.clone()];
1982            let mut show_thinking = self.show_thinking;
1983            if let Some(profile) = self.llm_providers.get(&alias) {
1984                if let Some(v) = &profile.provider {
1985                    provider = v.clone();
1986                }
1987                if let Some(v) = &profile.api_key {
1988                    api_key = v.clone();
1989                }
1990                if !profile.api_keys.is_empty() {
1991                    api_keys = profile.api_keys.clone();
1992                }
1993                if let Some(v) = &profile.llm_base_url {
1994                    llm_base_url = Some(v.clone());
1995                }
1996                if let Some(v) = &profile.llm_user_agent {
1997                    llm_user_agent = v.clone();
1998                }
1999                if let Some(v) = &profile.default_model {
2000                    default_model = v.clone();
2001                }
2002                if !profile.models.is_empty() {
2003                    models = profile.models.clone();
2004                }
2005                if let Some(v) = profile.show_thinking {
2006                    show_thinking = v;
2007                }
2008            }
2009            default_model = resolve_model_name_with_fallback(
2010                &provider,
2011                Some(&default_model),
2012                Some(&self.model),
2013            );
2014            models = models
2015                .into_iter()
2016                .filter_map(|model| normalize_model_name(&model))
2017                .collect();
2018            if !models.iter().any(|m| m == &default_model) {
2019                models.push(default_model.clone());
2020            }
2021            models.sort();
2022            models.dedup();
2023            return Some(ResolvedLlmProviderProfile {
2024                alias,
2025                provider,
2026                api_key,
2027                api_keys,
2028                llm_base_url,
2029                llm_user_agent,
2030                default_model,
2031                models,
2032                show_thinking,
2033            });
2034        }
2035
2036        let profile = self.llm_providers.get(&alias)?;
2037        let provider = profile.provider.clone().unwrap_or_else(|| alias.clone());
2038        let api_key = profile
2039            .api_key
2040            .clone()
2041            .unwrap_or_else(|| self.api_key.clone());
2042        // A profile with its own key(s) never inherits the top-level pool.
2043        let api_keys = if !profile.api_keys.is_empty() {
2044            profile.api_keys.clone()
2045        } else if profile.api_key.is_none() {
2046            self.api_keys.clone()
2047        } else {
2048            Vec::new()
2049        };
2050        let llm_base_url = profile
2051            .llm_base_url
2052            .clone()
2053            .or_else(|| self.llm_base_url.clone());
2054        let llm_user_agent = profile
2055            .llm_user_agent
2056            .clone()
2057            .unwrap_or_else(|| self.llm_user_agent.clone());
2058        let default_model = resolve_model_name_with_fallback(
2059            &provider,
2060            profile.default_model.as_deref(),
2061            Some(&self.model),
2062        );
2063        let mut models = if profile.models.is_empty() {
2064            vec![default_model.clone()]
2065        } else {
2066            profile
2067                .models
2068                .clone()
2069                .into_iter()
2070                .filter_map(|model| normalize_model_name(&model))
2071                .collect()
2072        };
2073        let show_thinking = profile.show_thinking.unwrap_or(self.show_thinking);
2074        if !models.iter().any(|m| m == &default_model) {
2075            models.push(default_model.clone());
2076        }
2077        models.sort();
2078        models.dedup();
2079        Some(ResolvedLlmProviderProfile {
2080            alias,
2081            provider,
2082            api_key,
2083            api_keys,
2084            llm_base_url,
2085            llm_user_agent,
2086            default_model,
2087            models,
2088            show_thinking,
2089        })
2090    }
2091
2092    pub fn resolve_llm_provider_profile(&self, alias: &str) -> Option<ResolvedLlmProviderProfile> {
2093        self.merged_profile_from_alias(alias)
2094    }
2095
2096    pub fn list_llm_provider_profiles(&self) -> Vec<ResolvedLlmProviderProfile> {
2097        let mut out = Vec::new();
2098        if let Some(default_profile) = self.resolve_llm_provider_profile(&self.llm_provider) {
2099            out.push(default_profile);
2100        }
2101        let mut aliases: Vec<String> = self.llm_providers.keys().cloned().collect();
2102        aliases.sort();
2103        aliases.dedup();
2104        for alias in aliases {
2105            if alias == self.llm_provider {
2106                continue;
2107            }
2108            if let Some(profile) = self.resolve_llm_provider_profile(&alias) {
2109                out.push(profile);
2110            }
2111        }
2112        out
2113    }
2114
2115    /// Deserialize a typed channel config from the `channels` map.
2116    pub fn channel_config<T: DeserializeOwned>(&self, name: &str) -> Option<T> {
2117        self.channels
2118            .get(name)
2119            .and_then(|v| serde_yaml::from_value(v.clone()).ok())
2120    }
2121
2122    pub fn model_price(&self, model: &str) -> Option<&ModelPrice> {
2123        let needle = model.trim();
2124        self.model_prices
2125            .iter()
2126            .find(|p| p.model.eq_ignore_ascii_case(needle))
2127            .or_else(|| self.model_prices.iter().find(|p| p.model == "*"))
2128    }
2129
2130    pub fn estimate_cost_usd(
2131        &self,
2132        model: &str,
2133        input_tokens: i64,
2134        output_tokens: i64,
2135    ) -> Option<f64> {
2136        let price = self.model_price(model)?;
2137        let in_tok = input_tokens.max(0) as f64;
2138        let out_tok = output_tokens.max(0) as f64;
2139        Some(
2140            (in_tok / 1_000_000.0) * price.input_per_million_usd
2141                + (out_tok / 1_000_000.0) * price.output_per_million_usd,
2142        )
2143    }
2144
2145    pub fn tool_timeout_secs(&self, tool_name: &str, fallback: u64) -> u64 {
2146        let normalized = tool_name.trim().to_ascii_lowercase();
2147        if let Some(timeout_secs) = self.tool_timeout_overrides.get(&normalized) {
2148            return *timeout_secs;
2149        }
2150        if self.default_tool_timeout_secs == 0 {
2151            fallback
2152        } else {
2153            self.default_tool_timeout_secs
2154        }
2155    }
2156
2157    pub fn mcp_request_timeout_secs(&self) -> u64 {
2158        if self.default_mcp_request_timeout_secs == 0 {
2159            default_mcp_request_timeout_secs()
2160        } else {
2161            self.default_mcp_request_timeout_secs
2162        }
2163    }
2164
2165    /// Save config as YAML to the given path.
2166    #[allow(dead_code)]
2167    pub fn save_yaml(&self, path: &str) -> Result<(), MicroClawError> {
2168        let content = serde_yaml::to_string(self)
2169            .map_err(|e| MicroClawError::Config(format!("Failed to serialize config: {e}")))?;
2170        std::fs::write(path, content)?;
2171        Ok(())
2172    }
2173}
2174
2175pub(crate) fn normalize_body_override_params(
2176    params: HashMap<String, serde_json::Value>,
2177) -> HashMap<String, serde_json::Value> {
2178    params
2179        .into_iter()
2180        .filter_map(|(key, value)| {
2181            let key = key.trim().to_string();
2182            if key.is_empty() {
2183                None
2184            } else {
2185                Some((key, value))
2186            }
2187        })
2188        .collect()
2189}
2190
2191pub(crate) fn normalize_provider_profiles(
2192    profiles: HashMap<String, LlmProviderProfile>,
2193) -> HashMap<String, LlmProviderProfile> {
2194    profiles
2195        .into_iter()
2196        .filter_map(|(alias, mut profile)| {
2197            let alias = alias.trim().to_ascii_lowercase();
2198            if alias.is_empty() {
2199                return None;
2200            }
2201            profile.provider = profile
2202                .provider
2203                .as_ref()
2204                .map(|v| v.trim().to_ascii_lowercase())
2205                .filter(|v| !v.is_empty());
2206            profile.api_key = profile
2207                .api_key
2208                .as_ref()
2209                .map(|v| v.trim().to_string())
2210                .filter(|v| !v.is_empty());
2211            profile.llm_base_url = profile
2212                .llm_base_url
2213                .as_ref()
2214                .map(|v| v.trim().to_string())
2215                .filter(|v| !v.is_empty());
2216            profile.llm_user_agent = profile
2217                .llm_user_agent
2218                .as_ref()
2219                .map(|v| v.trim().to_string())
2220                .filter(|v| !v.is_empty());
2221            profile.default_model = profile
2222                .default_model
2223                .as_ref()
2224                .and_then(|v| normalize_model_name(v));
2225            profile.models = profile
2226                .models
2227                .into_iter()
2228                .filter_map(|m| normalize_model_name(&m))
2229                .collect::<Vec<_>>();
2230            profile.models.sort();
2231            profile.models.dedup();
2232            Some((alias, profile))
2233        })
2234        .collect()
2235}
2236
2237pub(crate) fn migrate_model_override_alias_to_provider_preset(
2238    value: &mut serde_yaml::Value,
2239    known_profiles: &HashMap<String, LlmProviderProfile>,
2240) {
2241    let Some(map) = value.as_mapping_mut() else {
2242        return;
2243    };
2244
2245    let provider_preset_key = serde_yaml::Value::String("provider_preset".to_string());
2246    let llm_provider_key = serde_yaml::Value::String("llm_provider".to_string());
2247    let model_key = serde_yaml::Value::String("model".to_string());
2248
2249    let has_provider_override =
2250        map.contains_key(&provider_preset_key) || map.contains_key(&llm_provider_key);
2251    if !has_provider_override {
2252        let maybe_profile_alias = map
2253            .get(&model_key)
2254            .and_then(|v| v.as_str())
2255            .map(str::trim)
2256            .filter(|v| !v.is_empty())
2257            .map(|v| v.to_ascii_lowercase());
2258        if let Some(alias) = maybe_profile_alias {
2259            if known_profiles.contains_key(&alias) {
2260                map.insert(
2261                    provider_preset_key.clone(),
2262                    serde_yaml::Value::String(alias),
2263                );
2264                map.remove(&model_key);
2265            }
2266        }
2267    }
2268
2269    let accounts_key = serde_yaml::Value::String("accounts".to_string());
2270    if let Some(accounts) = map.get_mut(&accounts_key).and_then(|v| v.as_mapping_mut()) {
2271        for (_, account) in accounts.iter_mut() {
2272            migrate_model_override_alias_to_provider_preset(account, known_profiles);
2273        }
2274    }
2275}
2276
2277pub(crate) fn merge_provider_profile(
2278    base: LlmProviderProfile,
2279    override_profile: LlmProviderProfile,
2280) -> LlmProviderProfile {
2281    let mut models = if override_profile.models.is_empty() {
2282        base.models
2283    } else {
2284        override_profile.models
2285    };
2286    models.sort();
2287    models.dedup();
2288
2289    LlmProviderProfile {
2290        provider: override_profile.provider.or(base.provider),
2291        api_key: override_profile.api_key.or(base.api_key),
2292        api_keys: if override_profile.api_keys.is_empty() {
2293            base.api_keys
2294        } else {
2295            override_profile.api_keys
2296        },
2297        llm_base_url: override_profile.llm_base_url.or(base.llm_base_url),
2298        llm_user_agent: override_profile.llm_user_agent.or(base.llm_user_agent),
2299        default_model: override_profile.default_model.or(base.default_model),
2300        models,
2301        show_thinking: override_profile.show_thinking.or(base.show_thinking),
2302    }
2303}
2304
2305/// Result of `microclaw config check` on one file. Errors mean the config
2306/// won't load; warnings mean it loads but something is probably a typo.
2307#[derive(Debug, Default)]
2308pub struct ConfigCheckReport {
2309    pub errors: Vec<String>,
2310    pub warnings: Vec<String>,
2311    /// Present when the config parsed: (enabled channels, configured-but-
2312    /// disabled channels, provider, model).
2313    pub summary: Option<(Vec<&'static str>, Vec<&'static str>, String, String)>,
2314}
2315
2316impl ConfigCheckReport {
2317    pub fn ok(&self) -> bool {
2318        self.errors.is_empty()
2319    }
2320}
2321
2322/// Validate config file content without starting anything: YAML syntax with
2323/// line/column, unknown-key warnings with did-you-mean, full schema
2324/// deserialization (typed enums reject typos), and post-deserialize
2325/// normalization/validation. Pure function over the text for testability.
2326pub fn check_config_content(path_str: &str, content: &str) -> ConfigCheckReport {
2327    let mut report = ConfigCheckReport::default();
2328
2329    // 1) YAML syntax. serde_yaml errors carry line/column.
2330    let raw: serde_yaml::Value = match serde_yaml::from_str(content) {
2331        Ok(v) => v,
2332        Err(e) => {
2333            report.errors.push(format!("YAML syntax error: {e}"));
2334            return report;
2335        }
2336    };
2337
2338    // 2) Unknown top-level keys (serde ignores them silently on load).
2339    if let Some(map) = raw.as_mapping() {
2340        report.warnings.extend(unknown_top_level_key_warnings(map));
2341    } else {
2342        report
2343            .errors
2344            .push("Config root must be a YAML mapping (key: value pairs).".to_string());
2345        return report;
2346    }
2347
2348    // 3) Full schema deserialization (typed enums catch value typos with a
2349    //    did-you-mean suggestion) + post-deserialize validation.
2350    match serde_yaml::from_str::<Config>(content) {
2351        Err(e) => {
2352            report.errors.push(friendly_yaml_error(path_str, &e));
2353        }
2354        Ok(mut config) => match config.post_deserialize() {
2355            // Covers value validation including the "no channel enabled" case.
2356            Err(e) => report.errors.push(e.to_string()),
2357            Ok(()) => {
2358                if crate::tool_guardrails::global_policy_has_no_rules(&config.tool_policy) {
2359                    report.warnings.push(format!(
2360                        "tool_policy.mode is `{}` but allow_tools, deny_tools and max_risk are all \
2361                         empty, so every tool is still permitted. Add an allowlist, a deny list \
2362                         or a max_risk ceiling.",
2363                        serde_yaml::to_string(&config.tool_policy.mode)
2364                            .unwrap_or_default()
2365                            .trim()
2366                    ));
2367                }
2368                let (enabled, disabled) = config.channel_status();
2369                report.summary = Some((
2370                    enabled,
2371                    disabled,
2372                    config.llm_provider.clone(),
2373                    config.model.clone(),
2374                ));
2375            }
2376        },
2377    }
2378    report
2379}
2380
2381/// CLI entry point for `microclaw config check`. Prints a human-readable
2382/// report and returns the process exit code (0 = loadable, 1 = errors,
2383/// 2 = file missing/unreadable).
2384pub fn run_config_check() -> i32 {
2385    let path = match Config::resolve_config_path() {
2386        Ok(Some(p)) => p,
2387        Ok(None) => {
2388            eprintln!("✗ No microclaw.config.yaml found. Run `microclaw setup` to create one.");
2389            return 2;
2390        }
2391        Err(e) => {
2392            eprintln!("✗ {e}");
2393            return 2;
2394        }
2395    };
2396    let path_str = path.to_string_lossy().to_string();
2397    let content = match std::fs::read_to_string(&path) {
2398        Ok(c) => c,
2399        Err(e) => {
2400            eprintln!("✗ Failed to read {path_str}: {e}");
2401            return 2;
2402        }
2403    };
2404
2405    println!("Checking {path_str}");
2406    let report = check_config_content(&path_str, &content);
2407    for w in &report.warnings {
2408        println!("  ⚠ {w}");
2409    }
2410    for e in &report.errors {
2411        println!("  ✗ {e}");
2412    }
2413    if let Some((enabled, disabled, provider, model)) = &report.summary {
2414        let enabled_str = if enabled.is_empty() {
2415            "none".to_string()
2416        } else {
2417            enabled.join(", ")
2418        };
2419        println!("  provider: {provider} · model: {model}");
2420        println!("  channels enabled: {enabled_str}");
2421        if !disabled.is_empty() {
2422            println!("  configured but disabled: {}", disabled.join(", "));
2423        }
2424    }
2425    if report.ok() {
2426        println!(
2427            "✓ Config OK{}",
2428            if report.warnings.is_empty() {
2429                ""
2430            } else {
2431                " (with warnings)"
2432            }
2433        );
2434        0
2435    } else {
2436        println!("✗ Config has errors — fix them and re-run, or run `microclaw setup`.");
2437        1
2438    }
2439}
2440
2441/// Turn a raw `serde_yaml` parse error into an actionable message. When the
2442/// error is an unknown field or variant (the common YAML typo), suggest the
2443/// closest valid name, and always point the user at `setup` / the example
2444/// config. The original error (with its line/column) is preserved.
2445pub(crate) fn friendly_yaml_error(path_str: &str, err: &serde_yaml::Error) -> String {
2446    let raw = err.to_string();
2447    let mut hint = String::new();
2448    if let Some((kind, token)) = extract_unknown_token(&raw) {
2449        match suggest_closest(token, &extract_backtick_options(&raw)) {
2450            Some(best) => {
2451                hint = format!("\n\n  Unknown {kind} `{token}` — did you mean `{best}`?");
2452            }
2453            None => hint = format!("\n\n  Unknown {kind} `{token}`."),
2454        }
2455    }
2456    format!(
2457        "Failed to parse {path_str}: {raw}{hint}\n\n  \
2458         Edit the config and re-run, or run `microclaw setup`.\n  \
2459         Reference: https://github.com/microclaw/microclaw/blob/main/microclaw.config.example.yaml"
2460    )
2461}
2462
2463/// Build the set of accepted top-level config keys by serializing a baseline
2464/// `Config` (so it stays in sync with the struct, including the flattened
2465/// `clawhub_*` keys), plus the few fields excluded from serialization and the
2466/// deprecated aliases handled elsewhere. Returns `None` if the baseline can't
2467/// be derived, so callers skip the check rather than emit spurious warnings.
2468pub(crate) fn known_top_level_config_keys() -> Option<std::collections::BTreeSet<String>> {
2469    let base: Config = serde_yaml::from_str("{}").ok()?;
2470    let serde_yaml::Value::Mapping(serialized) = serde_yaml::to_value(&base).ok()? else {
2471        return None;
2472    };
2473    let mut known: std::collections::BTreeSet<String> = serialized
2474        .keys()
2475        .filter_map(|k| k.as_str().map(str::to_string))
2476        .collect();
2477    // Accepted on input but excluded from serialization (skip_serializing[_if])
2478    // or kept only for backward-compatible deprecation warnings.
2479    for k in ["timezone", "override_timezone", "web_auth_token"] {
2480        known.insert(k.to_string());
2481    }
2482    // Sanity guard: a healthy Config has many keys; if we somehow derived only
2483    // a handful, treat the set as unreliable and skip the check.
2484    if known.len() < 5 {
2485        return None;
2486    }
2487    Some(known)
2488}
2489
2490/// Soft-validate top-level config keys: serde silently ignores unknown fields,
2491/// so a typo like `discrod:` is otherwise invisible. Returns one human-readable
2492/// warning per unrecognized key (with a did-you-mean suggestion when close).
2493/// Does not fail the load.
2494pub(crate) fn unknown_top_level_key_warnings(map: &serde_yaml::Mapping) -> Vec<String> {
2495    let Some(known) = known_top_level_config_keys() else {
2496        return Vec::new();
2497    };
2498    let candidates: Vec<String> = known.iter().cloned().collect();
2499    let mut warnings = Vec::new();
2500    for key in map.keys() {
2501        let Some(name) = key.as_str() else { continue };
2502        if known.contains(name) {
2503            continue;
2504        }
2505        match suggest_closest(name, &candidates) {
2506            Some(best) => warnings.push(format!(
2507                "Unknown config key `{name}` (ignored) — did you mean `{best}`?"
2508            )),
2509            None => warnings.push(format!("Unknown config key `{name}` (ignored).")),
2510        }
2511    }
2512    warnings
2513}
2514
2515/// Extract `(kind, token)` from a serde "unknown variant/field `X`" message.
2516pub(crate) fn extract_unknown_token(raw: &str) -> Option<(&'static str, &str)> {
2517    for (needle, kind) in [
2518        ("unknown variant `", "variant"),
2519        ("unknown field `", "field"),
2520    ] {
2521        if let Some(start) = raw.find(needle) {
2522            let rest = &raw[start + needle.len()..];
2523            if let Some(end) = rest.find('`') {
2524                return Some((kind, &rest[..end]));
2525            }
2526        }
2527    }
2528    None
2529}
2530
2531/// Collect the backtick-quoted options listed after "expected" in a serde error.
2532pub(crate) fn extract_backtick_options(raw: &str) -> Vec<String> {
2533    let Some(exp) = raw.find("expected") else {
2534        return Vec::new();
2535    };
2536    let mut out = Vec::new();
2537    let mut rest = &raw[exp..];
2538    while let Some(open) = rest.find('`') {
2539        rest = &rest[open + 1..];
2540        if let Some(close) = rest.find('`') {
2541            out.push(rest[..close].to_string());
2542            rest = &rest[close + 1..];
2543        } else {
2544            break;
2545        }
2546    }
2547    out
2548}
2549
2550/// Pick the closest option to `token` by edit distance, if one is "close
2551/// enough" (distance at most a third of the token length, min 2).
2552pub(crate) fn suggest_closest(token: &str, options: &[String]) -> Option<String> {
2553    let threshold = (token.chars().count() / 3).max(2);
2554    options
2555        .iter()
2556        .map(|o| (levenshtein(token, o), o))
2557        .filter(|(d, _)| *d <= threshold)
2558        .min_by_key(|(d, _)| *d)
2559        .map(|(_, o)| o.clone())
2560}
2561
2562/// Standard Levenshtein edit distance.
2563pub(crate) fn levenshtein(a: &str, b: &str) -> usize {
2564    let a: Vec<char> = a.chars().collect();
2565    let b: Vec<char> = b.chars().collect();
2566    let mut prev: Vec<usize> = (0..=b.len()).collect();
2567    let mut cur = vec![0usize; b.len() + 1];
2568    for (i, ca) in a.iter().enumerate() {
2569        cur[0] = i + 1;
2570        for (j, cb) in b.iter().enumerate() {
2571            let cost = if ca == cb { 0 } else { 1 };
2572            cur[j + 1] = (prev[j + 1] + 1).min(cur[j] + 1).min(prev[j] + cost);
2573        }
2574        std::mem::swap(&mut prev, &mut cur);
2575    }
2576    prev[b.len()]
2577}
2578
2579#[cfg(test)]
2580mod tests {
2581    use super::*;
2582    #[allow(unused_imports)]
2583    use crate::config::test_prelude::*;
2584
2585    #[test]
2586    fn config_check_reports_syntax_errors_with_location() {
2587        let report = check_config_content("t.yaml", "telegram_bot_token: [unclosed");
2588        assert!(!report.ok());
2589        assert!(report.errors[0].contains("YAML syntax error"));
2590        assert!(report.summary.is_none());
2591    }
2592
2593    #[test]
2594    fn config_check_warns_on_unknown_key_with_suggestion() {
2595        let report = check_config_content(
2596            "t.yaml",
2597            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nmax_tool_iterationz: 5\n",
2598        );
2599        assert!(report.ok(), "unknown keys warn but do not fail the check");
2600        assert!(
2601            report
2602                .warnings
2603                .iter()
2604                .any(|w| w.contains("max_tool_iterationz") && w.contains("max_tool_iterations")),
2605            "expected did-you-mean warning, got: {:?}",
2606            report.warnings
2607        );
2608        let (enabled, _, provider, _) = report.summary.as_ref().unwrap();
2609        assert!(enabled.contains(&"telegram"));
2610        assert_eq!(provider, "anthropic");
2611    }
2612
2613    #[test]
2614    fn config_check_rejects_bad_enum_value_with_suggestion() {
2615        let report = check_config_content("t.yaml", "api_key: key\ntool_policy:\n  mode: blok\n");
2616        assert!(!report.ok());
2617        assert!(
2618            report.errors[0].contains("blok") && report.errors[0].contains("block"),
2619            "expected did-you-mean on enum typo, got: {:?}",
2620            report.errors
2621        );
2622    }
2623
2624    #[test]
2625    fn config_check_warns_when_tool_policy_has_no_rules() {
2626        let report = check_config_content("t.yaml", "api_key: key\ntool_policy:\n  mode: block\n");
2627        assert!(report.ok(), "errors: {:?}", report.errors);
2628        assert!(
2629            report
2630                .warnings
2631                .iter()
2632                .any(|w| w.contains("tool_policy.mode is `block`")
2633                    && w.contains("every tool is still permitted")),
2634            "expected empty-policy warning, got: {:?}",
2635            report.warnings
2636        );
2637
2638        // Any rule silences it.
2639        let report = check_config_content(
2640            "t.yaml",
2641            "api_key: key\ntool_policy:\n  mode: block\n  allow_tools: [read_file]\n",
2642        );
2643        assert!(report.ok(), "errors: {:?}", report.errors);
2644        assert!(
2645            !report.warnings.iter().any(|w| w.contains("tool_policy")),
2646            "unexpected warning: {:?}",
2647            report.warnings
2648        );
2649        let report = check_config_content("t.yaml", "api_key: key\n");
2650        assert!(!report.warnings.iter().any(|w| w.contains("tool_policy")));
2651    }
2652
2653    #[test]
2654    fn config_check_flags_no_enabled_channel() {
2655        // The web channel is on by default, so a bare config is loadable.
2656        let report = check_config_content("t.yaml", "api_key: key\n");
2657        assert!(report.ok(), "errors: {:?}", report.errors);
2658        let (enabled, ..) = report.summary.as_ref().unwrap();
2659        assert!(enabled.contains(&"web"));
2660
2661        // Explicitly disabling every channel fails post-deserialize
2662        // validation — the check surfaces that as an error.
2663        let report = check_config_content(
2664            "t.yaml",
2665            "api_key: key\nchannels:\n  web:\n    enabled: false\n",
2666        );
2667        assert!(
2668            !report.ok(),
2669            "disabling all channels should be an error, got warnings: {:?}",
2670            report.warnings
2671        );
2672    }
2673
2674    #[test]
2675    fn config_check_rejects_non_mapping_root() {
2676        let report = check_config_content("t.yaml", "- just\n- a\n- list\n");
2677        assert!(!report.ok());
2678        assert!(report.errors[0].contains("mapping"));
2679    }
2680
2681    #[test]
2682    fn friendly_error_suggests_closest_field() {
2683        // A real serde_yaml unknown-field error for a mistyped key.
2684        #[derive(Debug, serde::Deserialize)]
2685        #[serde(deny_unknown_fields)]
2686        struct Mini {
2687            #[allow(dead_code)]
2688            discord: bool,
2689        }
2690        let err = serde_yaml::from_str::<Mini>("discrod: true\n").unwrap_err();
2691        let msg = friendly_yaml_error("cfg.yaml", &err);
2692        assert!(msg.contains("did you mean `discord`?"), "got: {msg}");
2693        assert!(msg.contains("microclaw setup"));
2694    }
2695
2696    #[test]
2697    fn extract_and_suggest_helpers() {
2698        let raw = "unknown variant `discrod`, expected one of `telegram`, `discord`, `slack`";
2699        assert_eq!(extract_unknown_token(raw), Some(("variant", "discrod")));
2700        let opts = extract_backtick_options(raw);
2701        assert_eq!(opts, vec!["telegram", "discord", "slack"]);
2702        assert_eq!(
2703            suggest_closest("discrod", &opts).as_deref(),
2704            Some("discord")
2705        );
2706        // Nothing close → no suggestion.
2707        assert_eq!(suggest_closest("zzzzzz", &opts), None);
2708    }
2709
2710    #[test]
2711    fn levenshtein_basics() {
2712        assert_eq!(levenshtein("kitten", "sitting"), 3);
2713        assert_eq!(levenshtein("discord", "discord"), 0);
2714        assert_eq!(levenshtein("", "abc"), 3);
2715    }
2716
2717    #[test]
2718    fn channel_status_splits_enabled_and_disabled() {
2719        let cfg: Config = serde_yaml::from_str(
2720            "api_key: k\nweb_enabled: false\nchannels:\n  telegram:\n    enabled: true\n  discord:\n    enabled: false\n",
2721        )
2722        .unwrap();
2723        let (enabled, disabled) = cfg.channel_status();
2724        assert_eq!(enabled, vec!["telegram"]);
2725        assert_eq!(disabled, vec!["discord"]);
2726    }
2727
2728    #[test]
2729    fn no_enabled_channel_error_names_disabled_channel() {
2730        let mut cfg: Config = serde_yaml::from_str(
2731            "api_key: k\nweb_enabled: false\nchannels:\n  telegram:\n    enabled: false\n",
2732        )
2733        .unwrap();
2734        let err = cfg.post_deserialize().unwrap_err().to_string();
2735        assert!(err.contains("configured but not enabled"), "got: {err}");
2736        assert!(err.contains("telegram"), "got: {err}");
2737    }
2738
2739    #[test]
2740    fn aux_models_parse_from_yaml() {
2741        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\naux_models:\n  compaction: claude-haiku-4-5\n  reflector: claude-haiku-4-5\n";
2742        let config: Config = serde_yaml::from_str(yaml).unwrap();
2743        assert_eq!(
2744            config.aux_models.compaction.as_deref(),
2745            Some("claude-haiku-4-5")
2746        );
2747        assert_eq!(
2748            config.aux_models.reflector_model(),
2749            Some("claude-haiku-4-5")
2750        );
2751    }
2752
2753    #[test]
2754    fn aux_models_absent_yaml_defaults_to_none() {
2755        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2756        let config: Config = serde_yaml::from_str(yaml).unwrap();
2757        assert!(config.aux_models.compaction.is_none());
2758    }
2759
2760    #[test]
2761    fn aux_models_title_vision_parse_from_yaml() {
2762        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\naux_models:\n  title: claude-haiku-4-5\n  vision: claude-haiku-4-5\n";
2763        let config: Config = serde_yaml::from_str(yaml).unwrap();
2764        assert_eq!(config.aux_models.title_model(), Some("claude-haiku-4-5"));
2765        assert_eq!(config.aux_models.vision_model(), Some("claude-haiku-4-5"));
2766    }
2767
2768    #[test]
2769    fn test_clawhub_config_defaults() {
2770        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2771        let config: Config = serde_yaml::from_str(yaml).unwrap();
2772        assert_eq!(config.clawhub.registry, "https://clawhub.ai");
2773        assert!(config.clawhub.agent_tools_enabled);
2774    }
2775
2776    #[test]
2777    fn test_voice_config_defaults() {
2778        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2779        let config: Config = serde_yaml::from_str(yaml).unwrap();
2780        assert_eq!(config.voice_provider, "openai");
2781        assert!(config.voice_transcription_command.is_none());
2782    }
2783
2784    #[test]
2785    fn test_voice_config_local_provider() {
2786        let yaml = r#"
2787telegram_bot_token: tok
2788bot_username: bot
2789api_key: key
2790voice_provider: "local"
2791voice_transcription_command: "whisper-mlx --file {file}"
2792"#;
2793        let config: Config = serde_yaml::from_str(yaml).unwrap();
2794        assert_eq!(config.voice_provider, "local");
2795        assert_eq!(
2796            config.voice_transcription_command,
2797            Some("whisper-mlx --file {file}".into())
2798        );
2799    }
2800
2801    #[test]
2802    fn test_config_yaml_roundtrip() {
2803        let config = test_config();
2804        let yaml = serde_yaml::to_string(&config).unwrap();
2805        let parsed: Config = serde_yaml::from_str(&yaml).unwrap();
2806        assert_eq!(parsed.telegram_bot_token, "tok");
2807        assert_eq!(parsed.max_tokens, 8192);
2808        assert_eq!(parsed.llm_provider, "anthropic");
2809    }
2810
2811    #[test]
2812    fn test_default_data_dir_uses_microclaw_home() {
2813        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2814        let config: Config = serde_yaml::from_str(yaml).unwrap();
2815        assert!(config.data_dir.ends_with(".microclaw"));
2816    }
2817
2818    #[test]
2819    fn test_config_sandbox_defaults_to_off() {
2820        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2821        let config: Config = serde_yaml::from_str(yaml).unwrap();
2822        assert!(matches!(config.sandbox.mode, SandboxMode::Off));
2823        assert!(matches!(config.sandbox.backend, SandboxBackend::Auto));
2824        assert!(config.sandbox.require_runtime);
2825        assert_eq!(config.sandbox.image, "ubuntu:25.10");
2826    }
2827
2828    #[test]
2829    fn test_post_deserialize_empty_working_dir_uses_default() {
2830        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nworking_dir: '  '\n";
2831        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2832        config.post_deserialize().unwrap();
2833        assert!(std::path::PathBuf::from(&config.working_dir)
2834            .ends_with(std::path::Path::new(".microclaw").join("working_dir")));
2835    }
2836
2837    #[test]
2838    fn test_post_deserialize_zero_memory_budget_uses_default() {
2839        let yaml =
2840            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nmemory_token_budget: 0\n";
2841        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2842        config.post_deserialize().unwrap();
2843        assert_eq!(config.memory_token_budget, 1500);
2844    }
2845
2846    #[test]
2847    fn test_config_working_dir_isolation_defaults_to_chat() {
2848        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2849        let config: Config = serde_yaml::from_str(yaml).unwrap();
2850        assert!(matches!(
2851            config.working_dir_isolation,
2852            WorkingDirIsolation::Chat
2853        ));
2854    }
2855
2856    #[test]
2857    fn test_config_working_dir_isolation_accepts_chat() {
2858        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nworking_dir_isolation: chat\n";
2859        let config: Config = serde_yaml::from_str(yaml).unwrap();
2860        assert!(matches!(
2861            config.working_dir_isolation,
2862            WorkingDirIsolation::Chat
2863        ));
2864    }
2865
2866    #[test]
2867    fn test_config_working_dir_isolation_accepts_true() {
2868        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nworking_dir_isolation: true\n";
2869        let config: Config = serde_yaml::from_str(yaml).unwrap();
2870        assert!(matches!(
2871            config.working_dir_isolation,
2872            WorkingDirIsolation::Chat
2873        ));
2874    }
2875
2876    #[test]
2877    fn test_config_working_dir_isolation_accepts_false() {
2878        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nworking_dir_isolation: false\n";
2879        let config: Config = serde_yaml::from_str(yaml).unwrap();
2880        assert!(matches!(
2881            config.working_dir_isolation,
2882            WorkingDirIsolation::Shared
2883        ));
2884    }
2885
2886    #[test]
2887    fn test_high_risk_tool_user_confirmation_required_defaults_true() {
2888        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\n";
2889        let config: Config = serde_yaml::from_str(yaml).unwrap();
2890        assert!(config.high_risk_tool_user_confirmation_required);
2891    }
2892
2893    #[test]
2894    fn test_high_risk_tool_user_confirmation_required_accepts_false() {
2895        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nhigh_risk_tool_user_confirmation_required: false\n";
2896        let config: Config = serde_yaml::from_str(yaml).unwrap();
2897        assert!(!config.high_risk_tool_user_confirmation_required);
2898    }
2899
2900    #[test]
2901    fn test_config_post_deserialize() {
2902        let yaml =
2903            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_provider: ANTHROPIC\n";
2904        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2905        config.post_deserialize().unwrap();
2906        assert_eq!(config.llm_provider, "anthropic");
2907        assert_eq!(config.model, "claude-sonnet-4-5-20250929");
2908    }
2909
2910    #[test]
2911    fn test_post_deserialize_invalid_timezone() {
2912        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\noverride_timezone: Mars/Olympus\n";
2913        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2914        let err = config.post_deserialize().unwrap_err();
2915        let msg = err.to_string();
2916        assert!(msg.contains("Invalid timezone"));
2917    }
2918
2919    #[test]
2920    fn test_post_deserialize_auto_timezone_resolves_to_valid_tz() {
2921        let yaml =
2922            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\noverride_timezone: auto\n";
2923        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2924        config.post_deserialize().unwrap();
2925        assert!(config.timezone.parse::<chrono_tz::Tz>().is_ok());
2926    }
2927
2928    #[test]
2929    fn test_post_deserialize_missing_api_key() {
2930        let yaml = "telegram_bot_token: tok\nbot_username: bot\n";
2931        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2932        let err = config.post_deserialize().unwrap_err();
2933        let msg = err.to_string();
2934        assert!(msg.contains("api_key is required"));
2935    }
2936
2937    #[test]
2938    fn test_post_deserialize_openai_codex_allows_empty_api_key() {
2939        let _guard = env_lock();
2940        let prev_codex_home = std::env::var("CODEX_HOME").ok();
2941        let prev_access = std::env::var("OPENAI_CODEX_ACCESS_TOKEN").ok();
2942        std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
2943
2944        let auth_dir = std::env::temp_dir().join(format!(
2945            "microclaw-codex-auth-{}",
2946            std::time::SystemTime::now()
2947                .duration_since(std::time::UNIX_EPOCH)
2948                .unwrap_or_default()
2949                .as_nanos()
2950        ));
2951        std::fs::create_dir_all(&auth_dir).unwrap();
2952        std::fs::write(
2953            auth_dir.join("auth.json"),
2954            r#"{"tokens":{"access_token":"tok"}}"#,
2955        )
2956        .unwrap();
2957        std::env::set_var("CODEX_HOME", &auth_dir);
2958
2959        let yaml =
2960            "telegram_bot_token: tok\nbot_username: bot\nllm_provider: openai-codex\nmodel: gpt-5.3-codex\n";
2961        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2962        config.post_deserialize().unwrap();
2963
2964        if let Some(prev) = prev_codex_home {
2965            std::env::set_var("CODEX_HOME", prev);
2966        } else {
2967            std::env::remove_var("CODEX_HOME");
2968        }
2969        if let Some(prev) = prev_access {
2970            std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", prev);
2971        } else {
2972            std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
2973        }
2974        let _ = std::fs::remove_file(auth_dir.join("auth.json"));
2975        let _ = std::fs::remove_dir(auth_dir);
2976        assert_eq!(config.llm_provider, "openai-codex");
2977    }
2978
2979    #[test]
2980    fn test_post_deserialize_missing_bot_tokens() {
2981        let yaml = "bot_username: bot\napi_key: key\nweb_enabled: false\n";
2982        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2983        let err = config.post_deserialize().unwrap_err();
2984        let msg = err.to_string();
2985        assert!(msg.contains("channel must be enabled"));
2986    }
2987
2988    #[test]
2989    fn test_post_deserialize_discord_only() {
2990        let yaml = "bot_username: bot\napi_key: key\ndiscord_bot_token: discord_tok\n";
2991        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
2992        // Should succeed: discord_bot_token is set even though telegram_bot_token is empty
2993        config.post_deserialize().unwrap();
2994    }
2995
2996    #[test]
2997    fn test_post_deserialize_irc_only() {
2998        let yaml = r##"
2999api_key: key
3000channels:
3001  irc:
3002    enabled: true
3003    server: "irc.example.com"
3004    nick: "microclaw"
3005    channels: "#microclaw"
3006"##;
3007        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3008        config.post_deserialize().unwrap();
3009        assert!(config.channel_enabled("irc"));
3010    }
3011
3012    #[test]
3013    fn test_post_deserialize_matrix_only() {
3014        let yaml = r##"
3015api_key: key
3016channels:
3017  matrix:
3018    enabled: true
3019    homeserver_url: "https://matrix.example.com"
3020    access_token: "syt_xxx"
3021    bot_user_id: "@microclaw:example.com"
3022"##;
3023        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3024        config.post_deserialize().unwrap();
3025        assert!(config.channel_enabled("matrix"));
3026    }
3027
3028    #[test]
3029    fn test_post_deserialize_channel_enabled_flag_overrides_legacy_inference() {
3030        let yaml = "telegram_bot_token: tok\nbot_username: bot\ndiscord_bot_token: discord_tok\napi_key: key\nchannels:\n  telegram:\n    enabled: false\n  discord:\n    enabled: true\n  web:\n    enabled: false\n";
3031        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3032        config.post_deserialize().unwrap();
3033
3034        assert!(!config.channel_enabled("telegram"));
3035        assert!(config.channel_enabled("discord"));
3036        assert!(!config.channel_enabled("web"));
3037    }
3038
3039    #[test]
3040    fn test_post_deserialize_channel_enabled_flag_controls_web() {
3041        let yaml =
3042            "api_key: key\ndiscord_bot_token: discord_tok\nchannels:\n  web:\n    enabled: false\n";
3043        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3044        config.post_deserialize().unwrap();
3045
3046        assert!(!config.channel_enabled("web"));
3047    }
3048
3049    #[test]
3050    fn test_post_deserialize_openai_default_model() {
3051        let yaml =
3052            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_provider: openai\n";
3053        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3054        config.post_deserialize().unwrap();
3055        assert_eq!(config.model, "gpt-5.2");
3056    }
3057
3058    #[test]
3059    fn test_post_deserialize_wildcard_model_falls_back_to_provider_default() {
3060        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_provider: openai\nmodel: '*'\n";
3061        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3062        config.post_deserialize().unwrap();
3063        assert_eq!(config.model, "gpt-5.2");
3064    }
3065
3066    #[test]
3067    fn test_post_deserialize_openai_codex_default_model() {
3068        let _guard = env_lock();
3069        let prev_codex_home = std::env::var("CODEX_HOME").ok();
3070        let prev_access = std::env::var("OPENAI_CODEX_ACCESS_TOKEN").ok();
3071        std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3072
3073        let auth_dir = std::env::temp_dir().join(format!(
3074            "microclaw-codex-auth-{}",
3075            std::time::SystemTime::now()
3076                .duration_since(std::time::UNIX_EPOCH)
3077                .unwrap_or_default()
3078                .as_nanos()
3079        ));
3080        std::fs::create_dir_all(&auth_dir).unwrap();
3081        std::fs::write(
3082            auth_dir.join("auth.json"),
3083            r#"{"tokens":{"access_token":"tok"}}"#,
3084        )
3085        .unwrap();
3086        std::env::set_var("CODEX_HOME", &auth_dir);
3087
3088        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: openai-codex\n";
3089        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3090        config.post_deserialize().unwrap();
3091
3092        if let Some(prev) = prev_codex_home {
3093            std::env::set_var("CODEX_HOME", prev);
3094        } else {
3095            std::env::remove_var("CODEX_HOME");
3096        }
3097        if let Some(prev) = prev_access {
3098            std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", prev);
3099        } else {
3100            std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3101        }
3102        let _ = std::fs::remove_file(auth_dir.join("auth.json"));
3103        let _ = std::fs::remove_dir(auth_dir);
3104        assert_eq!(config.model, "gpt-5.3-codex");
3105    }
3106
3107    #[test]
3108    fn test_post_deserialize_openai_codex_missing_oauth_token() {
3109        let _guard = env_lock();
3110        let prev_codex_home = std::env::var("CODEX_HOME").ok();
3111        let prev_access = std::env::var("OPENAI_CODEX_ACCESS_TOKEN").ok();
3112        std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3113
3114        let auth_dir = std::env::temp_dir().join(format!(
3115            "microclaw-codex-auth-missing-{}",
3116            std::time::SystemTime::now()
3117                .duration_since(std::time::UNIX_EPOCH)
3118                .unwrap_or_default()
3119                .as_nanos()
3120        ));
3121        std::fs::create_dir_all(&auth_dir).unwrap();
3122        std::env::set_var("CODEX_HOME", &auth_dir);
3123
3124        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: openai-codex\n";
3125        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3126        let err = config.post_deserialize().unwrap_err();
3127        let msg = err.to_string();
3128
3129        if let Some(prev) = prev_codex_home {
3130            std::env::set_var("CODEX_HOME", prev);
3131        } else {
3132            std::env::remove_var("CODEX_HOME");
3133        }
3134        if let Some(prev) = prev_access {
3135            std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", prev);
3136        } else {
3137            std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3138        }
3139        let _ = std::fs::remove_dir(auth_dir);
3140
3141        assert!(msg.contains("openai-codex requires ~/.codex/auth.json"));
3142    }
3143
3144    #[test]
3145    fn test_post_deserialize_openai_codex_rejects_plain_api_key_without_oauth() {
3146        let _guard = env_lock();
3147        let prev_codex_home = std::env::var("CODEX_HOME").ok();
3148        let prev_access = std::env::var("OPENAI_CODEX_ACCESS_TOKEN").ok();
3149        std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3150
3151        let auth_dir = std::env::temp_dir().join(format!(
3152            "microclaw-codex-auth-plain-key-{}",
3153            std::time::SystemTime::now()
3154                .duration_since(std::time::UNIX_EPOCH)
3155                .unwrap_or_default()
3156                .as_nanos()
3157        ));
3158        std::fs::create_dir_all(&auth_dir).unwrap();
3159        std::env::set_var("CODEX_HOME", &auth_dir);
3160
3161        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: openai-codex\napi_key: sk-user-stale\n";
3162        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3163        let err = config.post_deserialize().unwrap_err();
3164        let msg = err.to_string();
3165
3166        if let Some(prev) = prev_codex_home {
3167            std::env::set_var("CODEX_HOME", prev);
3168        } else {
3169            std::env::remove_var("CODEX_HOME");
3170        }
3171        if let Some(prev) = prev_access {
3172            std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", prev);
3173        } else {
3174            std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3175        }
3176        let _ = std::fs::remove_dir(auth_dir);
3177
3178        assert!(msg.contains("ignores microclaw.config.yaml api_key"));
3179    }
3180
3181    #[test]
3182    fn test_post_deserialize_openai_codex_allows_env_access_token() {
3183        let _guard = env_lock();
3184        let prev_codex_home = std::env::var("CODEX_HOME").ok();
3185        let prev_access = std::env::var("OPENAI_CODEX_ACCESS_TOKEN").ok();
3186        std::env::remove_var("CODEX_HOME");
3187        std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", "env-token");
3188
3189        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: openai-codex\n";
3190        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3191        config.post_deserialize().unwrap();
3192
3193        if let Some(prev) = prev_codex_home {
3194            std::env::set_var("CODEX_HOME", prev);
3195        } else {
3196            std::env::remove_var("CODEX_HOME");
3197        }
3198        if let Some(prev) = prev_access {
3199            std::env::set_var("OPENAI_CODEX_ACCESS_TOKEN", prev);
3200        } else {
3201            std::env::remove_var("OPENAI_CODEX_ACCESS_TOKEN");
3202        }
3203
3204        assert_eq!(config.llm_provider, "openai-codex");
3205    }
3206
3207    #[test]
3208    fn test_post_deserialize_qwen_code_allows_oauth_without_api_key() {
3209        let _guard = env_lock();
3210        let prev_qwen_home = std::env::var("QWEN_HOME").ok();
3211        let prev_qwen_access = std::env::var("QWEN_PORTAL_ACCESS_TOKEN").ok();
3212        std::env::remove_var("QWEN_PORTAL_ACCESS_TOKEN");
3213
3214        let qwen_dir = std::env::temp_dir().join(format!(
3215            "microclaw-qwen-auth-{}",
3216            std::time::SystemTime::now()
3217                .duration_since(std::time::UNIX_EPOCH)
3218                .unwrap_or_default()
3219                .as_nanos()
3220        ));
3221        std::fs::create_dir_all(&qwen_dir).unwrap();
3222        std::fs::write(
3223            qwen_dir.join("oauth_creds.json"),
3224            r#"{"access_token":"qwen-oauth-token"}"#,
3225        )
3226        .unwrap();
3227        std::env::set_var("QWEN_HOME", &qwen_dir);
3228
3229        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: qwen-portal\n";
3230        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3231        config.post_deserialize().unwrap();
3232
3233        if let Some(prev) = prev_qwen_home {
3234            std::env::set_var("QWEN_HOME", prev);
3235        } else {
3236            std::env::remove_var("QWEN_HOME");
3237        }
3238        if let Some(prev) = prev_qwen_access {
3239            std::env::set_var("QWEN_PORTAL_ACCESS_TOKEN", prev);
3240        } else {
3241            std::env::remove_var("QWEN_PORTAL_ACCESS_TOKEN");
3242        }
3243        let _ = std::fs::remove_file(qwen_dir.join("oauth_creds.json"));
3244        let _ = std::fs::remove_dir(qwen_dir);
3245
3246        assert_eq!(config.llm_provider, "qwen-portal");
3247    }
3248
3249    #[test]
3250    fn test_post_deserialize_qwen_code_missing_oauth_and_api_key() {
3251        let _guard = env_lock();
3252        let prev_qwen_home = std::env::var("QWEN_HOME").ok();
3253        let prev_qwen_access = std::env::var("QWEN_PORTAL_ACCESS_TOKEN").ok();
3254        std::env::remove_var("QWEN_PORTAL_ACCESS_TOKEN");
3255
3256        let qwen_dir = std::env::temp_dir().join(format!(
3257            "microclaw-qwen-auth-missing-{}",
3258            std::time::SystemTime::now()
3259                .duration_since(std::time::UNIX_EPOCH)
3260                .unwrap_or_default()
3261                .as_nanos()
3262        ));
3263        std::fs::create_dir_all(&qwen_dir).unwrap();
3264        std::env::set_var("QWEN_HOME", &qwen_dir);
3265
3266        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: qwen-portal\n";
3267        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3268        let err = config.post_deserialize().unwrap_err();
3269
3270        if let Some(prev) = prev_qwen_home {
3271            std::env::set_var("QWEN_HOME", prev);
3272        } else {
3273            std::env::remove_var("QWEN_HOME");
3274        }
3275        if let Some(prev) = prev_qwen_access {
3276            std::env::set_var("QWEN_PORTAL_ACCESS_TOKEN", prev);
3277        } else {
3278            std::env::remove_var("QWEN_PORTAL_ACCESS_TOKEN");
3279        }
3280        let _ = std::fs::remove_dir(qwen_dir);
3281
3282        assert!(err
3283            .to_string()
3284            .contains("qwen-portal requires api_key, or ~/.qwen/oauth_creds.json"));
3285    }
3286
3287    #[test]
3288    fn test_post_deserialize_ollama_default_model_and_empty_key() {
3289        let yaml = "telegram_bot_token: tok\nbot_username: bot\nllm_provider: ollama\n";
3290        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3291        config.post_deserialize().unwrap();
3292        assert_eq!(config.model, "llama3.2");
3293    }
3294
3295    #[test]
3296    fn test_post_deserialize_empty_base_url_becomes_none() {
3297        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_base_url: '  '\n";
3298        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3299        config.post_deserialize().unwrap();
3300        assert!(config.llm_base_url.is_none());
3301    }
3302
3303    #[test]
3304    fn test_post_deserialize_empty_llm_user_agent_uses_default() {
3305        let yaml =
3306            "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_user_agent: '  '\n";
3307        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3308        config.post_deserialize().unwrap();
3309        assert_eq!(
3310            config.llm_user_agent,
3311            crate::http_client::default_llm_user_agent()
3312        );
3313    }
3314
3315    #[test]
3316    fn test_post_deserialize_provider_case_insensitive() {
3317        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nllm_provider: '  ANTHROPIC  '\n";
3318        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3319        config.post_deserialize().unwrap();
3320        assert_eq!(config.llm_provider, "anthropic");
3321        assert_eq!(config.model, "claude-sonnet-4-5-20250929");
3322    }
3323
3324    #[test]
3325    fn test_post_deserialize_normalizes_openai_compat_body_overrides() {
3326        let yaml = r#"
3327telegram_bot_token: tok
3328bot_username: bot
3329api_key: key
3330openai_compat_body_overrides:
3331  " temperature ": 0.2
3332  "  ": 1
3333openai_compat_body_overrides_by_provider:
3334  " OPENAI ":
3335    " top_p ": 0.95
3336    "": 1
3337  "  ":
3338    seed: 7
3339openai_compat_body_overrides_by_model:
3340  " gpt-5.2 ":
3341    " frequency_penalty ": 0.1
3342    "": 1
3343  " ":
3344    seed: 7
3345"#;
3346        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3347        config.post_deserialize().unwrap();
3348
3349        assert_eq!(
3350            config.openai_compat_body_overrides.get("temperature"),
3351            Some(&serde_json::json!(0.2))
3352        );
3353        assert!(!config.openai_compat_body_overrides.contains_key("  "));
3354
3355        let provider_params = config
3356            .openai_compat_body_overrides_by_provider
3357            .get("openai")
3358            .unwrap();
3359        assert_eq!(provider_params.get("top_p"), Some(&serde_json::json!(0.95)));
3360        assert!(!provider_params.contains_key(""));
3361        assert!(!config
3362            .openai_compat_body_overrides_by_provider
3363            .contains_key(" OPENAI "));
3364
3365        let model_params = config
3366            .openai_compat_body_overrides_by_model
3367            .get("gpt-5.2")
3368            .unwrap();
3369        assert_eq!(
3370            model_params.get("frequency_penalty"),
3371            Some(&serde_json::json!(0.1))
3372        );
3373        assert!(!model_params.contains_key(""));
3374    }
3375
3376    #[test]
3377    fn test_post_deserialize_normalizes_subagent_acp_config() {
3378        let yaml = r#"
3379telegram_bot_token: tok
3380bot_username: bot
3381api_key: key
3382subagents:
3383  acp:
3384    enabled: true
3385    command: "  codex  "
3386    args: ["  --model  ", " ", "gpt-5.4"]
3387    env:
3388      " OPENAI_API_KEY ": abc
3389      "   ": ignored
3390    default_target: "  worker  "
3391    targets:
3392      " worker ":
3393        enabled: true
3394        command: "  codex-worker  "
3395        args: [" --fast "]
3396        env:
3397          " TOKEN ": xyz
3398"#;
3399        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3400        config.post_deserialize().unwrap();
3401
3402        assert!(config.subagents.acp.default_target.enabled);
3403        assert_eq!(config.subagents.acp.default_target.command, "codex");
3404        assert_eq!(
3405            config.subagents.acp.default_target.args,
3406            vec!["--model".to_string(), "gpt-5.4".to_string()]
3407        );
3408        assert_eq!(
3409            config
3410                .subagents
3411                .acp
3412                .default_target
3413                .env
3414                .get("OPENAI_API_KEY"),
3415            Some(&"abc".to_string())
3416        );
3417        assert_eq!(
3418            config.subagents.acp.default_target_name.as_deref(),
3419            Some("worker")
3420        );
3421        assert!(!config.subagents.acp.default_target.env.contains_key("   "));
3422        let target = config.subagents.acp.targets.get("worker").unwrap();
3423        assert!(target.enabled);
3424        assert_eq!(target.command, "codex-worker");
3425        assert_eq!(target.args, vec!["--fast".to_string()]);
3426        assert_eq!(target.env.get("TOKEN"), Some(&"xyz".to_string()));
3427    }
3428
3429    #[test]
3430    fn test_post_deserialize_web_non_local_no_token_required() {
3431        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nweb_enabled: true\nweb_host: 0.0.0.0\n";
3432        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3433        config.post_deserialize().unwrap();
3434    }
3435
3436    #[test]
3437    fn test_post_deserialize_web_channel_auth_token_is_removed() {
3438        let yaml = "telegram_bot_token: tok\nbot_username: bot\napi_key: key\nweb_enabled: true\nweb_host: 0.0.0.0\nchannels:\n  web:\n    enabled: true\n    auth_token: token123\n";
3439        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3440        config.post_deserialize().unwrap();
3441        let has_auth_token = config
3442            .channels
3443            .get("web")
3444            .and_then(|v| v.as_mapping())
3445            .map(|map| map.contains_key(serde_yaml::Value::String("auth_token".to_string())))
3446            .unwrap_or(false);
3447        assert!(!has_auth_token);
3448    }
3449
3450    #[test]
3451    fn test_model_prices_parse_and_estimate() {
3452        let yaml = r#"
3453telegram_bot_token: tok
3454bot_username: bot
3455api_key: key
3456model_prices:
3457  - model: claude-sonnet-4-5-20250929
3458    input_per_million_usd: 3.0
3459    output_per_million_usd: 15.0
3460"#;
3461        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3462        config.post_deserialize().unwrap();
3463        let est = config
3464            .estimate_cost_usd("claude-sonnet-4-5-20250929", 1000, 2000)
3465            .unwrap();
3466        assert!((est - 0.033).abs() < 1e-9);
3467    }
3468
3469    #[test]
3470    fn test_model_prices_invalid_rejected() {
3471        let yaml = r#"
3472telegram_bot_token: tok
3473bot_username: bot
3474api_key: key
3475model_prices:
3476  - model: ""
3477    input_per_million_usd: 1.0
3478    output_per_million_usd: 1.0
3479"#;
3480        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3481        let err = config.post_deserialize().unwrap_err();
3482        assert!(err
3483            .to_string()
3484            .contains("model_prices entries must include non-empty model"));
3485    }
3486
3487    #[test]
3488    fn test_config_yaml_with_all_optional_fields() {
3489        let yaml = r#"
3490telegram_bot_token: tok
3491bot_username: bot
3492api_key: key
3493openai_api_key: sk-test
3494override_timezone: US/Eastern
3495allowed_groups: [123, 456]
3496control_chat_ids: [999]
3497max_session_messages: 60
3498compact_keep_recent: 30
3499discord_bot_token: discord_tok
3500discord_allowed_channels: [111, 222]
3501"#;
3502        let mut config: Config = serde_yaml::from_str(yaml).unwrap();
3503        config.post_deserialize().unwrap();
3504        assert_eq!(config.openai_api_key.as_deref(), Some("sk-test"));
3505        assert_eq!(config.timezone, "US/Eastern");
3506        assert_eq!(config.allowed_groups, vec![123, 456]);
3507        assert_eq!(config.control_chat_ids, vec![999]);
3508        assert_eq!(config.max_session_messages, 60);
3509        assert_eq!(config.compact_keep_recent, 30);
3510        assert_eq!(config.discord_allowed_channels, vec![111, 222]);
3511    }
3512
3513    #[test]
3514    fn test_expand_path_with_tilde() {
3515        let home = PathBuf::from(shellexpand::tilde("~").as_ref());
3516        let path = "~/foo/bar";
3517        let expanded = expand_path(path);
3518        assert_eq!(expanded, home.join("foo/bar"));
3519
3520        let path = "~";
3521        let expanded = expand_path(path);
3522        assert_eq!(expanded, home);
3523
3524        let path = "/absolute/path";
3525        let expanded = expand_path(path);
3526        assert_eq!(expanded, std::path::PathBuf::from("/absolute/path"));
3527    }
3528
3529    #[test]
3530    fn unknown_top_level_key_is_flagged() {
3531        let map = mapping_of("definitely_not_a_key: true\napi_key: k\n");
3532        let warnings = unknown_top_level_key_warnings(&map);
3533        assert!(
3534            warnings.iter().any(|w| w.contains("definitely_not_a_key")),
3535            "expected an unknown-key warning, got: {warnings:?}"
3536        );
3537        // A real key in the same document must not be flagged.
3538        assert!(
3539            !warnings.iter().any(|w| w.contains("`api_key`")),
3540            "api_key should be recognized, got: {warnings:?}"
3541        );
3542    }
3543
3544    #[test]
3545    fn unknown_key_gets_did_you_mean() {
3546        // `api_ky` is one edit away from the real `api_key`.
3547        let map = mapping_of("api_ky: k\n");
3548        let warnings = unknown_top_level_key_warnings(&map);
3549        assert!(
3550            warnings
3551                .iter()
3552                .any(|w| w.contains("api_ky") && w.contains("did you mean `api_key`")),
3553            "expected a did-you-mean suggestion, got: {warnings:?}"
3554        );
3555    }
3556
3557    #[test]
3558    fn known_top_level_keys_produce_no_warnings() {
3559        // A spread of real keys: plain fields, a nested struct, the flattened
3560        // clawhub_* keys, and the skip-serialized timezone fields.
3561        let yaml = "api_key: k\ntelegram_bot_token: t\nclawhub_registry: https://x\n\
3562timezone: UTC\noverride_timezone: UTC\nsandbox:\n  enabled: false\n";
3563        let warnings = unknown_top_level_key_warnings(&mapping_of(yaml));
3564        assert!(warnings.is_empty(), "unexpected warnings: {warnings:?}");
3565    }
3566}