kamchatka/lib.rs
1//! A terminal agent for Linux, built on [`nachalnik`]: the context, the budget and every decision
2//! on screen, and a shell the kernel confines.
3//!
4//! Four tabs, each of which gets the whole window, because each of them is a whole view.
5//! **chat** is the conversation, and every other agent in the terminal has one. **context** is
6//! the reason this exists: the context, item by item, with what each one costs, whether it is
7//! going into the next request, and - for the ones that are not - why not, in the projector's own
8//! words. Space moves an item from active to elided to excluded and back; `p` pins it so that
9//! compaction cannot have it; enter shows what it actually says. **trace** is every event the
10//! runtime emits, as it happens, under the same names the session log is made of. **permissions**
11//! is every answer somebody has given the policy, what each one covers, and a count of what is
12//! still a question - changeable where it is read rather than one prompt at a time.
13//!
14//! Nothing is inferred and nothing is hidden: the context tab is a list of ordinary values the
15//! runtime hands out, and `ctrl+p` prints the exact request they add up to.
16//!
17//! `/attach PATH [TEXT]` puts a file in the context and asks about it in one go, and `-f` is the
18//! same act at startup. Source and markdown go in as text; a PDF, an image or a recording goes in
19//! as [`nachalnik::Content::Blob`], which nothing here can price - so the row, the chat line and
20//! `/budget` all say a piece of the figure is missing rather than putting a `0` where a number
21//! should be. It sends pictures and draws none: a terminal cell is not a pixel.
22//!
23//! Four of the tools are about the session itself, and they are offered like the rest of them.
24//!
25//! - [`introspect::Context`] is the context. It lists what is being carried and what each item
26//! costs, reports the budget against what the last request really cost, shows the request about
27//! to go out, and finds text anywhere in it - what is excluded included, which nothing else can
28//! read without paying to carry it again. It also elides, excludes, pins, restores and rewrites
29//! what is being carried, writes down something compaction cannot take, and walks its own
30//! changes back.
31//! - [`introspect::Fork`] stands up a throwaway copy of the session and asks it something, so an
32//! answer can be read before it is given, and a piece of context can be taken away to see what
33//! it was doing.
34//! - [`introspect::Log`] reads the record kept beside the context: what was added, replaced,
35//! elided or compacted, and what was asked permission for and answered. It leads with what there
36//! is and what taking it would cost, so a short answer is never mistaken for a quiet session.
37//! - [`introspect::Setup`] reads what the session is running *with*: which model, which tools and
38//! what each declares, what the policy will refuse before it is asked, what the compactor and
39//! the projector will do unasked, and whether this conversation was resumed from somebody
40//! else's.
41//!
42//! None of them is allowed to touch what a person pinned. Nothing in the runtime knows about any
43//! of this - it is what a tool can already do with a context that is a list of public values and a
44//! request that can be built without being sent. `/tools toggle ID` stops offering one of them, or
45//! any other tool, and offers it again; the `tools` key in a settings file says which of them a
46//! session starts with.
47//!
48//! `--api gemini` swaps the wire format for Google's own, in which an assistant turn is an ordered
49//! list of parts rather than a content slot beside a list of calls. What that buys is the order
50//! itself: thinking, a sentence, a tool call, more thinking - recorded as it happened, counted,
51//! elided and excluded like any other turn, and sent back the same way. `--api anthropic` does the
52//! same with Anthropic's Messages API, whose thinking is signed and has to go back as it came, and
53//! `--api responses` with OpenAI's Responses API, whose thinking is sealed and goes back the same
54//! way. Every dialect answers one trait ([`nachalnik_providers::Endpoint`]), so nothing above them
55//! knows which one it got.
56//!
57//! Everything in here is code above the runtime: the tools, the policy, the compactor, the
58//! confinement and the rendering, and the providers next door in [`nachalnik_providers`]. The
59//! kernel supplies the state machine, the context and the paper trail.
60//!
61//! It is a library because the screen has to be testable, and because the screen is not the
62//! program. `ui::draw` against a `TestBackend` is how the tests check that an excluded item really
63//! does leave the next request. [`app::App`] holds the session, and the keys are one caller of it:
64//! `submit` takes the same line a person types, a command or a message, and `on_event` takes what
65//! the kernel says back. The program is the `kamchatka` binary.
66//!
67//! The `tui` feature, on by default, is the drawing and the keys: `ui`, the prompt, and the
68//! bindings. Without it the library is the same program with nothing rendering it, and without
69//! the dependencies only the drawing wants - which is what a session driven by something other
70//! than a person at a terminal needs.
71//!
72//! `--serve` puts a socket in front of the session and `--connect` attaches to one. The session
73//! belongs to the program running it rather than to whoever is looking at it: a turn carries on
74//! with nobody attached, a question waits for somebody to come back and answer it, and a client
75//! picking it up an hour later picks up the same session. See [`remote`] for why the records are
76//! the half that cannot be lost and the fragments are the half that can, and for why there is no
77//! authentication in the protocol and none is planned.
78//!
79//! The way in is [`wiring::Setup`], which assembles a kernel, a policy, the tools, the sandbox
80//! and an [`app::App`] around them in the order they have to go in, and hands back the two
81//! receivers a loop needs. [`headless::Headless`] is one such loop, [`remote::Server`] is the
82//! second and the program's own is the third. A host with an event loop of its own wants none of
83//! them, and [`app::App::submit`] is where it hands in a line. [`config::Settings`] is the JSON
84//! the program's `--config-file` takes, for a host that would rather read its defaults out of a
85//! file than hard-code them.
86//!
87//! What a session may spend is [`wiring::Setup::spend`], and it is enforced on the `App` rather
88//! than in either loop: the accounting is in `on_event` and the refusal in `start_turn`. That is
89//! how a host with a loop of its own gets the same ceiling as the program does.
90
91#![deny(missing_docs)]
92#![deny(unsafe_code)]
93
94// note: Linux only, on the two architectures sandlock's seccomp filter is written for. The `shell`
95// tool is safe to hand to a model only because of Landlock, `openat2` beneath a directory, and
96// sandlock's supervisor; all are Linux-only. Elsewhere the shell ran unconfined, with only a question read off the
97// command's name. 0.15.1 is the last version that builds anywhere else.
98#[cfg(not(all(
99 target_os = "linux",
100 any(target_arch = "x86_64", target_arch = "aarch64")
101)))]
102compile_error!(
103 "kamchatka builds for Linux on x86_64 and aarch64 only; 0.15.1 is the last version that \
104 builds anywhere else"
105);
106
107pub mod app;
108pub mod args;
109pub mod attach;
110pub mod check;
111pub mod clipboard;
112pub mod config;
113pub mod endpoint;
114pub mod headless;
115pub mod introspect;
116#[cfg(feature = "mcp")]
117pub mod mcp;
118#[cfg(feature = "webui")]
119pub mod qr;
120pub mod reconcile;
121pub mod remote;
122pub mod sandbox;
123pub mod stopping;
124pub mod tools;
125#[cfg(feature = "tui")]
126pub mod ui;
127#[cfg(feature = "webui")]
128pub mod web;
129pub mod wiring;
130
131pub mod help;