Merge pull request #7 from nikomatsakis/improve-docs

docs: Improve and polish README etc

Author: nikomatsakis

Cargo.lock

@@ -3,7 +3,9 @@ members = [
     "src/sacp-proxy",
     "src/sacp-conductor",
     "src/sacp",
+    "src/sacp-tokio",
     "src/elizacp",
+    "src/sacp-doc-test",
 ]
 resolver = "2"
 

Cargo.toml

@@ -1,119 +1,40 @@
-# SACP: Symposium's Extensions to ACP
+# SACP: Symposium Agent Client Protocol SDK
 
-**SACP** is an SDK for building composable AI agent systems using the [Agent-Client Protocol](https://agentclientprotocol.com/).
+This repository houses the **Symposium ACP SDK**, which aims to:
 
-## What is SACP?
+1. **Provide a nicer SDK for working with ACP in general** - Type-safe, async-first, and easy to use for building agents and editors
+2. **Support proxy components for composable extensions** - Build modular components that extend agent behavior without modifying the agent itself
 
-SACP extends ACP to enable **composable agent architectures through proxy chains**. Instead of building monolithic AI tools, SACP allows you to create modular components that can intercept and transform messages flowing between editors and agents.
+Instead of building monolithic AI tools, SACP enables **composable agent architectures through proxy chains** where functionality can be added, removed, or reconfigured dynamically.
 
 ```mermaid
 flowchart LR
     Editor[ACP Editor] -->|ACP| Conductor
-    
+
     subgraph Conductor[Conductor Process]
         P1[Proxy 1]
         P2[Proxy 2]
         Agent[Base Agent]
-        
+
         P1 --> P2 --> Agent
     end
 ```
 
 ## Repository Structure
 
-This repository contains three core crates:
+This repository contains several crates:
+
+**Core SDK:**
+- **[`sacp`](./src/sacp/)** - Core ACP SDK for building agents and editors in Rust
+- **[`sacp-tokio`](./src/sacp-tokio/)** - Tokio-specific utilities (process spawning, connection management)
 
-- **[`sacp`](./src/sacp/)** - Core protocol types and traits for building clients and agents
-- **[`sacp-proxy`](./src/sacp-proxy/)** - Framework for building proxy components
+**Proxy Framework:**
+- **[`sacp-proxy`](./src/sacp-proxy/)** - Framework for building ACP proxy components
 - **[`sacp-conductor`](./src/sacp-conductor/)** - Binary that orchestrates proxy chains
+
+**Examples & Testing:**
 - **[`elizacp`](./src/elizacp/)** - Example ACP agent implementing the classic Eliza chatbot (useful for testing)
 
 ## Documentation
 
-Full documentation is available in the [mdbook](https://rust-lang.github.io/mdBook/):
-
-```bash
-mdbook serve
-```
-
-Then visit http://localhost:3000
-
-Key chapters:
-- [Introduction](./md/introduction.md) - What is SACP and why use it
-- [Architecture Overview](./md/architecture.md) - How proxy chains work
-- [Protocol Reference](./md/protocol.md) - Technical protocol details
-
-## Quick Start
-
-### Using as a Library
-
-Add to your `Cargo.toml`:
-
-```toml
-[dependencies]
-sacp = "0.1"           # Core protocol types
-sacp-proxy = "0.1"     # For building proxies
-```
-
-### Building the Conductor
-
-```bash
-cargo build --release -p sacp-conductor
-```
-
-The conductor binary will be at `target/release/sacp-conductor`.
-
-### Running a Proxy Chain
-
-```bash
-# Start a proxy chain with two components
-sacp-conductor agent proxy-component-1 proxy-component-2 base-agent
-```
-
-The conductor presents as a normal ACP agent to editors while orchestrating the proxy chain internally.
-
-## Example Use Case: Sparkle Integration
-
-The [sparkle-acp-proxy](https://github.com/nikomatsakis/sparkle-acp-proxy) demonstrates a real-world SACP proxy that:
-
-1. Injects Sparkle's MCP server during initialization
-2. Prepends embodiment sequences to prompts
-3. Provides collaborative AI patterns transparently
-
-## Development
-
-### Building
-
-```bash
-cargo build
-```
-
-### Testing
-
-```bash
-cargo test
-```
-
-### Running Examples
-
-See the test files in each crate for usage examples.
-
-## Design Documentation
-
-The `md/` directory contains detailed design documentation extracted from the Symposium project:
-
-- [proxying-acp.md](./md/proxying-acp.md) - Complete RFD with protocol specification
-- [pacp-components.md](./md/pacp-components.md) - Component architecture overview
-- [conductor.md](./md/conductor.md) - Conductor implementation details
-
-## Relationship to ACP
-
-SACP is an [extension to ACP](https://agentclientprotocol.com/protocol/extensibility), not a fork. SACP components communicate using ACP's extension protocol (`_meta` fields and custom methods). Standard ACP editors and agents work with SACP without modification.
-
-## License
-
-MIT OR Apache-2.0
-
-## Contributing
-
-This repository will be upstreamed to the `agent-client-protocol` organization. Contributions welcome!
+Full documentation is available in the [mdbook](https://rust-lang.github.io/mdBook/). You can browse the latest version on [our Github pages site](https://symposium-acp.github.io/symposium-acp/).

README.md

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2024"
 description = "Classic Eliza chatbot as an ACP agent for testing"
 license = "MIT OR Apache-2.0"
-repository = "https://github.com/agent-client-protocol/symposium-acp"
+repository = "https://github.com/symposium-dev/symposium-acp"
 keywords = ["acp", "agent", "eliza", "testing"]
 categories = ["development-tools"]
 authors = ["Niko Matsakis <niko@alum.mit.edu>"]

src/elizacp/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.1"
 edition = "2024"
 description = "Conductor for orchestrating SACP proxy chains"
 license = "MIT OR Apache-2.0"
-repository = "https://github.com/agent-client-protocol/symposium-acp"
+repository = "https://github.com/symposium-dev/symposium-acp"
 keywords = ["acp", "agent", "conductor", "ai"]
 categories = ["development-tools"]
 

src/sacp-conductor/Cargo.toml

@@ -0,0 +1,86 @@
+# sacp-conductor
+
+Binary for orchestrating ACP proxy chains.
+
+## What is the conductor?
+
+The conductor is a tool that manages proxy chains - it spawns proxy components and the base agent, then routes messages between them. From the editor's perspective, the conductor appears as a single ACP agent.
+
+```
+Editor ← stdio → Conductor → Proxy 1 → Proxy 2 → Agent
+```
+
+## Usage
+
+### Agent Mode
+
+Orchestrate a chain of proxies in front of an agent:
+
+```bash
+# Chain format: proxy1 proxy2 ... agent
+sacp-conductor agent "python proxy1.py" "python proxy2.py" "python base-agent.py"
+```
+
+The conductor:
+1. Spawns each component as a subprocess
+2. Connects them in a chain
+3. Presents as a single agent on stdin/stdout
+4. Manages the lifecycle of all processes
+
+### MCP Bridge Mode
+
+Connect stdio to a TCP-based MCP server:
+
+```bash
+# Bridge stdio to MCP server on localhost:8080
+sacp-conductor mcp 8080
+```
+
+This allows stdio-based tools to communicate with TCP MCP servers.
+
+## How It Works
+
+**Component Communication:**
+- Editor talks to conductor via stdio
+- Conductor uses `_proxy/successor/*` protocol extensions to route messages
+- Each proxy can intercept, transform, or forward messages
+- Final agent receives standard ACP messages
+
+**Process Management:**
+- All components are spawned as child processes
+- When conductor exits, all children are terminated
+- Errors in any component bring down the entire chain
+
+## Example Use Case
+
+Add Sparkle embodiment + custom tools to any agent:
+
+```bash
+sacp-conductor agent \
+  "sparkle-acp-proxy" \
+  "my-custom-tools-proxy" \
+  "claude-agent"
+```
+
+This creates a stack where:
+1. Sparkle proxy injects MCP servers and prepends embodiment
+2. Custom tools proxy adds domain-specific functionality  
+3. Base agent handles the actual AI responses
+
+## Building
+
+```bash
+cargo build --release -p sacp-conductor
+```
+
+Binary will be at `target/release/sacp-conductor`.
+
+## Related Crates
+
+- **[sacp-proxy](../sacp-proxy/)** - Framework for building proxy components
+- **[sacp](../sacp/)** - Core ACP SDK
+- **[sacp-tokio](../sacp-tokio/)** - Tokio utilities for process spawning
+
+## License
+
+MIT OR Apache-2.0

src/sacp-conductor/README.md

@@ -70,9 +70,9 @@ use sacp_proxy::{
 };
 
 use sacp::{
-    JrConnection, JrConnectionCx, JrNotification, JrRequestCx, JrResponse, JsonRpcRequest,
-    MessageAndCx, MetaCapabilityExt, NullHandler, Proxy, TypeNotification, TypeRequest,
-    UntypedMessage,
+    JrConnection, JrConnectionCx, JrNotification, JrRequest, JrRequestCx, JrResponse, MessageAndCx,
+    MetaCapabilityExt, NullHandler, Proxy, UntypedMessage,
+    util::{TypeNotification, TypeRequest},
 };
 use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 use tracing::{debug, info};
@@ -480,7 +480,7 @@ impl Conductor {
     /// * If the message is going to a proxy component, then we have to wrap
     ///   it in a "from successor" wrapper, because the conductor is the
     ///   proxy's client.
-    fn send_message_to_predecessor_of<Req: JsonRpcRequest, N: JrNotification>(
+    fn send_message_to_predecessor_of<Req: JrRequest, N: JrNotification>(
         &mut self,
         client: &JrConnectionCx,
         source_component_index: usize,
@@ -504,7 +504,7 @@ impl Conductor {
         }
     }
 
-    fn send_request_to_predecessor_of<Req: JsonRpcRequest>(
+    fn send_request_to_predecessor_of<Req: JrRequest>(
         &mut self,
         client: &JrConnectionCx,
         source_component_index: usize,

src/sacp-conductor/src/conductor.rs

@@ -0,0 +1,10 @@
+[package]
+name = "sacp-doc-test"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sacp = { path = "../sacp" }
+serde.workspace = true
+futures.workspace = true
+serde_json.workspace = true