agentpool 2.1.9__py3-none-any.whl

acp/schema/tool_call.py

@@ -0,0 +1,347 @@
+"""Tool call schema definitions."""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence  # noqa: TC003
+from typing import TYPE_CHECKING, Any, Literal, Self
+
+from pydantic import Field
+
+from acp.schema.base import AnnotatedObject, Schema
+from acp.schema.content_blocks import (  # noqa: TC001
+    Annotations,
+    Audience,
+    AudioContentBlock,
+    BlobResourceContents,
+    ContentBlock,
+    EmbeddedResourceContentBlock,
+    ImageContentBlock,
+    ResourceContentBlock,
+    TextContentBlock,
+    TextResourceContents,
+)
+
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+ToolCallKind = Literal[
+    "read",
+    "edit",
+    "delete",
+    "move",
+    "search",
+    "execute",
+    "think",
+    "fetch",
+    "switch_mode",
+    "other",
+]
+ToolCallStatus = Literal["pending", "in_progress", "completed", "failed"]
+PermissionKind = Literal["allow_once", "allow_always", "reject_once", "reject_always"]
+
+
+class ToolCall(AnnotatedObject):
+    """Details about the tool call requiring permission."""
+
+    content: Sequence[ToolCallContent] | None = None
+    """Replace the content collection."""
+
+    kind: ToolCallKind | None = None
+    """Update the tool kind."""
+
+    locations: Sequence[ToolCallLocation] | None = None
+    """Replace the locations collection."""
+
+    raw_input: Any | None = None
+    """Update the raw input."""
+
+    raw_output: Any | None = None
+    """Update the raw output."""
+
+    status: ToolCallStatus | None = None
+    """Update the execution status."""
+
+    title: str | None = None
+    """Update the human-readable title."""
+
+    tool_call_id: str
+    """The ID of the tool call being updated."""
+
+
+class FileEditToolCallContent(AnnotatedObject):
+    """File modification shown as a diff."""
+
+    type: Literal["diff"] = Field(default="diff", init=False)
+    """File modification shown as a diff."""
+
+    new_text: str
+    """The new content after modification."""
+
+    old_text: str | None
+    """The original content (None for new files)."""
+
+    path: str
+    """The file path being modified."""
+
+
+class TerminalToolCallContent(Schema):
+    """Embed a terminal created with `terminal/create` by its id.
+
+    The terminal must be added before calling `terminal/release`.
+    See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminal)
+    """
+
+    type: Literal["terminal"] = Field(default="terminal", init=False)
+    """Terminal tool call content."""
+
+    terminal_id: str
+    """The ID of the terminal being embedded."""
+
+
+class ContentToolCallContent[TContentBlock: ContentBlock = ContentBlock](Schema):
+    """Standard content block (text, images, resources)."""
+
+    type: Literal["content"] = Field(default="content", init=False)
+    """Standard content block (text, images, resources)."""
+
+    content: TContentBlock
+    """The actual content block."""
+
+    @classmethod
+    def text(
+        cls,
+        text: str,
+        *,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing text.
+
+        Args:
+            text: The text content.
+            audience: The audience for the text.
+            last_modified: The last modified date of the text.
+            priority: The priority of the text.
+        """
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        return cls(content=TextContentBlock(text=text, annotations=annotations))
+
+    @classmethod
+    def image(
+        cls,
+        data: str | bytes,
+        mime_type: str,
+        uri: str | None = None,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing an embedded image resource.
+
+        Args:
+            data: The image data.
+            mime_type: The MIME type of the image.
+            uri: The URI of the image.
+            audience: The audience for the image.
+            last_modified: The last modified date of the image.
+            priority: The priority of the image.
+        """
+        if isinstance(data, bytes):
+            data = base64.b64encode(data).decode()
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        image = ImageContentBlock(data=data, mime_type=mime_type, uri=uri, annotations=annotations)
+        return cls(content=image)
+
+    @classmethod
+    def audio(
+        cls,
+        data: str | bytes,
+        mime_type: str,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing audio content.
+
+        Args:
+            data: The audio data.
+            mime_type: The MIME type of the audio data.
+            audience: The audience for the audio chunk.
+            last_modified: The last modified date of the audio chunk.
+            priority: The priority of the audio chunk.
+        """
+        if isinstance(data, bytes):
+            data = base64.b64encode(data).decode()
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        content = AudioContentBlock(data=data, mime_type=mime_type, annotations=annotations)
+        return cls(content=content)
+
+    @classmethod
+    def resource(
+        cls,
+        name: str,
+        uri: str,
+        description: str | None = None,
+        mime_type: str | None = None,
+        size: int | None = None,
+        title: str | None = None,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing a resource content block.
+
+        Args:
+            name: The name of the resource.
+            uri: The URI of the resource.
+            description: The description of the resource.
+            mime_type: The MIME type of the resource.
+            size: The size of the resource.
+            title: The title of the resource.
+            audience: The audience of the resource.
+            last_modified: The last modified date of the resource.
+            priority: The priority of the resource.
+        """
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        block = ResourceContentBlock(
+            name=name,
+            uri=uri,
+            description=description,
+            mime_type=mime_type,
+            size=size,
+            title=title,
+            annotations=annotations,
+        )
+        return cls(content=block)
+
+    @classmethod
+    def embedded_text_resource(
+        cls,
+        text: str,
+        uri: str,
+        mime_type: str | None = None,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing an embedded text resource.
+
+        Args:
+            text: The text to embed.
+            uri: The URI of the resource.
+            mime_type: The MIME type of the resource.
+            audience: The audience to apply to the resource.
+            last_modified: The last modified date of the resource.
+            priority: The priority of the resource.
+        """
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        contents = TextResourceContents(text=text, mime_type=mime_type, uri=uri)
+        content = EmbeddedResourceContentBlock(annotations=annotations, resource=contents)
+        return cls(content=content)  # ty: ignore[invalid-argument-type]
+
+    @classmethod
+    def embedded_blob_resource(
+        cls,
+        data: bytes | str,
+        uri: str,
+        mime_type: str | None = None,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self:
+        """Create a ToolCallContent containing an embedded blob resource.
+
+        Args:
+            data: The data to embed.
+            uri: The URI of the resource.
+            mime_type: The MIME type of the resource.
+            audience: The audience to apply to the resource.
+            last_modified: The last modified date of the resource.
+            priority: The priority of the resource.
+        """
+        if isinstance(data, bytes):
+            data = base64.b64encode(data).decode()
+        annotations = Annotations.optionally_create(
+            audience=audience,
+            last_modified=last_modified,
+            priority=priority,
+        )
+        resource = BlobResourceContents(blob=data, mime_type=mime_type, uri=uri)
+        content = EmbeddedResourceContentBlock(annotations=annotations, resource=resource)
+        return cls(content=content)  # ty: ignore[invalid-argument-type]
+
+
+class ToolCallLocation(AnnotatedObject):
+    """A file location being accessed or modified by a tool.
+
+    Enables clients to implement "follow-along" features that track
+    which files the agent is working with in real-time.
+    See protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent)
+    """
+
+    line: int = Field(default=0, ge=0)
+    """Line number within the file (0 = beginning/unspecified)."""
+
+    path: str
+    """The file path being accessed or modified."""
+
+
+class DeniedOutcome(Schema):
+    """The prompt turn was cancelled before the user responded.
+
+    When a client sends a `session/cancel` notification to cancel an ongoing
+    prompt turn, it MUST respond to all pending `session/request_permission`
+    requests with this `Cancelled` outcome.
+    See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
+    """
+
+    outcome: Literal["cancelled"] = Field(default="cancelled", init=False)
+
+
+class AllowedOutcome(Schema):
+    """The user selected one of the provided options."""
+
+    option_id: str
+    """The ID of the option the user selected."""
+
+    outcome: Literal["selected"] = Field(default="selected", init=False)
+
+
+class PermissionOption(AnnotatedObject):
+    """An option presented to the user when requesting permission."""
+
+    kind: PermissionKind
+    """Hint about the nature of this permission option."""
+
+    name: str
+    """Human-readable label to display to the user."""
+
+    option_id: str
+    """Unique identifier for this permission option."""
+
+
+ToolCallContent = ContentToolCallContent | FileEditToolCallContent | TerminalToolCallContent

acp/stdio.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+import sys
+from typing import TYPE_CHECKING, Any
+
+import anyio
+
+from acp.agent.connection import AgentSideConnection
+from acp.client.connection import ClientSideConnection
+from acp.connection import Connection
+from acp.transports import spawn_stdio_transport
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Mapping
+    from pathlib import Path
+
+    from anyio.abc import ByteReceiveStream, ByteSendStream, Process
+
+    from acp.agent.protocol import Agent
+    from acp.client.protocol import Client
+    from acp.connection import MethodHandler, StreamObserver
+
+__all__ = [
+    "connect_to_agent",
+    "run_agent",
+    "spawn_agent_process",
+    "spawn_client_process",
+    "spawn_stdio_connection",
+    "stdio_streams",
+]
+
+
+class StdinStream(anyio.abc.ByteReceiveStream):
+    """Wrapper for stdin that implements ByteReceiveStream interface."""
+
+    async def receive(self, max_bytes: int = 65536) -> bytes:
+        """Read bytes from stdin.
+
+        Uses read1() which returns as soon as any data is available,
+        rather than blocking until max_bytes are read.
+        """
+        loop = asyncio.get_running_loop()
+        # read1() returns immediately when any data is available (up to max_bytes)
+        # unlike read() which blocks until exactly max_bytes are read or EOF
+        data: bytes = await loop.run_in_executor(None, sys.stdin.buffer.read1, max_bytes)  # type: ignore[union-attr]
+        if not data:
+            raise anyio.EndOfStream
+        return data
+
+    async def aclose(self) -> None:
+        """Close is a no-op for stdin."""
+
+
+class StdoutStream(anyio.abc.ByteSendStream):
+    """Wrapper for stdout that implements ByteSendStream interface."""
+
+    async def send(self, item: bytes) -> None:
+        """Write bytes to stdout."""
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self._write, item)
+
+    def _write(self, data: bytes) -> None:
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+
+    async def aclose(self) -> None:
+        """Close is a no-op for stdout."""
+
+
+async def stdio_streams() -> tuple[StdinStream, StdoutStream]:
+    """Create stdio anyio-compatible streams (cross-platform).
+
+    Returns (stdin, stdout) as byte stream wrappers compatible with
+    ByteReceiveStream and ByteSendStream interfaces.
+    """
+    return StdinStream(), StdoutStream()
+
+
+@asynccontextmanager
+async def spawn_stdio_connection(
+    handler: MethodHandler,
+    command: str,
+    *args: str,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    observers: list[StreamObserver] | None = None,
+    **transport_kwargs: Any,
+) -> 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 (
+        reader,
+        writer,
+        process,
+    ):
+        conn = Connection(handler, writer, reader, observers=observers)
+        try:
+            yield conn, process
+        finally:
+            await conn.close()
+
+
+@asynccontextmanager
+async def spawn_agent_process(
+    to_client: Callable[[Agent], Client],
+    command: str,
+    *args: str,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    transport_kwargs: Mapping[str, Any] | None = None,
+    **connection_kwargs: Any,
+) -> AsyncIterator[tuple[ClientSideConnection, Process]]:
+    """Spawn an ACP agent subprocess and return a ClientSideConnection to it."""
+    async with spawn_stdio_transport(
+        command,
+        *args,
+        env=env,
+        cwd=cwd,
+        **(dict(transport_kwargs) if transport_kwargs else {}),
+    ) as (reader, writer, process):
+        conn = ClientSideConnection(to_client, writer, reader, **connection_kwargs)
+        try:
+            yield conn, process
+        finally:
+            await conn.close()
+
+
+@asynccontextmanager
+async def spawn_client_process(
+    to_agent: Callable[[AgentSideConnection], Agent],
+    command: str,
+    *args: str,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    transport_kwargs: Mapping[str, Any] | None = None,
+    **connection_kwargs: Any,
+) -> AsyncIterator[tuple[AgentSideConnection, Process]]:
+    """Spawn an ACP client subprocess and return an AgentSideConnection to it."""
+    async with spawn_stdio_transport(
+        command,
+        *args,
+        env=env,
+        cwd=cwd,
+        **(dict(transport_kwargs) if transport_kwargs else {}),
+    ) as (reader, writer, process):
+        conn = AgentSideConnection(to_agent, writer, reader, **connection_kwargs)
+        try:
+            yield conn, process
+        finally:
+            await conn.close()
+
+
+async def run_agent(
+    agent: Agent | Callable[[AgentSideConnection], Agent],
+    input_stream: ByteSendStream | None = None,
+    output_stream: ByteReceiveStream | None = None,
+    **connection_kwargs: Any,
+) -> None:
+    """Run an ACP agent over stdio or provided streams.
+
+    This is the recommended entry point for running agents. It handles stream
+    setup and connection lifecycle automatically.
+
+    Args:
+        agent: An Agent implementation or a factory callable that takes
+            an AgentSideConnection and returns an Agent. Using a factory allows
+            the agent to access the connection for client communication.
+        input_stream: Optional ByteSendStream for output (defaults to stdio).
+        output_stream: Optional ByteReceiveStream for input (defaults to stdio).
+        **connection_kwargs: Additional keyword arguments for AgentSideConnection.
+
+    Example with direct agent:
+        ```python
+        class MyAgent(Agent):
+            async def initialize(self, params: InitializeRequest) -> InitializeResponse:
+                return InitializeResponse(protocol_version=params.protocol_version)
+            # ... implement protocol methods ...
+
+        await run_agent(MyAgent())
+        ```
+
+    Example with factory:
+        ```python
+        class MyAgent(Agent):
+            def __init__(self, connection: AgentSideConnection):
+                self.connection = connection
+            # ... implement protocol methods ...
+
+        def create_agent(conn: AgentSideConnection) -> MyAgent:
+            return MyAgent(conn)
+
+        await run_agent(create_agent)
+        ```
+    """
+    if input_stream is None or output_stream is None:
+        # For stdio, we need to create byte streams from the text wrappers
+        # This follows the MCP SDK server pattern
+        _stdin_file, _stdout_file = await stdio_streams()
+        # Note: run_agent expects ByteSendStream/ByteReceiveStream but stdio_streams
+        # returns text AsyncFiles. For now, we'll use the underlying buffer.
+        # TODO: Consider refactoring to use memory object streams like MCP SDK
+        msg = "run_agent with stdio streams requires explicit stream arguments for now"
+        raise NotImplementedError(msg)
+
+    # Wrap agent instance in factory if needed
+    if callable(agent):
+        agent_factory = agent  # pyright: ignore[reportAssignmentType]
+    else:
+
+        def agent_factory(connection: AgentSideConnection) -> Agent:
+            return agent  # ty: ignore[invalid-return-type]
+
+    conn = AgentSideConnection(agent_factory, input_stream, output_stream, **connection_kwargs)
+    shutdown_event = asyncio.Event()
+    try:
+        # Keep the connection alive until cancelled
+        await shutdown_event.wait()
+    except asyncio.CancelledError:
+        pass
+    finally:
+        await conn.close()
+
+
+def connect_to_agent(
+    client: Client,
+    input_stream: ByteSendStream,
+    output_stream: ByteReceiveStream,
+    **connection_kwargs: Any,
+) -> ClientSideConnection:
+    """Create a ClientSideConnection to an ACP agent.
+
+    This is the recommended entry point for client-side connections.
+
+    Args:
+        client: The client implementation.
+        input_stream: ByteSendStream for sending to the agent.
+        output_stream: ByteReceiveStream for receiving from the agent.
+        **connection_kwargs: Additional keyword arguments for ClientSideConnection.
+
+    Returns:
+        A ClientSideConnection connected to the agent.
+    """
+
+    # Create a factory that ignores the connection parameter
+    def client_factory(connection: Agent) -> Client:
+        return client
+
+    return ClientSideConnection(client_factory, input_stream, output_stream, **connection_kwargs)

acp/task/__init__.py

@@ -0,0 +1,53 @@
+"""Task package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+__all__ = ["RpcTask", "RpcTaskKind"]
+
+
+class RpcTaskKind(Enum):
+    """RpcTaskKind represents the kind of task to be executed by the agent."""
+
+    REQUEST = "request"
+    NOTIFICATION = "notification"
+
+
+@dataclass(slots=True)
+class RpcTask:
+    """RpcTask represents a task to be executed by the agent."""
+
+    kind: RpcTaskKind
+    message: dict[str, Any]
+
+
+from .dispatcher import (
+    DefaultMessageDispatcher,
+    MessageDispatcher,
+    NotificationRunner,
+    RequestRunner,
+)
+from .queue import InMemoryMessageQueue, MessageQueue
+from .sender import MessageSender, SenderFactory
+from .state import InMemoryMessageStateStore, MessageStateStore
+from .supervisor import TaskSupervisor
+from .debug import DebugEntry, DebuggingMessageStateStore
+
+__all__ += [
+    "DebugEntry",
+    "DebuggingMessageStateStore",
+    "DefaultMessageDispatcher",
+    "InMemoryMessageQueue",
+    "InMemoryMessageStateStore",
+    "MessageDispatcher",
+    "MessageQueue",
+    "MessageSender",
+    "MessageStateStore",
+    "NotificationRunner",
+    "RequestRunner",
+    "SenderFactory",
+    "TaskSupervisor",
+]