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