docs(acp-nats-agent): add README

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

rsworkspace/crates/acp-nats-agent/README.md

@@ -0,0 +1,109 @@
+# acp-nats-agent
+
+Server-side framework for building [ACP](https://agentclientprotocol.com/) agents over NATS.
+
+Mirrors the ACP SDK's `AgentSideConnection` pattern — implement the `Agent` trait, pass a NATS client, and the framework handles subscription, dispatch, serialization, and replies.
+
+## Usage
+
+```rust
+use acp_nats::AcpPrefix;
+use acp_nats_agent::AgentSideNatsConnection;
+use agent_client_protocol::*;
+
+struct MyAgent;
+
+#[async_trait::async_trait(?Send)]
+impl Agent for MyAgent {
+    async fn initialize(&self, args: InitializeRequest) -> Result<InitializeResponse> {
+        Ok(InitializeResponse::new(ProtocolVersion::V0))
+    }
+
+    async fn new_session(&self, args: NewSessionRequest) -> Result<NewSessionResponse> {
+        Ok(NewSessionResponse::new("session-123"))
+    }
+
+    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse> {
+        // Your LLM logic here
+        Ok(PromptResponse::new(StopReason::EndTurn))
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    let nats = async_nats::connect("localhost:4222").await.unwrap();
+
+    let (connection, io_task) = AgentSideNatsConnection::new(
+        MyAgent,
+        nats,
+        AcpPrefix::new("acp").unwrap(),
+        |fut| { tokio::task::spawn_local(fut); },
+    );
+
+    // connection.client_for_session(session_id) returns a Client
+    // for sending notifications, permissions, file ops back to the IDE
+
+    let local = tokio::task::LocalSet::new();
+    local.run_until(io_task).await.unwrap();
+}
+```
+
+## Architecture
+
+```
+IDE <-> Bridge (acp-nats-stdio) <-> NATS <-> Agent (acp-nats-agent)
+```
+
+The bridge sits between the IDE and NATS. This framework sits on the other side — it subscribes to agent subjects, dispatches to your `Agent` trait implementation, and replies via NATS.
+
+### What the framework handles
+
+- NATS subscription to `{prefix}.agent.>` and `{prefix}.*.agent.>`
+- Subject parsing and dispatch to all 15 ACP 0.10.2 agent methods
+- JSON serialization/deserialization of requests and responses
+- Error replies on deserialization failure (`InvalidParams`)
+- Ext method vs ext notification detection (by reply subject presence)
+- Trace context propagation on replies
+- Flush after every reply
+
+### What you implement
+
+- The `Agent` trait — your business logic
+- Session state management (if needed)
+- Concurrency strategy (via the `spawn` callback)
+
+## Client callbacks
+
+During prompt handling, agents often need to call back to the IDE — send notifications, request permissions, read files, run terminal commands. Use `connection.client_for_session(session_id)` to get a `Client` impl scoped to that session:
+
+```rust
+let client = connection.client_for_session(session_id);
+
+// Send progress updates
+client.session_notification(notification).await?;
+
+// Request user permission for a tool call
+let response = client.request_permission(request).await?;
+
+// Read a file from the IDE
+let file = client.read_text_file(request).await?;
+```
+
+## Concurrency
+
+The `spawn` callback controls how incoming messages are dispatched. Each message is spawned as a separate task via your callback — the message loop never blocks.
+
+```rust
+// Single-threaded cooperative (recommended)
+|fut| { tokio::task::spawn_local(fut); }
+
+// With backpressure
+let semaphore = Rc::new(Semaphore::new(64));
+|fut| {
+    let permit = semaphore.clone();
+    tokio::task::spawn_local(async move {
+        let _permit = permit.acquire().await;
+        fut.await;
+    });
+}
+```