agentpool 2.1.9__py3-none-any.whl

acp/schema/content_blocks.py

@@ -0,0 +1,188 @@
+"""Content block schema definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Annotated, Literal, Self
+
+from pydantic import Field
+
+from acp.schema.base import AnnotatedObject
+
+
+Audience = Sequence[Literal["assistant", "user"]]
+
+
+class BaseResourceContents(AnnotatedObject):
+    """Text-based resource contents."""
+
+    mime_type: str | None = None
+    """MIME type of the resource."""
+
+    uri: str
+    """URI of the resource."""
+
+
+class TextResourceContents(BaseResourceContents):
+    """Text-based resource contents."""
+
+    text: str
+    """Text content of the resource."""
+
+
+class BlobResourceContents(BaseResourceContents):
+    """Binary resource contents."""
+
+    blob: str
+    """Base64-encoded binary content of the resource."""
+
+
+class Annotations(AnnotatedObject):
+    """Optional annotations for the client.
+
+    The client can use annotations to inform how objects are used or displayed.
+    """
+
+    audience: Audience | None = None
+    """Audience for the annotated resource."""
+
+    last_modified: str | None = None
+    """Last modified timestamp of the annotated resource."""
+
+    priority: float | None = None
+    """Priority of the annotated resource."""
+
+    @classmethod
+    def optionally_create(
+        cls,
+        audience: Audience | None = None,
+        last_modified: datetime | str | None = None,
+        priority: float | None = None,
+    ) -> Self | None:
+        """Create an annotations object if any value is given, otherwise return None."""
+        if audience is None and last_modified is None and priority is None:
+            return None
+        if isinstance(last_modified, datetime):
+            last_modified = last_modified.strftime("%Y-%m-%dT%H:%M:%SZ")
+        return cls(audience=audience, last_modified=last_modified, priority=priority)
+
+
+class BaseContentBlock(AnnotatedObject):
+    """Base content block."""
+
+    annotations: Annotations | None = None
+    """Annotations for the content block."""
+
+
+ResourceContents = TextResourceContents | BlobResourceContents
+
+
+class EmbeddedResourceContentBlock[TResourceContents: ResourceContents = ResourceContents](
+    BaseContentBlock
+):
+    """Complete resource contents embedded directly in the message.
+
+    Preferred for including context as it avoids extra round-trips.
+
+    Requires the `embeddedContext` prompt capability when included in prompts.
+    """
+
+    type: Literal["resource"] = Field(default="resource", init=False)
+
+    resource: TResourceContents
+    """Resource content that can be embedded in a message."""
+
+
+class TextContentBlock(BaseContentBlock):
+    """Text content.
+
+    May be plain text or formatted with Markdown.
+
+    All agents MUST support text content blocks in prompts.
+    Clients SHOULD render this text as Markdown.
+    """
+
+    type: Literal["text"] = Field(default="text", init=False)
+
+    text: str
+    """Text content of the block."""
+
+
+class ImageContentBlock(BaseContentBlock):
+    """Images for visual context or analysis.
+
+    Requires the `image` prompt capability when included in prompts.
+    """
+
+    type: Literal["image"] = Field(default="image", init=False)
+
+    data: str
+    """Base64-encoded image data."""
+
+    mime_type: str
+    """MIME type of the image."""
+
+    uri: str | None = None
+    """URI of the image."""
+
+
+class AudioContentBlock(BaseContentBlock):
+    """Audio data for transcription or analysis.
+
+    Requires the `audio` prompt capability when included in prompts.
+    """
+
+    type: Literal["audio"] = Field(default="audio", init=False)
+
+    data: str
+    """Base64-encoded audio data."""
+
+    mime_type: str
+    """MIME type of the audio."""
+
+
+# Resource links:
+# [@index.js](file:///Users/.../projects/reqwest/examples/wasm_github_fetch/index.js)
+# [@wasm](file:///Users/.../projects/reqwest/src/wasm)
+# [@error](file:///Users/.../projects/reqwest/src/async_impl/client.rs?symbol=Error#L2661:2661)
+# [@error.rs (23:27)](file:///Users/.../projects/reqwest/src/error.rs#L23:27)
+
+
+class ResourceContentBlock(BaseContentBlock):
+    """References to resources that the agent can access.
+
+    All agents MUST support resource links in prompts.
+    """
+
+    type: Literal["resource_link"] = Field(default="resource_link", init=False)
+
+    description: str | None = None
+    """Description of the resource."""
+
+    mime_type: str | None = None
+    """MIME type of the resource."""
+
+    name: str
+    """Name of the resource."""
+
+    size: int | None = Field(default=None, ge=0)
+    """Size of the resource in bytes."""
+
+    title: str | None = None
+    """Title of the resource."""
+
+    uri: str
+    """URI of the resource."""
+
+
+ContentBlock = Annotated[
+    (
+        TextContentBlock
+        | ImageContentBlock
+        | AudioContentBlock
+        | ResourceContentBlock
+        | EmbeddedResourceContentBlock
+    ),
+    Field(discriminator="type"),
+]

acp/schema/mcp.py

@@ -0,0 +1,82 @@
+"""MCP schema definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence  # noqa: TC003
+from typing import Literal
+
+from pydantic import Field, HttpUrl  # noqa: TC002
+
+from acp.schema.base import AnnotatedObject, Schema
+from acp.schema.common import EnvVariable  # noqa: TC001
+
+
+class HttpHeader(AnnotatedObject):
+    """An HTTP header to set when making requests to the MCP server."""
+
+    name: str
+    """The name of the HTTP header."""
+
+    value: str
+    """The value to set for the HTTP header."""
+
+
+class BaseMcpServer(Schema):
+    """MCP server base class."""
+
+    name: str
+    """Human-readable name identifying this MCP server."""
+
+
+class HttpMcpServer(BaseMcpServer):
+    """HTTP transport configuration.
+
+    Only available when the Agent capabilities indicate `mcp_capabilities.http` is `true`.
+    """
+
+    headers: Sequence[HttpHeader]
+    """HTTP headers to set when making requests to the MCP server."""
+
+    type: Literal["http"] = Field(default="http", init=False)
+    """HTTP transport type."""
+
+    url: HttpUrl
+    """URL to the MCP server."""
+
+
+class SseMcpServer(BaseMcpServer):
+    """SSE transport configuration.
+
+    Only available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`.
+    """
+
+    headers: Sequence[HttpHeader]
+    """HTTP headers to set when making requests to the MCP server."""
+
+    type: Literal["sse"] = Field(default="sse", init=False)
+    """SSE transport type."""
+
+    url: HttpUrl
+    """URL to the MCP server."""
+
+
+class StdioMcpServer(BaseMcpServer):
+    """Stdio transport configuration.
+
+    All Agents MUST support this transport.
+    """
+
+    args: Sequence[str]
+    """Command-line arguments to pass to the MCP server."""
+
+    # typ: Literal["stdio"] = Field(default="stdio", init=False)
+    # """Stdio transport type."""
+
+    command: str
+    """Path to the MCP server executable."""
+
+    env: Sequence[EnvVariable]
+    """Environment variables to set when launching the MCP server."""
+
+
+McpServer = HttpMcpServer | SseMcpServer | StdioMcpServer

acp/schema/messages.py

@@ -0,0 +1,171 @@
+"""Message schema definitions."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from acp.schema.agent_requests import AgentRequest  # noqa: TC001
+from acp.schema.agent_responses import AgentResponse  # noqa: TC001
+from acp.schema.base import Schema
+from acp.schema.client_requests import ClientRequest  # noqa: TC001
+from acp.schema.client_responses import ClientResponse  # noqa: TC001
+from acp.schema.common import Error  # noqa: TC001
+from acp.schema.notifications import (  # noqa: TC001
+    CancelNotification,
+    SessionNotification,
+)
+
+
+AgentMethod = Literal[
+    "authenticate",
+    "initialize",
+    "session/cancel",
+    "session/load",
+    "session/new",
+    "session/prompt",
+    "session/set_mode",
+    "session/set_model",
+    "session/list",
+    "session/fork",
+    "session/resume",
+]
+
+ClientMethod = Literal[
+    "fs/read_text_file",
+    "fs/write_text_file",
+    "session/request_permission",
+    "session/update",
+    "terminal/create",
+    "terminal/kill",
+    "terminal/output",
+    "terminal/release",
+    "terminal/wait_for_exit",
+]
+
+
+class JsonRPCMessage(Schema):
+    """JSON-RPC 2.0 message."""
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0", init=False)
+    """JSON RPC Messsage."""
+
+
+class ClientNotificationMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    method: ClientMethod | str
+    """Method name."""
+
+    params: CancelNotification | Any | None = None
+    """Agent notification parameters."""
+
+
+class ClientResponseMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    id: int | str | None = None
+    """JSON RPC Request Id."""
+
+    result: ClientResponse | Any
+    """All possible responses that a client can send to an agent.
+
+    This enum is used internally for routing RPC responses. You typically won't need
+    to use this directly - the responses are handled automatically by the connection.
+    These are responses to the corresponding `AgentRequest` variants."""
+
+
+class AgentResponseMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    id: int | str | None = None
+    """JSON RPC Request Id."""
+
+    result: AgentResponse | Any
+    """All possible responses that an agent can send to a client.
+
+    This enum is used internally for routing RPC responses. You typically won't need
+    to use this directly - the responses are handled automatically by the connection.
+    These are responses to the corresponding `ClientRequest` variants."""
+
+
+class ClientRequestMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    id: int | str | None = None
+    """JSON RPC Request Id."""
+
+    method: ClientMethod | str
+    """Method name."""
+
+    params: ClientRequest | Any | None = None
+    """Client request parameters."""
+
+
+class AgentRequestMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    id: int | str | None = None
+    """JSON RPC Request Id."""
+
+    method: AgentMethod | str
+    """Method name."""
+
+    params: AgentRequest | Any | None = None
+    """Agent request parameters."""
+
+
+class AgentNotificationMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    method: AgentMethod | str
+    """Method name."""
+
+    params: SessionNotification | Any | None = None
+    """Agent notification parameters."""
+
+
+class ErrorMessage(JsonRPCMessage):
+    """A message (request, response, or notification) with `"jsonrpc": "2.0"`.
+
+    Specified as
+    [required by JSON-RPC 2.0 Specification][1].
+
+    [1]: https://www.jsonrpc.org/specification#compatibility
+    """
+
+    id: int | str | None = None
+    """JSON RPC Request Id."""
+
+    error: Error

acp/schema/notifications.py

@@ -0,0 +1,82 @@
+"""Notification schema definitions."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from acp.schema.base import AnnotatedObject
+from acp.schema.session_updates import SessionUpdate
+
+
+TSessionUpdate_co = TypeVar(
+    "TSessionUpdate_co",
+    covariant=True,
+    bound=SessionUpdate,
+)
+
+
+class SessionNotification[TSessionUpdate_co: SessionUpdate = SessionUpdate](AnnotatedObject):
+    """Notification containing a session update from the agent.
+
+    Used to stream real-time progress and results during prompt processing.
+
+    See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)
+    """
+
+    session_id: str
+    """The ID of the session this update pertains to."""
+
+    update: TSessionUpdate_co
+    """The session update data."""
+
+
+class CancelNotification(AnnotatedObject):
+    """Notification to cancel ongoing operations for a session.
+
+    This is a notification sent by the client to cancel an ongoing prompt turn.
+
+    Upon receiving this notification, the Agent SHOULD:
+    - Stop all language model requests as soon as possible
+    - Abort all tool call invocations in progress
+    - Send any pending `session/update` notifications
+    - Respond to the original `session/prompt` request with `StopReason::Cancelled`
+
+    See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
+    """
+
+    session_id: str
+    """The ID of the session to cancel operations for."""
+
+
+class ExtNotification(AnnotatedObject):
+    """Extension notification from client or agent.
+
+    Allows sending arbitrary notifications that are not part of the ACP spec.
+    Extension notifications provide a way to send one-way messages for custom
+    functionality while maintaining protocol compatibility.
+
+    The method name should be prefixed with an underscore (e.g., `_myExtension/notify`).
+
+    See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
+    """
+
+    method: str
+    """The extension method name (should be prefixed with underscore)."""
+
+    params: dict[str, Any] | None = None
+    """Optional parameters for the notification."""
+
+
+AgentNotification = SessionNotification | ExtNotification
+"""All possible notifications that an agent can send to a client.
+
+This is used internally for routing RPC notifications.
+Notifications do not expect a response.
+"""
+
+ClientNotification = CancelNotification | ExtNotification
+"""All possible notifications that a client can send to an agent.
+
+This is used internally for routing RPC notifications.
+Notifications do not expect a response.
+"""

acp/schema/protocol_stuff.md

@@ -0,0 +1,3 @@
+Stdio MCP server type discriminator
+ReadTextFileRequest.line should be ge 1, not ge 0?
+AudioContentBlock should have "uri"?

acp/schema/session_state.py

@@ -0,0 +1,160 @@
+"""Session state schema definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from acp.schema.base import AnnotatedObject
+
+
+# Type aliases for config option identifiers
+SessionConfigId = str
+"""Unique identifier for a configuration option."""
+
+SessionConfigValueId = str
+"""Unique identifier for a possible value within a configuration option."""
+
+SessionConfigGroupId = str
+"""Unique identifier for a group of values within a configuration option."""
+
+
+class ModelInfo(AnnotatedObject):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Information about a selectable model.
+    """
+
+    description: str | None = None
+    """Optional description of the model."""
+
+    model_id: str
+    """Unique identifier for the model."""
+
+    name: str
+    """Human-readable name of the model."""
+
+
+class SessionModelState(AnnotatedObject):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    The set of models and the one currently active.
+    """
+
+    available_models: Sequence[ModelInfo]
+    """The set of models that the Agent can use."""
+
+    current_model_id: str
+    """The current model the Agent is using."""
+
+
+class SessionMode(AnnotatedObject):
+    """A mode the agent can operate in.
+
+    See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+    """
+
+    description: str | None = None
+    """Optional description of the mode."""
+
+    id: str
+    """Unique identifier for the mode."""
+
+    name: str
+    """Human-readable name of the mode."""
+
+
+class SessionModeState(AnnotatedObject):
+    """The set of modes and the one currently active."""
+
+    available_modes: Sequence[SessionMode]
+    """The set of modes that the Agent can operate in."""
+
+    current_mode_id: str
+    """The current mode the Agent is in."""
+
+
+class SessionInfo(AnnotatedObject):
+    """**UNSTABLE**: This capability is not part of the spec yet.
+
+    Information about a session returned by session/list.
+    """
+
+    cwd: str
+    """The working directory for this session. Must be an absolute path."""
+
+    session_id: str
+    """Unique identifier for the session."""
+
+    title: str | None = None
+    """Human-readable title for the session."""
+
+    updated_at: str | None = None
+    """ISO 8601 timestamp of last activity."""
+
+
+class SessionConfigSelectOption(AnnotatedObject):
+    """A possible value for a configuration selector."""
+
+    id: SessionConfigValueId
+    """Unique identifier for this value."""
+
+    label: str
+    """Human-readable label for this value."""
+
+    description: str | None = None
+    """Optional description explaining this value."""
+
+
+class SessionConfigSelectGroup(AnnotatedObject):
+    """A group of possible values for a configuration selector."""
+
+    id: SessionConfigGroupId
+    """Unique identifier for this group."""
+
+    label: str
+    """Human-readable label for this group."""
+
+    options: Sequence[SessionConfigSelectOption]
+    """The options within this group."""
+
+
+SessionConfigSelectOptions = Sequence[SessionConfigSelectOption | SessionConfigSelectGroup]
+"""The possible values for a configuration selector, optionally organized into groups."""
+
+
+class SessionConfigSelect(AnnotatedObject):
+    """A configuration option that allows selecting a single value from a list.
+
+    Similar to a dropdown/select UI element.
+    """
+
+    type: Literal["select"] = Field(default="select", init=False)
+    """Discriminator for the config option type."""
+
+    id: SessionConfigId
+    """Unique identifier for this configuration option."""
+
+    label: str
+    """Human-readable label for this option."""
+
+    description: str | None = None
+    """Optional description explaining this option."""
+
+    options: SessionConfigSelectOptions
+    """The possible values for this option."""
+
+    value: SessionConfigValueId
+    """The currently selected value ID."""
+
+
+SessionConfigOption = Annotated[
+    SessionConfigSelect,
+    Field(discriminator="type"),
+]
+"""A session configuration option.
+
+Currently only supports select-type options, but designed for extensibility.
+"""