refactor(v2): minimize experimental runtime API

Author: PsiACE

docs/experimental-v2.md

@@ -47,10 +47,24 @@ Agents that serve both versions use `AgentProtocolRouter`:
 ```python
 from acp.experimental import AgentProtocolRouter
 
-router = AgentProtocolRouter(v1=v1_agent, v2=v2_agent)
+router = AgentProtocolRouter(
+    v1=lambda connection: V1Agent(connection),
+    v2=lambda connection: V2Agent(connection),
+)
 await router.run()
 ```
 
+The factories create a fresh agent for each connection, so connection state is
+never shared accidentally.
+
+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

src/acp/experimental/negotiation.py

@@ -12,19 +12,19 @@
 from acp.connection import Connection, MethodHandler
 from acp.exceptions import RequestError
 from acp.interfaces import Agent as V1Agent
-from acp.interfaces import Client as V1Client
 
 from . import v2
 from .v2._connection import open_connection
-from .v2.agent import AgentFactory as V2AgentFactory
 from .v2.agent import AgentSideConnection as V2AgentSideConnection
+from .v2.meta import AGENT_METHODS as V2_AGENT_METHODS
 
 __all__ = [
     "AgentProtocolConnection",
     "AgentProtocolRouter",
 ]
 
-V1AgentFactory = Callable[[V1Client], V1Agent]
+V1AgentFactory = Callable[[V1AgentSideConnection], V1Agent]
+V2AgentFactory = Callable[[V2AgentSideConnection], v2.Agent]
 
 
 def _dump(model: BaseModel) -> dict[str, Any]:
@@ -71,8 +71,8 @@ def _normalize_initialize(params: Any, selected_version: int) -> dict[str, Any]:
 class _AgentNegotiationHandler:
     def __init__(
         self,
-        v1_agent: V1AgentFactory | V1Agent | None,
-        v2_agent: V2AgentFactory | v2.Agent | None,
+        v1_agent: V1AgentFactory | None,
+        v2_agent: V2AgentFactory | None,
     ) -> None:
         self._v1_agent = v1_agent
         self._v2_agent = v2_agent
@@ -88,13 +88,13 @@ async def __call__(self, method: str, params: Any | None, is_notification: bool)
         async with self._lock:
             if self._selected is None:
                 return await self._initialize(method, params, is_notification)
-            if not is_notification and method == v2.AGENT_METHODS["initialize"]:
+            if not is_notification and method == V2_AGENT_METHODS["initialize"]:
                 raise RequestError.invalid_request({"details": "ACP connections may only be initialized once"})
             handler = self._selected
         return await handler(method, params, is_notification)
 
     async def _initialize(self, method: str, params: Any, is_notification: bool) -> Any:
-        if is_notification or method != v2.AGENT_METHODS["initialize"]:
+        if is_notification or method != V2_AGENT_METHODS["initialize"]:
             raise RequestError.invalid_request({"details": "The first ACP request must be initialize"})
         requested = _read_protocol_version(params)
         selected = self._select(requested)
@@ -139,7 +139,7 @@ class AgentProtocolConnection:
     def __init__(self, connection: Connection) -> None:
         self._connection = connection
 
-    async def listen(self) -> None:
+    async def _listen(self) -> None:
         await self._connection.main_loop()
 
     async def close(self) -> None:
@@ -158,15 +158,23 @@ class AgentProtocolRouter:
     def __init__(
         self,
         *,
-        v1: V1AgentFactory | V1Agent | None = None,
-        v2: V2AgentFactory | v2.Agent | None = None,
+        v1: V1AgentFactory | None = None,
+        v2: V2AgentFactory | None = None,
     ) -> None:
         if v1 is None and v2 is None:
             raise ValueError("Configure at least one ACP protocol implementation")
         self._v1 = v1
         self._v2 = v2
 
     def connect(
+        self,
+        input_stream: Any,
+        output_stream: Any = None,
+        **connection_kwargs: Any,
+    ) -> AgentProtocolConnection:
+        return self._connect(input_stream, output_stream, **connection_kwargs)
+
+    def _connect(
         self,
         input_stream: Any,
         output_stream: Any = None,
@@ -197,13 +205,13 @@ async def run(
             from acp.stdio import stdio_streams
 
             output_stream, input_stream = await stdio_streams(limit=stdio_buffer_limit_bytes)
-        connection = self.connect(
+        connection = self._connect(
             input_stream,
             output_stream,
             listening=False,
             **connection_kwargs,
         )
         try:
-            await connection.listen()
+            await connection._listen()
         finally:
             await asyncio.shield(connection.close())

src/acp/experimental/v2/__init__.py

@@ -3,17 +3,13 @@
 from . import schema
 from .agent import AgentSideConnection, run_agent
 from .client import ClientSideConnection, connect_to_agent
-from .interfaces import Agent, Client
-from .meta import AGENT_METHODS, CLIENT_METHODS, PROTOCOL_METHODS, PROTOCOL_VERSION
+from .interfaces import Agent
+from .meta import PROTOCOL_VERSION
 
 __all__ = [
-    "AGENT_METHODS",
-    "CLIENT_METHODS",
-    "PROTOCOL_METHODS",
     "PROTOCOL_VERSION",
     "Agent",
     "AgentSideConnection",
-    "Client",
     "ClientSideConnection",
     "connect_to_agent",
     "run_agent",

src/acp/experimental/v2/_initialization.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import asyncio
-from dataclasses import dataclass
 from typing import Literal
 
 from acp.exceptions import RequestError
@@ -12,17 +11,9 @@
 InitializationPhase = Literal["uninitialized", "initializing", "initialized", "failed"]
 
 
-@dataclass(frozen=True, slots=True)
-class Initialization:
-    request: schema.InitializeRequest
-    response: schema.InitializeResponse
-
-
 class InitializationState:
     def __init__(self) -> None:
         self._phase: InitializationPhase = "uninitialized"
-        self._request: schema.InitializeRequest | None = None
-        self._initialization: Initialization | None = None
         self._failure: BaseException | None = None
         self._ready = asyncio.Event()
 
@@ -38,25 +29,18 @@ def begin(self, request: schema.InitializeRequest) -> None:
                 "expectedProtocolVersion": PROTOCOL_VERSION,
                 "receivedProtocolVersion": request.protocol_version,
             })
-        self._request = request.model_copy(deep=True)
         self._phase = "initializing"
 
-    def complete(self, response: schema.InitializeResponse) -> Initialization:
-        if self._phase != "initializing" or self._request is None:
+    def complete(self, response: schema.InitializeResponse) -> None:
+        if self._phase != "initializing":
             raise RequestError.invalid_request({"details": "ACP v2 initialization is not in progress"})
         if response.protocol_version != PROTOCOL_VERSION:
             raise RequestError.invalid_request({
                 "expectedProtocolVersion": PROTOCOL_VERSION,
                 "receivedProtocolVersion": response.protocol_version,
             })
-        initialization = Initialization(
-            request=self._request.model_copy(deep=True),
-            response=response.model_copy(deep=True),
-        )
-        self._initialization = initialization
         self._phase = "initialized"
         self._ready.set()
-        return initialization
 
     def fail(self, error: BaseException) -> None:
         if self._phase == "initialized":
@@ -65,11 +49,11 @@ def fail(self, error: BaseException) -> None:
         self._failure = error
         self._ready.set()
 
-    async def initialized(self) -> Initialization:
+    async def initialized(self) -> None:
         if self._phase in {"uninitialized", "initializing"}:
             await self._ready.wait()
-        if self._initialization is not None:
-            return self._initialization
+        if self._phase == "initialized":
+            return
         if self._failure is not None:
             raise self._failure
         raise RequestError.invalid_request({"details": "ACP v2 connection has not been initialized"})

src/acp/experimental/v2/_methods.py

@@ -109,7 +109,7 @@ def notification(method: str, handler: str, params_type: Any) -> NotificationSpe
         schema.PromptResponse,
         empty_response=True,
     ),
-    request(AGENT_METHODS["mcp_message"], "message_mcp", schema.MessageMcpRequest, Any),
+    request(AGENT_METHODS["mcp_message"], "mcp_message", schema.MessageMcpRequest, Any),
     request(AGENT_METHODS["session_list"], "list_sessions", schema.ListSessionsRequest, schema.ListSessionsResponse),
     request(
         AGENT_METHODS["session_delete"],
@@ -148,8 +148,8 @@ def notification(method: str, handler: str, params_type: Any) -> NotificationSpe
 )
 
 AGENT_NOTIFICATIONS = (
-    notification(AGENT_METHODS["session_cancel"], "cancel", schema.CancelSessionNotification),
-    notification(AGENT_METHODS["mcp_message"], "message_mcp", schema.MessageMcpNotification),
+    notification(AGENT_METHODS["session_cancel"], "cancel_session", schema.CancelSessionNotification),
+    notification(AGENT_METHODS["mcp_message"], "notify_mcp", schema.MessageMcpNotification),
     notification(AGENT_METHODS["document_did_open"], "did_open", schema.DidOpenDocumentNotification),
     notification(AGENT_METHODS["document_did_change"], "did_change", schema.DidChangeDocumentNotification),
     notification(AGENT_METHODS["document_did_close"], "did_close", schema.DidCloseDocumentNotification),
@@ -167,7 +167,7 @@ def notification(method: str, handler: str, params_type: Any) -> NotificationSpe
         schema.RequestPermissionResponse,
     ),
     request(CLIENT_METHODS["mcp_connect"], "connect_mcp", schema.ConnectMcpRequest, schema.ConnectMcpResponse),
-    request(CLIENT_METHODS["mcp_message"], "message_mcp", schema.MessageMcpRequest, Any),
+    request(CLIENT_METHODS["mcp_message"], "mcp_message", schema.MessageMcpRequest, Any),
     request(
         CLIENT_METHODS["mcp_disconnect"],
         "disconnect_mcp",
@@ -185,7 +185,7 @@ def notification(method: str, handler: str, params_type: Any) -> NotificationSpe
 
 CLIENT_NOTIFICATIONS = (
     notification(CLIENT_METHODS["session_update"], "session_update", schema.UpdateSessionNotification),
-    notification(CLIENT_METHODS["mcp_message"], "message_mcp", schema.MessageMcpNotification),
+    notification(CLIENT_METHODS["mcp_message"], "notify_mcp", schema.MessageMcpNotification),
     notification(
         CLIENT_METHODS["elicitation_complete"],
         "complete_elicitation",

src/acp/experimental/v2/_router.py

@@ -38,7 +38,7 @@ async def handle_request(self, spec: RequestSpec, params: Any) -> Any:
     async def handle_notification(self, spec: NotificationSpec, params: Any) -> None:
         handler = getattr(self._target, spec.handler, None)
         if handler is None:
-            raise RequestError.method_not_found(spec.method)
+            return
         await handler(spec.params.validate_python(params))
 
     async def __call__(self, method: str, params: Any | None, is_notification: bool) -> Any:
@@ -47,7 +47,7 @@ async def __call__(self, method: str, params: Any | None, is_notification: bool)
         if is_notification:
             spec = self._notifications.get(method)
             if spec is None:
-                raise RequestError.method_not_found(method)
+                return None
             await self.handle_notification(spec, params)
             return None
         spec = self._requests.get(method)
@@ -56,8 +56,10 @@ async def __call__(self, method: str, params: Any | None, is_notification: bool)
         return await self.handle_request(spec, params)
 
     async def _handle_extension(self, method: str, params: Any, is_notification: bool) -> Any:
-        handler_name = "ext_notification" if is_notification else "ext_method"
+        handler_name = "handle_extension_notification" if is_notification else "handle_extension_request"
         handler = getattr(self._target, handler_name, None)
         if handler is None:
+            if is_notification:
+                return None
             raise RequestError.method_not_found(method)
         return await handler(method, params)