docs: prepare for 0.3.0

Signed-off-by: Chojan Shang <chojan.shang@vesoft.com>

Author: Chojan Shang

README.md

@@ -5,6 +5,7 @@ A Python implementation of the Agent Client Protocol (ACP). Use it to build agen
 - Package name: `agent-client-protocol` (import as `acp`)
 - Repository: https://github.com/psiace/agent-client-protocol-python
 - Docs: https://psiace.github.io/agent-client-protocol-python/
+- Featured: Listed as the first third-party SDK on the official ACP site — see https://agentclientprotocol.com/libraries/community
 
 ## Install
 
@@ -24,51 +25,54 @@ make test      # run tests
 
 ## Minimal agent example
 
+See a complete streaming echo example in [examples/echo_agent.py](examples/echo_agent.py). It streams back each text block using `session/update` and ends the turn.
+
 ```python
 import asyncio
 
 from acp import (
     Agent,
     AgentSideConnection,
-    AuthenticateRequest,
-    CancelNotification,
     InitializeRequest,
     InitializeResponse,
-    LoadSessionRequest,
     NewSessionRequest,
     NewSessionResponse,
     PromptRequest,
     PromptResponse,
+    SessionNotification,
     stdio_streams,
 )
+from acp.schema import ContentBlock1, SessionUpdate2
 
 
 class EchoAgent(Agent):
+    def __init__(self, conn):
+        self._conn = conn
+
     async def initialize(self, params: InitializeRequest) -> InitializeResponse:
         return InitializeResponse(protocolVersion=params.protocolVersion)
 
     async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
         return NewSessionResponse(sessionId="sess-1")
 
-    async def loadSession(self, params: LoadSessionRequest) -> None:
-        return None
-
-    async def authenticate(self, params: AuthenticateRequest) -> None:
-        return None
-
     async def prompt(self, params: PromptRequest) -> PromptResponse:
-        # Normally you'd stream updates via sessionUpdate
+        for block in params.prompt:
+            text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=SessionUpdate2(
+                        sessionUpdate="agent_message_chunk",
+                        content=ContentBlock1(type="text", text=text),
+                    ),
+                )
+            )
         return PromptResponse(stopReason="end_turn")
 
-    async def cancel(self, params: CancelNotification) -> None:
-        return None
-
 
 async def main() -> None:
     reader, writer = await stdio_streams()
-    # For an agent process, local writes go to client stdin (writer=stdout)
-    AgentSideConnection(lambda _conn: EchoAgent(), writer, reader)
-    # Keep running; in a real agent you would await tasks or add your own loop
+    AgentSideConnection(lambda conn: EchoAgent(conn), writer, reader)
     await asyncio.Event().wait()
 
 

docs/index.md

@@ -11,20 +11,56 @@ pip install agent-client-protocol
 ## Minimal usage
 
 ```python
-from acp import Agent, AgentSideConnection, Client, stdio_streams, PROTOCOL_VERSION, InitializeRequest, InitializeResponse, PromptRequest, PromptResponse
-from acp.schema import ContentBlock1, SessionUpdate2, SessionNotification
-
-class MyAgent(Agent):
-    def __init__(self, client: Client):
-        self.client = client
-    async def initialize(self, _p: InitializeRequest) -> InitializeResponse:
-        return InitializeResponse(protocolVersion=PROTOCOL_VERSION)
-    async def prompt(self, p: PromptRequest) -> PromptResponse:
-        await self.client.sessionUpdate(SessionNotification(
-            sessionId=p.sessionId,
-            update=SessionUpdate2(sessionUpdate="agent_message_chunk", content=ContentBlock1(type="text", text="Hello from ACP")),
-        ))
+import asyncio
+
+from acp import (
+    Agent,
+    AgentSideConnection,
+    InitializeRequest,
+    InitializeResponse,
+    NewSessionRequest,
+    NewSessionResponse,
+    PromptRequest,
+    PromptResponse,
+    SessionNotification,
+    stdio_streams,
+)
+from acp.schema import ContentBlock1, SessionUpdate2
+
+
+class EchoAgent(Agent):
+    def __init__(self, conn):
+        self._conn = conn
+
+    async def initialize(self, params: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=params.protocolVersion)
+
+    async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
+        return NewSessionResponse(sessionId="sess-1")
+
+    async def prompt(self, params: PromptRequest) -> PromptResponse:
+        for block in params.prompt:
+            text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=SessionUpdate2(
+                        sessionUpdate="agent_message_chunk",
+                        content=ContentBlock1(type="text", text=text),
+                    ),
+                )
+            )
         return PromptResponse(stopReason="end_turn")
+
+
+async def main() -> None:
+    reader, writer = await stdio_streams()
+    AgentSideConnection(lambda conn: EchoAgent(conn), writer, reader)
+    await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 - Quickstart: [quickstart.md](quickstart.md)

docs/mini-swe-agent.md

@@ -1,6 +1,6 @@
 # Mini SWE Agent bridge
 
-This example wraps mini-swe-agent behind ACP so Zed can run it as an external agent over stdio.
+This example wraps mini-swe-agent behind ACP so Zed can run it as an external agent over stdio. It also includes a local Textual UI client connected via a duet launcher.
 
 ## Behavior
 
@@ -15,14 +15,29 @@ Non-terminating events (e.g. user rejection or timeouts) are surfaced both as a
 
 ## Configuration
 
-Environment variables set in the Zed server config control the model:
+Environment variables control the model:
 
 - `MINI_SWE_MODEL`: model ID (e.g. `openrouter/openai/gpt-4o-mini`)
-- `MINI_SWE_MODEL_KWARGS`: JSON string of extra parameters (e.g. `{ "api_base": "https://openrouter.ai/api/v1" }`)
-- Vendor API keys (e.g. `OPENROUTER_API_KEY`) must be present in the environment
+- `OPENROUTER_API_KEY` for OpenRouter; or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` for native providers
+- Optional `MINI_SWE_MODEL_KWARGS`: JSON, e.g. `{ "api_base": "https://openrouter.ai/api/v1" }` (auto-injected for OpenRouter if missing)
+
+Agent behavior automatically maps the appropriate API key based on the chosen model and available environment variables.
 
 If `mini-swe-agent` is not installed in the venv, the bridge attempts to import a vendored reference copy under `reference/mini-swe-agent/src`.
 
+## How to run
+
+- In Zed (editor integration): configure an agent server to launch `examples/mini_swe_agent/agent.py` and set the environment variables there.
+- In terminal (local TUI): run the duet launcher to start both the agent and the Textual client with the same environment and dedicated pipes:
+
+```bash
+python examples/mini_swe_agent/duet.py
+```
+
+The launcher loads `.env` from the repo root (using python-dotenv) so both processes share the same configuration.
+
 ## Files
 
-- Example entry: [`examples/mini_swe_agent/agent.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/mini_swe_agent/agent.py)
+- Agent entry: [`examples/mini_swe_agent/agent.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/mini_swe_agent/agent.py)
+- Duet launcher: [`examples/mini_swe_agent/duet.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/mini_swe_agent/duet.py)
+- Textual client: [`examples/mini_swe_agent/client.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/mini_swe_agent/client.py)

docs/quickstart.md

@@ -16,45 +16,46 @@ import asyncio
 from acp import (
     Agent,
     AgentSideConnection,
-    AuthenticateRequest,
-    CancelNotification,
     InitializeRequest,
     InitializeResponse,
-    LoadSessionRequest,
     NewSessionRequest,
     NewSessionResponse,
     PromptRequest,
     PromptResponse,
+    SessionNotification,
     stdio_streams,
 )
+from acp.schema import ContentBlock1, SessionUpdate2
 
 
 class EchoAgent(Agent):
+    def __init__(self, conn):
+        self._conn = conn
+
     async def initialize(self, params: InitializeRequest) -> InitializeResponse:
         return InitializeResponse(protocolVersion=params.protocolVersion)
 
     async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
         return NewSessionResponse(sessionId="sess-1")
 
-    async def loadSession(self, params: LoadSessionRequest) -> None:
-        return None
-
-    async def authenticate(self, params: AuthenticateRequest) -> None:
-        return None
-
     async def prompt(self, params: PromptRequest) -> PromptResponse:
-        # Normally you'd stream updates via sessionUpdate
+        for block in params.prompt:
+            text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=SessionUpdate2(
+                        sessionUpdate="agent_message_chunk",
+                        content=ContentBlock1(type="text", text=text),
+                    ),
+                )
+            )
         return PromptResponse(stopReason="end_turn")
 
-    async def cancel(self, params: CancelNotification) -> None:
-        return None
-
 
 async def main() -> None:
     reader, writer = await stdio_streams()
-    # For an agent process, local writes go to client stdin (writer=stdout)
-    AgentSideConnection(lambda _conn: EchoAgent(), writer, reader)
-    # Keep running; in a real agent you would await tasks or add your own loop
+    AgentSideConnection(lambda conn: EchoAgent(conn), writer, reader)
     await asyncio.Event().wait()
 
 
@@ -84,14 +85,26 @@ Add an agent server to Zed’s `settings.json`:
       ],
       "env": {
         "MINI_SWE_MODEL": "openrouter/openai/gpt-4o-mini",
-        "MINI_SWE_MODEL_KWARGS": "{\"api_base\":\"https://openrouter.ai/api/v1\"}",
         "OPENROUTER_API_KEY": "sk-or-..."
       }
     }
   }
 }
 ```
 
+- For OpenRouter, `api_base` is set automatically to `https://openrouter.ai/api/v1` if not provided.
+- Alternatively, use native providers by setting `MINI_SWE_MODEL` accordingly and providing `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
+
 In Zed, open the Agents panel and select "Mini SWE Agent (Python)".
 
 See [mini-swe-agent.md](mini-swe-agent.md) for behavior and message mapping details.
+
+## Run locally with a TUI
+
+Use the duet launcher to run both the agent and the local Textual client over dedicated pipes:
+
+```bash
+python examples/mini_swe_agent/duet.py
+```
+
+The launcher loads `.env` from the repo root so both processes share the same configuration (requires python-dotenv).

examples/echo_agent.py

@@ -0,0 +1,50 @@
+import asyncio
+
+from acp import (
+    Agent,
+    AgentSideConnection,
+    InitializeRequest,
+    InitializeResponse,
+    NewSessionRequest,
+    NewSessionResponse,
+    PromptRequest,
+    PromptResponse,
+    SessionNotification,
+    stdio_streams,
+)
+from acp.schema import ContentBlock1, SessionUpdate2
+
+
+class EchoAgent(Agent):
+    def __init__(self, conn):
+        self._conn = conn
+
+    async def initialize(self, params: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=params.protocolVersion)
+
+    async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
+        return NewSessionResponse(sessionId="sess-1")
+
+    async def prompt(self, params: PromptRequest) -> PromptResponse:
+        for block in params.prompt:
+            text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=SessionUpdate2(
+                        sessionUpdate="agent_message_chunk",
+                        content=ContentBlock1(type="text", text=text),
+                    ),
+                )
+            )
+        return PromptResponse(stopReason="end_turn")
+
+
+async def main() -> None:
+    reader, writer = await stdio_streams()
+    AgentSideConnection(lambda conn: EchoAgent(conn), writer, reader)
+    await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/mini_swe_agent/README.md

@@ -1,8 +1,8 @@
 # Mini SWE Agent (Python) — ACP Bridge
 
-A minimal Agent Client Protocol (ACP) bridge that wraps mini-swe-agent so it can be run by Zed as an external agent over stdio.
+A minimal Agent Client Protocol (ACP) bridge that wraps mini-swe-agent so it can be run by Zed as an external agent over stdio, and also provides a local Textual UI client.
 
-## Configure in Zed
+## Configure in Zed (recommended for editor integration)
 
 Add an `agent_servers` entry to Zed’s `settings.json`. Point `command` to the Python interpreter that has both `agent-client-protocol` and `mini-swe-agent` installed, and `args` to this example script:
 
@@ -32,16 +32,24 @@ Notes
   - Set `OPENROUTER_API_KEY` to your API key.
 - Alternatively, you can use native OpenAI/Anthropic APIs. Set `MINI_SWE_MODEL` accordingly and provide the vendor-specific API key; `MINI_SWE_MODEL_KWARGS` is optional.
 
-## Requirements
+## Run locally with a TUI (Textual)
 
-Install mini-swe-agent (or at least its core deps) into the same environment:
+Use the duet launcher to run both the ACP agent and the local Textual client connected over dedicated pipes. The client keeps your terminal stdio; ACP messages flow over separate FDs.
 
 ```bash
-pip install agent-client-protocol mini-swe-agent
-# or: pip install litellm jinja2 tenacity
+# From repo root
+python examples/mini_swe_agent/duet.py
 ```
 
-Then in Zed, open the Agents panel and select "Mini SWE Agent (Python)" to start a thread.
+Environment
+- The launcher loads `.env` from the repo root using python-dotenv (override=True) so both child processes inherit the same environment.
+- Minimum for OpenRouter:
+  - `MINI_SWE_MODEL="openrouter/openai/gpt-4o-mini"`
+  - `OPENROUTER_API_KEY="sk-or-..."`
+  - Optional: `MINI_SWE_MODEL_KWARGS='{"api_base":"https://openrouter.ai/api/v1"}'` (auto-injected if missing)
+
+Quit behavior
+- Quit from the TUI cleanly ends the background loop; duet will terminate both processes gracefully and force-kill after a short timeout if needed.
 
 ## Behavior overview
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-client-protocol"
-version = "0.0.1"
+version = "0.3.0"
 description = "A Python implement of Agent Client Protocol (ACP, by Zed Industries)"
 authors = [{ name = "Chojan Shang", email = "psiace@apache.org" }]
 readme = "README.md"