agentpool 2.1.9__py3-none-any.whl

acp/schema/__init__.py

@@ -0,0 +1,265 @@
+"""Schema definitions for the ACP protocol."""
+
+from acp.schema.agent_plan import PlanEntry, PlanEntryPriority, PlanEntryStatus
+from acp.schema.agent_requests import (
+    AgentRequest,
+    CreateTerminalRequest,
+    KillTerminalCommandRequest,
+    ReadTextFileRequest,
+    ReleaseTerminalRequest,
+    RequestPermissionRequest,
+    TerminalOutputRequest,
+    WaitForTerminalExitRequest,
+    WriteTextFileRequest,
+)
+from acp.schema.agent_responses import (
+    AgentResponse,
+    AuthenticateResponse,
+    CustomResponse,
+    ForkSessionResponse,
+    InitializeResponse,
+    LoadSessionResponse,
+    NewSessionResponse,
+    ListSessionsResponse,
+    PromptResponse,
+    ResumeSessionResponse,
+    SetSessionConfigOptionResponse,
+    SetSessionModeResponse,
+    SetSessionModelResponse,
+    StopReason,
+)
+from acp.schema.capabilities import (
+    AgentCapabilities,
+    ClientCapabilities,
+    FileSystemCapability,
+    McpCapabilities,
+    PromptCapabilities,
+    SessionCapabilities,
+    SessionForkCapabilities,
+    SessionListCapabilities,
+    SessionResumeCapabilities,
+)
+from acp.schema.client_requests import (
+    AuthenticateRequest,
+    ClientRequest,
+    CustomRequest,
+    ForkSessionRequest,
+    InitializeRequest,
+    ListSessionsRequest,
+    LoadSessionRequest,
+    NewSessionRequest,
+    PromptRequest,
+    ResumeSessionRequest,
+    SetSessionConfigOptionRequest,
+    SetSessionModeRequest,
+    SetSessionModelRequest,
+)
+from acp.schema.client_responses import (
+    ClientResponse,
+    CreateTerminalResponse,
+    KillTerminalCommandResponse,
+    ReadTextFileResponse,
+    ReleaseTerminalResponse,
+    RequestPermissionResponse,
+    TerminalOutputResponse,
+    WaitForTerminalExitResponse,
+    WriteTextFileResponse,
+)
+from acp.schema.common import AuthMethod, EnvVariable, Implementation
+from acp.schema.content_blocks import (
+    Annotations,
+    AudioContentBlock,
+    Audience,
+    BlobResourceContents,
+    ContentBlock,
+    EmbeddedResourceContentBlock,
+    ImageContentBlock,
+    ResourceContentBlock,
+    TextContentBlock,
+    TextResourceContents,
+)
+from acp.schema.mcp import (
+    HttpHeader,
+    HttpMcpServer,
+    McpServer,
+    SseMcpServer,
+    StdioMcpServer,
+)
+from acp.schema.messages import AgentMethod, ClientMethod
+from acp.schema.notifications import (
+    AgentNotification,
+    CancelNotification,
+    ClientNotification,
+    ExtNotification,
+    SessionNotification,
+)
+from acp.schema.session_state import (
+    ModelInfo,
+    SessionConfigOption,
+    SessionConfigSelect,
+    SessionConfigSelectGroup,
+    SessionConfigSelectOption,
+    SessionConfigSelectOptions,
+    SessionInfo,
+    SessionMode,
+    SessionModeState,
+    SessionModelState,
+)
+from acp.schema.slash_commands import (
+    AvailableCommand,
+    AvailableCommandInput,
+    CommandInputHint,
+)
+from acp.schema.terminal import TerminalExitStatus
+from acp.schema.tool_call import (
+    AllowedOutcome,
+    ContentToolCallContent,
+    DeniedOutcome,
+    FileEditToolCallContent,
+    PermissionKind,
+    PermissionOption,
+    TerminalToolCallContent,
+    ToolCall,
+    ToolCallContent,
+    ToolCallKind,
+    ToolCallLocation,
+    ToolCallStatus,
+)
+from acp.schema.session_updates import (
+    AgentMessageChunk,
+    AgentPlanUpdate,
+    AgentThoughtChunk,
+    AvailableCommandsUpdate,
+    ConfigOptionUpdate,
+    CurrentModeUpdate,
+    CurrentModelUpdate,
+    SessionUpdate,
+    ToolCallProgress,
+    ToolCallStart,
+    UserMessageChunk,
+)
+
+PROTOCOL_VERSION = 1
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "AgentCapabilities",
+    "AgentMessageChunk",
+    "AgentMethod",
+    "AgentNotification",
+    "AgentPlanUpdate",
+    "AgentRequest",
+    "AgentResponse",
+    "AgentThoughtChunk",
+    "AllowedOutcome",
+    "Annotations",
+    "Audience",
+    "AudioContentBlock",
+    "AuthMethod",
+    "AuthenticateRequest",
+    "AuthenticateResponse",
+    "AvailableCommand",
+    "AvailableCommandInput",
+    "AvailableCommandsUpdate",
+    "BlobResourceContents",
+    "CancelNotification",
+    "ClientCapabilities",
+    "ClientMethod",
+    "ClientNotification",
+    "ClientRequest",
+    "ClientResponse",
+    "CommandInputHint",
+    "ConfigOptionUpdate",
+    "ContentBlock",
+    "ContentToolCallContent",
+    "CreateTerminalRequest",
+    "CreateTerminalResponse",
+    "CurrentModeUpdate",
+    "CurrentModelUpdate",
+    "CustomRequest",
+    "CustomResponse",
+    "DeniedOutcome",
+    "EmbeddedResourceContentBlock",
+    "EnvVariable",
+    "ExtNotification",
+    "FileEditToolCallContent",
+    "FileSystemCapability",
+    "ForkSessionRequest",
+    "ForkSessionResponse",
+    "HttpHeader",
+    "HttpMcpServer",
+    "ImageContentBlock",
+    "Implementation",
+    "InitializeRequest",
+    "InitializeResponse",
+    "KillTerminalCommandRequest",
+    "KillTerminalCommandResponse",
+    "ListSessionsRequest",
+    "ListSessionsResponse",
+    "LoadSessionRequest",
+    "LoadSessionResponse",
+    "McpCapabilities",
+    "McpServer",
+    "ModelInfo",
+    "NewSessionRequest",
+    "NewSessionResponse",
+    "PermissionKind",
+    "PermissionOption",
+    "PlanEntry",
+    "PlanEntryPriority",
+    "PlanEntryStatus",
+    "PromptCapabilities",
+    "PromptRequest",
+    "PromptResponse",
+    "ReadTextFileRequest",
+    "ReadTextFileResponse",
+    "ReleaseTerminalRequest",
+    "ReleaseTerminalResponse",
+    "RequestPermissionRequest",
+    "RequestPermissionResponse",
+    "ResourceContentBlock",
+    "ResumeSessionRequest",
+    "ResumeSessionResponse",
+    "SessionCapabilities",
+    "SessionConfigOption",
+    "SessionConfigSelect",
+    "SessionConfigSelectGroup",
+    "SessionConfigSelectOption",
+    "SessionConfigSelectOptions",
+    "SessionForkCapabilities",
+    "SessionInfo",
+    "SessionListCapabilities",
+    "SessionMode",
+    "SessionModeState",
+    "SessionModelState",
+    "SessionNotification",
+    "SessionResumeCapabilities",
+    "SessionUpdate",
+    "SetSessionConfigOptionRequest",
+    "SetSessionConfigOptionResponse",
+    "SetSessionModeRequest",
+    "SetSessionModeResponse",
+    "SetSessionModelRequest",
+    "SetSessionModelResponse",
+    "SseMcpServer",
+    "StdioMcpServer",
+    "StopReason",
+    "TerminalExitStatus",
+    "TerminalOutputRequest",
+    "TerminalOutputResponse",
+    "TerminalToolCallContent",
+    "TextContentBlock",
+    "TextResourceContents",
+    "ToolCall",
+    "ToolCallContent",
+    "ToolCallKind",
+    "ToolCallLocation",
+    "ToolCallProgress",
+    "ToolCallStart",
+    "ToolCallStatus",
+    "UserMessageChunk",
+    "WaitForTerminalExitRequest",
+    "WaitForTerminalExitResponse",
+    "WriteTextFileRequest",
+    "WriteTextFileResponse",
+]

acp/schema/agent_plan.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from acp.schema.base import AnnotatedObject
+
+
+PlanEntryPriority = Literal["high", "medium", "low"]
+PlanEntryStatus = Literal["pending", "in_progress", "completed"]
+
+
+class PlanEntry(AnnotatedObject):
+    """A single entry in the execution plan.
+
+    Represents a task or goal that the assistant intends to accomplish
+    as part of fulfilling the user's request.
+    See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)
+    """
+
+    content: str
+    """Human-readable description of what this task aims to accomplish."""
+
+    priority: PlanEntryPriority
+    """The relative importance of this task.
+
+    Used to indicate which tasks are most critical to the overall goal.
+    """
+
+    status: PlanEntryStatus
+    """Current execution status of this task."""

acp/schema/agent_requests.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from collections.abc import Sequence  # noqa: TC003
+
+from pydantic import Field
+
+from acp.schema.base import Request
+from acp.schema.common import EnvVariable  # noqa: TC001
+from acp.schema.tool_call import PermissionOption, ToolCall  # noqa: TC001
+
+
+class BaseAgentRequest(Request):
+    """Base class for all agent requests."""
+
+    session_id: str
+    """The session ID for this request."""
+
+
+class WriteTextFileRequest(BaseAgentRequest):
+    """Request to write content to a text file.
+
+    Only available if the client supports the `fs.writeTextFile` capability.
+    """
+
+    content: str
+    """The text content to write to the file."""
+
+    path: str
+    """Absolute path to the file to write."""
+
+
+class ReadTextFileRequest(BaseAgentRequest):
+    """Request to read content from a text file.
+
+    Only available if the client supports the `fs.readTextFile` capability.
+    """
+
+    limit: int | None = Field(default=None, ge=0)
+    """Maximum number of lines to read."""
+
+    line: int | None = Field(default=None, ge=0)
+    """Line number to start reading from (1-based)."""
+
+    path: str
+    """Absolute path to the file to read."""
+
+
+class TerminalOutputRequest(BaseAgentRequest):
+    """Request to get the current output and status of a terminal."""
+
+    terminal_id: str
+    """The ID of the terminal to get output from."""
+
+
+class WaitForTerminalExitRequest(BaseAgentRequest):
+    """Request to wait for a terminal command to exit."""
+
+    terminal_id: str
+    """The ID of the terminal to wait for."""
+
+
+class CreateTerminalRequest(BaseAgentRequest):
+    """Request to create a new terminal and execute a command."""
+
+    args: Sequence[str] | None = None
+    """Array of command arguments."""
+
+    command: str
+    """The command to execute."""
+
+    cwd: str | None = None
+    """Working directory for the command (absolute path)."""
+
+    env: Sequence[EnvVariable] | None = None
+    """Environment variables for the command."""
+
+    output_byte_limit: int | None = Field(default=None, ge=0)
+    """Maximum number of output bytes to retain.
+
+    When the limit is exceeded, the Client truncates from the beginning of the output
+    to stay within the limit.
+
+    The Client MUST ensure truncation happens at a character boundary to maintain valid
+    string output, even if this means the retained output is slightly less than the
+    specified limit."""
+
+
+class KillTerminalCommandRequest(BaseAgentRequest):
+    """Request to kill a terminal command without releasing the terminal."""
+
+    terminal_id: str
+    """The ID of the terminal to kill."""
+
+
+class ReleaseTerminalRequest(BaseAgentRequest):
+    """Request to release a terminal and free its resources."""
+
+    terminal_id: str
+    """The ID of the terminal to release."""
+
+
+class RequestPermissionRequest(BaseAgentRequest):
+    """Request for user permission to execute a tool call.
+
+    Sent when the agent needs authorization before performing a sensitive operation.
+
+    See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)
+    """
+
+    options: Sequence[PermissionOption]
+    """Available permission options for the user to choose from."""
+
+    tool_call: ToolCall
+    """Details about the tool call requiring permission."""
+
+
+AgentRequest = (
+    WriteTextFileRequest
+    | ReadTextFileRequest
+    | RequestPermissionRequest
+    | CreateTerminalRequest
+    | TerminalOutputRequest
+    | ReleaseTerminalRequest
+    | WaitForTerminalExitRequest
+    | KillTerminalCommandRequest
+)

acp/schema/agent_responses.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from collections.abc import Sequence  # noqa: TC003
+from typing import Any, Literal, Self
+
+from pydantic import Field
+
+from acp.schema.base import Response
+from acp.schema.capabilities import AgentCapabilities
+from acp.schema.common import AuthMethod, Implementation  # noqa: TC001
+from acp.schema.session_state import (  # noqa: TC001
+    SessionInfo,
+    SessionModelState,
+    SessionModeState,
+)
+
+
+class CustomResponse(Response):
+    """Response for custom/extension methods."""
+
+    data: dict[str, Any] | None = None
+    """The method result data."""
+
+
+StopReason = Literal[
+    "end_turn",
+    "max_tokens",
+    "max_turn_requests",
+    "refusal",
+    "cancelled",
+]
+
+
+class SetSessionModelResponse(Response):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Response to `session/set_model` method.
+    """
+
+
+class NewSessionResponse(Response):
+    """Response from creating a new session.
+
+    See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)
+    """
+
+    models: SessionModelState | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet.
+
+    Initial model state if supported by the Agent
+    """
+
+    modes: SessionModeState | None = None
+    """Initial mode state if supported by the Agent
+
+    See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+    """
+
+    session_id: str
+    """Unique identifier for the created session.
+
+    Used in all subsequent requests for this conversation.
+    """
+
+
+class LoadSessionResponse(Response):
+    """Response from loading an existing session."""
+
+    models: SessionModelState | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet.
+
+    Initial model state if supported by the Agent
+    """
+
+    modes: SessionModeState | None = None
+    """Initial mode state if supported by the Agent
+
+    See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+    """
+
+
+class ForkSessionResponse(Response):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Response from forking an existing session.
+    """
+
+    models: SessionModelState | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet.
+
+    Initial model state if supported by the Agent
+    """
+
+    modes: SessionModeState | None = None
+    """Initial mode state if supported by the Agent
+
+    See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+    """
+
+    session_id: str
+    """Unique identifier for the newly created forked session."""
+
+
+class ResumeSessionResponse(Response):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Response from resuming an existing session.
+    """
+
+    models: SessionModelState | None = None
+    """**UNSTABLE**
+
+    This capability is not part of the spec yet.
+
+    Initial model state if supported by the Agent
+    """
+
+    modes: SessionModeState | None = None
+    """Initial mode state if supported by the Agent
+
+    See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+    """
+
+
+class SetSessionModeResponse(Response):
+    """Response to `session/set_mode` method."""
+
+
+class SetSessionConfigOptionResponse(Response):
+    """Response to `session/set_config_option` method."""
+
+
+class PromptResponse(Response):
+    """Response from processing a user prompt.
+
+    See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)
+    """
+
+    stop_reason: StopReason
+    """Indicates why the agent stopped processing the turn."""
+
+
+class AuthenticateResponse(Response):
+    """Response to authenticate method."""
+
+
+class InitializeResponse(Response):
+    """Response from the initialize method.
+
+    Contains the negotiated protocol version and agent capabilities.
+
+    See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
+    """
+
+    agent_capabilities: AgentCapabilities | None = Field(default_factory=AgentCapabilities)
+    """Capabilities supported by the agent."""
+
+    agent_info: Implementation | None = None
+    """Information about the Agent name and version sent to the Client.
+
+
+    Note: in future versions of the protocol, this will be required."""
+
+    auth_methods: Sequence[AuthMethod] | None = Field(default_factory=list)
+    """Authentication methods supported by the agent."""
+
+    protocol_version: int = Field(ge=0, le=65535)
+    """The protocol version the client specified if supported by the agent.
+
+    Or the latest protocol version supported by the agent.
+    The client should disconnect, if it doesn't support this version.
+    """
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        title: str,
+        version: str,
+        protocol_version: int,
+        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,
+        auth_methods: Sequence[AuthMethod] | None = None,
+    ) -> Self:
+        """Create an instance of AgentCapabilities.
+
+        Args:
+            name: The name of the agent.
+            title: The title of the agent.
+            version: The version of the agent.
+            protocol_version: The protocol version of the agent.
+            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).
+            auth_methods: The authentication methods supported by the agent.
+        """
+        caps = AgentCapabilities.create(
+            load_session=load_session,
+            http_mcp_servers=http_mcp_servers,
+            sse_mcp_servers=sse_mcp_servers,
+            audio_prompts=audio_prompts,
+            embedded_context_prompts=embedded_context_prompts,
+            image_prompts=image_prompts,
+            list_sessions=list_sessions,
+        )
+        return cls(
+            agent_info=Implementation(name=name, title=title, version=version),
+            protocol_version=protocol_version,
+            agent_capabilities=caps,
+            auth_methods=auth_methods,
+        )
+
+
+class ListSessionsResponse(Response):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Response from listing sessions.
+    """
+
+    next_cursor: str | None = None
+    """Opaque cursor token. If present, pass this in the next request's cursor parameter
+    to fetch the next page. If absent, there are no more results."""
+
+    sessions: Sequence[SessionInfo] = Field(default_factory=list)
+    """Array of session information objects."""
+
+
+AgentResponse = (
+    InitializeResponse
+    | AuthenticateResponse
+    | NewSessionResponse
+    | LoadSessionResponse
+    | ForkSessionResponse
+    | ResumeSessionResponse
+    | ListSessionsResponse
+    | SetSessionModeResponse
+    | SetSessionConfigOptionResponse
+    | PromptResponse
+    | SetSessionModelResponse
+    | CustomResponse
+)