agentpool 2.1.9__py3-none-any.whl

acp/schema/base.py

@@ -0,0 +1,39 @@
+"""Base class for generated models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+def convert(text: str) -> str:
+    if text == "field_meta":
+        return "_meta"
+    return to_camel(text)
+
+
+class Schema(BaseModel):
+    """Base class for generated models."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=convert,
+        use_attribute_docstrings=True,
+    )
+
+
+class AnnotatedObject(Schema):
+    """Base class for generated models."""
+
+    field_meta: dict[str, Any] | None = None
+    """Extension point for implementations."""
+
+
+class Request(AnnotatedObject):
+    """Base request model."""
+
+
+class Response(AnnotatedObject):
+    """Base request model."""

acp/schema/capabilities.py

@@ -0,0 +1,230 @@
+"""Capability schema."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field
+
+from acp.schema.base import AnnotatedObject
+
+
+class FileSystemCapability(AnnotatedObject):
+    """File system capabilities that a client may support.
+
+    See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)
+    """
+
+    read_text_file: bool | None = False
+    """Whether the Client supports `fs/read_text_file` requests."""
+
+    write_text_file: bool | None = False
+    """Whether the Client supports `fs/write_text_file` requests."""
+
+
+class ClientCapabilities(AnnotatedObject):
+    """Capabilities supported by the client.
+
+    Advertised during initialization to inform the agent about
+    available features and methods.
+
+    See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)
+    """
+
+    fs: FileSystemCapability | None = Field(default_factory=FileSystemCapability)
+    """File system capabilities supported by the client.
+
+    Determines which file operations the agent can request.
+    """
+
+    terminal: bool | None = False
+    """Whether the Client support all `terminal/*` methods."""
+
+    @classmethod
+    def create(
+        cls,
+        read_text_file: bool | None = False,
+        write_text_file: bool | None = False,
+        terminal: bool | None = False,
+    ) -> Self:
+        """Create a new instance of ClientCapabilities.
+
+        Args:
+            read_text_file: Whether the Client supports `fs/read_text_file` requests.
+            write_text_file: Whether the Client supports `fs/write_text_file` requests.
+            terminal: Whether the Client supports all `terminal/*` methods.
+
+        Returns:
+            A new instance of ClientCapabilities.
+        """
+        fs = FileSystemCapability(read_text_file=read_text_file, write_text_file=write_text_file)
+        return cls(fs=fs, terminal=terminal)
+
+
+class PromptCapabilities(AnnotatedObject):
+    """Prompt capabilities supported by the agent in `session/prompt` requests.
+
+    Baseline agent functionality requires support for [`ContentBlock::Text`]
+    and [`ContentBlock::ResourceContentBlock`] in prompt requests.
+
+    Other variants must be explicitly opted in to.
+    Capabilities for different types of content in prompt requests.
+
+    Indicates which content types beyond the baseline (text and resource links)
+    the agent can process.
+
+    See protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)
+    """
+
+    audio: bool | None = False
+    """Agent supports [`ContentBlock::Audio`]."""
+
+    embedded_context: bool | None = False
+    """Agent supports embedded context in `session/prompt` requests.
+
+    When enabled, the Client is allowed to include [`ContentBlock::Resource`]
+    in prompt requests for pieces of context that are referenced in the message.
+    """
+
+    image: bool | None = False
+    """Agent supports [`ContentBlock::Image`]."""
+
+
+class McpCapabilities(AnnotatedObject):
+    """MCP capabilities supported by the agent."""
+
+    http: bool | None = False
+    """Agent supports [`McpServer::Http`]."""
+
+    sse: bool | None = False
+    """Agent supports [`McpServer::Sse`]."""
+
+
+class SessionListCapabilities(AnnotatedObject):
+    """Capabilities for the `session/list` method.
+
+    **UNSTABLE**: This capability is not part of the spec yet,
+    and may be removed or changed at any point.
+
+    By supplying `{}` it means that the agent supports listing of sessions.
+    Further capabilities can be added in the future for other means of
+    filtering or searching the list.
+    """
+
+
+class SessionForkCapabilities(AnnotatedObject):
+    """Capabilities for the `session/fork` method.
+
+    **UNSTABLE**: This capability is not part of the spec yet,
+    and may be removed or changed at any point.
+
+    By supplying `{}` it means that the agent supports forking of sessions.
+    """
+
+
+class SessionResumeCapabilities(AnnotatedObject):
+    """Capabilities for the `session/resume` method.
+
+    **UNSTABLE**: This capability is not part of the spec yet,
+    and may be removed or changed at any point.
+
+    By supplying `{}` it means that the agent supports resuming of sessions.
+    """
+
+
+class SessionCapabilities(AnnotatedObject):
+    """Session capabilities supported by the agent.
+
+    As a baseline, all Agents **MUST** support `session/new`, `session/prompt`,
+    `session/cancel`, and `session/update`.
+
+    Optionally, they **MAY** support other session methods and notifications
+    by specifying additional capabilities.
+
+    Note: `session/load` is still handled by the top-level `load_session` capability.
+    This will be unified in future versions of the protocol.
+
+    See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)
+    """
+
+    fork: SessionForkCapabilities | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet, and may be removed or changed at any point.
+
+    Whether the agent supports `session/fork`.
+    """
+
+    list: SessionListCapabilities | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet, and may be removed or changed at any point.
+
+    Whether the agent supports `session/list`.
+    """
+
+    resume: SessionResumeCapabilities | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet, and may be removed or changed at any point.
+
+    Whether the agent supports `session/resume`.
+    """
+
+
+class AgentCapabilities(AnnotatedObject):
+    """Capabilities supported by the agent.
+
+    Advertised during initialization to inform the client about
+    available features and content types.
+
+    See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)
+    """
+
+    load_session: bool | None = False
+    """Whether the agent supports `session/load`."""
+
+    mcp_capabilities: McpCapabilities | None = Field(default_factory=McpCapabilities)
+    """MCP capabilities supported by the agent."""
+
+    prompt_capabilities: PromptCapabilities | None = Field(default_factory=PromptCapabilities)
+    """Prompt capabilities supported by the agent."""
+
+    session_capabilities: SessionCapabilities | None = Field(default_factory=SessionCapabilities)
+    """Session capabilities supported by the agent."""
+
+    @classmethod
+    def create(
+        cls,
+        load_session: bool | None = False,
+        http_mcp_servers: bool = False,
+        sse_mcp_servers: bool = False,
+        audio_prompts: bool = False,
+        embedded_context_prompts: bool = False,
+        image_prompts: bool = False,
+        list_sessions: bool = False,
+    ) -> Self:
+        """Create an instance of AgentCapabilities.
+
+        Args:
+            load_session: Whether the agent supports `session/load`.
+            http_mcp_servers: Whether the agent supports HTTP MCP servers.
+            sse_mcp_servers: Whether the agent supports SSE MCP servers.
+            audio_prompts: Whether the agent supports audio prompts.
+            embedded_context_prompts: Whether the agent supports embedded context prompts.
+            image_prompts: Whether the agent supports image prompts.
+            list_sessions: Whether the agent supports `session/list` (unstable).
+        """
+        session_caps = SessionCapabilities(
+            list=SessionListCapabilities() if list_sessions else None,
+        )
+        return cls(
+            load_session=load_session,
+            mcp_capabilities=McpCapabilities(http=http_mcp_servers, sse=sse_mcp_servers),
+            prompt_capabilities=PromptCapabilities(
+                audio=audio_prompts,
+                embedded_context=embedded_context_prompts,
+                image=image_prompts,
+            ),
+            session_capabilities=session_caps,
+        )

acp/schema/client_requests.py

@@ -0,0 +1,247 @@
+"""Client request schema definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence  # noqa: TC003
+from typing import Any, Self
+
+from pydantic import Field
+
+from acp.schema.base import Request
+from acp.schema.capabilities import ClientCapabilities, FileSystemCapability
+from acp.schema.common import Implementation
+from acp.schema.content_blocks import ContentBlock  # noqa: TC001
+from acp.schema.mcp import McpServer  # noqa: TC001
+
+
+class CustomRequest(Request):
+    """Request for custom/extension methods."""
+
+    method: str
+    """The custom method name (without underscore prefix)."""
+
+    data: dict[str, Any]
+    """The method parameters."""
+
+
+class NewSessionRequest(Request):
+    """Request parameters for creating a new session.
+
+    See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)
+    """
+
+    cwd: str
+    """The working directory for this session. Must be an absolute path."""
+
+    mcp_servers: Sequence[McpServer]
+    """List of MCP (Model Context Protocol) servers the agent should connect to."""
+
+
+class LoadSessionRequest(Request):
+    """Request parameters for loading an existing session.
+
+    Only available if the Agent supports the `loadSession` capability.
+
+    See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
+    """
+
+    cwd: str
+    """The working directory for this session."""
+
+    mcp_servers: Sequence[McpServer]
+    """List of MCP servers to connect to for this session."""
+
+    session_id: str
+    """The ID of the session to load."""
+
+
+class ListSessionsRequest(Request):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Request parameters for listing existing sessions.
+
+    Only available if the Agent supports the `listSessions` capability.
+    """
+
+    cursor: str | None = None
+    """Opaque cursor token from a previous response's nextCursor field for pagination."""
+
+    cwd: str | None = None
+    """Filter sessions by working directory. Must be an absolute path."""
+
+
+class ForkSessionRequest(Request):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Request parameters for forking an existing session.
+
+    Creates a new session based on the context of an existing one, allowing
+    operations like generating summaries without affecting the original session's history.
+
+    Only available if the Agent supports the `session.fork` capability.
+    """
+
+    session_id: str
+    """The ID of the session to fork."""
+
+    cwd: str
+    """The working directory for the new session."""
+
+    mcp_servers: Sequence[McpServer] = Field(default_factory=list)
+    """List of MCP servers to connect to for this session."""
+
+
+class ResumeSessionRequest(Request):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Request parameters for resuming an existing session.
+
+    Resumes an existing session without returning previous messages (unlike `session/load`).
+    This is useful for agents that can resume sessions but don't implement full session loading.
+
+    Only available if the Agent supports the `session.resume` capability.
+    """
+
+    cwd: str
+    """The working directory for this session."""
+
+    mcp_servers: Sequence[McpServer] = Field(default_factory=list)
+    """List of MCP servers to connect to for this session."""
+
+    session_id: str
+    """The ID of the session to resume."""
+
+
+class SetSessionModeRequest(Request):
+    """Request parameters for setting a session mode."""
+
+    mode_id: str
+    """The ID of the mode to set."""
+
+    session_id: str
+    """The ID of the session to set the mode for."""
+
+
+class PromptRequest(Request):
+    """Request parameters for sending a user prompt to the agent.
+
+    Contains the user's message and any additional context.
+
+    See protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message)
+    """
+
+    prompt: Sequence[ContentBlock]
+    """The blocks of content that compose the user's message.
+
+    As a baseline, the Agent MUST support [`ContentBlock::Text`] and
+    [`ContentBlock::ResourceContentBlock`],
+    while other variants are optionally enabled via [`PromptCapabilities`].
+
+    The Client MUST adapt its interface according to [`PromptCapabilities`].
+
+    The client MAY include referenced pieces of context as either
+    [`ContentBlock::Resource`] or [`ContentBlock::ResourceContentBlock`].
+
+    When available, [`ContentBlock::Resource`] is preferred
+    as it avoids extra round-trips and allows the message to include
+    pieces of context from sources the agent may not have access to.
+    """
+
+    session_id: str
+    """The ID of the session to send this user message to."""
+
+
+class SetSessionModelRequest(Request):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Request parameters for setting a session model.
+    """
+
+    model_id: str
+    """The ID of the model to set."""
+
+    session_id: str
+    """The ID of the session to set the model for."""
+
+
+class SetSessionConfigOptionRequest(Request):
+    """Request parameters for setting a session configuration option.
+
+    See protocol docs: [Session Config Options](https://agentclientprotocol.com/protocol/session-config-options)
+    """
+
+    config_id: str
+    """The ID of the configuration option to set."""
+
+    session_id: str
+    """The ID of the session to set the config option for."""
+
+    value_id: str
+    """The ID of the value to set for this configuration option."""
+
+
+class InitializeRequest(Request):
+    """Request parameters for the initialize method.
+
+    Sent by the client to establish connection and negotiate capabilities.
+
+    See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
+    """
+
+    client_capabilities: ClientCapabilities | None = Field(default_factory=ClientCapabilities)
+    """Capabilities supported by the client."""
+
+    client_info: Implementation | None = None
+    """Information about the Client name and version sent to the Agent.
+
+    Note: in future versions of the protocol, this will be required.
+    """
+
+    protocol_version: int
+    """The latest protocol version supported by the client."""
+
+    @classmethod
+    def create(
+        cls,
+        title: str,
+        name: str,
+        version: str,
+        terminal: bool = True,
+        read_text_file: bool = True,
+        write_text_file: bool = True,
+        protocol_version: int = 1,
+    ) -> Self:
+        """Create a new InitializeRequest instance."""
+        fs = FileSystemCapability(read_text_file=read_text_file, write_text_file=write_text_file)
+        caps = ClientCapabilities(terminal=terminal, fs=fs)
+        impl = Implementation(title=title, name=name, version=version)
+        return cls(client_capabilities=caps, client_info=impl, protocol_version=protocol_version)
+
+
+class AuthenticateRequest(Request):
+    """Request parameters for the authenticate method.
+
+    Specifies which authentication method to use.
+    """
+
+    method_id: str
+    """The ID of the authentication method to use.
+
+    Must be one of the methods advertised in the initialize response.
+    """
+
+
+ClientRequest = (
+    InitializeRequest
+    | AuthenticateRequest
+    | NewSessionRequest
+    | LoadSessionRequest
+    | ListSessionsRequest
+    | ForkSessionRequest
+    | ResumeSessionRequest
+    | SetSessionModeRequest
+    | SetSessionConfigOptionRequest
+    | PromptRequest
+    | SetSessionModelRequest
+    | CustomRequest
+)

acp/schema/client_responses.py

@@ -0,0 +1,96 @@
+"""Client response schema definitions."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from acp.schema.base import Response
+from acp.schema.terminal import TerminalExitStatus  # noqa: TC001
+from acp.schema.tool_call import AllowedOutcome, DeniedOutcome
+
+
+# terminal
+
+
+class CreateTerminalResponse(Response):
+    """Response containing the ID of the created terminal."""
+
+    terminal_id: str
+    """The unique identifier for the created terminal."""
+
+
+class KillTerminalCommandResponse(Response):
+    """Response to terminal/kill command method."""
+
+
+class ReleaseTerminalResponse(Response):
+    """Response to terminal/release method."""
+
+
+class TerminalOutputResponse(Response):
+    """Response containing the terminal output and exit status."""
+
+    exit_status: TerminalExitStatus | None = None
+    """Exit status if the command has completed."""
+
+    output: str
+    """The terminal output captured so far."""
+
+    truncated: bool
+    """Whether the output was truncated due to byte limits."""
+
+
+class WaitForTerminalExitResponse(Response):
+    """Response containing the exit status of a terminal command."""
+
+    exit_code: int | None = None
+    """The process exit code (may be null if terminated by signal)."""
+
+    signal: str | None = None
+    """The signal that terminated the process (may be null if exited normally)."""
+
+
+# Filesystem
+
+
+class WriteTextFileResponse(Response):
+    """Response to `fs/write_text_file`."""
+
+
+class ReadTextFileResponse(Response):
+    """Response containing the contents of a text file."""
+
+    content: str
+    """The contents of the text file."""
+
+
+# permissions
+
+
+class RequestPermissionResponse(Response):
+    """Response to a permission request."""
+
+    outcome: DeniedOutcome | AllowedOutcome
+    """The user's decision on the permission request."""
+
+    @classmethod
+    def denied(cls) -> Self:
+        """Create a response indicating that the permission request was denied."""
+        return cls(outcome=DeniedOutcome())
+
+    @classmethod
+    def allowed(cls, option_id: str) -> Self:
+        """Create a response indicating that the permission request was allowed."""
+        return cls(outcome=AllowedOutcome(option_id=option_id))
+
+
+ClientResponse = (
+    WriteTextFileResponse
+    | ReadTextFileResponse
+    | RequestPermissionResponse
+    | CreateTerminalResponse
+    | TerminalOutputResponse
+    | ReleaseTerminalResponse
+    | WaitForTerminalExitResponse
+    | KillTerminalCommandResponse
+)

acp/schema/common.py

@@ -0,0 +1,81 @@
+"""Common schema definitions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from acp.schema.base import AnnotatedObject, Schema
+
+
+class EnvVariable(AnnotatedObject):
+    """An environment variable to set when launching an MCP server."""
+
+    name: str
+    """The name of the environment variable."""
+
+    value: str
+    """The value to set for the environment variable."""
+
+
+class Implementation(Schema):
+    """Describes the name and version of an ACP implementation.
+
+    Includes an optional title for UI representation.
+    """
+
+    name: str
+    """Intended for programmatic or logical use.
+
+    Can be used as a display name fallback if title isn't present."""
+
+    title: str | None = None
+    """Intended for UI and end-user contexts.
+
+    Optimized to be human-readable and easily understood.
+    If not provided, the name should be used for display."""
+
+    version: str
+    """Version of the implementation.
+
+    Can be displayed to the user or used for debugging or metrics purposes."""
+
+
+class AuthMethod(AnnotatedObject):
+    """Describes an available authentication method."""
+
+    description: str | None = None
+    """Optional description providing more details about this authentication method."""
+
+    id: str
+    """Unique identifier for this authentication method."""
+
+    name: str
+    """Human-readable name of the authentication method."""
+
+
+class Error(Schema):
+    """JSON-RPC error object.
+
+    Represents an error that occurred during method execution, following the
+    JSON-RPC 2.0 error object specification with optional additional data.
+
+    See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)
+    """
+
+    code: int
+    """A number indicating the error type that occurred.
+
+    This must be an integer as defined in the JSON-RPC specification.
+    """
+
+    data: Any | None = None
+    """Optional primitive or structured value that contains additional errorinformation.
+
+    This may include debugging information or context-specific details.
+    """
+
+    message: str
+    """A string providing a short description of the error.
+
+    The message should be limited to a concise single sentence.
+    """