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