agentpool 2.1.9__py3-none-any.whl → 2.2.3__py3-none-any.whl

acp/__init__.py

@@ -73,6 +73,13 @@ from acp.schema import (
     ToolCall,
 )
 from acp.stdio import stdio_streams, run_agent, connect_to_agent
+from acp.transports import (
+    serve,
+    StdioTransport,
+    WebSocketTransport,
+    StreamTransport,
+    Transport,
+)
 from acp.exceptions import RequestError
 
 __version__ = "0.0.1"
@@ -169,4 +176,10 @@ __all__ = [  # noqa: RUF022
     # filesystem
     "ACPFileSystem",
     "ACPPath",
+    # transport
+    "serve",
+    "StdioTransport",
+    "WebSocketTransport",
+    "StreamTransport",
+    "Transport",
 ]

acp/bridge/README.md

@@ -1,10 +1,23 @@
 # ACP Bridge
 
-A stdio-to-HTTP bridge for ACP (Agent Client Protocol) agents.
+Bridges for exposing **external** stdio-based ACP agents over network transports.
+
+## When to Use
+
+**Use the bridge** when you need to expose an **external** stdio-based ACP agent (one you don't control) over HTTP or WebSocket.
+
+**Use native transports** when building your own agent with the `acp` library. The `acp.serve()` function supports multiple transports directly:
+
+```python
+from acp import serve, WebSocketTransport
+
+# Native WebSocket transport (no bridge needed)
+await serve(my_agent, WebSocketTransport(host="0.0.0.0", port=8765))
+```
 
 ## Overview
 
-The ACP Bridge allows you to expose stdio-based ACP agents via a streamable HTTP endpoint. This is useful when you want to run an agent as a subprocess but communicate with it over HTTP instead of stdio.
+The ACP Bridge allows you to expose stdio-based ACP agents via HTTP or WebSocket endpoints. This is useful when you want to run an external agent as a subprocess but communicate with it over the network instead of stdio.
 
 ## Features
 

acp/bridge/__init__.py

@@ -1,6 +1,7 @@
-"""ACP Bridge - stdio to streamable-http transport bridge for ACP agents."""
+"""ACP Bridge - transport bridges for ACP agents."""
 
 from acp.bridge.bridge import ACPBridge
 from acp.bridge.settings import BridgeSettings
+from acp.bridge.ws_server import ACPWebSocketServer
 
-__all__ = ["ACPBridge", "BridgeSettings"]
+__all__ = ["ACPBridge", "ACPWebSocketServer", "BridgeSettings"]

acp/bridge/__main__.py

@@ -1,8 +1,13 @@
 """CLI entry point for running the ACP bridge.
 
 Usage:
-    uv run -m acp_bridge <command> [args...]
-    uv run -m acp_bridge --port 8080 -- your-agent-command --arg1 value1
+    # HTTP bridge (default)
+    uv run -m acp.bridge <command> [args...]
+    uv run -m acp.bridge --port 8080 -- your-agent-command --arg1 value1
+
+    # WebSocket bridge
+    uv run -m acp.bridge --transport websocket <command> [args...]
+    uv run -m acp.bridge -t ws --port 8765 -- uv run agentpool serve-acp
 """
 
 from __future__ import annotations
@@ -18,24 +23,35 @@ import anyio
 def main() -> None:
     """Run the ACP bridge from command line."""
     parser = argparse.ArgumentParser(
-        description="Bridge a stdio ACP agent to streamable HTTP transport.",
+        description="Bridge a stdio ACP agent to HTTP or WebSocket transport.",
         epilog=(
             "Examples:\n"
+            "  # HTTP bridge\n"
             "  acp-bridge your-agent-command\n"
             "  acp-bridge --port 8080 -- your-agent --config config.yml\n"
-            "  acp-bridge -H 0.0.0.0 -p 9000 -- uv run my-agent\n"
+            "\n"
+            "  # WebSocket bridge\n"
+            "  acp-bridge -t ws -- uv run agentpool serve-acp\n"
+            "  acp-bridge --transport websocket --port 8765 -- uv run my-agent\n"
         ),
         formatter_class=argparse.RawTextHelpFormatter,
     )
 
     parser.add_argument("command", help="Command to spawn the ACP agent.")
     parser.add_argument("args", nargs="*", help="Arguments for the agent command.")
+    parser.add_argument(
+        "-t",
+        "--transport",
+        choices=["http", "websocket", "ws"],
+        default="http",
+        help="Transport type: http (default) or websocket/ws",
+    )
     parser.add_argument(
         "-p",
         "--port",
         type=int,
-        default=8080,
-        help="Port to serve the HTTP endpoint on. Default: 8080",
+        default=None,
+        help="Port to serve on. Default: 8080 (HTTP) or 8765 (WebSocket)",
     )
     parser.add_argument(
         "-H",
@@ -53,7 +69,7 @@ def main() -> None:
         "--allow-origin",
         action="append",
         default=[],
-        help="Allowed CORS origins. Can be specified multiple times.",
+        help="Allowed CORS origins (HTTP only). Can be specified multiple times.",
     )
     parser.add_argument(
         "--cwd",
@@ -69,22 +85,47 @@ def main() -> None:
 
     logging.basicConfig(
         level=getattr(logging, parsed.log_level),
-        format="[%(levelname)1.1s %(asctime)s.%(msecs)03d %(name)s] %(message)s",
-        datefmt="%H:%M:%S",
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
     )
 
-    from acp.bridge import ACPBridge, BridgeSettings
+    use_websocket = parsed.transport in ("websocket", "ws")
 
-    settings = BridgeSettings(
-        host=parsed.host,
-        port=parsed.port,
-        log_level=parsed.log_level,
-        allow_origins=parsed.allow_origin if parsed.allow_origin else None,
-    )
+    if use_websocket:
+        # Reduce websockets noise
+        logging.getLogger("websockets").setLevel(logging.WARNING)
+
+        from acp.bridge.ws_server import ACPWebSocketServer
+
+        port = parsed.port or 8765
+        server = ACPWebSocketServer(
+            command=parsed.command,
+            args=parsed.args,
+            host=parsed.host,
+            port=port,
+            cwd=parsed.cwd,
+        )
+
+        print(f"🔗 ACP WebSocket bridge starting on ws://{parsed.host}:{port}")
+        print(f"   Agent command: {parsed.command} {' '.join(parsed.args)}")
+
+        with contextlib.suppress(KeyboardInterrupt):
+            anyio.run(server.serve)
+    else:
+        from acp.bridge import ACPBridge, BridgeSettings
+
+        port = parsed.port or 8080
+        settings = BridgeSettings(
+            host=parsed.host,
+            port=port,
+            log_level=parsed.log_level,
+            allow_origins=parsed.allow_origin if parsed.allow_origin else None,
+        )
 
-    bridge = ACPBridge(command=parsed.command, args=parsed.args, cwd=parsed.cwd, settings=settings)
-    with contextlib.suppress(KeyboardInterrupt):
-        anyio.run(bridge.run)
+        bridge = ACPBridge(
+            command=parsed.command, args=parsed.args, cwd=parsed.cwd, settings=settings
+        )
+        with contextlib.suppress(KeyboardInterrupt):
+            anyio.run(bridge.run)
 
 
 if __name__ == "__main__":

acp/bridge/ws_server.py

@@ -0,0 +1,173 @@
+"""WebSocket server that bridges to a stdio ACP agent.
+
+Spawns a stdio-based ACP agent subprocess and exposes it via WebSocket,
+allowing clients like mcp-ws to connect.
+
+Usage:
+    python -m acp.bridge.ws_server "uv run agentpool serve-acp" --port 8765
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+import anyenv
+import websockets
+
+from acp.transports import spawn_stdio_transport
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from anyio.abc import ByteReceiveStream, ByteSendStream, Process
+    from websockets.asyncio.server import ServerConnection
+
+logger = logging.getLogger(__name__)
+
+
+class ACPWebSocketServer:
+    """WebSocket server that bridges to a stdio ACP agent."""
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str] | None = None,
+        *,
+        host: str = "localhost",
+        port: int = 8765,
+        env: Mapping[str, str] | None = None,
+        cwd: str | Path | None = None,
+    ) -> None:
+        """Initialize the WebSocket server.
+
+        Args:
+            command: Command to spawn the ACP agent.
+            args: Arguments for the command.
+            host: Host to bind the WebSocket server to.
+            port: Port for the WebSocket server.
+            env: Environment variables for the subprocess.
+            cwd: Working directory for the subprocess.
+        """
+        self.command = command
+        self.args = args or []
+        self.host = host
+        self.port = port
+        self.env = env
+        self.cwd = cwd
+
+        self._process: Process | None = None
+        self._reader: ByteReceiveStream | None = None
+        self._writer: ByteSendStream | None = None
+        self._websocket: ServerConnection | None = None
+        self._shutdown = asyncio.Event()
+        self._read_buffer = b""
+
+    async def _read_jsonrpc_message(self) -> dict[str, Any] | None:
+        """Read a JSON-RPC message from the agent's stdout."""
+        if self._reader is None:
+            return None
+
+        while True:
+            # Check if we have a complete line in buffer
+            if b"\n" in self._read_buffer:
+                line, self._read_buffer = self._read_buffer.split(b"\n", 1)
+                if line.strip():
+                    try:
+                        return anyenv.load_json(line.decode(), return_type=dict)
+                    except anyenv.JsonLoadError:
+                        logger.exception("Failed to parse JSON from agent")
+                        continue
+
+            # Read more data
+            try:
+                chunk = await self._reader.receive(65536)
+                if not chunk:
+                    return None
+                self._read_buffer += chunk
+            except Exception:  # noqa: BLE001
+                return None
+
+    async def _send_to_agent(self, message: dict[str, Any]) -> None:
+        """Send a JSON-RPC message to the agent's stdin."""
+        if self._writer is None:
+            return
+
+        data = json.dumps(message) + "\n"
+        await self._writer.send(data.encode())
+
+    async def _agent_to_websocket(self) -> None:
+        """Forward messages from agent stdout to WebSocket."""
+        while not self._shutdown.is_set():
+            try:
+                message = await self._read_jsonrpc_message()
+                if message is None:
+                    logger.info("Agent stdout closed")
+                    break
+
+                if self._websocket is not None:
+                    await self._websocket.send(json.dumps(message))
+                    logger.debug("Agent → WebSocket: %s", message.get("method", message.get("id")))
+            except Exception:
+                logger.exception("Error forwarding agent → WebSocket")
+                break
+
+    async def _handle_client(self, websocket: ServerConnection) -> None:
+        """Handle a WebSocket client connection."""
+        logger.info("WebSocket client connected")
+        self._websocket = websocket
+
+        try:
+            async for raw_message in websocket:
+                try:
+                    message = json.loads(raw_message)
+                    logger.debug("WebSocket → Agent: %s", message.get("method", message.get("id")))
+                    await self._send_to_agent(message)
+                except json.JSONDecodeError:
+                    logger.exception("Invalid JSON from WebSocket")
+                    error_response = {
+                        "jsonrpc": "2.0",
+                        "id": None,
+                        "error": {"code": -32700, "message": "Parse error"},
+                    }
+                    await websocket.send(json.dumps(error_response))
+        except websockets.exceptions.ConnectionClosed:
+            logger.info("WebSocket client disconnected")
+        finally:
+            self._websocket = None
+
+    async def serve(self) -> None:
+        """Start the WebSocket server and agent process."""
+        cmd_str = f"{self.command} {' '.join(self.args)}".strip()
+        logger.info("Starting ACP agent: %s", cmd_str)
+
+        async with spawn_stdio_transport(self.command, *self.args, env=self.env, cwd=self.cwd) as (
+            reader,
+            writer,
+            process,
+        ):
+            self._reader = reader
+            self._writer = writer
+            self._process = process
+
+            # Start forwarding agent output to WebSocket
+            forward_task = asyncio.create_task(self._agent_to_websocket())
+
+            try:
+                async with websockets.serve(
+                    self._handle_client,
+                    self.host,
+                    self.port,
+                ):
+                    logger.info("WebSocket server running on ws://%s:%d", self.host, self.port)
+                    await self._shutdown.wait()
+            finally:
+                self._shutdown.set()
+                forward_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await forward_task

acp/bridge/ws_server_cli.py

@@ -0,0 +1,89 @@
+"""CLI entry point for the ACP WebSocket server bridge.
+
+Usage:
+    python -m acp.bridge.ws_server_cli "uv run agentpool serve-acp"
+    python -m acp.bridge.ws_server_cli --port 8765 -- uv run agentpool serve-acp
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import logging
+import sys
+
+import anyio
+
+
+def main() -> None:
+    """Run the ACP WebSocket server bridge from command line."""
+    parser = argparse.ArgumentParser(
+        description="Bridge a stdio ACP agent to WebSocket transport.",
+        epilog=(
+            "Examples:\n"
+            '  acp-ws-server "uv run agentpool serve-acp"\n'
+            "  acp-ws-server --port 8765 -- uv run agentpool serve-acp\n"
+            "  acp-ws-server -H 0.0.0.0 -p 9000 -- uv run my-agent\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    parser.add_argument("command", help="Command to spawn the ACP agent.")
+    parser.add_argument("args", nargs="*", help="Arguments for the agent command.")
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=8765,
+        help="Port for the WebSocket server. Default: 8765",
+    )
+    parser.add_argument(
+        "-H",
+        "--host",
+        default="localhost",
+        help="Host to bind the server to. Default: localhost",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Log level. Default: INFO",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=None,
+        help="Working directory for the agent subprocess.",
+    )
+
+    parsed = parser.parse_args()
+
+    if not parsed.command:
+        parser.print_help()
+        sys.exit(1)
+
+    logging.basicConfig(
+        level=getattr(logging, parsed.log_level),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    # Reduce websockets noise
+    logging.getLogger("websockets").setLevel(logging.WARNING)
+
+    from acp.bridge.ws_server import ACPWebSocketServer
+
+    server = ACPWebSocketServer(
+        command=parsed.command,
+        args=parsed.args,
+        host=parsed.host,
+        port=parsed.port,
+        cwd=parsed.cwd,
+    )
+
+    print(f"🔗 ACP WebSocket bridge starting on ws://{parsed.host}:{parsed.port}")
+    print(f"   Agent command: {parsed.command} {' '.join(parsed.args)}")
+
+    with contextlib.suppress(KeyboardInterrupt):
+        anyio.run(server.serve)
+
+
+if __name__ == "__main__":
+    main()

acp/notifications.py

@@ -34,6 +34,7 @@ from acp.schema.tool_call import ToolCallLocation
 from acp.tool_call_reporter import ToolCallReporter
 from acp.utils import generate_tool_title, infer_tool_kind, to_acp_content_blocks
 from agentpool.log import get_logger
+from agentpool.utils.pydantic_ai_helpers import safe_args_as_dict
 
 
 if TYPE_CHECKING:
@@ -703,7 +704,7 @@ class ACPNotifications:
 
                 case ToolCallPart(tool_call_id=tool_call_id):
                     # Store tool call inputs for later use with ToolReturnPart
-                    tool_input = part.args_as_dict()
+                    tool_input = safe_args_as_dict(part)
                     self._tool_call_inputs[tool_call_id] = tool_input
                     # Skip sending notification - ACP protocol overrides previous
                     # tool call state

acp/stdio.py

@@ -87,10 +87,20 @@ async def spawn_stdio_connection(
     env: Mapping[str, str] | None = None,
     cwd: str | Path | None = None,
     observers: list[StreamObserver] | None = None,
-    **transport_kwargs: Any,
+    log_stderr: bool = False,
 ) -> AsyncIterator[tuple[Connection, Process]]:
-    """Spawn a subprocess and bind its stdio to a low-level Connection."""
-    async with spawn_stdio_transport(command, *args, env=env, cwd=cwd, **transport_kwargs) as (
+    """Spawn a subprocess and bind its stdio to a low-level Connection.
+
+    Args:
+        handler: Method handler for the connection.
+        command: The command to execute.
+        *args: Arguments for the command.
+        env: Environment variables for the subprocess.
+        cwd: Working directory for the subprocess.
+        observers: Optional stream observers.
+        log_stderr: If True, log stderr output from the subprocess.
+    """
+    async with spawn_stdio_transport(command, *args, env=env, cwd=cwd, log_stderr=log_stderr) as (
         reader,
         writer,
         process,
@@ -109,16 +119,26 @@ async def spawn_agent_process(
     *args: str,
     env: Mapping[str, str] | None = None,
     cwd: str | Path | None = None,
-    transport_kwargs: Mapping[str, Any] | None = None,
+    log_stderr: bool = False,
     **connection_kwargs: Any,
 ) -> AsyncIterator[tuple[ClientSideConnection, Process]]:
-    """Spawn an ACP agent subprocess and return a ClientSideConnection to it."""
+    """Spawn an ACP agent subprocess and return a ClientSideConnection to it.
+
+    Args:
+        to_client: Factory function that creates a Client from an Agent.
+        command: The command to execute.
+        *args: Arguments for the command.
+        env: Environment variables for the subprocess.
+        cwd: Working directory for the subprocess.
+        log_stderr: If True, log stderr output from the subprocess.
+        **connection_kwargs: Additional arguments for ClientSideConnection.
+    """
     async with spawn_stdio_transport(
         command,
         *args,
         env=env,
         cwd=cwd,
-        **(dict(transport_kwargs) if transport_kwargs else {}),
+        log_stderr=log_stderr,
     ) as (reader, writer, process):
         conn = ClientSideConnection(to_client, writer, reader, **connection_kwargs)
         try:
@@ -134,16 +154,26 @@ async def spawn_client_process(
     *args: str,
     env: Mapping[str, str] | None = None,
     cwd: str | Path | None = None,
-    transport_kwargs: Mapping[str, Any] | None = None,
+    log_stderr: bool = False,
     **connection_kwargs: Any,
 ) -> AsyncIterator[tuple[AgentSideConnection, Process]]:
-    """Spawn an ACP client subprocess and return an AgentSideConnection to it."""
+    """Spawn an ACP client subprocess and return an AgentSideConnection to it.
+
+    Args:
+        to_agent: Factory function that creates an Agent from an AgentSideConnection.
+        command: The command to execute.
+        *args: Arguments for the command.
+        env: Environment variables for the subprocess.
+        cwd: Working directory for the subprocess.
+        log_stderr: If True, log stderr output from the subprocess.
+        **connection_kwargs: Additional arguments for AgentSideConnection.
+    """
     async with spawn_stdio_transport(
         command,
         *args,
         env=env,
         cwd=cwd,
-        **(dict(transport_kwargs) if transport_kwargs else {}),
+        log_stderr=log_stderr,
     ) as (reader, writer, process):
         conn = AgentSideConnection(to_agent, writer, reader, **connection_kwargs)
         try: