channel-bot-cli-acp 0.1.0__tar.gz

channel_bot_cli_acp-0.1.0/.agents/skills/acp-python-sdk-docs/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: acp-python-sdk-docs
+description: Local knowledge base mirroring the official Agent Client Protocol (ACP) Python SDK (agent-client-protocol) documentation and runnable examples. Use when building, integrating, debugging, or migrating ACP-compatible AI agents and clients in Python over stdio, Streamable HTTP (HTTP/2 + SSE), or WebSocket transports, working with acp.schema Pydantic models, acp.contrib helpers (SessionAccumulator, ToolCallTracker, PermissionBroker), or experimental Protocol v2 (acp.experimental.v2).
+metadata:
+  author: Ecat
+  version: "1.0.0"
+  source: https://github.com/agentclientprotocol/python-sdk
+---
+
+# Agent Client Protocol (ACP) Python SDK Documentation
+
+This skill provides the official documentation, migration guides, and runnable example scripts for the **Agent Client Protocol (ACP) Python SDK** (`agent-client-protocol`), enabling Python applications to implement ACP-compatible AI agents and clients without rebuilding JSON-RPC transports or schema models.
+
+---
+
+## ⚠️ Important Note on Reference Links & Path Mapping
+
+This skill directory (`skills/acp-python-sdk-docs`) is a local mirror of the official [`agentclientprotocol/python-sdk`](https://github.com/agentclientprotocol/python-sdk) repository. When reading the Markdown files in `docs/`, resolve reference links using these rules:
+
+1. **GitHub Repository Links (`blob/main/` & `tree/main/`)**:
+   Any link starting with `https://github.com/agentclientprotocol/python-sdk/blob/main/` or `https://github.com/agentclientprotocol/python-sdk/tree/main/` maps directly to the root of this skill directory (`skills/acp-python-sdk-docs/`).
+   - The local [`examples/`](examples/) directory is a direct mirror of the GitHub repository's `examples/` folder:
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/echo_agent.py` ➔ [`examples/echo_agent.py`](examples/echo_agent.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/agent.py` ➔ [`examples/agent.py`](examples/agent.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/client.py` ➔ [`examples/client.py`](examples/client.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/duet.py` ➔ [`examples/duet.py`](examples/duet.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/gemini.py` ➔ [`examples/gemini.py`](examples/gemini.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/http_server.py` ➔ [`examples/http_server.py`](examples/http_server.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/http_client.py` ➔ [`examples/http_client.py`](examples/http_client.py)
+     - `https://github.com/agentclientprotocol/python-sdk/blob/main/examples/ws_client.py` ➔ [`examples/ws_client.py`](examples/ws_client.py)
+     - `https://github.com/agentclientprotocol/python-sdk/tree/main/examples` ➔ [`examples/`](examples/)
+2. **Relative Documentation Links**:
+   Links within `docs/*.md` such as `[Quickstart](quickstart.md)`, `[Use Cases](use-cases.md)`, or `[contrib.md](contrib.md)` are relative to the `docs/` directory (e.g., `docs/quickstart.md`, `docs/use-cases.md`, `docs/contrib.md`).
+3. **Unmirrored Internal SDK Source Files (`src/acp/`, `tests/`, `schema/`)**:
+   Mentions of internal repository paths like `src/acp/interfaces.py`, `src/acp/schema.py`, `src/acp/core.py`, or `tests/` refer to the upstream SDK source code and are not included in this documentation mirror. Use `docs/` and `examples/` for API signatures and usage patterns.
+
+---
+
+## 📦 Package & Environment Overview
+
+- **PyPI Package**: `agent-client-protocol`
+- **Import Root**: `acp`
+- **Python Requirement**: Python `>=3.10` (3.10–3.14+)
+- **Bundled Protocol Schemas**:
+  - **Stable v1**: `schema-v1.23.0` (`acp`, `acp.schema`, `acp.interfaces`)
+  - **Experimental v2**: `schema-v2.0.0-alpha.5` (`acp.experimental.v2`)
+
+```bash
+# Core SDK (stdio transport + Pydantic schema models)
+pip install agent-client-protocol
+# or
+uv add agent-client-protocol
+
+# Optional web transports (Streamable HTTP over HTTP/2 + SSE, WebSocket, Starlette ASGI server)
+pip install "agent-client-protocol[http]"
+```
+
+---
+
+## 📚 Documentation Index (`docs/`)
+
+| Document | Topic | Key Contents |
+|---|---|---|
+| [`docs/index.md`](docs/index.md) | **Overview & Architecture** | High-level overview of ACP, SDK building blocks (`acp.schema`, `acp.agent`/`acp.client`, `acp.contrib`), and navigation links. |
+| [`docs/quickstart.md`](docs/quickstart.md) | **Quickstart & v1 Guide** | Installation, running the echo agent, Zed `settings.json` wiring, `spawn_agent_process`, subclassing `acp.Agent`, session notices (`SessionUpdateNotice`), additional v1 methods (`session/delete`, `providers/*`, `logout`, `mcp/*`, `nes/*`, `document/*`), request cancellation (`$/cancel_request`), `@param_model` routing, and Gemini CLI bridge. |
+| [`docs/web-transport.md`](docs/web-transport.md) | **Web Transports (HTTP & WS)** | Experimental remote transports (`agent-client-protocol[http]`): Streamable HTTP (`create_http_stream`) and WebSocket (`create_websocket_stream`), Starlette server (`create_asgi_app`), sub-app mounting with lifespan, `load_session` / `resume_session` SSE routing, and HTTP/2 server setup with Hypercorn. |
+| [`docs/contrib.md`](docs/contrib.md) | **Experimental Contrib Helpers** | Production utilities in `acp.contrib`: `SessionAccumulator` (`acp.contrib.session_state`), `ToolCallTracker` (`acp.contrib.tool_calls`), and `PermissionBroker` (`acp.contrib.permissions`). |
+| [`docs/experimental-v2.md`](docs/experimental-v2.md) | **Experimental Protocol v2** | Draft v2 bindings (`acp.experimental.v2`, `schema-v2.0.0-alpha.5`), v2 `Agent`/`Client` handlers, non-blocking `prompt` with `message_id`, session notices, patch semantics (`None` vs omitted), and serving v1+v2 simultaneously via `AgentProtocolRouter`. |
+| [`docs/use-cases.md`](docs/use-cases.md) | **Real-World Use Cases** | Production agents and clients built with the SDK (kimi-cli, Mini-Agent, OpenHands-CLI, fast-agent, agent-client-kernel, simple-acp-client). |
+| [`docs/migration-guide-0.11.md`](docs/migration-guide-0.11.md) | **Migration Guide: 0.11** | Upgrading to 0.11 (`schema-v1.16.0`): `session_id`-first parameter ordering on `Client` and `Agent`, removal of `PromptRequest.message_id` and `set_session_model`, elicitation support (`create_elicitation`, `complete_elicitation`), `AgentPlanContentUpdate` / `AgentPlanRemovedUpdate`, and `AcpMcpServer`. |
+| [`docs/migration-guide-0.8.md`](docs/migration-guide-0.8.md) | **Migration Guide: 0.8** | Upgrading to 0.8 (`schema-v0.10.8`): removal of `TerminalHandle` (use `CreateTerminalResponse.terminal_id`), `SessionInfoUpdate`, and 50MB default `stdio_buffer_limit_bytes`. |
+| [`docs/migration-guide-0.7.md`](docs/migration-guide-0.7.md) | **Migration Guide: 0.7** | Upgrading to 0.7: `snake_case` Pydantic fields (`by_alias=True` when dumping), `run_agent` / `connect_to_agent` replacing manual `AgentSideConnection` / `ClientSideConnection`, and expanded method signatures. |
+| [`docs/releasing.md`](docs/releasing.md) | **Releasing & Schema Sync** | Regenerating schema bindings (`ACP_SCHEMA_VERSION=... make gen-all`), running `make check` / `make test`, and publishing releases. |
+
+---
+
+## 💻 Mirrored Code Examples (`examples/`)
+
+All upstream example scripts are mirrored locally under [`examples/`](examples/):
+
+| File | Role / Transport | Description & Key APIs Demonstrated |
+|---|---|---|
+| [`examples/echo_agent.py`](examples/echo_agent.py) | Minimal Agent (stdio) | Smallest streaming agent: subclasses `Agent`, captures `Client` connection in `on_connect`, handles `initialize`, `new_session`, and streams `AgentMessageChunk` via `self._conn.session_update()` inside `prompt()`, launched with `run_agent()`. |
+| [`examples/agent.py`](examples/agent.py) | Full-Featured Agent (stdio) | Implements `initialize` (with `AgentCapabilities` and `Implementation`), `authenticate`, `new_session`, `load_session`, `set_session_mode`, `prompt`, `cancel`, `ext_method`, and `ext_notification`. |
+| [`examples/client.py`](examples/client.py) | Interactive Client (stdio) | Spawns an agent subprocess, wires stdio with `connect_to_agent()`, implements `Client` callbacks (`request_permission`, `read_text_file`, `write_text_file`, terminal methods, `create_elicitation`, `complete_elicitation`, `session_update`), and runs an interactive console prompt loop. |
+| [`examples/duet.py`](examples/duet.py) | Client + Agent Duet (stdio) | Uses `spawn_agent_process(client, sys.executable, str(agent_path))` context manager to launch [`examples/agent.py`](examples/agent.py) and drive it interactively with `ExampleClient` from [`examples/client.py`](examples/client.py). |
+| [`examples/gemini.py`](examples/gemini.py) | Gemini CLI Bridge (stdio) | Complete ACP client driving `gemini --acp` (or `--experimental-acp`): implements file read/write (`FileSystemCapabilities`), terminal callbacks, interactive or `--yolo` auto-approval permission flows (`AllowedOutcome` / `DeniedOutcome`), and `:cancel` handling. |
+| [`examples/http_server.py`](examples/http_server.py) | Remote Agent Server (HTTP/2 + WS) | Wraps an `EchoAgent` in a Starlette ASGI app using `create_asgi_app(lambda conn: EchoAgent())` and serves both Streamable HTTP and WebSocket on `http://localhost:8000/acp` via Hypercorn with HTTP/2 enabled (`alpn_protocols = ["h2", "http/1.1"]`). |
+| [`examples/http_client.py`](examples/http_client.py) | Remote Client (Streamable HTTP) | Connects to a remote ACP server using `create_http_stream("http://localhost:8000/acp")` and `connect_to_agent()`. |
+| [`examples/ws_client.py`](examples/ws_client.py) | Remote Client (WebSocket) | Connects to a remote ACP server using `await create_websocket_stream("ws://localhost:8000/acp")` and `connect_to_agent()`. |
+
+---
+
+## 🚀 Core Usage Patterns & Quick Reference
+
+### 1. Implementing a Streaming ACP Agent (stdio)
+
+Subclass `acp.Agent`, store the peer `Client` connection in `on_connect`, stream updates via `session_update`, and start the stdio loop with `run_agent()`:
+
+```python
+import asyncio
+from typing import Any
+from uuid import uuid4
+
+from acp import Agent, InitializeResponse, NewSessionResponse, PromptResponse, run_agent
+from acp.interfaces import Client
+from acp.schema import AgentMessageChunk, ClientCapabilities, Implementation, TextContentBlock
+
+
+class MyAgent(Agent):
+    _conn: Client
+
+    def on_connect(self, conn: Client) -> None:
+        self._conn = conn
+
+    async def initialize(
+        self,
+        protocol_version: int,
+        client_capabilities: ClientCapabilities | None = None,
+        client_info: Implementation | None = None,
+        **kwargs: Any,
+    ) -> InitializeResponse:
+        return InitializeResponse(protocol_version=protocol_version)
+
+    async def new_session(self, cwd: str, **kwargs: Any) -> NewSessionResponse:
+        return NewSessionResponse(session_id=uuid4().hex)
+
+    async def prompt(self, session_id: str, prompt: list[Any], **kwargs: Any) -> PromptResponse:
+        await self._conn.session_update(
+            session_id=session_id,
+            update=AgentMessageChunk(content=TextContentBlock(text="Processing prompt...")),
+        )
+        return PromptResponse(stop_reason="end_turn")
+
+
+if __name__ == "__main__":
+    asyncio.run(run_agent(MyAgent()))
+```
+
+### 2. Programmatically Spawning & Driving an Agent from Python
+
+Use `spawn_agent_process` (or `spawn_client_process`) to manage child process lifecycle and stdio framing automatically:
+
+```python
+import asyncio
+import sys
+from typing import Any
+
+from acp import PROTOCOL_VERSION, spawn_agent_process
+from acp.interfaces import Client
+from acp.schema import TextContentBlock
+
+
+class SimpleClient(Client):
+    async def request_permission(self, session_id: str, tool_call: Any, options: Any, **kwargs: Any) -> Any:
+        return {"outcome": {"outcome": "cancelled"}}
+
+    async def session_update(self, session_id: str, update: Any, **kwargs: Any) -> None:
+        print("update:", session_id, update)
+
+
+async def main() -> None:
+    async with spawn_agent_process(SimpleClient(), sys.executable, "examples/echo_agent.py") as (conn, _proc):
+        await conn.initialize(protocol_version=PROTOCOL_VERSION)
+        session = await conn.new_session(cwd=".", mcp_servers=[])
+        await conn.prompt(
+            session_id=session.session_id,
+            prompt=[TextContentBlock(text="Hello from Python client!")],
+        )
+
+
+asyncio.run(main())
+```
+
+### 3. Remote Web Transports (Streamable HTTP & WebSocket)
+
+Requires `pip install "agent-client-protocol[http]"`. See [`docs/web-transport.md`](docs/web-transport.md) for full details.
+
+- **Server (`acp.http.asgi.create_asgi_app`)**:
+  Creates a Starlette application serving both Streamable HTTP (`POST`/`GET` SSE/`DELETE`) and WebSocket upgrades at `/acp` (configurable via `path="/rpc"`).
+  > ⚠️ **HTTP/2 Requirement**: Streamable HTTP requires an HTTP/2-capable ASGI server such as **Hypercorn**, Daphne, or Granian (Uvicorn only supports WebSocket, not HTTP/2).
+- **Client (`acp.http.create_http_stream` / `acp.ws.create_websocket_stream`)**:
+  ```python
+  from acp import connect_to_agent
+  from acp.http import create_http_stream
+  from acp.ws import create_websocket_stream
+
+  # Streamable HTTP
+  transport = create_http_stream("http://localhost:8000/acp")
+  conn = connect_to_agent(my_client, transport)
+
+  # Or WebSocket
+  transport = await create_websocket_stream("ws://localhost:8000/acp")
+  conn = connect_to_agent(my_client, transport)
+  ```
+
+### 4. Additional v1 Protocol Methods & Unstable Opt-In
+
+In `schema-v1.23.0`, `session/delete` (`delete_session`) and `logout` (`logout`) are stable. Unstable methods require `use_unstable_protocol=True` on the receiving connection or `run_agent()`:
+- **Agent receivers**: `delete_session` (stable), `logout` (stable), `list_providers`, `set_provider`, `disable_provider`, `start_nes`, `suggest_nes`, `close_nes`, `accept_nes`, `reject_nes`, `did_open`, `did_change`, `did_close`, `did_save`, `did_focus`.
+- **Client receivers**: `connect_mcp`, `disconnect_mcp`, `create_elicitation`, `complete_elicitation`.
+- **Either peer**: `mcp_message` (request), `notify_mcp` (notification).
+
+See [`docs/quickstart.md`](docs/quickstart.md#additional-v1-protocol-methods) and [`docs/migration-guide-0.11.md`](docs/migration-guide-0.11.md#4-handle-elicitation-if-your-agent-or-client-advertises-it) for handler signatures.
+
+### 5. Experimental Contrib Utilities (`acp.contrib`)
+
+See [`docs/contrib.md`](docs/contrib.md) for stateful helpers:
+- **`acp.contrib.session_state.SessionAccumulator`**: Reconciles streamed `SessionNotification` events (`tool_call`, `tool_call_update`, plans, messages) into immutable `SessionSnapshot` Pydantic models with `apply()`, `snapshot()`, and `subscribe()`.
+- **`acp.contrib.tool_calls.ToolCallTracker`**: Emits canonical `ToolCallStart` / `ToolCallProgress` updates (`start()`, `progress()`, `append_stream_text()`) and tracks in-memory tool call views.
+- **`acp.contrib.permissions.PermissionBroker`**: Wraps `requestPermission` RPCs (`request_for()`) with default Approve / Approve for session / Reject options (`default_permission_options()`), syncing state with `ToolCallTracker`.
+
+### 6. Experimental Protocol v2 & Dual-Version Routing (`acp.experimental`)
+
+See [`docs/experimental-v2.md`](docs/experimental-v2.md) for draft `schema-v2.0.0-alpha.5` support:
+- Import `from acp.experimental import v2` for `v2.Agent`, `v2.Client`, `v2.connect_to_agent`, `v2.run_agent`, and `v2.schema`.
+- Use `AgentProtocolRouter(v1=lambda conn: V1Agent(conn), v2=lambda conn: V2Agent(conn))` from `acp.experimental` to serve both v1 and v2 clients from a single agent process.

channel_bot_cli_acp-0.1.0/.agents/skills/acp-python-sdk-docs/docs/contrib.md

@@ -0,0 +1,41 @@
+# Experimental Contrib Modules
+
+The helpers under `acp.contrib` package recurring patterns we saw in integrations such as Toad, kimi-cli, and Gemini. Keep in mind they are experimental—APIs can still shift as we learn. Use this page as a menu:
+
+- **`session_state.SessionAccumulator`** — build a canonical, immutable snapshot of every session update so UIs can render tool calls and plans without re-implementing state machines.
+- **`tool_calls.ToolCallTracker` + `permissions.PermissionBroker`** — coordinate streamed tool call updates and permission prompts from one place.
+
+## SessionAccumulator (`acp.contrib.session_state`)
+
+**Use it when:** you need a live, merged view of `SessionNotification` events (e.g. tool calls, plan entries, user/agent messages) to drive UI widgets.
+
+**Key capabilities**
+
+- `SessionAccumulator.apply(notification)` reconciles `tool_call` and `tool_call_update` payloads, even if the start event arrives late.
+- `snapshot()` returns an immutable `SessionSnapshot` Pydantic model containing the plan, current mode, commands, and ordered message history.
+- Raw tool input/output payloads are copied when applying notifications and creating snapshots, so nested payload mutations do not change the accumulated state.
+- `subscribe(callback)` lets you push snapshots into stores or UI components whenever state changes.
+- Automatic reset on session-change (toggle with `auto_reset_on_session_change`).
+
+> Tip: Create one accumulator per UI controller. Feed every raw `SessionNotification` into it and render from `snapshot.tool_calls` / `snapshot.user_messages` instead of mutating state manually.
+
+## ToolCallTracker & PermissionBroker (`acp.contrib.tool_calls`, `acp.contrib.permissions`)
+
+**Use them when:** your agent runtime synthesises tool call IDs, streams arguments, and prompts the user for approval. The helpers centralise the bookkeeping so you don’t juggle raw Pydantic models.
+
+- `ToolCallTracker.start()/progress()/append_stream_text()` emits canonical `ToolCallStart` / `ToolCallProgress` updates and keeps an in-memory view via `view()` or `tool_call_model()`.
+- `PermissionBroker.request_for()` wraps `requestPermission` RPCs. It reuses tracker state (or a provided `ToolCall`), lets you append extra content, and defaults to Approve / Approve for session / Reject options.
+- Omit `options` or pass `None` to use broker defaults. An explicit empty option list raises `MissingPermissionOptionsError` before the permission request is sent; the same applies to empty `default_options` when no per-request options are supplied.
+- `default_permission_options()` exposes that canonical option triple if you need to customise it.
+
+> Tip: Keep one tracker near the agent event loop. Emit notifications through it and share the tracker with `PermissionBroker` so permission prompts always match the latest tool call state.
+
+## Design Guardrails
+
+To stay aligned with the ACP schema, the contrib layer follows a few rules:
+
+- Schema data classes continue to live in `acp.schema`. Contrib helpers clone them with `.model_copy(deep=True)` before mutation.
+- The core runtime never imports contrib modules implicitly—you opt in when they help.
+- Helpers focus on painful bookkeeping (tool call aggregation, permission UX) and leave product-specific policy to your application.
+
+Try the contrib modules, then open an issue or PR with feedback so we know which APIs should graduate into the stable surface.

channel_bot_cli_acp-0.1.0/.agents/skills/acp-python-sdk-docs/docs/experimental-v2.md

@@ -0,0 +1,157 @@
+# Experimental Protocol v2
+
+> **Experimental.** Protocol v2 is a draft. Import it from `acp.experimental` and
+> expect its API and generated models to change with the upstream schema.
+
+The bindings use `schema-v2.0.0-alpha.5`.
+
+The v2 runtime is separate from the stable v1 API. Like v1, connection methods
+and agent/client handlers accept expanded, snake-case parameters. Responses and
+nested values (content blocks, updates, capabilities) use `v2.schema` models.
+Extra keyword arguments carry request `_meta`.
+
+Install update handlers before opening a session because updates are independent
+connection traffic:
+
+```python
+from typing import Any
+from acp.experimental import v2
+
+class MyClient(v2.Client):
+    async def session_update(
+        self, session_id: str, update: Any, **kwargs: Any,
+    ) -> None:
+        handle_update(session_id, update)
+
+
+connection = v2.connect_to_agent(MyClient(), transport)
+initialized = await connection.initialize(
+    protocol_version=v2.PROTOCOL_VERSION,
+    info=v2.schema.Implementation(name="my-client", version="1.0.0"),
+)
+session = await connection.new_session(cwd="/workspace")
+accepted = await connection.prompt(
+    session_id=session.session_id,
+    prompt=[v2.schema.TextContentBlock(text="Hello")],
+)
+```
+
+Implement an agent with the same expanded handler style:
+
+```python
+class MyAgent(v2.Agent):
+    async def initialize(
+        self,
+        protocol_version: int,
+        info: v2.schema.Implementation,
+        capabilities: v2.schema.ClientCapabilities | None = None,
+        **kwargs: Any,
+    ) -> v2.schema.InitializeResponse:
+        return v2.schema.InitializeResponse(
+            protocol_version=v2.PROTOCOL_VERSION,
+            info=v2.schema.Implementation(name="my-agent", version="1.0.0"),
+        )
+
+    async def new_session(
+        self,
+        cwd: str,
+        additional_directories: list[str] | None = None,
+        mcp_servers: list[Any] | None = None,
+        **kwargs: Any,
+    ) -> v2.schema.NewSessionResponse:
+        return v2.schema.NewSessionResponse(session_id="session-1")
+
+
+await v2.run_agent(MyAgent())
+```
+
+`v2.Agent` and `v2.Client` describe the v2 handler signatures; subclassing is
+optional. Implement only the methods you support. Unimplemented requests return
+method-not-found, and unimplemented notifications are ignored. The v2 protocols
+are separate from v1 because initialization, prompt responses, permissions, and
+session updates have different contracts. Both versions use `param_model`
+metadata to derive their routes. V2 retains strict request/response validation
+and requires successful initialization before other traffic.
+
+Previously, v2 methods accepted a whole request model. Replace
+`connection.new_session(v2.schema.NewSessionRequest(cwd="/workspace"))` with
+`connection.new_session(cwd="/workspace")`, and expand handler parameters likewise.
+
+Union requests also use expanded parameters:
+
+```python
+await connection.set_config_option(config_id="thinking", session_id=session.session_id, value=True)
+# type defaults to "boolean" for bool values and "id" otherwise.
+await connection.set_config_option(
+    config_id="vendor/limit", session_id=session.session_id, value=10, type="vendor/number",
+)
+await agent_connection.create_elicitation(
+    message="Sign in", mode="url", session_id=session.session_id,
+    elicitation_id="sign-in-1", url="https://example.com/login",
+)
+```
+
+For elicitation, `session_id` selects session scope; otherwise `request_id`
+selects request scope (including `None`). Pass `requested_schema` for form mode,
+or `elicitation_id` and `url` for URL mode. Handlers receive the validated
+branch's fields, including `type` for config options and `mode` for elicitation.
+
+`session/prompt` returns after the agent inserts the user message into the ACP
+conversation, without waiting for processing to finish. The response requires a
+non-null `message_id`. Agents return `v2.schema.PromptResponse(message_id=...)`
+and echo the user message in a `UserMessageUpdate` or `UserMessageChunk` carrying
+the same ID. That update may arrive before or after the response; use
+`accepted.message_id` to match it. Other session updates are independent traffic
+and do not carry a prompt identifier.
+
+Agents can send `v2.schema.SessionNotice(severity="warning", title="Context is nearly full")`
+with `await agent_connection.session_update(session_id=session_id, update=notice)`. V2 notices require no client capability and
+are live advisory events, outside retained session history. Clients may ignore
+them. Titles must be non-empty, and severity also accepts custom or future strings.
+
+For patch fields in session updates, omit a field to leave its current
+value unchanged, or explicitly pass `None` to clear it. For example,
+`v2.schema.SessionToolCallUpdate(tool_call_id="tool-1", name=None)` clears the
+tool name, while omitting `name` leaves it unchanged. This also applies to
+terminal updates and patch metadata. When applying received patches, use
+`update.model_dump(by_alias=True, exclude_unset=True)` to retain that distinction.
+
+Setting `replay_from=v2.schema.ReplayFromStartVariant()` on `connection.resume_session(...)`
+requests all retained conversation history; agents need not retain every message.
+Accepted elicitation content validates scalar values and string lists; nested
+objects are not valid form values.
+
+Agents that serve both versions use `AgentProtocolRouter`:
+
+```python
+from acp.experimental import AgentProtocolRouter
+
+router = AgentProtocolRouter(
+    v1=lambda connection: V1Agent(connection),
+    v2=lambda connection: V2Agent(connection),
+)
+await router.run()
+```
+
+The selected factory is called once per connection. Return a fresh agent from
+each call to avoid sharing connection state.
+
+Extension method names are explicit and must include the protocol-required `_`
+prefix:
+
+```python
+result = await connection.send_extension_request("_vendor/method", {"value": 1})
+await connection.send_extension_notification("_vendor/event", {"value": 1})
+```
+
+The selected runtime remains strict after initialization: v1 messages are not
+accepted by a v2 connection, and v2 messages are not translated into v1 calls.
+Only the initial v2 request is reduced to the common v1 initialization fields
+when an agent selects v1.
+
+Client-side fallback is application controlled and may require opening a new
+transport. Protocol-level request cancellation (`$/cancel_request`) is handled
+by the shared connection layer, as in v1: cancelling the task awaiting a request
+sends a best-effort cancellation to the peer, and an incoming cancellation
+cancels the handler task, which answers with its result or `-32800`.
+`session/cancel` remains available for cancelling active session work.

channel_bot_cli_acp-0.1.0/.agents/skills/acp-python-sdk-docs/docs/index.md

@@ -0,0 +1,64 @@
+<a href="https://agentclientprotocol.com/">
+  <img alt="Agent Client Protocol" src="https://zed.dev/img/acp/banner-dark.webp">
+</a>
+
+# Agent Client Protocol SDK (Python)
+
+Ship ACP-compatible agents and clients in Python without rebuilding JSON-RPC transports or schema models. This SDK mirrors each ACP release so your integrations stay interoperable with editors, CLIs, and hosted clients.
+
+## Install & verify
+
+```bash
+pip install agent-client-protocol
+# or
+uv add agent-client-protocol
+```
+
+Next steps live in the [Quickstart](quickstart.md): launch the echo agent, wire it to Zed (or another ACP client), and exercise the programmatic spawn helpers.
+
+## ACP at a glance
+
+- ACP is the stdio protocol that lets “clients” (editors, shells, CLIs) orchestrate AI “agents.”
+- Sessions exchange structured payloads (`session/update`, permission prompts, tool calls) defined in the upstream schema.
+- Matching the schema version keeps your Python integrations compatible with tools such as Zed, Gemini CLI, or kimi-cli.
+
+## SDK building blocks
+
+- `acp.schema`: generated Pydantic models with defaults for protocol discriminator fields.
+- `acp.agent` / `acp.client`: async base classes, JSON-RPC supervision, and lifecycle orchestration.
+- `acp.contrib`: experimental utilities (session accumulators, permission brokers, tool call trackers) harvested from production deployments.
+- `examples/`: runnable agents, clients, duet demos, and the Gemini CLI bridge.
+
+## Quick links
+
+| Need | Link |
+| --- | --- |
+| Quickstart walkthrough | [quickstart.md](quickstart.md) |
+| Real-world adopters | [use-cases.md](use-cases.md) |
+| Contrib helpers | [contrib.md](contrib.md) |
+| Releasing workflow | [releasing.md](releasing.md) |
+| Upgrade to 0.11 | [migration-guide-0.11.md](migration-guide-0.11.md) |
+| Example scripts | [github.com/agentclientprotocol/python-sdk/tree/main/examples](https://github.com/agentclientprotocol/python-sdk/tree/main/examples) |
+
+## Choose a path
+
+- **Just exploring?** Skim [use-cases.md](use-cases.md) to see how kimi-cli, agent-client-kernel, and others use the SDK.
+- **Building agents?** Copy `examples/echo_agent.py` or `examples/agent.py`, then use the generated models directly. Use `acp.contrib` for permission workflows and other stateful patterns.
+- **Embedding clients?** Start with `examples/client.py` or the `spawn_agent_process` / `spawn_client_process` helpers in the [Quickstart](quickstart.md#programmatic-launch).
+
+## Reference material
+
+- [Quickstart](quickstart.md) — installation, editor wiring, and programmatic launch walkthroughs.
+- [Use Cases](use-cases.md) — real adopters with succinct descriptions of what they build.
+- [Experimental Contrib](contrib.md) — deep dives on the `acp.contrib` utilities.
+- [Releasing](releasing.md) — schema upgrade process, versioning policy, and publishing checklist.
+- [0.11 Migration Guide](migration-guide-0.11.md) — interface signature updates, elicitation, and schema notes for 0.10 users.
+
+Need API-level details? Browse the source in `src/acp/` or generate docs with `mkdocstrings`.
+
+## Feedback & support
+
+- Open issues or discussions on GitHub for bugs, feature requests, or integration help.
+- Join [GitHub Discussions](https://github.com/agentclientprotocol/python-sdk/discussions) to swap ideas.
+- Chat with the community on [agentclientprotocol.zulipchat.com](https://agentclientprotocol.zulipchat.com/).
+- Follow ACP roadmap updates at [agentclientprotocol.com](https://agentclientprotocol.com/).

channel_bot_cli_acp-0.1.0/.agents/skills/acp-python-sdk-docs/docs/migration-guide-0.11.md

@@ -0,0 +1,144 @@
+# Migrating to ACP Python SDK 0.11
+
+ACP Python SDK 0.11 updates the generated bindings to `schema-v1.16.0` and aligns the high-level interfaces with the new schema. Most applications only need to update method signatures and review the new unstable capabilities. Agents and clients that already pass keyword arguments are the easiest to migrate.
+
+## 1. Regenerate schema-derived code
+
+If your project vendors ACP schema files, generated models, or protocol metadata, regenerate them against the same upstream schema tag:
+
+```bash
+ACP_SCHEMA_VERSION=schema-v1.16.0 make gen-all
+```
+
+The SDK package version is `0.11.0`, while the protocol schema tag is `schema-v1.16.0`.
+
+## 2. Update interface method signatures
+
+Several generated request models changed field order or fields. The SDK now exposes those shapes through `Agent` and `Client` protocol methods. Prefer keyword calls when invoking connection helpers; keyword calls are stable across field-order changes.
+
+### Client methods
+
+Update client implementations from the 0.10 positional order:
+
+```python
+async def request_permission(self, options, session_id, tool_call, **kwargs): ...
+async def write_text_file(self, content, path, session_id, **kwargs): ...
+async def read_text_file(self, path, session_id, limit=None, line=None, **kwargs): ...
+async def create_terminal(self, command, session_id, args=None, cwd=None, env=None, **kwargs): ...
+```
+
+to the 0.11 order:
+
+```python
+async def request_permission(self, session_id, tool_call, options, **kwargs): ...
+async def write_text_file(self, session_id, path, content, **kwargs): ...
+async def read_text_file(self, session_id, path, line=None, limit=None, **kwargs): ...
+async def create_terminal(self, session_id, command, args=None, env=None, cwd=None, **kwargs): ...
+```
+
+### Agent methods
+
+Update agent implementations from the 0.10 prompt and mode signatures:
+
+```python
+async def set_session_mode(self, mode_id, session_id, **kwargs): ...
+async def prompt(self, prompt, session_id, message_id=None, **kwargs): ...
+```
+
+to the 0.11 signatures:
+
+```python
+async def set_session_mode(self, session_id, mode_id, **kwargs): ...
+async def prompt(self, session_id, prompt, **kwargs): ...
+```
+
+The `message_id` field was removed from `PromptRequest`. If your client generated a user message ID before calling `conn.prompt(...)`, stop passing it there. Message IDs now belong to streamed content chunks such as `UserMessageChunk` and `AgentMessageChunk`.
+
+## 3. Remove `session/model` handling
+
+The generated `SetSessionModelRequest` and `SetSessionModelResponse` types are no longer exported, and the `Agent.set_session_model(...)` protocol method is gone. If your agent used this endpoint to switch models, move that behavior into session modes or configuration options exposed through `set_session_mode(...)` and `set_config_option(...)`.
+
+## 4. Handle elicitation if your agent or client advertises it
+
+0.11 adds schema and connection support for the unstable `elicitation/create` request and `elicitation/complete` notification.
+
+Clients that advertise elicitation support should implement:
+
+```python
+from typing import Any
+
+from acp import AcceptElicitationResponse, Client, CreateElicitationResponse, ElicitationMode
+
+
+class MyClient(Client):
+    async def create_elicitation(
+        self,
+        message: str,
+        mode: ElicitationMode,
+        **kwargs: Any,
+    ) -> CreateElicitationResponse:
+        return AcceptElicitationResponse(action="accept", content={})
+
+    async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None:
+        ...
+```
+
+Agents can request structured input through the connected client:
+
+```python
+from acp import (
+    ElicitationFormSessionMode,
+    ElicitationSchema,
+    ElicitationStringPropertySchema,
+)
+
+response = await client_conn.create_elicitation(
+    message="Choose a deployment target",
+    mode=ElicitationFormSessionMode(
+        session_id=session_id,
+        requested_schema=ElicitationSchema(
+            properties={"target": ElicitationStringPropertySchema(type="string")},
+            required=["target"],
+        ),
+    ),
+)
+```
+
+For URL-based flows, use `ElicitationUrlSessionMode` or `ElicitationUrlRequestMode` and call `complete_elicitation(...)` once the external flow finishes.
+
+## 5. Review new session update variants
+
+Clients that exhaustively match `session_update` variants should add the new plan update variants:
+
+```python
+from acp.schema import AgentPlanContentUpdate, AgentPlanRemovedUpdate
+
+async def session_update(self, session_id, update, **kwargs):
+    if isinstance(update, AgentPlanContentUpdate):
+        ...
+    elif isinstance(update, AgentPlanRemovedUpdate):
+        ...
+```
+
+The existing full-plan `AgentPlanUpdate` variant remains available.
+
+## 6. Review MCP server configuration types
+
+Session creation, loading, forking, and resuming now accept `AcpMcpServer` in addition to HTTP, SSE, and stdio MCP server definitions:
+
+```python
+from acp.schema import AcpMcpServer, HttpMcpServer, McpServerStdio, SseMcpServer
+```
+
+If you validate `mcp_servers` with your own union, add `AcpMcpServer` to keep accepting all SDK-supported server types.
+
+## 7. Re-run examples and checks
+
+After changing signatures, run the standard gates:
+
+```bash
+make check
+make test
+```
+
+Also run any example or integration that subclasses `Agent` or `Client`. Positional argument bugs usually surface there first; using keyword arguments for connection calls avoids most of them.