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