agentpool 2.1.9__py3-none-any.whl

acp/README.md

@@ -0,0 +1,64 @@
+## ACP Protocol Features
+
+### JSON-RPC 2.0 Communication
+
+ACP uses JSON-RPC 2.0 over newline-delimited JSON streams:
+
+```json
+// Initialize request
+{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":1},"id":1}
+
+// Initialize response
+{"jsonrpc":"2.0","result":{"protocolVersion":1,"agentCapabilities":{...}},"id":1}
+
+// Create session
+{"jsonrpc":"2.0","method":"session/new","params":{"cwd":"/tmp"},"id":2}
+
+// Session response
+{"jsonrpc":"2.0","result":{"sessionId":"sess_abc123"},"id":2}
+
+// Send prompt
+{"jsonrpc":"2.0","method":"session/prompt","params":{
+  "sessionId":"sess_abc123",
+  "prompt":[{"type":"text","text":"Hello!"}]
+},"id":3}
+
+// Streaming responses via session updates
+{"jsonrpc":"2.0","method":"session/update","params":{
+  "sessionId":"sess_abc123",
+  "update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Hi there!"}}
+}}
+```
+
+### Content Blocks
+
+ACP supports rich content blocks:
+
+```python
+# Text content
+TextContent(text="Hello world")
+
+# Image content
+ImageContent(type="image", data="base64...", mimeType="image/png")
+
+# Audio content
+AudioContent(type="audio", data="base64...", mimeType="audio/wav")
+
+# Resource links
+ResourceContentBlock(type="resource_link", uri="file:///path/to/file", name="document.pdf")
+
+# Embedded resources
+EmbeddedResource(type="resource", resource=TextResourceContents(uri="...", text="..."))
+```
+
+
+### MCP Server Integration
+
+ACP provides seamless integration with MCP (Model Context Protocol) servers, allowing agents to access external tools and data sources. MCP servers are automatically connected when creating sessions.
+
+#### How MCP Integration Works
+
+1. **Session Creation**: Client provides MCP server configurations in `session/new`
+2. **Automatic Connection**: ACP server connects to all specified MCP servers
+3. **Tool Integration**: MCP tools become available to the agent automatically
+4. **Transparent Usage**: Agent can use MCP tools just like built-in tools

acp/__init__.py

@@ -0,0 +1,172 @@
+"""Agent Client protocol (ACP) implementation."""
+
+from acp.client import DefaultACPClient, HeadlessACPClient, NoOpClient, ClientSideConnection
+from acp.agent import AgentSideConnection
+from acp.bridge import ACPBridge, BridgeSettings
+from acp.filesystem import ACPFileSystem, ACPPath
+from acp.agent.protocol import Agent
+from acp.client.protocol import Client
+from acp.terminal_handle import TerminalHandle
+from acp.tool_call_state import ToolCallState
+from acp.schema import (
+    AuthenticateRequest,
+    AuthenticateResponse,
+    CancelNotification,
+    CreateTerminalRequest,
+    ClientCapabilities,
+    SessionMode,
+    FileSystemCapability,
+    AgentMessageChunk,
+    UserMessageChunk,
+    TextContentBlock,
+    SessionModeState,
+    Implementation,
+    ToolCallLocation,
+    EnvVariable,
+    StdioMcpServer,
+    SseMcpServer,
+    HttpMcpServer,
+    CreateTerminalResponse,
+    InitializeRequest,
+    PlanEntryPriority,
+    PlanEntryStatus,
+    InitializeResponse,
+    KillTerminalCommandRequest,
+    KillTerminalCommandResponse,
+    LoadSessionRequest,
+    LoadSessionResponse,
+    ModelInfo,
+    AllowedOutcome,
+    DeniedOutcome,
+    NewSessionRequest,
+    NewSessionResponse,
+    PromptRequest,
+    PromptResponse,
+    ReadTextFileRequest,
+    ReadTextFileResponse,
+    ReleaseTerminalRequest,
+    ReleaseTerminalResponse,
+    RequestPermissionRequest,
+    RequestPermissionResponse,
+    SessionModelState,
+    SessionNotification,
+    SetSessionModelRequest,
+    SetSessionModelResponse,
+    SetSessionModeRequest,
+    SetSessionModeResponse,
+    TerminalOutputRequest,
+    TerminalOutputResponse,
+    WaitForTerminalExitRequest,
+    WaitForTerminalExitResponse,
+    WriteTextFileRequest,
+    WriteTextFileResponse,
+    PermissionOption,
+    PROTOCOL_VERSION,
+    AgentMethod,
+    ClientMethod,
+    Annotations,
+    AvailableCommand,
+    PlanEntry,
+    ToolCallContent,
+    ToolCallKind,
+    ToolCallStatus,
+    ToolCall,
+)
+from acp.stdio import stdio_streams, run_agent, connect_to_agent
+from acp.exceptions import RequestError
+
+__version__ = "0.0.1"
+
+__all__ = [  # noqa: RUF022
+    # bridge
+    "ACPBridge",
+    "BridgeSettings",
+    # client implementations
+    "DefaultACPClient",
+    "HeadlessACPClient",
+    "NoOpClient",
+    # constants
+    "PROTOCOL_VERSION",
+    # literal types
+    "AgentMethod",
+    "ClientMethod",
+    # types
+    "Annotations",
+    "AvailableCommand",
+    "PlanEntry",
+    "AllowedOutcome",
+    "ToolCall",
+    "DeniedOutcome",
+    "ToolCallContent",
+    "PermissionOption",
+    "ToolCallKind",
+    "PlanEntryPriority",
+    "PlanEntryStatus",
+    "ToolCallStatus",
+    "InitializeRequest",
+    "ToolCallLocation",
+    "InitializeResponse",
+    "EnvVariable",
+    "HttpMcpServer",
+    "StdioMcpServer",
+    "SseMcpServer",
+    "NewSessionRequest",
+    "AgentMessageChunk",
+    "UserMessageChunk",
+    "TextContentBlock",
+    "NewSessionResponse",
+    "LoadSessionRequest",
+    "LoadSessionResponse",
+    "AuthenticateRequest",
+    "AuthenticateResponse",
+    "PromptRequest",
+    "ClientCapabilities",
+    "SessionModeState",
+    "SessionMode",
+    "Implementation",
+    "PromptResponse",
+    "WriteTextFileRequest",
+    "WriteTextFileResponse",
+    "ReadTextFileRequest",
+    "ReadTextFileResponse",
+    "RequestPermissionRequest",
+    "RequestPermissionResponse",
+    "CancelNotification",
+    "SessionNotification",
+    "SetSessionModeRequest",
+    "SetSessionModeResponse",
+    # model types
+    "ModelInfo",
+    "SessionModelState",
+    "SetSessionModelRequest",
+    "SetSessionModelResponse",
+    # terminal types
+    "CreateTerminalRequest",
+    "CreateTerminalResponse",
+    "TerminalOutputRequest",
+    "TerminalOutputResponse",
+    "WaitForTerminalExitRequest",
+    "WaitForTerminalExitResponse",
+    "KillTerminalCommandRequest",
+    "KillTerminalCommandResponse",
+    "ReleaseTerminalRequest",
+    "ReleaseTerminalResponse",
+    # core
+    "AgentSideConnection",
+    "ClientSideConnection",
+    "RequestError",
+    "Agent",
+    "Client",
+    "TerminalHandle",
+    "ToolCallState",
+    # connection helpers (recommended)
+    "run_agent",
+    "connect_to_agent",
+    # split protocols
+    "FileSystemCapability",
+    # stdio helper
+    "stdio_streams",
+    # filesystem
+    "ACPFileSystem",
+    "ACPPath",
+]

acp/__main__.py

@@ -0,0 +1,10 @@
+"""ACP package main entry point.
+
+Allows running the ACP debug server with:
+    python -m acp
+"""
+
+if __name__ == "__main__":
+    from acp.agent.implementations.debug_server.cli import main
+
+    main()

acp/acp_requests.py

@@ -0,0 +1,285 @@
+"""ACP request utilities for simplified client interactions."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from acp.schema import (
+    CreateTerminalRequest,
+    EnvVariable,
+    KillTerminalCommandRequest,
+    PermissionOption,
+    ReadTextFileRequest,
+    ReleaseTerminalRequest,
+    RequestPermissionRequest,
+    TerminalOutputRequest,
+    ToolCall,
+    WaitForTerminalExitRequest,
+    WriteTextFileRequest,
+)
+from acp.terminal_handle import TerminalHandle
+from agentpool.log import get_logger
+
+
+if TYPE_CHECKING:
+    from acp import (
+        Client,
+        RequestPermissionResponse,
+        TerminalOutputResponse,
+        WaitForTerminalExitResponse,
+    )
+
+logger = get_logger(__name__)
+
+
+RULES_FILE_NAMES = [
+    ".rules",
+    "CLAUDE.md",
+    "AGENT.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".windsurfrules",
+    ".clinerules",
+    ".github/copilot-instructions.md",
+]
+
+
+class ACPRequests:
+    """Clean API for creating and sending ACP session requests.
+
+    Provides convenient methods for common request patterns,
+    handling both creation and sending in a single call.
+    """
+
+    def __init__(self, client: Client, session_id: str) -> None:
+        """Initialize requests helper.
+
+        Args:
+            client: ACP client
+            session_id: Session ID
+        """
+        self.client = client
+        self.id = session_id
+
+    async def read_text_file(
+        self,
+        path: str,
+        *,
+        limit: int | None = None,
+        line: int | None = None,
+    ) -> str:
+        """Read text content from a file.
+
+        Args:
+            path: File path to read
+            limit: Maximum number of lines to read
+            line: Line number to start reading from (1-based)
+
+        Returns:
+            File content as string
+        """
+        request = ReadTextFileRequest(
+            session_id=self.id,
+            path=path,
+            limit=limit,
+            line=line,
+        )
+        response = await self.client.read_text_file(request)
+        return response.content
+
+    async def read_agent_rules(self, cwd: str) -> str | None:
+        """Check common agent rule files and return content of first match.
+
+        Args:
+            cwd: Current working directory
+
+        Returns:
+            Agent rules as string or None if not found
+        """
+        for filename in RULES_FILE_NAMES:
+            if info := await self.read_text_file(f"{cwd}/{filename}"):
+                return info
+        return None
+
+    async def write_text_file(self, path: str, content: str) -> None:
+        """Write text content to a file.
+
+        Args:
+            path: File path to write
+            content: Text content to write
+        """
+        request = WriteTextFileRequest(session_id=self.id, path=path, content=content)
+        await self.client.write_text_file(request)
+
+    async def create_terminal(
+        self,
+        command: str,
+        *,
+        args: list[str] | None = None,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        output_byte_limit: int | None = None,
+    ) -> TerminalHandle:
+        """Create a new terminal session.
+
+        Args:
+            command: Command to run. For shell commands (pipes, redirects, etc.),
+                pass the full command string and omit args.
+            args: Command arguments, appended to command.
+            cwd: Working directory for terminal
+            env: Environment variables for terminal
+            output_byte_limit: Maximum bytes to capture from output
+        """
+        request = CreateTerminalRequest(
+            session_id=self.id,
+            command=command,
+            # Only include args if non-empty, following claude-code-acp pattern.
+            # When args is None/empty, ACP clients interpret command as a shell command.
+            args=args or None,
+            cwd=cwd,
+            env=[EnvVariable(name=k, value=v) for k, v in (env or {}).items()],
+            output_byte_limit=output_byte_limit,
+        )
+        response = await self.client.create_terminal(request)
+        return TerminalHandle(terminal_id=response.terminal_id, requests=self)
+
+    async def terminal_output(self, terminal_id: str) -> TerminalOutputResponse:
+        """Get output from a terminal session.
+
+        Args:
+            terminal_id: Terminal identifier
+
+        Returns:
+            Terminal output response
+        """
+        request = TerminalOutputRequest(session_id=self.id, terminal_id=terminal_id)
+        return await self.client.terminal_output(request)
+
+    async def wait_for_terminal_exit(
+        self,
+        terminal_id: str,
+    ) -> WaitForTerminalExitResponse:
+        """Wait for a terminal to exit.
+
+        Args:
+            terminal_id: Terminal identifier
+
+        Returns:
+            Terminal exit response with exit_code
+        """
+        request = WaitForTerminalExitRequest(session_id=self.id, terminal_id=terminal_id)
+        return await self.client.wait_for_terminal_exit(request)
+
+    async def kill_terminal(self, terminal_id: str) -> None:
+        """Kill a terminal session.
+
+        Args:
+            terminal_id: Terminal identifier to kill
+        """
+        request = KillTerminalCommandRequest(session_id=self.id, terminal_id=terminal_id)
+        await self.client.kill_terminal(request)
+
+    async def release_terminal(self, terminal_id: str) -> None:
+        """Release a terminal session.
+
+        Args:
+            terminal_id: Terminal identifier to release
+        """
+        request = ReleaseTerminalRequest(session_id=self.id, terminal_id=terminal_id)
+        await self.client.release_terminal(request)
+
+    async def run_command(
+        self,
+        command: str,
+        *,
+        args: list[str] | None = None,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        output_byte_limit: int | None = None,
+        timeout_seconds: int | None = None,
+    ) -> tuple[str, int | None]:
+        """Execute a shell command and return output and exit code.
+
+        This is a high-level convenience method that creates a terminal,
+        runs the command, waits for completion, and cleans up.
+
+        Args:
+            command: Command to execute
+            args: Command arguments
+            cwd: Working directory for command execution
+            env: Environment variables for command execution
+            output_byte_limit: Maximum bytes to capture from output
+            timeout_seconds: Command timeout in seconds
+
+        Returns:
+            Tuple of (output, exit_code)
+        """
+        terminal_handle = await self.create_terminal(
+            command=command,
+            args=args,
+            cwd=cwd,
+            env=env,
+            output_byte_limit=output_byte_limit,
+        )
+        terminal_id = terminal_handle.terminal_id
+
+        try:
+            if timeout_seconds:  # Wait for completion (with optional timeout)
+                try:
+                    exit_result = await asyncio.wait_for(
+                        self.wait_for_terminal_exit(terminal_id),
+                        timeout=timeout_seconds,
+                    )
+                except TimeoutError:  # Kill on timeout and get partial output
+                    await self.kill_terminal(terminal_id)
+                    output_response = await self.terminal_output(terminal_id)
+                    return output_response.output, None
+            else:
+                exit_result = await self.wait_for_terminal_exit(terminal_id)
+
+            output_response = await self.terminal_output(terminal_id)
+            return output_response.output, exit_result.exit_code
+
+        finally:  # Always release terminal
+            await self.release_terminal(terminal_id)
+
+    async def request_permission(
+        self,
+        tool_call_id: str,
+        *,
+        title: str | None = None,
+        options: list[PermissionOption] | None = None,
+    ) -> RequestPermissionResponse:
+        """Request permission from user before executing a tool call.
+
+        Args:
+            tool_call_id: Unique identifier for the tool call
+            title: Human-readable description of the operation
+            options: Available permission options (defaults to allow/reject once)
+
+        Returns:
+            Permission response with user's decision
+        """
+        if options is None:
+            options = [
+                PermissionOption(
+                    option_id="allow-once",
+                    name="Allow once",
+                    kind="allow_once",
+                ),
+                PermissionOption(
+                    option_id="reject-once",
+                    name="Reject",
+                    kind="reject_once",
+                ),
+            ]
+
+        tool_call = ToolCall(tool_call_id=tool_call_id, title=title)
+        request = RequestPermissionRequest(
+            session_id=self.id,
+            tool_call=tool_call,
+            options=options,
+        )
+        return await self.client.request_permission(request)

acp/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Agent (Server) ACP Connection."""
+
+from acp.agent.protocol import Agent
+from acp.agent.connection import AgentSideConnection
+
+__all__ = ["Agent", "AgentSideConnection"]