1use serde::Serialize;
7use std::collections::BTreeMap;
8
9#[derive(Debug, Clone, Serialize)]
10pub struct ConfigSchema {
11 pub version: u32,
12 pub sections: BTreeMap<String, SectionSchema>,
13}
14
15#[derive(Debug, Clone, Serialize)]
16pub struct SectionSchema {
17 pub description: String,
18 pub keys: BTreeMap<String, KeySchema>,
19}
20
21#[derive(Debug, Clone, Serialize)]
22pub struct KeySchema {
23 #[serde(rename = "type")]
24 pub ty: String,
25 pub default: serde_json::Value,
26 pub description: String,
27 #[serde(skip_serializing_if = "Option::is_none")]
28 pub values: Option<Vec<String>>,
29 #[serde(skip_serializing_if = "Option::is_none")]
30 pub env_override: Option<String>,
31}
32
33fn clean_f32(v: f32) -> serde_json::Value {
34 let clean: f64 = format!("{v}").parse().unwrap_or(v as f64);
35 serde_json::json!(clean)
36}
37
38fn key(ty: &str, default: serde_json::Value, desc: &str) -> KeySchema {
39 KeySchema {
40 ty: ty.to_string(),
41 default,
42 description: desc.to_string(),
43 values: None,
44 env_override: None,
45 }
46}
47
48fn key_enum(values: &[&str], default: &str, desc: &str) -> KeySchema {
49 KeySchema {
50 ty: "enum".to_string(),
51 default: serde_json::Value::String(default.to_string()),
52 description: desc.to_string(),
53 values: Some(values.iter().map(ToString::to_string).collect()),
54 env_override: None,
55 }
56}
57
58fn key_with_env(ty: &str, default: serde_json::Value, desc: &str, env: &str) -> KeySchema {
59 KeySchema {
60 ty: ty.to_string(),
61 default,
62 description: desc.to_string(),
63 values: None,
64 env_override: Some(env.to_string()),
65 }
66}
67
68fn key_enum_with_env(values: &[&str], default: &str, desc: &str, env: &str) -> KeySchema {
69 KeySchema {
70 ty: "enum".to_string(),
71 default: serde_json::Value::String(default.to_string()),
72 description: desc.to_string(),
73 values: Some(values.iter().map(ToString::to_string).collect()),
74 env_override: Some(env.to_string()),
75 }
76}
77
78impl ConfigSchema {
79 pub fn generate() -> Self {
80 let cfg = super::Config::default();
81 let mut sections = BTreeMap::new();
82
83 let mut root = BTreeMap::new();
84 root.insert(
85 "ultra_compact".into(),
86 key(
87 "bool",
88 serde_json::json!(false),
89 "Legacy flag for maximum compression (use compression_level instead)",
90 ),
91 );
92 root.insert(
93 "tee_mode".into(),
94 key_enum(
95 &["never", "failures", "always"],
96 "failures",
97 "Controls when shell output is tee'd to disk for later retrieval",
98 ),
99 );
100 root.insert(
101 "output_density".into(),
102 key_enum_with_env(
103 &["normal", "terse", "ultra"],
104 "normal",
105 "Controls how dense/compact MCP tool output is formatted",
106 "LEAN_CTX_OUTPUT_DENSITY",
107 ),
108 );
109 root.insert(
110 "checkpoint_interval".into(),
111 key(
112 "u32",
113 serde_json::json!(cfg.checkpoint_interval),
114 "Session checkpoint interval in minutes",
115 ),
116 );
117 root.insert(
118 "excluded_commands".into(),
119 key(
120 "string[]",
121 serde_json::json!(cfg.excluded_commands),
122 "Commands to exclude from shell hook interception",
123 ),
124 );
125 root.insert(
126 "passthrough_urls".into(),
127 key(
128 "string[]",
129 serde_json::json!(cfg.passthrough_urls),
130 "URLs to pass through without proxy interception",
131 ),
132 );
133 root.insert("slow_command_threshold_ms".into(), key("u64", serde_json::json!(cfg.slow_command_threshold_ms), "Commands taking longer than this (ms) are recorded in the slow log. Set to 0 to disable"));
134 root.insert(
135 "theme".into(),
136 key(
137 "string",
138 serde_json::json!(cfg.theme),
139 "Dashboard color theme",
140 ),
141 );
142 root.insert(
143 "buddy_enabled".into(),
144 key(
145 "bool",
146 serde_json::json!(cfg.buddy_enabled),
147 "Enable the buddy system for multi-agent coordination",
148 ),
149 );
150 root.insert(
151 "enable_wakeup_ctx".into(),
152 key(
153 "bool",
154 serde_json::json!(cfg.enable_wakeup_ctx),
155 "Append wakeup briefing (facts, session summary) to ctx_overview output. Set false to reduce context bloat when calling ctx_overview frequently.",
156 ),
157 );
158 root.insert(
159 "redirect_exclude".into(),
160 key(
161 "string[]",
162 serde_json::json!(cfg.redirect_exclude),
163 "URL patterns to exclude from proxy redirection",
164 ),
165 );
166 root.insert(
167 "disabled_tools".into(),
168 key(
169 "string[]",
170 serde_json::json!(cfg.disabled_tools),
171 "Tools to exclude from the MCP tool list",
172 ),
173 );
174 root.insert(
175 "rules_scope".into(),
176 key_enum(
177 &["both", "global", "project"],
178 "both",
179 "Where agent rule files are installed. Override via LEAN_CTX_RULES_SCOPE",
180 ),
181 );
182 root.insert(
183 "extra_ignore_patterns".into(),
184 key(
185 "string[]",
186 serde_json::json!(cfg.extra_ignore_patterns),
187 "Extra glob patterns to ignore in graph/overview/preload",
188 ),
189 );
190 root.insert(
191 "terse_agent".into(),
192 key_enum_with_env(
193 &["off", "lite", "full", "ultra"],
194 "off",
195 "Controls agent output verbosity via instructions injection",
196 "LEAN_CTX_TERSE_AGENT",
197 ),
198 );
199 root.insert(
200 "compression_level".into(),
201 key_enum_with_env(
202 &["off", "lite", "standard", "max"],
203 "off",
204 "Unified compression level for all output",
205 "LEAN_CTX_COMPRESSION",
206 ),
207 );
208 root.insert(
209 "allow_paths".into(),
210 key_with_env(
211 "string[]",
212 serde_json::json!(cfg.allow_paths),
213 "Additional paths allowed by PathJail (absolute)",
214 "LEAN_CTX_ALLOW_PATH",
215 ),
216 );
217 root.insert(
218 "content_defined_chunking".into(),
219 key(
220 "bool",
221 serde_json::json!(false),
222 "Enable Rabin-Karp chunking for cache-optimal output ordering",
223 ),
224 );
225 root.insert(
226 "minimal_overhead".into(),
227 key_with_env(
228 "bool",
229 serde_json::json!(false),
230 "Skip session/knowledge/gotcha blocks in MCP instructions",
231 "LEAN_CTX_MINIMAL",
232 ),
233 );
234 root.insert(
235 "shell_hook_disabled".into(),
236 key_with_env(
237 "bool",
238 serde_json::json!(false),
239 "Disable shell hook injection",
240 "LEAN_CTX_NO_HOOK",
241 ),
242 );
243 root.insert(
244 "shell_activation".into(),
245 key_enum_with_env(
246 &["always", "agents-only", "off"],
247 "always",
248 "Controls when the shell hook auto-activates aliases",
249 "LEAN_CTX_SHELL_ACTIVATION",
250 ),
251 );
252 root.insert(
253 "update_check_disabled".into(),
254 key_with_env(
255 "bool",
256 serde_json::json!(false),
257 "Disable the daily version check",
258 "LEAN_CTX_NO_UPDATE_CHECK",
259 ),
260 );
261 root.insert(
262 "bm25_max_cache_mb".into(),
263 key_with_env(
264 "u64",
265 serde_json::json!(cfg.bm25_max_cache_mb),
266 "Maximum BM25 cache file size in MB",
267 "LEAN_CTX_BM25_MAX_CACHE_MB",
268 ),
269 );
270 root.insert(
271 "graph_index_max_files".into(),
272 key(
273 "u64",
274 serde_json::json!(cfg.graph_index_max_files),
275 "Maximum files in graph index. 0 = unlimited (default). Set >0 to cap for constrained systems",
276 ),
277 );
278 root.insert(
279 "memory_profile".into(),
280 key_enum_with_env(
281 &["low", "balanced", "performance"],
282 "balanced",
283 "Controls RAM vs feature trade-off",
284 "LEAN_CTX_MEMORY_PROFILE",
285 ),
286 );
287 root.insert(
288 "memory_cleanup".into(),
289 key_enum_with_env(
290 &["aggressive", "shared"],
291 "aggressive",
292 "Controls how aggressively memory is freed when idle",
293 "LEAN_CTX_MEMORY_CLEANUP",
294 ),
295 );
296 root.insert(
297 "savings_footer".into(),
298 key_enum_with_env(
299 &["auto", "always", "never"],
300 "never",
301 "Controls visibility of token savings footers: never (default, suppress everywhere), always, auto (context-dependent)",
302 "LEAN_CTX_SAVINGS_FOOTER",
303 ),
304 );
305 root.insert(
306 "max_ram_percent".into(),
307 key_with_env(
308 "u8",
309 serde_json::json!(cfg.max_ram_percent),
310 "Maximum percentage of system RAM that lean-ctx may use (1-50, default 5)",
311 "LEAN_CTX_MAX_RAM_PERCENT",
312 ),
313 );
314 sections.insert(
315 "root".into(),
316 SectionSchema {
317 description: "Top-level configuration keys".into(),
318 keys: root,
319 },
320 );
321
322 let mut archive = BTreeMap::new();
323 archive.insert(
324 "enabled".into(),
325 key(
326 "bool",
327 serde_json::json!(cfg.archive.enabled),
328 "Enable zero-loss compression archive",
329 ),
330 );
331 archive.insert(
332 "threshold_chars".into(),
333 key(
334 "usize",
335 serde_json::json!(cfg.archive.threshold_chars),
336 "Minimum output size (chars) to trigger archiving",
337 ),
338 );
339 archive.insert(
340 "max_age_hours".into(),
341 key(
342 "u64",
343 serde_json::json!(cfg.archive.max_age_hours),
344 "Maximum age of archived entries before cleanup",
345 ),
346 );
347 archive.insert(
348 "max_disk_mb".into(),
349 key(
350 "u64",
351 serde_json::json!(cfg.archive.max_disk_mb),
352 "Maximum total disk usage for the archive",
353 ),
354 );
355 sections.insert("archive".into(), SectionSchema {
356 description: "Settings for the zero-loss compression archive (large tool outputs saved to disk)".into(),
357 keys: archive,
358 });
359
360 let mut autonomy = BTreeMap::new();
361 autonomy.insert(
362 "enabled".into(),
363 key(
364 "bool",
365 serde_json::json!(cfg.autonomy.enabled),
366 "Enable autonomous background behaviors",
367 ),
368 );
369 autonomy.insert(
370 "auto_preload".into(),
371 key(
372 "bool",
373 serde_json::json!(cfg.autonomy.auto_preload),
374 "Auto-preload related files on first read",
375 ),
376 );
377 autonomy.insert(
378 "auto_dedup".into(),
379 key(
380 "bool",
381 serde_json::json!(cfg.autonomy.auto_dedup),
382 "Auto-deduplicate repeated reads",
383 ),
384 );
385 autonomy.insert(
386 "auto_related".into(),
387 key(
388 "bool",
389 serde_json::json!(cfg.autonomy.auto_related),
390 "Auto-load graph-related files",
391 ),
392 );
393 autonomy.insert(
394 "auto_consolidate".into(),
395 key(
396 "bool",
397 serde_json::json!(cfg.autonomy.auto_consolidate),
398 "Auto-consolidate knowledge periodically",
399 ),
400 );
401 autonomy.insert(
402 "silent_preload".into(),
403 key(
404 "bool",
405 serde_json::json!(cfg.autonomy.silent_preload),
406 "Suppress preload notifications in output",
407 ),
408 );
409 autonomy.insert(
410 "dedup_threshold".into(),
411 key(
412 "usize",
413 serde_json::json!(cfg.autonomy.dedup_threshold),
414 "Number of repeated reads before dedup triggers",
415 ),
416 );
417 autonomy.insert(
418 "consolidate_every_calls".into(),
419 key(
420 "u32",
421 serde_json::json!(cfg.autonomy.consolidate_every_calls),
422 "Consolidate knowledge every N tool calls",
423 ),
424 );
425 autonomy.insert(
426 "consolidate_cooldown_secs".into(),
427 key(
428 "u64",
429 serde_json::json!(cfg.autonomy.consolidate_cooldown_secs),
430 "Minimum seconds between consolidation runs",
431 ),
432 );
433 sections.insert(
434 "autonomy".into(),
435 SectionSchema {
436 description:
437 "Controls autonomous background behaviors (preload, dedup, consolidation)"
438 .into(),
439 keys: autonomy,
440 },
441 );
442
443 let mut loop_det = BTreeMap::new();
444 loop_det.insert(
445 "normal_threshold".into(),
446 key(
447 "u32",
448 serde_json::json!(cfg.loop_detection.normal_threshold),
449 "Repetitions before reducing output",
450 ),
451 );
452 loop_det.insert(
453 "reduced_threshold".into(),
454 key(
455 "u32",
456 serde_json::json!(cfg.loop_detection.reduced_threshold),
457 "Repetitions before further reducing output",
458 ),
459 );
460 loop_det.insert(
461 "blocked_threshold".into(),
462 key(
463 "u32",
464 serde_json::json!(cfg.loop_detection.blocked_threshold),
465 "Repetitions before blocking. 0 = disabled",
466 ),
467 );
468 loop_det.insert(
469 "window_secs".into(),
470 key(
471 "u64",
472 serde_json::json!(cfg.loop_detection.window_secs),
473 "Time window in seconds for loop detection",
474 ),
475 );
476 loop_det.insert(
477 "search_group_limit".into(),
478 key(
479 "u32",
480 serde_json::json!(cfg.loop_detection.search_group_limit),
481 "Maximum unique searches within a loop window",
482 ),
483 );
484 sections.insert(
485 "loop_detection".into(),
486 SectionSchema {
487 description: "Loop detection settings for preventing repeated identical tool calls"
488 .into(),
489 keys: loop_det,
490 },
491 );
492
493 let mut cloud = BTreeMap::new();
494 cloud.insert(
495 "contribute_enabled".into(),
496 key(
497 "bool",
498 serde_json::json!(cfg.cloud.contribute_enabled),
499 "Enable contributing anonymized stats to lean-ctx cloud",
500 ),
501 );
502 sections.insert(
503 "cloud".into(),
504 SectionSchema {
505 description: "Cloud feature settings".into(),
506 keys: cloud,
507 },
508 );
509
510 let mut proxy = BTreeMap::new();
511 proxy.insert(
512 "anthropic_upstream".into(),
513 key(
514 "string?",
515 serde_json::json!(cfg.proxy.anthropic_upstream),
516 "Custom upstream URL for Anthropic API proxy",
517 ),
518 );
519 proxy.insert(
520 "openai_upstream".into(),
521 key(
522 "string?",
523 serde_json::json!(cfg.proxy.openai_upstream),
524 "Custom upstream URL for OpenAI API proxy",
525 ),
526 );
527 proxy.insert(
528 "gemini_upstream".into(),
529 key(
530 "string?",
531 serde_json::json!(cfg.proxy.gemini_upstream),
532 "Custom upstream URL for Gemini API proxy",
533 ),
534 );
535 sections.insert(
536 "proxy".into(),
537 SectionSchema {
538 description: "Proxy upstream configuration for API routing".into(),
539 keys: proxy,
540 },
541 );
542
543 let mem = &cfg.memory;
544 let mut mem_knowledge = BTreeMap::new();
545 mem_knowledge.insert(
546 "max_facts".into(),
547 key(
548 "usize",
549 serde_json::json!(mem.knowledge.max_facts),
550 "Maximum number of knowledge facts stored per project",
551 ),
552 );
553 mem_knowledge.insert(
554 "max_patterns".into(),
555 key(
556 "usize",
557 serde_json::json!(mem.knowledge.max_patterns),
558 "Maximum number of patterns stored",
559 ),
560 );
561 mem_knowledge.insert(
562 "max_history".into(),
563 key(
564 "usize",
565 serde_json::json!(mem.knowledge.max_history),
566 "Maximum history entries retained",
567 ),
568 );
569 mem_knowledge.insert(
570 "contradiction_threshold".into(),
571 key(
572 "f32",
573 clean_f32(mem.knowledge.contradiction_threshold),
574 "Confidence threshold for contradiction detection",
575 ),
576 );
577 mem_knowledge.insert(
578 "recall_facts_limit".into(),
579 key(
580 "usize",
581 serde_json::json!(mem.knowledge.recall_facts_limit),
582 "Maximum facts returned per recall query",
583 ),
584 );
585 mem_knowledge.insert(
586 "rooms_limit".into(),
587 key(
588 "usize",
589 serde_json::json!(mem.knowledge.rooms_limit),
590 "Maximum number of rooms returned",
591 ),
592 );
593 mem_knowledge.insert(
594 "timeline_limit".into(),
595 key(
596 "usize",
597 serde_json::json!(mem.knowledge.timeline_limit),
598 "Maximum number of timeline entries returned",
599 ),
600 );
601 mem_knowledge.insert(
602 "relations_limit".into(),
603 key(
604 "usize",
605 serde_json::json!(mem.knowledge.relations_limit),
606 "Maximum number of relations returned",
607 ),
608 );
609 sections.insert(
610 "memory.knowledge".into(),
611 SectionSchema {
612 description: "Knowledge memory budgets (facts, patterns, gotchas)".into(),
613 keys: mem_knowledge,
614 },
615 );
616
617 let mut mem_episodic = BTreeMap::new();
618 mem_episodic.insert(
619 "max_episodes".into(),
620 key(
621 "usize",
622 serde_json::json!(mem.episodic.max_episodes),
623 "Maximum number of episodes retained",
624 ),
625 );
626 mem_episodic.insert(
627 "max_actions_per_episode".into(),
628 key(
629 "usize",
630 serde_json::json!(mem.episodic.max_actions_per_episode),
631 "Maximum actions tracked per episode",
632 ),
633 );
634 mem_episodic.insert(
635 "summary_max_chars".into(),
636 key(
637 "usize",
638 serde_json::json!(mem.episodic.summary_max_chars),
639 "Maximum characters in episode summary",
640 ),
641 );
642 sections.insert(
643 "memory.episodic".into(),
644 SectionSchema {
645 description: "Episodic memory budgets (session episodes)".into(),
646 keys: mem_episodic,
647 },
648 );
649
650 let mut mem_procedural = BTreeMap::new();
651 mem_procedural.insert(
652 "max_procedures".into(),
653 key(
654 "usize",
655 serde_json::json!(mem.procedural.max_procedures),
656 "Maximum number of learned procedures stored",
657 ),
658 );
659 mem_procedural.insert(
660 "min_repetitions".into(),
661 key(
662 "usize",
663 serde_json::json!(mem.procedural.min_repetitions),
664 "Minimum repetitions before a pattern is stored",
665 ),
666 );
667 mem_procedural.insert(
668 "min_sequence_len".into(),
669 key(
670 "usize",
671 serde_json::json!(mem.procedural.min_sequence_len),
672 "Minimum sequence length for procedure detection",
673 ),
674 );
675 mem_procedural.insert(
676 "max_window_size".into(),
677 key(
678 "usize",
679 serde_json::json!(mem.procedural.max_window_size),
680 "Maximum window size for pattern analysis",
681 ),
682 );
683 sections.insert(
684 "memory.procedural".into(),
685 SectionSchema {
686 description: "Procedural memory budgets (learned patterns)".into(),
687 keys: mem_procedural,
688 },
689 );
690
691 let mut mem_lifecycle = BTreeMap::new();
692 mem_lifecycle.insert(
693 "decay_rate".into(),
694 key(
695 "f32",
696 clean_f32(mem.lifecycle.decay_rate),
697 "Rate at which knowledge confidence decays over time",
698 ),
699 );
700 mem_lifecycle.insert(
701 "low_confidence_threshold".into(),
702 key(
703 "f32",
704 clean_f32(mem.lifecycle.low_confidence_threshold),
705 "Threshold below which facts are considered low-confidence",
706 ),
707 );
708 mem_lifecycle.insert(
709 "stale_days".into(),
710 key(
711 "i64",
712 serde_json::json!(mem.lifecycle.stale_days),
713 "Days after which unused facts are considered stale",
714 ),
715 );
716 mem_lifecycle.insert(
717 "similarity_threshold".into(),
718 key(
719 "f32",
720 clean_f32(mem.lifecycle.similarity_threshold),
721 "Similarity threshold for deduplication",
722 ),
723 );
724 sections.insert(
725 "memory.lifecycle".into(),
726 SectionSchema {
727 description: "Knowledge lifecycle policy (decay, staleness, dedup)".into(),
728 keys: mem_lifecycle,
729 },
730 );
731
732 let mut mem_gotcha = BTreeMap::new();
733 mem_gotcha.insert(
734 "max_gotchas_per_project".into(),
735 key(
736 "usize",
737 serde_json::json!(mem.gotcha.max_gotchas_per_project),
738 "Maximum gotchas stored per project",
739 ),
740 );
741 mem_gotcha.insert(
742 "retrieval_budget_per_room".into(),
743 key(
744 "usize",
745 serde_json::json!(mem.gotcha.retrieval_budget_per_room),
746 "Maximum gotchas retrieved per room per query",
747 ),
748 );
749 mem_gotcha.insert(
750 "default_decay_rate".into(),
751 key(
752 "f32",
753 clean_f32(mem.gotcha.default_decay_rate),
754 "Default decay rate for gotcha importance",
755 ),
756 );
757 sections.insert(
758 "memory.gotcha".into(),
759 SectionSchema {
760 description: "Gotcha memory settings (project-specific warnings and pitfalls)"
761 .into(),
762 keys: mem_gotcha,
763 },
764 );
765
766 let mut mem_embeddings = BTreeMap::new();
767 mem_embeddings.insert(
768 "max_facts".into(),
769 key(
770 "usize",
771 serde_json::json!(mem.embeddings.max_facts),
772 "Maximum number of embedding facts stored",
773 ),
774 );
775 sections.insert(
776 "memory.embeddings".into(),
777 SectionSchema {
778 description: "Embeddings memory settings for semantic search".into(),
779 keys: mem_embeddings,
780 },
781 );
782
783 let mut aliases = BTreeMap::new();
784 aliases.insert(
785 "command".into(),
786 key(
787 "string",
788 serde_json::json!(""),
789 "The command pattern to match (e.g. 'deploy')",
790 ),
791 );
792 aliases.insert(
793 "alias".into(),
794 key(
795 "string",
796 serde_json::json!(""),
797 "The alias definition to execute",
798 ),
799 );
800 sections.insert("custom_aliases".into(), SectionSchema {
801 description: "Custom command aliases (array of {command, alias} entries). Note: field names are 'command' and 'alias' (not 'name')".into(),
802 keys: aliases,
803 });
804
805 if let Some(root_section) = sections.get_mut("root") {
806 root_section.keys.insert(
807 "custom_aliases".into(),
808 key(
809 "array",
810 serde_json::json!([]),
811 "Custom command aliases (array of {command, alias} entries)",
812 ),
813 );
814 }
815
816 ConfigSchema {
817 version: 1,
818 sections,
819 }
820 }
821
822 pub fn known_keys(&self) -> Vec<String> {
824 let mut keys = Vec::new();
825 for (section, schema) in &self.sections {
826 for key_name in schema.keys.keys() {
827 if section == "root" {
828 keys.push(key_name.clone());
829 } else {
830 keys.push(format!("{section}.{key_name}"));
831 }
832 }
833 }
834 keys
835 }
836}