refactor: polish all code to align spec impl

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

Author: Chojan Shang

AGENTS.md

@@ -1,19 +1,24 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-The package code lives under `src/acp`, exposing the high-level Agent, transport helpers, and generated protocol schema. Generated artifacts such as `schema/` and `src/acp/schema.py` are refreshed via `scripts/gen_all.py` against the upstream ACP schema. Integration examples are in `examples/`, including `echo_agent.py` and the mini SWE bridge. Tests reside in `tests/` with async fixtures and doctests; documentation sources live in `docs/` and publish via MkDocs. Built distributions drop into `dist/` after builds.
+The runtime package lives in `src/acp`, exposing the top-level agent entrypoints, transport adapters, and the generated `schema.py`. Regenerate protocol artifacts via `scripts/gen_all.py`, which refreshes both `schema/` and `src/acp/schema.py`. Examples demonstrating stdio bridges and quick-start flows are under `examples/`, while async-focused tests and fixtures sit in `tests/`. Documentation sources for MkDocs reside in `docs/`, and built artifacts land in `dist/` after release builds.
 
 ## Build, Test, and Development Commands
-Run `make install` to create a `uv` managed virtualenv and install pre-commit hooks. `make check` executes lock verification, Ruff linting, `ty` static checks, and deptry analysis. `make test` calls `uv run python -m pytest --doctest-modules`. For release prep use `make build` or `make build-and-publish`. `make gen-all` regenerates protocol models; export `ACP_SCHEMA_VERSION=<ref>` beforehand to fetch a specific upstream schema (defaults to the cached copy). `make docs` serves MkDocs locally; `make docs-test` ensures clean builds.
+- `make install`: Provisions a `uv`-managed virtualenv and installs pre-commit hooks.
+- `make check`: Runs lock verification, Ruff linting, `ty` type analysis, and deptry dependency checks.
+- `make test`: Executes `uv run python -m pytest --doctest-modules` across the suite.
+- `make gen-all`: Regenerates protocol schemas (set `ACP_SCHEMA_VERSION=<ref>` to target a specific upstream tag).
+- `make build` / `make build-and-publish`: Produce or ship distribution artifacts.
+- `make docs` and `make docs-test`: Serve or validate MkDocs documentation locally.
 
 ## Coding Style & Naming Conventions
-Target Python 3.10+ with type hints and 120-character lines enforced by Ruff (`pyproject.toml`). Prefer dataclasses/pydantic models from the schema modules rather than bare dicts. Tests may ignore security lint (see per-file ignores) but still follow snake_case names. Keep public API modules under `acp/*` lean; place utilities in internal `_`-prefixed modules when needed.
+Target Python 3.10+ with 4-space indentation and type hints on public APIs. Ruff (configured via `pyproject.toml`) enforces formatting, 120-character lines, and linting; keep `ruff --fix` output clean before opening a PR. Prefer dataclasses and Pydantic models generated in `acp.schema` over ad-hoc dicts. Place shared utilities in `_`-prefixed internal modules and keep public surfaces lean.
 
 ## Testing Guidelines
-Pytest is the main framework with `pytest-asyncio` for coroutine tests and doctests activated on modules. Name test files `test_*.py` and co-locate fixtures under `tests/conftest.py`. Aim to cover new protocol surfaces with integration-style tests using the async agent stubs. Generate coverage reports via `tox -e py310` when assessing CI parity.
+Pytest with `pytest-asyncio` powers the suite, and doctests are enabled for modules. Name test files `test_*.py`, keep fixtures in `tests/conftest.py`, and run `make test` before pushing. For deeper coverage investigation, run `tox -e py310` and review the HTML report in `.tox/py310/tmp/coverage`.
 
 ## Commit & Pull Request Guidelines
-Commit history follows Conventional Commits (`feat:`, `fix:`, `docs:`). Scope commits narrowly and include context on affected protocol version or tooling. PRs should describe agent behaviors exercised, link related issues, and mention schema regeneration if applicable. Attach test output (`make check` or targeted pytest) and screenshots only when UI-adjacent docs change. Update docs/examples when altering the public agent API.
+Follow Conventional Commits (`feat:`, `fix:`, `docs:`) with narrow scopes and mention schema regeneration when applicable. PRs should describe exercised agent behaviors, link related issues, and attach `make check` (or targeted pytest) output. Update docs and examples whenever public agent APIs change, and include environment notes for new agent integrations.
 
 ## Agent Integration Tips
-Leverage `examples/mini_swe_agent/` as a template when bridging other command executors. Use `AgentSideConnection` with `stdio_streams()` for ACP-compliant clients; document any extra environment variables in README updates.
+Use `examples/echo_agent.py` as the minimal agent template, or look at `examples/client.py` and `examples/duet.py` for spawning patterns that rely on `spawn_agent_process`/`spawn_client_process`. Document any environment requirements in `README.md`, and verify round-trip messaging with the echo agent before extending transports.

README.md

@@ -71,15 +71,15 @@ Full example with streaming and lifecycle hooks lives in [examples/echo_agent.py
 
 ## Examples
 
-- `examples/mini_swe_agent`: bridges mini-swe-agent into ACP, including a duet launcher and Textual TUI client
-- Additional transport helpers are documented in the [Mini SWE guide](docs/mini-swe-agent.md)
+- `examples/echo_agent.py`: self-contained streaming agent suitable for smoke tests
+- `examples/client.py`: interactive console client that can spawn any ACP agent subprocess
+- `examples/duet.py`: demo launcher that starts both the example client and agent together
 
 ## Documentation
 
 - Project docs (MkDocs): https://psiace.github.io/agent-client-protocol-python/
 - Local sources: `docs/`
   - [Quickstart](docs/quickstart.md)
-  - [Mini SWE Agent bridge](docs/mini-swe-agent.md)
 
 ## Development workflow
 

docs/index.md

@@ -25,6 +25,5 @@ Prefer a guided tour? Head to the [Quickstart](quickstart.md) for step-by-step i
 ## Documentation map
 
 - [Quickstart](quickstart.md): install, run, and extend the echo agent
-- [Mini SWE Agent guide](mini-swe-agent.md): bridge mini-swe-agent over ACP, including duet launcher and Textual client
 
 Source code lives under `src/acp/`, while tests and additional examples are available in `tests/` and `examples/`. If you plan to contribute, see the repository README for the development workflow.

docs/mini-swe-agent.md

@@ -50,6 +50,62 @@ Open the Agents panel and start the session. Each message you send should be ech
 
 Any ACP client that communicates over stdio can spawn the same script; no additional transport configuration is required.
 
+### Programmatic launch
+
+You can also embed the agent inside another Python process without shelling out manually. Use
+`acp.spawn_agent_process` to bootstrap the child and receive a `ClientSideConnection`:
+
+```python
+import asyncio
+import sys
+from pathlib import Path
+
+from acp import spawn_agent_process
+from acp.interfaces import Client
+from acp.schema import (
+    DeniedOutcome,
+    InitializeRequest,
+    NewSessionRequest,
+    PromptRequest,
+    RequestPermissionRequest,
+    RequestPermissionResponse,
+    SessionNotification,
+    TextContentBlock,
+)
+
+
+class SimpleClient(Client):
+    async def requestPermission(self, params: RequestPermissionRequest) -> RequestPermissionResponse:
+        return RequestPermissionResponse(outcome=DeniedOutcome(outcome="cancelled"))
+
+    async def sessionUpdate(self, params: SessionNotification) -> None:  # noqa: D401 - logging only
+        print("update:", params)
+
+    # Optional client methods omitted for brevity
+
+
+async def main() -> None:
+    script = Path("examples/echo_agent.py").resolve()
+
+    async with spawn_agent_process(lambda agent: SimpleClient(), sys.executable, str(script)) as (
+        conn,
+        _process,
+    ):
+        await conn.initialize(InitializeRequest(protocolVersion=1))
+        session = await conn.newSession(NewSessionRequest(cwd=str(script.parent), mcpServers=[]))
+        await conn.prompt(
+            PromptRequest(
+                sessionId=session.sessionId,
+                prompt=[TextContentBlock(type="text", text="Hello from spawn!")],
+            )
+        )
+
+asyncio.run(main())
+```
+
+Inside the context manager the subprocess is monitored, stdin/stdout are tied into ACP, and the
+connection cleans itself up on exit.
+
 ## 4. Extend the agent
 
 Create your own agent by subclassing `acp.Agent`. The pattern mirrors the echo example:
@@ -65,14 +121,3 @@ class MyAgent(Agent):
 ```
 
 Hook it up with `AgentSideConnection` inside an async entrypoint and wire it to your client. Refer to [examples/echo_agent.py](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/echo_agent.py) for the complete structure, including lifetime hooks (`initialize`, `newSession`) and streaming responses.
-
-## Optional: Mini SWE Agent bridge
-
-The repository also ships a bridge for [mini-swe-agent](https://github.com/groundx-ai/mini-swe-agent). To try it:
-
-1. Install the dependency:
-   ```bash
-   pip install mini-swe-agent
-   ```
-2. Configure Zed to run `examples/mini_swe_agent/agent.py` and supply environment variables such as `MINI_SWE_MODEL` and `OPENROUTER_API_KEY`.
-3. Review the [Mini SWE Agent guide](mini-swe-agent.md) for environment options, tool-call mapping, and a duet launcher that starts both the bridge and a Textual client (`python examples/mini_swe_agent/duet.py`).

docs/quickstart.md

@@ -49,13 +49,16 @@ async def _send_chunk(self, session_id: str, content: Any) -> None:
 
     async def initialize(self, params: InitializeRequest) -> InitializeResponse:  # noqa: ARG002
         logging.info("Received initialize request")
+        mcp_caps: McpCapabilities = McpCapabilities(http=False, sse=False)
+        prompt_caps: PromptCapabilities = PromptCapabilities(audio=False, embeddedContext=False, image=False)
+        agent_caps: AgentCapabilities = AgentCapabilities(
+            loadSession=False,
+            mcpCapabilities=mcp_caps,
+            promptCapabilities=prompt_caps,
+        )
         return InitializeResponse(
             protocolVersion=PROTOCOL_VERSION,
-            agentCapabilities=AgentCapabilities(
-                loadSession=False,
-                mcpCapabilities=McpCapabilities(http=False, sse=False),
-                promptCapabilities=PromptCapabilities(audio=False, embeddedContext=False, image=False),
-            ),
+            agentCapabilities=agent_caps,
         )
 
     async def authenticate(self, params: AuthenticateRequest) -> AuthenticateResponse | None:  # noqa: ARG002

examples/agent.py

@@ -1,4 +1,5 @@
 import asyncio
+import asyncio.subprocess as aio_subprocess
 import contextlib
 import logging
 import os
@@ -118,8 +119,8 @@ async def main(argv: list[str]) -> int:
     proc = await asyncio.create_subprocess_exec(
         spawn_program,
         *spawn_args,
-        stdin=asyncio.subprocess.PIPE,
-        stdout=asyncio.subprocess.PIPE,
+        stdin=aio_subprocess.PIPE,
+        stdout=aio_subprocess.PIPE,
     )
 
     if proc.stdin is None or proc.stdout is None:

examples/client.py

@@ -1,27 +1,44 @@
 import asyncio
+import importlib.util
 import os
 import sys
 from pathlib import Path
 
 
+def _load_client_module(path: Path):
+    spec = importlib.util.spec_from_file_location("examples_client", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load client module from {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules.setdefault("examples_client", module)
+    spec.loader.exec_module(module)
+    return module
+
+
+from acp import PROTOCOL_VERSION, spawn_agent_process
+from acp.schema import InitializeRequest, NewSessionRequest
+
+
 async def main() -> int:
     root = Path(__file__).resolve().parent
-    agent_path = str(root / "agent.py")
-    client_path = str(root / "client.py")
+    agent_path = root / "agent.py"
 
-    # Ensure PYTHONPATH includes project src for `from acp import ...`
     env = os.environ.copy()
     src_dir = str((root.parent / "src").resolve())
     env["PYTHONPATH"] = src_dir + os.pathsep + env.get("PYTHONPATH", "")
 
-    # Run the client and let it spawn the agent, wiring stdio automatically.
-    proc = await asyncio.create_subprocess_exec(
-        sys.executable,
-        client_path,
-        agent_path,
-        env=env,
-    )
-    return await proc.wait()
+    client_module = _load_client_module(root / "client.py")
+    client = client_module.ExampleClient()
+
+    async with spawn_agent_process(lambda _agent: client, sys.executable, str(agent_path), env=env) as (
+        conn,
+        process,
+    ):
+        await conn.initialize(InitializeRequest(protocolVersion=PROTOCOL_VERSION, clientCapabilities=None))
+        session = await conn.newSession(NewSessionRequest(mcpServers=[], cwd=str(root)))
+        await client_module.interactive_loop(conn, session.sessionId)
+
+    return process.returncode or 0
 
 
 if __name__ == "__main__":