Skip to main content

microclaw_engine/config/
core.rs

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