talon/lib.rs
1//! # talon — host orchestrator and CLI
2//!
3//! The `talon` binary is the long-running host process plus the operator
4//! CLI:
5//!
6//! | command | purpose |
7//! |---|---|
8//! | `talon run` (default) | orchestrator: channels, message loop, queue, scheduler, IPC watcher, LLM gateway |
9//! | `talon setup <step> [args]` | setup steps from `talon-setup` (machine-readable status blocks) |
10//! | `talon doctor` | environment, vLLM, container runtime and LLM gateway diagnostics |
11//! | `talon audit verify` | recompute the hash-chained audit log |
12//! | `talon audit tail [-n N] [--kind prefix]` | recent audit events as JSON lines |
13//! | `talon version` | print the version |
14//!
15//! ## Architecture of `talon run`
16//!
17//! ```text
18//! channels (http, telegram, emacs, webhook)
19//! │ ChannelHost::on_message ── sender allowlist (drop) ── store ── Notify
20//! ▼
21//! message loop (event-driven, poll fallback) ── trigger gating ── session commands
22//! │ pipe follow-up into the lane's container (IPC input) or enqueue a lane run
23//! ▼
24//! GroupQueue (per-lane serialization, global limit) ◀── TaskScheduler (due tasks)
25//! │ LaneProcessor::process_messages / run_task
26//! ▼
27//! Orchestrator::run_agent ── session/provider fingerprint ── snapshots
28//! │ LLM gateway token (stdin only) ── ContainerRunner ── output frames
29//! ▼
30//! outbound: redact ── format per channel dialect ── Channel::send_message
31//! ```
32//!
33//! Everything that needs the outside world (container runtime, LLM gateway,
34//! channels) sits behind a trait ([`agent::ContainerLauncher`],
35//! [`agent::LlmAccess`], `talon_core::channel::Channel`) so the orchestrator
36//! logic is unit-tested with fakes and an in-memory database.
37
38#![warn(missing_docs)]
39#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
40
41pub mod agent;
42pub mod allowlist;
43pub mod app;
44pub mod audit_cmd;
45pub mod cli;
46pub mod doctor;
47pub mod investigation;
48pub mod logging;
49pub mod orchestrator;
50pub mod output_limits;
51pub mod palace;
52pub mod safe_fs;
53pub mod secrets;
54
55#[cfg(test)]
56mod testutil;
57
58/// Version of the `talon` package (`CARGO_PKG_VERSION`).
59pub const VERSION: &str = env!("CARGO_PKG_VERSION");