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//! | [`trust`] | 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// koda-core requires a Unix-like OS (macOS or Linux).
40// The built-in shell tool uses `sh` which does not exist on Windows.
41// Windows users: install WSL2 — https://learn.microsoft.com/windows/wsl
42#![cfg_attr(
43 not(unix),
44 compile_error(
45 "koda-core requires a Unix-like operating system (macOS or Linux). \
46 Windows is not supported. On Windows, use WSL2 instead: \
47 https://learn.microsoft.com/windows/wsl"
48 )
49)]
50#![warn(missing_docs)]
51
52/// Sub-agent configuration, discovery, and invocation.
53pub mod agent;
54/// Approval flow and user interaction during tool execution.
55pub(crate) mod approval_flow;
56/// Heuristic path-escape detection for bash commands.
57pub mod bash_path_lint;
58/// Bash command safety classification — ReadOnly, LocalMutation, Destructive.
59pub mod bash_safety;
60/// Background sub-agent registry — tracks and drains async agent results.
61pub mod bg_agent;
62/// Context compaction — summarise old messages to reclaim token budget.
63pub mod compact;
64/// Global configuration: provider, model, model settings, CLI flags.
65pub mod config;
66/// Context window management and token budgeting (engine-internal).
67pub(crate) mod context;
68/// Context analysis — per-tool token breakdown and duplicate detection.
69pub mod context_analysis;
70/// SQLite persistence layer — sessions, messages, usage tracking.
71pub mod db;
72/// Engine protocol: `EngineEvent` / `EngineCommand` enums.
73pub mod engine;
74/// File lifecycle tracker — tracks files created by Koda per session (#465).
75pub mod file_tracker;
76/// Git context injection — branch, staged/unstaged diffs, recent commits.
77pub mod git;
78/// The main inference loop — send messages, stream responses, dispatch tools.
79pub mod inference;
80/// Shared helpers used by the inference loop.
81pub mod inference_helpers;
82/// Credential storage — `keys.toml` with env var fallback.
83pub mod keystore;
84/// Last-used provider recall (stored in SQLite KV store, not a config file).
85pub mod last_provider;
86/// Loop detection — catches runaway repeated tool calls.
87pub mod loop_guard;
88/// MCP client — connect to external MCP servers (#662).
89pub mod mcp;
90/// Project memory — `MEMORY.md` / `CLAUDE.md` read/write.
91pub mod memory;
92/// Microcompact — lightweight tool result aging without full compaction.
93pub mod microcompact;
94/// Hardcoded model aliases for stable, cross-provider model selection.
95pub mod model_alias;
96/// Hardcoded context-window lookup table (fallback when API doesn't report).
97pub mod model_context;
98/// Context-scaled output caps for tool results.
99pub mod output_caps;
100/// `Persistence` trait — the database contract.
101pub mod persistence;
102/// Diff preview generation for file mutations.
103pub mod preview;
104/// System prompt construction.
105pub mod prompt;
106/// Static provider catalog: `ProviderType` + `ProviderMeta` lookup tables.
107pub mod provider_catalog;
108/// LLM provider abstraction — Anthropic, Gemini, OpenAI-compatible.
109pub mod providers;
110/// Thread-safe runtime environment — replaces `std::env::set_var`.
111pub mod runtime_env;
112/// Process sandboxing for the Bash tool (macOS seatbelt / Linux bwrap).
113pub mod sandbox;
114/// Session lifecycle — create, resume, list, delete.
115pub mod session;
116/// Skill-scoped tool filtering — hard enforcement of `allowed_tools`.
117pub mod skill_scope;
118/// Skill discovery and activation (project, user, built-in).
119pub mod skills;
120/// Sub-agent result caching — zero-cost retries after compaction.
121pub mod sub_agent_cache;
122/// Sub-agent invocation and lifecycle management.
123pub(crate) mod sub_agent_dispatch;
124/// Tool dispatch — routes tool calls from inference to the registry.
125pub mod tool_dispatch;
126/// Tool name normalization — maps model-emitted variants to canonical PascalCase.
127pub mod tool_normalize;
128/// Tool registry, definitions, execution, and path safety.
129pub mod tools;
130/// Token-safe output truncation.
131pub mod truncate;
132/// Unified trust mode — single permission knob replacing ApprovalMode × SandboxMode.
133pub mod trust;
134/// Undo stack for file mutations.
135pub mod undo;
136/// Version string and update-check helpers.
137pub mod version;