koda_core/
lib.rs

1//! Koda Core — the engine library for the Koda AI coding agent.
2//!
3//! This crate contains the pure engine logic with zero terminal dependencies.
4//! It communicates exclusively through [`engine::EngineEvent`] (output) and
5//! [`engine::EngineCommand`] (input) enums.
6//!
7//! ## Quick navigation
8//!
9//! | Module | What it does |
10//! |---|---|
11//! | [`agent`] | Agent construction and built-in agent catalog |
12//! | [`tools`] | 19 built-in tools (file ops, shell, search, web, memory, agents) |
13//! | [`providers`] | 14 LLM providers (Anthropic, OpenAI, Gemini, local, etc.) |
14//! | [`inference`] | Streaming inference loop with tool execution |
15//! | [`config`] | Configuration loading, agent discovery, settings |
16//! | [`approval`] | Safety gates and approval modes |
17//! | [`engine`] | Event/command protocol (client–engine boundary) |
18//! | [`compact`] | Context compaction (summarize old messages) |
19//! | [`memory`] | Persistent semantic memory (`MEMORY.md`) |
20//! | [`skills`] | Expertise modules (prompt injection, zero LLM cost) |
21//! | [`db`] | SQLite persistence (sessions, history, file ownership) |
22//!
23//! ## Architecture
24//!
25//! ```text
26//! ┌───────────────┐  EngineEvent   ┌─────────────────┐
27//! │   koda-cli    │ ←───────────── │    koda-core    │
28//! │  (TUI/REPL)   │ ─────────────→ │   (engine lib)  │
29//! └───────────────┘  EngineCommand └────────┬────────┘
30//!                                           │
31//!                                    ┌──────┴──────┐
32//!                                    │  providers  │
33//!                                    │ (LLM APIs)  │
34//!                                    └─────────────┘
35//! ```
36//!
37//! See `DESIGN.md` in the repository root for the full architectural rationale.
38
39#![warn(missing_docs)]
40
41/// Sub-agent configuration, discovery, and invocation.
42pub mod agent;
43/// Tool approval modes, safety gates, and shared mode state.
44pub mod approval;
45/// Approval flow and user interaction during tool execution.
46pub(crate) mod approval_flow;
47/// Heuristic path-escape detection for bash commands.
48pub mod bash_path_lint;
49/// Bash command safety classification — ReadOnly, LocalMutation, Destructive.
50pub mod bash_safety;
51/// Background sub-agent registry — tracks and drains async agent results.
52pub mod bg_agent;
53/// Context compaction — summarise old messages to reclaim token budget.
54pub mod compact;
55/// Global configuration: provider, model, model settings, CLI flags.
56pub mod config;
57/// Context window management and token budgeting (engine-internal).
58pub(crate) mod context;
59/// Context analysis — per-tool token breakdown and duplicate detection.
60pub mod context_analysis;
61/// SQLite persistence layer — sessions, messages, usage tracking.
62pub mod db;
63/// Engine protocol: `EngineEvent` / `EngineCommand` enums.
64pub mod engine;
65/// File lifecycle tracker — tracks files created by Koda per session (#465).
66pub mod file_tracker;
67/// Git context injection — branch, staged/unstaged diffs, recent commits.
68pub mod git;
69/// The main inference loop — send messages, stream responses, dispatch tools.
70pub mod inference;
71/// Shared helpers used by the inference loop.
72pub mod inference_helpers;
73/// Credential storage — `keys.toml` with env var fallback.
74pub mod keystore;
75/// Loop detection — catches runaway repeated tool calls.
76pub mod loop_guard;
77/// Project memory — `MEMORY.md` / `CLAUDE.md` read/write.
78pub mod memory;
79/// Microcompact — lightweight tool result aging without full compaction.
80pub mod microcompact;
81/// Hardcoded model aliases for stable, cross-provider model selection.
82pub mod model_alias;
83/// Hardcoded context-window lookup table (fallback when API doesn't report).
84pub mod model_context;
85/// Context-scaled output caps for tool results.
86pub mod output_caps;
87/// `Persistence` trait — the database contract.
88pub mod persistence;
89/// Diff preview generation for file mutations.
90pub mod preview;
91/// Progress reporting helpers for long operations.
92pub mod progress;
93/// System prompt construction.
94pub mod prompt;
95/// LLM provider abstraction — Anthropic, Gemini, OpenAI-compatible.
96pub mod providers;
97/// Thread-safe runtime environment — replaces `std::env::set_var`.
98pub mod runtime_env;
99/// Session lifecycle — create, resume, list, delete.
100pub mod session;
101/// Last-used provider persistence (`~/.config/koda/settings.toml`).
102pub mod settings;
103/// Skill discovery and activation (project, user, built-in).
104pub mod skills;
105/// Sub-agent result caching — zero-cost retries after compaction.
106pub mod sub_agent_cache;
107/// Sub-agent invocation and lifecycle management.
108pub(crate) mod sub_agent_dispatch;
109/// Tool dispatch — routes tool calls from inference to the registry.
110pub mod tool_dispatch;
111/// Tool name normalization — maps model-emitted variants to canonical PascalCase.
112pub mod tool_normalize;
113/// Tool registry, definitions, execution, and path safety.
114pub mod tools;
115/// Token-safe output truncation.
116pub mod truncate;
117/// Undo stack for file mutations.
118pub mod undo;
119/// Version string and update-check helpers.
120pub mod version;
121/// Git worktree provisioning for sub-agent isolation.
122pub mod worktree;
koda_core/lib.rs

koda_core/
lib.rs
