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

acp/transports.py

@@ -1,19 +1,331 @@
+"""Transport abstractions for ACP agents.
+
+This module provides transport configuration classes and utilities for running
+ACP agents over different transports (stdio, WebSocket, etc.).
+"""
+
 from __future__ import annotations
 
+import asyncio
 import contextlib
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
+import logging
 import os
 import subprocess
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Literal
 
 import anyio
 
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Mapping
+    from collections.abc import AsyncIterator, Callable, Mapping
     from pathlib import Path
 
     from anyio.abc import ByteReceiveStream, ByteSendStream, Process
+    from websockets.asyncio.server import ServerConnection
+
+    from acp.agent.connection import AgentSideConnection
+    from acp.agent.protocol import Agent
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Transport Configuration Classes
+# =============================================================================
+
+
+@dataclass
+class StdioTransport:
+    """Configuration for stdio transport.
+
+    This is the default transport for ACP agents, communicating over
+    stdin/stdout streams.
+    """
+
+
+@dataclass
+class WebSocketTransport:
+    """Configuration for WebSocket server transport.
+
+    Runs an ACP agent as a WebSocket server that accepts client connections.
+    Each client connection gets its own agent instance.
+
+    Attributes:
+        host: Host to bind the WebSocket server to.
+        port: Port for the WebSocket server.
+    """
+
+    host: str = "localhost"
+    port: int = 8765
+
+
+@dataclass
+class StreamTransport:
+    """Configuration for custom stream transport.
+
+    Allows passing pre-created streams for the agent to use.
+
+    Attributes:
+        reader: Stream to read incoming messages from.
+        writer: Stream to write outgoing messages to.
+    """
+
+    reader: ByteReceiveStream
+    writer: ByteSendStream
+
+
+# Type alias for all supported transports
+Transport = StdioTransport | WebSocketTransport | StreamTransport | Literal["stdio", "websocket"]
+
+
+# =============================================================================
+# Transport Runner
+# =============================================================================
+
+
+async def serve(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+    transport: Transport = "stdio",
+    *,
+    shutdown_event: asyncio.Event | None = None,
+    debug_file: str | None = None,
+    **kwargs: Any,
+) -> None:
+    """Run an ACP agent with the specified transport.
+
+    This is the main entry point for running ACP agents. It handles transport
+    setup and lifecycle management automatically.
+
+    Args:
+        agent: An Agent implementation or a factory callable that takes
+            an AgentSideConnection and returns an Agent.
+        transport: Transport configuration. Can be:
+            - "stdio" or StdioTransport(): Use stdin/stdout
+            - "websocket" or WebSocketTransport(...): Run WebSocket server
+            - StreamTransport(...): Use custom streams
+        shutdown_event: Optional event to signal shutdown. If not provided,
+            runs until cancelled.
+        debug_file: Optional file path for debug message logging.
+        **kwargs: Additional keyword arguments passed to AgentSideConnection.
+
+    Example:
+        ```python
+        # Stdio (default)
+        await serve(MyAgent())
+
+        # WebSocket server
+        await serve(MyAgent(), WebSocketTransport(host="0.0.0.0", port=9000))
+
+        # With shutdown control
+        shutdown = asyncio.Event()
+        task = asyncio.create_task(serve(MyAgent(), shutdown_event=shutdown))
+        # ... later ...
+        shutdown.set()
+        await task
+        ```
+    """
+    # Normalize string shortcuts to config objects
+    match transport:
+        case "stdio":
+            transport = StdioTransport()
+        case "websocket":
+            transport = WebSocketTransport()
+
+    # Dispatch to appropriate runner
+    match transport:
+        case StdioTransport():
+            await _serve_stdio(agent, shutdown_event, debug_file, **kwargs)
+        case WebSocketTransport(host=host, port=port):
+            await _serve_websocket(agent, host, port, shutdown_event, debug_file, **kwargs)
+        case StreamTransport(reader=reader, writer=writer):
+            await _serve_streams(agent, reader, writer, shutdown_event, debug_file, **kwargs)
+        case _:
+            msg = f"Unsupported transport: {transport}"
+            raise ValueError(msg)
+
+
+async def _serve_stdio(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+    shutdown_event: asyncio.Event | None,
+    debug_file: str | None,
+    **kwargs: Any,
+) -> None:
+    """Run agent over stdio."""
+    from acp.agent.connection import AgentSideConnection
+    from acp.stdio import stdio_streams
+
+    agent_factory = _ensure_factory(agent)
+    reader, writer = await stdio_streams()
+
+    conn = AgentSideConnection(agent_factory, writer, reader, debug_file=debug_file, **kwargs)
+    try:
+        if shutdown_event:
+            await shutdown_event.wait()
+        else:
+            await asyncio.Event().wait()  # Wait forever
+    except asyncio.CancelledError:
+        pass
+    finally:
+        await conn.close()
+
+
+async def _serve_streams(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+    reader: ByteReceiveStream,
+    writer: ByteSendStream,
+    shutdown_event: asyncio.Event | None,
+    debug_file: str | None,
+    **kwargs: Any,
+) -> None:
+    """Run agent over custom streams."""
+    from acp.agent.connection import AgentSideConnection
+
+    agent_factory = _ensure_factory(agent)
+    conn = AgentSideConnection(agent_factory, writer, reader, debug_file=debug_file, **kwargs)
+    try:
+        if shutdown_event:
+            await shutdown_event.wait()
+        else:
+            await asyncio.Event().wait()
+    except asyncio.CancelledError:
+        pass
+    finally:
+        await conn.close()
+
+
+async def _serve_websocket(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+    host: str,
+    port: int,
+    shutdown_event: asyncio.Event | None,
+    debug_file: str | None,
+    **kwargs: Any,
+) -> None:
+    """Run agent as WebSocket server."""
+    import websockets
+
+    from acp.agent.connection import AgentSideConnection
+
+    agent_factory = _ensure_factory(agent)
+    shutdown = shutdown_event or asyncio.Event()
+    connections: list[AgentSideConnection] = []
+
+    async def handle_client(websocket: ServerConnection) -> None:
+        """Handle a single WebSocket client connection."""
+        logger.info("WebSocket client connected")
+
+        # Create stream adapters for WebSocket
+        ws_reader = _WebSocketReadStream(websocket)
+        ws_writer = _WebSocketWriteStream(websocket)
+
+        conn = AgentSideConnection(
+            agent_factory, ws_writer, ws_reader, debug_file=debug_file, **kwargs
+        )
+        connections.append(conn)
+
+        try:
+            # Keep connection alive until client disconnects or shutdown
+            client_done = asyncio.Event()
+
+            async def monitor_websocket() -> None:
+                try:
+                    async for _ in websocket:
+                        pass  # Messages handled by ws_reader
+                except websockets.exceptions.ConnectionClosed:
+                    pass
+                finally:
+                    client_done.set()
+
+            monitor_task = asyncio.create_task(monitor_websocket())
+            _done, _ = await asyncio.wait(
+                [asyncio.create_task(client_done.wait()), asyncio.create_task(shutdown.wait())],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            monitor_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await monitor_task
+        except websockets.exceptions.ConnectionClosed:
+            logger.info("WebSocket client disconnected")
+        finally:
+            connections.remove(conn)
+            await conn.close()
+
+    logger.info("Starting WebSocket server on ws://%s:%d", host, port)
+    async with websockets.serve(handle_client, host, port):
+        logger.info("WebSocket server running on ws://%s:%d", host, port)
+        await shutdown.wait()
+
+    # Clean up remaining connections
+    for conn in connections:
+        await conn.close()
+
+
+class _WebSocketReadStream(anyio.abc.ByteReceiveStream):
+    """Adapter to read from WebSocket as a ByteReceiveStream."""
+
+    def __init__(self, websocket: Any) -> None:
+        self._websocket = websocket
+        self._buffer = b""
+
+    async def receive(self, max_bytes: int = 65536) -> bytes:
+        # If we have buffered data, return it
+        if self._buffer:
+            data = self._buffer[:max_bytes]
+            self._buffer = self._buffer[max_bytes:]
+            return data
+
+        # Read from WebSocket
+        try:
+            message = await self._websocket.recv()
+            if isinstance(message, str):
+                message = message.encode()
+            # Add newline for JSON-RPC line protocol
+            if not message.endswith(b"\n"):
+                message += b"\n"
+            self._buffer = message[max_bytes:]
+            return message[:max_bytes]  # type: ignore[no-any-return]
+        except Exception as e:
+            raise anyio.EndOfStream from e
+
+    async def aclose(self) -> None:
+        pass
+
+
+class _WebSocketWriteStream(anyio.abc.ByteSendStream):
+    """Adapter to write to WebSocket as a ByteSendStream."""
+
+    def __init__(self, websocket: Any) -> None:
+        self._websocket = websocket
+
+    async def send(self, item: bytes) -> None:
+        # WebSocket sends complete messages, strip newline if present
+        message = item.decode().strip()
+        if message:
+            await self._websocket.send(message)
+
+    async def aclose(self) -> None:
+        pass
+
+
+def _ensure_factory(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+) -> Callable[[AgentSideConnection], Agent]:
+    """Ensure agent is wrapped in a factory function."""
+    if callable(agent) and not hasattr(agent, "initialize"):
+        return agent  # Already a factory
+
+    # Wrap instance in factory
+    def factory(connection: AgentSideConnection) -> Agent:
+        return agent  # type: ignore[return-value]
+
+    return factory
+
+
+# =============================================================================
+# Subprocess Transport Utilities (for spawning agents)
+# =============================================================================
 
 
 DEFAULT_INHERITED_ENV_VARS = (
@@ -50,6 +362,32 @@ def default_environment() -> dict[str, str]:
     return env
 
 
+async def _drain_stderr_to_log(
+    process: Process,
+    command: str,
+    log_level: int = logging.WARNING,
+) -> None:
+    """Read stderr from a process and log each line.
+
+    Args:
+        process: The subprocess to read stderr from.
+        command: Command name for log messages.
+        log_level: Log level for stderr output (default WARNING).
+    """
+    if process.stderr is None:
+        return
+
+    try:
+        async for line_bytes in process.stderr:
+            line = line_bytes.decode(errors="replace").rstrip()
+            if line:
+                logger.log(log_level, "[%s stderr] %s", command, line)
+    except anyio.EndOfStream:
+        pass
+    except Exception:  # noqa: BLE001
+        logger.debug("Error reading stderr from %s", command, exc_info=True)
+
+
 @asynccontextmanager
 async def spawn_stdio_transport(
     command: str,
@@ -58,11 +396,23 @@ async def spawn_stdio_transport(
     cwd: str | Path | None = None,
     stderr: int | None = subprocess.PIPE,
     shutdown_timeout: float = 2.0,
+    log_stderr: bool = False,
+    stderr_log_level: int = logging.WARNING,
 ) -> AsyncIterator[tuple[ByteReceiveStream, ByteSendStream, Process]]:
     """Launch a subprocess and expose its stdio streams as anyio streams.
 
     This mirrors the defensive shutdown behaviour used by the MCP Python SDK:
     close stdin first, wait for graceful exit, then escalate to terminate/kill.
+
+    Args:
+        command: The command to execute.
+        *args: Arguments for the command.
+        env: Environment variables (merged with defaults).
+        cwd: Working directory for the subprocess.
+        stderr: How to handle stderr (default: subprocess.PIPE).
+        shutdown_timeout: Timeout for graceful shutdown.
+        log_stderr: If True, read stderr in background and log each line.
+        stderr_log_level: Log level for stderr output (default WARNING).
     """
     merged_env = default_environment()
     if env:
@@ -83,9 +433,19 @@ async def spawn_stdio_transport(
         msg = "spawn_stdio_transport requires stdout/stdin pipes"
         raise RuntimeError(msg)
 
+    stderr_task: asyncio.Task[None] | None = None
+    if log_stderr and process.stderr is not None:
+        stderr_task = asyncio.create_task(_drain_stderr_to_log(process, command, stderr_log_level))
+
     try:
         yield process.stdout, process.stdin, process
     finally:
+        # Cancel stderr logging task
+        if stderr_task is not None:
+            stderr_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await stderr_task
+
         # Attempt graceful stdin shutdown first
         if process.stdin is not None:
             with contextlib.suppress(Exception):

acp/utils.py

@@ -122,8 +122,16 @@ def generate_tool_title(tool_name: str, tool_input: dict[str, Any]) -> str:  # n
     """
     name_lower = tool_name.lower()
 
+    # Exact matches for common tool names (OpenCode compatibility)
+    if name_lower == "read" and (path := tool_input.get("path") or tool_input.get("file_path")):
+        return f"Reading: {path}"
+    if name_lower in ("write", "edit") and (
+        path := tool_input.get("path") or tool_input.get("file_path")
+    ):
+        return f"Editing: {path}"
+
     # Command/script execution - show the command
-    if any(k in name_lower for k in ["command", "execute", "run", "shell", "script"]) and (
+    if any(k in name_lower for k in ["command", "execute", "run", "shell", "script", "bash"]) and (
         cmd := tool_input.get("command")
     ):
         # Truncate long commands
@@ -217,6 +225,11 @@ def infer_tool_kind(tool_name: str) -> ToolCallKind:  # noqa: PLR0911
         Tool kind string for ACP protocol
     """
     name_lower = tool_name.lower()
+
+    # Exact matches for common tool names (OpenCode compatibility)
+    if name_lower in ("read", "write", "edit"):
+        return "read" if name_lower == "read" else "edit"
+
     if any(i in name_lower for i in ["read", "load", "get"]) and any(
         i in name_lower for i in ["file", "path", "content"]
     ):
@@ -231,7 +244,7 @@ def infer_tool_kind(tool_name: str) -> ToolCallKind:  # noqa: PLR0911
         return "move"
     if any(i in name_lower for i in ["search", "find", "query", "lookup"]):
         return "search"
-    if any(i in name_lower for i in ["execute", "run", "exec", "command", "shell"]):
+    if any(i in name_lower for i in ["execute", "run", "exec", "command", "shell", "bash"]):
         return "execute"
     if any(i in name_lower for i in ["think", "plan", "reason", "analyze"]):
         return "think"

agentpool/__init__.py

@@ -13,7 +13,7 @@ from agentpool.models.manifest import AgentsManifest
 
 # Builtin toolsets imports removed to avoid circular dependency
 # Import them directly from agentpool_toolsets.builtin when needed
-from agentpool.agents import Agent, AgentContext
+from agentpool.agents import Agent, AgentContext, ClaudeCodeAgent, ACPAgent, AGUIAgent
 from agentpool.delegation import AgentPool, Team, TeamRun, BaseTeam
 from dotenv import load_dotenv
 from agentpool.messaging.messages import ChatMessage
@@ -40,6 +40,8 @@ __url__ = "https://github.com/phil65/agentpool"
 load_dotenv()
 
 __all__ = [
+    "ACPAgent",
+    "AGUIAgent",
     "Agent",
     "AgentContext",
     "AgentPool",
@@ -49,6 +51,7 @@ __all__ = [
     "BinaryContent",
     "BinaryImage",
     "ChatMessage",
+    "ClaudeCodeAgent",
     "DocumentUrl",
     "ImageUrl",
     "MessageNode",

agentpool/agents/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from agentpool.agents.agent import Agent
 from agentpool.agents.agui_agent import AGUIAgent
+from agentpool.agents.acp_agent import ACPAgent
 from agentpool.agents.claude_code_agent import ClaudeCodeAgent
 from agentpool.agents.events import (
     detailed_print_handler,
@@ -17,6 +18,7 @@ from agentpool.agents.sys_prompts import SystemPrompts
 
 
 __all__ = [
+    "ACPAgent",
     "AGUIAgent",
     "Agent",
     "AgentContext",