batrachian-toad 0.5.22__py3-none-any.whl

toad/acp/api.py

@@ -0,0 +1,47 @@
+# mypy: disable-error-code="empty-body"
+"""
+ACP remote API
+"""
+
+from toad import jsonrpc
+from toad.acp import protocol
+
+API = jsonrpc.API()
+
+
+@API.method()
+def initialize(
+    protocolVersion: int,
+    clientCapabilities: protocol.ClientCapabilities,
+    clientInfo: protocol.Implementation,
+) -> protocol.InitializeResponse:
+    """https://agentclientprotocol.com/protocol/initialization"""
+    ...
+
+
+@API.method(name="session/new")
+def session_new(
+    cwd: str, mcpServers: list[protocol.McpServer]
+) -> protocol.NewSessionResponse:
+    """https://agentclientprotocol.com/protocol/session-setup#session-id"""
+    ...
+
+
+@API.notification(name="session/cancel")
+def session_cancel(sessionId: str, _meta: dict):
+    """https://agentclientprotocol.com/protocol/prompt-turn#cancellation"""
+    ...
+
+
+@API.method(name="session/prompt")
+def session_prompt(
+    prompt: list[protocol.ContentBlock], sessionId: str
+) -> protocol.SessionPromptResponse:
+    """https://agentclientprotocol.com/protocol/prompt-turn#1-user-message"""
+    ...
+
+
+@API.method(name="session/set_mode")
+def session_set_mode(sessionId: str, modeId: str) -> protocol.SetSessionModeResponse:
+    """https://agentclientprotocol.com/protocol/session-modes#from-the-client"""
+    ...

toad/acp/encode_tool_call_id.py

@@ -0,0 +1,12 @@
+def encode_tool_call_id(tool_call_id: str) -> str:
+    """Encode the tool call id so that it fits within a TCSS id.
+
+    Args:
+        tool_call_id: Raw tool call id.
+
+    Returns:
+        Tool call usable as widget id.
+    """
+    hex_tool_call_id = "".join(f"{ord(character):2X}" for character in tool_call_id)
+    encoded_tool_call_id = f"tool-call-{hex_tool_call_id}"
+    return encoded_tool_call_id

toad/acp/messages.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from asyncio import Future
+from typing import Any, Mapping, TYPE_CHECKING
+from textual.message import Message
+
+import rich.repr
+
+from toad.answer import Answer
+from toad.acp import protocol
+from toad.acp.encode_tool_call_id import encode_tool_call_id
+from toad.acp.agent import Mode
+
+if TYPE_CHECKING:
+    from toad.widgets.terminal_tool import ToolState
+
+
+class AgentMessage(Message):
+    pass
+
+
+@dataclass
+class Thinking(AgentMessage):
+    type: str
+    text: str
+
+
+@dataclass
+class UpdateStatusLine(AgentMessage):
+    status_line: str
+
+
+@dataclass
+class Update(AgentMessage):
+    type: str
+    text: str
+
+
+@dataclass
+@rich.repr.auto
+class RequestPermission(AgentMessage):
+    options: list[protocol.PermissionOption]
+    tool_call: protocol.ToolCallUpdatePermissionRequest
+    result_future: Future[Answer]
+
+
+@dataclass
+class Plan(AgentMessage):
+    entries: list[protocol.PlanEntry]
+
+
+@dataclass
+class ToolCall(AgentMessage):
+    tool_call: protocol.ToolCall
+
+    @property
+    def tool_id(self) -> str:
+        """An id suitable for use as a TCSS ID."""
+        return encode_tool_call_id(self.tool_call["toolCallId"])
+
+
+@dataclass
+class ToolCallUpdate(AgentMessage):
+    tool_call: protocol.ToolCall
+    update: protocol.ToolCallUpdate
+
+    @property
+    def tool_id(self) -> str:
+        """An id suitable for use as a TCSS ID."""
+        return encode_tool_call_id(self.tool_call["toolCallId"])
+
+
+@dataclass
+class AvailableCommandsUpdate(AgentMessage):
+    """The agent is reporting its slash commands."""
+
+    commands: list[protocol.AvailableCommand]
+
+
+@dataclass
+class CreateTerminal(AgentMessage):
+    """Request a terminal in the conversation."""
+
+    terminal_id: str
+    command: str
+    result_future: Future[bool]
+    args: list[str] | None = None
+    cwd: str | None = None
+    env: Mapping[str, str] | None = None
+    output_byte_limit: int | None = None
+
+
+@dataclass
+class KillTerminal(AgentMessage):
+    """Kill a terminal process."""
+
+    terminal_id: str
+
+
+@dataclass
+class GetTerminalState(AgentMessage):
+    """Get the state of the terminal."""
+
+    terminal_id: str
+    result_future: Future[ToolState]
+
+
+@dataclass
+class ReleaseTerminal(AgentMessage):
+    """Release the terminal."""
+
+    terminal_id: str
+
+
+@dataclass
+class WaitForTerminalExit(AgentMessage):
+    """Wait for the terminal to exit."""
+
+    terminal_id: str
+    result_future: Future[tuple[int, str | None]]
+
+
+@rich.repr.auto
+@dataclass
+class SetModes(AgentMessage):
+    """Set modes from agent."""
+
+    current_mode: str
+    modes: dict[str, Mode]
+
+
+@dataclass
+class ModeUpdate(AgentMessage):
+    """Agent informed us about a mode change."""
+
+    current_mode: str

toad/acp/prompt.py

@@ -0,0 +1,54 @@
+import base64
+from pathlib import Path
+
+from toad.acp import protocol
+from toad.prompt.extract import extract_paths_from_prompt
+from toad.prompt.resource import load_resource, ResourceError
+
+
+def build(project_path: Path, prompt: str) -> list[protocol.ContentBlock]:
+    """Build the prompt structure and extract paths with the @ syntax.
+
+    Args:
+        project_path: The project root.
+        prompt: The prompt text.
+
+    Returns:
+        A list of content blocks.
+    """
+    prompt_content: list[protocol.ContentBlock] = []
+
+    prompt_content.append({"type": "text", "text": prompt})
+    for path, _, _ in extract_paths_from_prompt(prompt):
+        if path.endswith("/"):
+            continue
+        try:
+            resource = load_resource(project_path, Path(path))
+        except ResourceError:
+            # TODO: How should this be handled?
+            continue
+        uri = f"file://{resource.path.absolute().resolve()}"
+        if resource.text is not None:
+            prompt_content.append(
+                {
+                    "type": "resource",
+                    "resource": {
+                        "uri": uri,
+                        "text": resource.text,
+                        "mimeType": resource.mime_type,
+                    },
+                }
+            )
+        elif resource.data is not None:
+            prompt_content.append(
+                {
+                    "type": "resource",
+                    "resource": {
+                        "uri": uri,
+                        "blob": base64.b64encode(resource.data).decode("utf-8"),
+                        "mimeType": resource.mime_type,
+                    },
+                }
+            )
+
+    return prompt_content

toad/acp/protocol.py

@@ -0,0 +1,426 @@
+from typing import TypedDict, Required, Literal
+
+
+class SchemaDict(TypedDict, total=False):
+    pass
+
+
+# ---------------------------------------------------------------------------------------
+# Types
+
+
+class FileSystemCapability(SchemaDict, total=False):
+    readTextFile: bool
+    writeTextFile: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#clientcapabilities
+class ClientCapabilities(SchemaDict, total=False):
+    fs: FileSystemCapability
+    terminal: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#implementation
+class Implementation(SchemaDict, total=False):
+    name: Required[str]
+    title: str | None
+    version: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#promptcapabilities
+class PromptCapabilities(SchemaDict, total=False):
+    audio: bool
+    embeddedContent: bool
+    image: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#agentcapabilities
+class AgentCapabilities(SchemaDict, total=False):
+    loadSession: bool
+    promptCapabilities: PromptCapabilities
+
+
+class AuthMethod(SchemaDict, total=False):
+    description: str | None
+    id: Required[str]
+    name: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#envvariable
+class EnvVariable(SchemaDict, total=False):
+    _meta: dict
+    name: Required[str]
+    value: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#terminalexitstatus
+class TerminalExitStatus(SchemaDict, total=False):
+    _meta: dict
+    exitCode: int | None
+    signal: str | None
+
+
+# https://agentclientprotocol.com/protocol/schema#mcpserver
+class McpServer(SchemaDict, total=False):
+    args: list[str]
+    command: str
+    env: list[EnvVariable]
+    name: str
+
+
+# https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations
+class Annotations(SchemaDict, total=False):
+    audience: list[str]
+    priority: float
+    lastModified: str
+
+
+class TextContent(SchemaDict, total=False):
+    type: Required[str]
+    text: Required[str]
+    annotations: Annotations
+
+
+class ImageContent(SchemaDict, total=False):
+    type: Required[str]
+    data: Required[str]
+    mimeType: Required[str]
+    url: str
+    annotations: Annotations
+
+
+class AudioContent(SchemaDict, total=False):
+    type: Required[str]
+    data: Required[str]
+    mimeType: Required[str]
+    Annotations: Annotations
+
+
+class EmbeddedResourceText(SchemaDict, total=False):
+    uri: Required[str]
+    text: Required[str]
+    mimeType: str
+
+
+class EmbeddedResourceBlob(SchemaDict, total=False):
+    uri: Required[str]
+    blob: Required[str]
+    mimeType: str
+
+
+# https://agentclientprotocol.com/protocol/content#embedded-resource
+class EmbeddedResourceContent(SchemaDict, total=False):
+    type: Required[str]
+    resource: EmbeddedResourceText | EmbeddedResourceBlob
+
+
+class ResourceLinkContent(SchemaDict, total=False):
+    annotations: Annotations | None
+    description: str | None
+    mimeType: str | None
+    name: Required[str]
+    size: int | None
+    title: str | None
+    type: Required[str]
+    uri: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#contentblock
+type ContentBlock = (
+    TextContent
+    | ImageContent
+    | AudioContent
+    | EmbeddedResourceContent
+    | ResourceLinkContent
+)
+
+
+# https://agentclientprotocol.com/protocol/schema#param-user-message-chunk
+class UserMessageChunk(SchemaDict, total=False):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["user_message_chunk"]]
+
+
+class AgentMessageChunk(SchemaDict, total=False):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["agent_message_chunk"]]
+
+
+class AgentThoughtChunk(SchemaDict, total=False):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["agent_thought_chunk"]]
+
+
+class ToolCallContentContent(SchemaDict, total=False):
+    content: Required[ContentBlock]
+    type: Required[Literal["content"]]
+
+
+# https://agentclientprotocol.com/protocol/schema#param-diff
+class ToolCallContentDiff(SchemaDict, total=False):
+    newText: Required[str]
+    oldText: str | None
+    path: Required[str]
+    type: Required[Literal["diff"]]
+
+
+class ToolCallContentTerminal(SchemaDict, total=False):
+    terminalId: Required[str]
+    type: Required[Literal["terminal"]]
+
+
+# https://agentclientprotocol.com/protocol/schema#toolcallcontent
+type ToolCallContent = (
+    ToolCallContentContent | ToolCallContentDiff | ToolCallContentTerminal
+)
+
+# https://agentclientprotocol.com/protocol/schema#toolkind
+type ToolKind = Literal[
+    "read",
+    "edit",
+    "delete",
+    "move",
+    "search",
+    "execute",
+    "think",
+    "fetch",
+    "switch_mode",
+    "other",
+]
+
+type ToolCallStatus = Literal["pending", "in_progress", "completed", "failed"]
+
+
+class ToolCallLocation(SchemaDict, total=False):
+    line: int | None
+    path: Required[str]
+
+
+type ToolCallId = str
+
+
+# https://agentclientprotocol.com/protocol/schema#toolcall
+class ToolCall(SchemaDict, total=False):
+    _meta: dict
+    content: list[ToolCallContent]
+    kind: ToolKind
+    locations: list[ToolCallLocation]
+    rawInput: dict
+    rawOutput: dict
+    sessionUpdate: Required[Literal["tool_call"]]
+    status: ToolCallStatus
+    title: Required[str]
+    toolCallId: Required[ToolCallId]
+
+
+# https://agentclientprotocol.com/protocol/schema#toolcallupdate
+class ToolCallUpdate(SchemaDict, total=False):
+    _meta: dict
+    content: list[ToolCallContent] | None
+    kind: ToolKind | None
+    locations: list | None
+    rawInput: dict
+    rawOutput: dict
+    sessionUpdate: Required[Literal["tool_call_update"]]
+    status: ToolCallStatus | None
+    title: str | None
+    toolCallId: Required[ToolCallId]
+
+
+# https://agentclientprotocol.com/protocol/schema#param-tool-call
+# Use in the session/request_permission call (not the same as ToolCallUpdate)
+class ToolCallUpdatePermissionRequest(SchemaDict, total=False):
+    _meta: dict
+    content: list[ToolCallContent] | None
+    kind: ToolKind | None
+    locations: list | None
+    rawInput: dict
+    rawOutput: dict
+    status: ToolCallStatus | None
+    title: str | None
+    toolCallId: Required[ToolCallId]
+
+
+class PlanEntry(SchemaDict, total=False):
+    content: Required[str]
+    priority: Literal["high", "medium", "low"]
+    status: Literal["pending", "in_progress", "completed"]
+
+
+type SessionModeId = str
+
+
+# https://agentclientprotocol.com/protocol/schema#sessionmode
+class SessionMode(SchemaDict, total=False):
+    _meta: dict
+    description: str | None
+    id: Required[SessionModeId]
+    name: Required[str]
+
+
+class SessionModeState(SchemaDict, total=False):
+    _meta: dict
+    availableModes: Required[list[SessionMode]]
+    currentModeId: Required[SessionModeId]
+
+
+type ModelId = str
+
+
+# https://agentclientprotocol.com/protocol/schema#modelinfo
+class ModelInfo(SchemaDict, total=False):
+    _meta: dict
+    description: str | None
+    modelId: Required[ModelId]
+    name: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#sessionmodelstate
+class SessionModelState(SchemaDict, total=False):
+    _meta: dict
+    availableModels: Required[list[ModelInfo]]
+    currentModelId: Required[ModelId]
+
+
+# https://agentclientprotocol.com/protocol/schema#param-plan
+class Plan(SchemaDict, total=False):
+    entries: Required[list[PlanEntry]]
+    sessionUpdate: Required[Literal["plan"]]
+
+
+class AvailableCommandInput(SchemaDict, total=False):
+    hint: Required[str]
+
+
+class AvailableCommand(SchemaDict, total=False):
+    description: Required[str]
+    input: AvailableCommandInput | None
+    name: Required[str]
+
+
+class AvailableCommandsUpdate(SchemaDict, total=False):
+    availableCommands: Required[list[AvailableCommand]]
+    sessionUpdate: Required[Literal["available_commands_update"]]
+
+
+class CurrentModeUpdate(SchemaDict, total=False):
+    currentModeId: Required[str]
+    sessionUpdate: Required[Literal["current_mode_update"]]
+
+
+type SessionUpdate = (
+    UserMessageChunk
+    | AgentMessageChunk
+    | AgentThoughtChunk
+    | ToolCall
+    | ToolCallUpdate
+    | Plan
+    | AvailableCommandsUpdate
+    | CurrentModeUpdate
+)
+
+
+class SessionNotification(TypedDict, total=False):
+    sessionId: str
+    update: SessionUpdate
+
+
+type PermissionOptionKind = Literal[
+    "allow_once", "allow_always", "reject_once", "reject_always"
+]
+type PermissionOptionId = str
+
+
+class PermissionOption(TypedDict, total=False):
+    _meta: dict
+    kind: Required[PermissionOptionKind]
+    name: Required[str]
+    optionId: Required[PermissionOptionId]
+
+
+class OutcomeCancelled(TypedDict, total=False):
+    outcome: Literal["cancelled"]
+
+
+class OutcomeSelected(TypedDict, total=False):
+    optionId: Required[PermissionOptionId]
+    outcome: Literal["selected"]
+
+
+# https://agentclientprotocol.com/protocol/schema#requestpermissionoutcome
+type RequestPermissionOutcome = OutcomeSelected | OutcomeCancelled
+
+# ---------------------------------------------------------------------------------------
+# RPC responses
+
+
+class InitializeResponse(SchemaDict, total=False):
+    agentCapabilities: AgentCapabilities
+    authMethods: list[AuthMethod]
+    protocolVersion: Required[int]
+
+
+# https://agentclientprotocol.com/protocol/schema#newsessionresponse
+class NewSessionResponse(SchemaDict, total=False):
+    _meta: object
+    sessionId: Required[str]
+    # Unstable from here
+    models: SessionModelState | None
+    modes: SessionModeState | None
+
+
+class SessionPromptResponse(SchemaDict, total=False):
+    stopReason: Required[
+        Literal[
+            "end_turn",
+            "max_tokens",
+            "max_turn_requests",
+            "refusal",
+            "cancelled",
+        ]
+    ]
+
+
+# https://agentclientprotocol.com/protocol/schema#requestpermissionresponse
+class RequestPermissionResponse(TypedDict, total=False):
+    _meta: dict
+    outcome: Required[RequestPermissionOutcome]
+
+
+# https://agentclientprotocol.com/protocol/schema#createterminalresponse
+class CreateTerminalResponse(TypedDict, total=False):
+    _meta: dict
+    terminalId: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#killterminalcommandresponse
+class KillTerminalCommandResponse(TypedDict, total=False):
+    _meta: dict
+
+
+# https://agentclientprotocol.com/protocol/schema#terminaloutputresponse
+class TerminalOutputResponse(TypedDict, total=False):
+    _meta: dict
+    exitStatus: TerminalExitStatus | None
+    output: Required[str]
+    truncated: Required[bool]
+
+
+# https://agentclientprotocol.com/protocol/schema#releaseterminalresponse
+class ReleaseTerminalResponse(TypedDict, total=False):
+    _meta: dict
+
+
+# https://agentclientprotocol.com/protocol/schema#waitforterminalexitresponse
+class WaitForTerminalExitResponse(TypedDict, total=False):
+    _meta: dict
+    exitCode: int | None
+    signal: str | None
+
+
+# https://agentclientprotocol.com/protocol/schema#setsessionmoderesponse
+class SetSessionModeResponse(TypedDict, total=False):
+    meta: dict
+
+
+# ---------------------------------------------------------------------------------------