Merge pull request #91 from nikomatsakis/message-handler-send

feat(sacp)!: require Send for JrMessageHandler with boxing witness ma…

Author: nikomatsakis

md/building-agent.md

@@ -4,140 +4,273 @@ This chapter explains how to build an ACP agent using the `sacp` crate.
 
 ## Overview
 
-An agent is the final component in a SACP proxy chain. It provides the base AI model behavior and doesn't need awareness of SACP - it's just a standard ACP agent.
+An agent is the component that provides AI model behavior in an ACP system. It receives prompts from clients (editors like Zed or Claude Code) and returns responses. Agents can also work as the final component in a conductor proxy chain.
 
-However, the `sacp` crate provides useful types and utilities for building ACP agents.
+## Quick Start
 
-## Core Types
+Here's a minimal agent that handles initialization:
 
-The `sacp` crate provides Rust types for ACP protocol messages:
+```rust
+use sacp::AgentToClient;
+use sacp::schema::{AgentCapabilities, InitializeRequest, InitializeResponse};
+use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
+
+#[tokio::main]
+async fn main() -> Result<(), sacp::Error> {
+    AgentToClient::builder()
+        .name("my-agent")
+        .on_receive_request(
+            async move |req: InitializeRequest, request_cx, _cx| {
+                request_cx.respond(InitializeResponse {
+                    protocol_version: req.protocol_version,
+                    agent_capabilities: AgentCapabilities::default(),
+                    auth_methods: Default::default(),
+                    agent_info: Default::default(),
+                    meta: Default::default(),
+                })
+            },
+            sacp::on_receive_request!(),
+        )
+        .serve(sacp::ByteStreams::new(
+            tokio::io::stdout().compat_write(),
+            tokio::io::stdin().compat(),
+        ))
+        .await
+}
+```
+
+## Core Concepts
+
+### The Builder Pattern
+
+Agents are built using `AgentToClient::builder()`. You register handlers for different message types, then call `.serve()` with a transport:
 
 ```rust
-use sacp::{
-    InitializeRequest, InitializeResponse,
-    PromptRequest, PromptResponse,
-    // ... other ACP types
-};
+AgentToClient::builder()
+    .name("my-agent")                           // For logging/debugging
+    .on_receive_request(handler1, macro1)       // Handle specific request type
+    .on_receive_request(handler2, macro2)       // Chain multiple handlers
+    .on_receive_notification(handler3, macro3)  // Handle notifications
+    .serve(transport)
+    .await
 ```
 
-These types handle:
-- Serialization/deserialization
-- Protocol validation
-- Type safety for message handling
+### Request Handlers
 
-## JSON-RPC Foundation
+Request handlers receive three parameters:
 
-The `sacp` crate includes a JSON-RPC layer that handles:
+1. **The request** - Typed by what you're handling (e.g., `InitializeRequest`, `PromptRequest`)
+2. **The request context** (`JrRequestCx`) - Used to send the response
+3. **The connection context** (`JrConnectionCx`) - Used for sending notifications or spawning tasks
 
-- Message framing over stdio or other transports
-- Request/response correlation
-- Notification handling
-- Error propagation
+```rust
+.on_receive_request(
+    async move |request: PromptRequest, request_cx, cx| {
+        // Process the request...
+        
+        // Send the response
+        request_cx.respond(PromptResponse {
+            stop_reason: StopReason::EndTurn,
+            meta: None,
+        })
+    },
+    sacp::on_receive_request!(),
+)
+```
+
+### The Witness Macro
+
+Every handler registration requires a "witness" macro as the final parameter. This is a workaround for missing Rust language features (return-type notation). Always use the matching macro:
+
+- `.on_receive_request(..., sacp::on_receive_request!())`
+- `.on_receive_notification(..., sacp::on_receive_notification!())`
+- `.on_receive_message(..., sacp::on_receive_message!())`
+
+### Sending Notifications
+
+Use the connection context to send notifications back to the client:
 
 ```rust
-use sacp::{JsonRpcConnection, JsonRpcHandler};
+.on_receive_request(
+    async move |request: PromptRequest, request_cx, cx| {
+        // Send streaming content
+        cx.send_notification(SessionNotification {
+            session_id: request.session_id.clone(),
+            update: SessionUpdate::AgentMessageChunk(ContentChunk {
+                content: "Hello!".into(),
+                meta: None,
+            }),
+            meta: None,
+        })?;
+
+        // Complete the request
+        request_cx.respond(PromptResponse {
+            stop_reason: StopReason::EndTurn,
+            meta: None,
+        })
+    },
+    sacp::on_receive_request!(),
+)
+```
+
+### Spawning Background Work
 
-// Create a connection over stdio
-let connection = JsonRpcConnection::new(stdin(), stdout(), my_handler);
+Don't block the message loop with long-running operations. Use `cx.spawn()` to run work in the background:
 
-// Run the message loop
-connection.run().await?;
+```rust
+.on_receive_request(
+    async move |request: PromptRequest, request_cx, cx| {
+        let cx_clone = cx.clone();
+        cx.spawn(async move {
+            // Long-running AI inference...
+            let response = generate_response(&request).await;
+            
+            // Send notification with result
+            cx_clone.send_notification(SessionNotification { /* ... */ })?;
+            
+            // Complete the request
+            request_cx.respond(PromptResponse {
+                stop_reason: StopReason::EndTurn,
+                meta: None,
+            })
+        })
+    },
+    sacp::on_receive_request!(),
+)
 ```
 
-## Handler Pattern
+## Building a Reusable Agent Component
 
-Implement `JsonRpcHandler` to process ACP messages:
+For agents that can be composed into larger systems (e.g., with the conductor), implement the `Component` trait:
 
 ```rust
-use sacp::{JsonRpcHandler, MessageAndCx, Handled};
+use sacp::{AgentToClient, Component};
+use sacp::schema::*;
 
-struct MyAgent {
-    // Agent state
+pub struct MyAgent {
+    config: AgentConfig,
 }
 
-impl JsonRpcHandler for MyAgent {
-    async fn handle_message(&mut self, message: MessageAndCx) -> Result<Handled> {
-        match message {
-            MessageAndCx::Request(req, cx) => {
-                match req {
-                    AcpRequest::Initialize(init) => {
-                        // Handle initialization
-                        let response = InitializeResponse {
-                            protocolVersion: "0.7.0",
-                            serverInfo: ServerInfo { /* ... */ },
-                            capabilities: Capabilities { /* ... */ },
-                        };
-                        cx.respond(response)?;
-                        Ok(Handled::FullyHandled)
-                    }
-                    AcpRequest::Prompt(prompt) => {
-                        // Call your AI model
-                        let response = self.generate_response(prompt).await?;
-                        cx.respond(response)?;
-                        Ok(Handled::FullyHandled)
+impl Component for MyAgent {
+    async fn serve(self, client: impl Component) -> Result<(), sacp::Error> {
+        AgentToClient::builder()
+            .name("my-agent")
+            .on_receive_request(
+                async |req: InitializeRequest, request_cx, _cx| {
+                    request_cx.respond(InitializeResponse {
+                        protocol_version: req.protocol_version,
+                        agent_capabilities: AgentCapabilities::default(),
+                        auth_methods: Default::default(),
+                        agent_info: Default::default(),
+                        meta: Default::default(),
+                    })
+                },
+                sacp::on_receive_request!(),
+            )
+            .on_receive_request(
+                {
+                    let agent = self.clone();
+                    async move |req: PromptRequest, request_cx, cx| {
+                        agent.handle_prompt(req, request_cx, cx).await
                     }
-                    // ... other message types
-                }
-            }
-            MessageAndCx::Notification(notif, cx) => {
-                // Handle notifications
-            }
-        }
+                },
+                sacp::on_receive_request!(),
+            )
+            .connect_to(client)?
+            .serve()
+            .await
     }
 }
 ```
 
-## Working with Proxies
-
-Your agent doesn't need to know about SACP proxies. However, there are some optional capabilities that improve proxy integration:
+Note the difference: `.serve(transport)` for standalone agents vs `.connect_to(client)?.serve()` for composable components.
 
-### MCP-over-ACP Support
+## Handling Multiple Request Types
 
-If your agent can handle MCP servers declared with `acp:UUID` URLs, advertise the capability:
+Chain multiple `.on_receive_request()` calls to handle different message types. Handlers are tried in order until one matches:
 
 ```rust
-InitializeResponse {
-    // ...
-    _meta: json!({
-        "mcp_acp_transport": true
-    }),
-}
+AgentToClient::builder()
+    .name("my-agent")
+    .on_receive_request(
+        async |req: InitializeRequest, request_cx, _cx| {
+            request_cx.respond(InitializeResponse { /* ... */ })
+        },
+        sacp::on_receive_request!(),
+    )
+    .on_receive_request(
+        async |req: NewSessionRequest, request_cx, _cx| {
+            request_cx.respond(NewSessionResponse { /* ... */ })
+        },
+        sacp::on_receive_request!(),
+    )
+    .on_receive_request(
+        async |req: PromptRequest, request_cx, cx| {
+            // Handle prompts...
+            request_cx.respond(PromptResponse { /* ... */ })
+        },
+        sacp::on_receive_request!(),
+    )
+    .serve(transport)
+    .await
 ```
 
-This allows the conductor to skip bridging and pass MCP declarations through directly.
+## Catch-All Handler
 
-Without this capability, the conductor will automatically bridge MCP-over-ACP to stdio for you.
+Use `.on_receive_message()` to handle any message not caught by specific handlers:
 
-## Testing
+```rust
+AgentToClient::builder()
+    .name("my-agent")
+    .on_receive_request(/* ... specific handlers ... */)
+    .on_receive_message(
+        async move |message: MessageCx, cx| {
+            // Return an error for unhandled messages
+            message.respond_with_error(
+                sacp::util::internal_error("Unhandled message type"),
+                cx,
+            )
+        },
+        sacp::on_receive_message!(),
+    )
+    .serve(transport)
+    .await
+```
+
+## Protocol Types
 
-The `sacp` crate provides test utilities:
+The `sacp::schema` module provides all ACP protocol types:
 
 ```rust
-#[cfg(test)]
-mod tests {
-    use sacp::testing::*;
+use sacp::schema::{
+    // Initialization
+    InitializeRequest, InitializeResponse,
+    AgentCapabilities,
 
-    #[test]
-    fn test_prompt_handling() {
-        let agent = MyAgent::new();
-        let response = agent.handle_prompt(test_prompt()).await?;
-        assert_eq!(response.role, Role::Assistant);
-    }
-}
+    // Sessions
+    NewSessionRequest, NewSessionResponse,
+    LoadSessionRequest, LoadSessionResponse,
+    SessionId,
+    
+    // Prompts
+    PromptRequest, PromptResponse,
+    ContentBlock, ContentChunk,
+    StopReason,
+    
+    // Notifications
+    SessionNotification, SessionUpdate,
+    
+    // MCP
+    McpServer,
+};
 ```
 
-## Standard ACP Implementation
-
-Remember: An agent built with `sacp` is a standard ACP agent. It will work:
-
-- Directly with ACP editors (Zed, Claude Code, etc.)
-- As the final component in a SACP proxy chain
-- With any ACP-compatible tooling
+## Complete Example
 
-The `sacp` crate just provides convenient Rust types and infrastructure.
+See the [elizacp](https://github.com/symposium-dev/symposium-acp/tree/main/src/elizacp) crate for a complete working agent implementation with session management and MCP tool support.
 
 ## Next Steps
 
 - See [Protocol Reference](./protocol.md) for message format details
-- Read the `sacp` crate documentation for API details
+- Read the `sacp` crate rustdoc for full API documentation
 - Check the [ACP specification](https://agentclientprotocol.com/) for protocol details