Merge pull request #100 from nikomatsakis/main

sacp 10.0.0-alpha.1: ordering guarantees, docs reorganization, and compilable examples

Author: nikomatsakis

commit-messages.txt

@@ -0,0 +1,75 @@
+//! The roles in ACP: clients, agents, proxies, and conductors.
+//!
+//! The Agent-Client Protocol defines how AI agents communicate with the
+//! applications that use them. Understanding the four roles helps you choose
+//! the right approach for what you're building.
+//!
+//! # Clients
+//!
+//! A **client** is an application that wants to use an AI agent. Examples include:
+//!
+//! - IDEs like VS Code or JetBrains
+//! - Command-line tools
+//! - Web applications
+//! - Automation scripts
+//!
+//! Clients send prompts to agents and receive responses. They can also handle
+//! requests from the agent (like permission requests or tool approvals).
+//!
+//! # Agents
+//!
+//! An **agent** is an AI-powered service that responds to prompts. Examples include:
+//!
+//! - Claude Code
+//! - Custom agents built with language models
+//!
+//! Agents receive prompts, process them (typically by calling an LLM), and stream
+//! back responses. They may also request permissions, invoke tools, or ask for
+//! user input during processing.
+//!
+//! # Proxies
+//!
+//! A **proxy** sits between a client and an agent, intercepting and potentially
+//! modifying messages in both directions. Proxies are useful for:
+//!
+//! - Adding tools via MCP (Model Context Protocol) servers
+//! - Injecting system prompts or context
+//! - Logging and debugging
+//! - Filtering or transforming messages
+//!
+//! Proxies can be chained - you can have multiple proxies between a client and
+//! an agent, each adding its own capabilities.
+//!
+//! # Conductors
+//!
+//! A **conductor** orchestrates a chain of proxies with a final agent. It:
+//!
+//! - Spawns and manages proxy processes
+//! - Routes messages through the chain
+//! - Handles initialization and shutdown
+//!
+//! The [`sacp-conductor`] crate provides a conductor implementation. Most users
+//! don't need to implement conductors themselves - they just configure which
+//! proxies to use.
+//!
+//! # Message Flow
+//!
+//! Messages flow through the system like this:
+//!
+//! ```text
+//! Client <-> Proxy 1 <-> Proxy 2 <-> ... <-> Agent
+//!        ^                                ^
+//!        |                                |
+//!        +------ Conductor manages -------+
+//! ```
+//!
+//! Each arrow represents a bidirectional connection. Requests flow toward the
+//! agent, responses flow back toward the client, and notifications can flow
+//! in either direction.
+//!
+//! # Next Steps
+//!
+//! Now that you understand the roles, see [Connections and Links](super::connections)
+//! to learn how to establish connections in code.
+//!
+//! [`sacp-conductor`]: https://crates.io/crates/sacp-conductor

src/sacp/src/concepts/acp_basics.rs

@@ -0,0 +1,127 @@
+//! Handling incoming messages with `on_receive_*` callbacks.
+//!
+//! So far we've seen how to *send* messages. But ACP is bidirectional - the
+//! remote peer can also send messages to you. Use callbacks to handle them.
+//!
+//! # Handling Requests
+//!
+//! Use `on_receive_request` to handle incoming requests that expect a response:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{ValidateRequest, ValidateResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_request(async |req: ValidateRequest, request_cx, cx| {
+//!         // Process the request
+//!         let is_valid = req.data.len() > 0;
+//!
+//!         // Send the response
+//!         request_cx.respond(ValidateResponse { is_valid, error: None })
+//!     }, sacp::on_receive_request!())
+//!     .run_until(transport, async |cx| { Ok(()) })
+//!     .await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! Your callback receives three arguments:
+//! - The request payload (e.g., `PermissionRequest`)
+//! - A [`JrRequestCx`] for sending the response
+//! - A [`JrConnectionCx`] for sending other messages
+//!
+//! # Handling Notifications
+//!
+//! Use `on_receive_notification` for fire-and-forget messages that don't need
+//! a response:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::StatusUpdate;
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_notification(async |notif: StatusUpdate, cx| {
+//!         println!("Status: {}", notif.message);
+//!         Ok(())
+//!     }, sacp::on_receive_notification!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # The Request Context
+//!
+//! The [`JrRequestCx`] lets you send a response to the request:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{MyRequest, MyResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder()
+//! #   .on_receive_request(async |req: MyRequest, request_cx, cx| {
+//! // Send a successful response
+//! request_cx.respond(MyResponse { status: "ok".into() })?;
+//! # Ok(())
+//! #   }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! Or send an error:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{MyRequest, MyResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder()
+//! #   .on_receive_request(async |req: MyRequest, request_cx, cx| {
+//! request_cx.respond_with_error(sacp::Error::invalid_params())?;
+//! # Ok(())
+//! #   }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! You must send exactly one response per request. If your callback returns
+//! without responding, an error response is sent automatically.
+//!
+//! # Multiple Handlers
+//!
+//! You can register multiple handlers. They're tried in order until one
+//! handles the message:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{ValidateRequest, ValidateResponse, ExecuteRequest, ExecuteResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_request(async |req: ValidateRequest, request_cx, cx| {
+//!         // Handle validation requests
+//!         request_cx.respond(ValidateResponse { is_valid: true, error: None })
+//!     }, sacp::on_receive_request!())
+//!     .on_receive_request(async |req: ExecuteRequest, request_cx, cx| {
+//!         // Handle execution requests
+//!         request_cx.respond(ExecuteResponse { result: "done".into() })
+//!     }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Ordering Guarantees
+//!
+//! Callbacks run inside the dispatch loop and block further message processing
+//! until they complete. This gives you ordering guarantees but also means you
+//! need to be careful about deadlocks.
+//!
+//! See [Ordering](super::ordering) for the full details.
+//!
+//! # Next Steps
+//!
+//! - [Explicit Peers](super::peers) - Use `_from` variants to specify the source peer
+//! - [Ordering](super::ordering) - Understand dispatch loop semantics
+//!
+//! [`JrRequestCx`]: crate::JrRequestCx
+//! [`JrConnectionCx`]: crate::JrConnectionCx