basis_acp/lib.rs
1//! basis-acp — the ACP adapter: basis's explicit protocol surface.
2//!
3//! [ACP](https://agentclientprotocol.com) is JSON-RPC 2.0 over stdio, LSP-style
4//! — the standard editors and web UIs already speak. Serving it is what makes
5//! basis embeddable without basis shipping a client: Zed, JetBrains, and acp-ui
6//! drive it as-is (PROPOSAL.md Bet 2, ADR-0002).
7//!
8//! This is an adapter over [`basis`] and nothing else: the run lifecycle,
9//! the event stream and the seams are all the core's, and what is here is the
10//! translation at one edge. Opt-in by dependency, so a host embedding the
11//! harness in-process never compiles a JSON-RPC server it does not run
12//! (ADR-0011). The binary exposes this adapter through the explicit
13//! `basis serve --acp` command on stdin/stdout; a bare `basis` invocation is
14//! reserved for usage and prompt shorthand (ADR-0017).
15//!
16//! # Shape
17//!
18//! - [`session_update`] maps basis's [`Event`](basis::Event) onto
19//! `session/update`. That mapping is the whole reason `Event` is basis's own
20//! type rather than a re-export of mentra's: one normalization, many surfaces.
21//! - [`AcpApprover`] answers mentra's permission requests by asking the client,
22//! turning basis's existing [`Approver`](basis::Approver) seam into
23//! `session/request_permission` with no new plumbing.
24//! - [`SessionModes`] is the client's permission switch: ACP session modes over
25//! basis's [`Approver`](basis::Approver) seam, applied in front of the
26//! approver so the answer can still change mid-session. The three modes are
27//! [`ApprovalMode`], which is basis-acp's own because an enumerable mode list
28//! is a protocol concept — the core has the trait and nothing else.
29//! - `history` replays a resumed conversation, which is what separates
30//! `session/load` from `session/resume`.
31//! - [`SessionRegistry`] holds the open conversations, keyed by mentra's
32//! persisted agent id so that `session/load` is just
33//! [`Workspace::resume`](basis::Workspace::resume).
34//! - [`serve`] wires the handlers onto a connection, over one
35//! [`Runtime`](basis::Runtime) for the process and one
36//! [`Workspace`](basis::Workspace) per directory a client names
37//! (ADR-0018).
38//! - [`serve_stdio`] is the stdin/stdout transport, and the one place basis looks
39//! at what a peer sent before serving it.
40//! - [`available_commands`] and [`from_acp`] are the two mappings between a
41//! core convention and the wire: templates become the commands a client
42//! offers, and a client's `mcpServers` become servers basis can register.
43
44mod approver;
45mod commands;
46mod history;
47mod mcp;
48mod mode;
49mod server;
50mod session;
51mod stdio;
52mod update;
53
54pub use approver::AcpApprover;
55pub use commands::available_commands;
56pub use mcp::from_acp;
57pub use mode::{ApprovalMode, ModeError, ModedApprover, SessionModes};
58pub use server::{ServeConfig, SessionSource, serve};
59pub use session::{AcpSession, SessionRegistry};
60pub use stdio::{StdioError, serve_stdio};
61pub use update::session_update;