@scemoon/cdh 1.0.0

package/tui/acp/protocol.py

@@ -0,0 +1,462 @@
+from typing_extensions import Any, TypedDict, Required, Literal
+
+
+class SchemaDict(TypedDict, total=False, extra_items=Any):
+    pass
+
+
+# ---------------------------------------------------------------------------------------
+# Types
+
+
+# https://agentclientprotocol.com/rfds/session-usage#context-window-and-cost-via-session/update
+class Cost(TypedDict, total=False, extra_items=Any):
+    amount: float
+    currency: str
+
+
+class FileSystemCapability(SchemaDict, total=False, extra_items=Any):
+    readTextFile: bool
+    writeTextFile: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#clientcapabilities
+class ClientCapabilities(SchemaDict, total=False, extra_items=Any):
+    fs: FileSystemCapability
+    terminal: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#implementation
+class Implementation(SchemaDict, total=False, extra_items=Any):
+    name: Required[str]
+    title: str | None
+    version: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#promptcapabilities
+class PromptCapabilities(SchemaDict, total=False, extra_items=Any):
+    audio: bool
+    embeddedContent: bool
+    image: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#agentcapabilities
+class AgentCapabilities(SchemaDict, total=False, extra_items=Any):
+    loadSession: bool
+    promptCapabilities: PromptCapabilities
+
+
+class AuthMethod(SchemaDict, total=False, extra_items=Any):
+    description: str | None
+    id: Required[str]
+    name: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#envvariable
+class EnvVariable(SchemaDict, total=False, extra_items=Any):
+    _meta: dict
+    name: Required[str]
+    value: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#terminalexitstatus
+class TerminalExitStatus(SchemaDict, total=False, extra_items=Any):
+    _meta: dict
+    exitCode: int | None
+    signal: str | None
+
+
+# https://agentclientprotocol.com/protocol/schema#mcpserver
+class McpServer(SchemaDict, total=False, extra_items=Any):
+    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, extra_items=Any):
+    audience: list[str]
+    priority: float
+    lastModified: str
+
+
+class TextContent(SchemaDict, total=False, extra_items=Any):
+    type: Required[str]
+    text: Required[str]
+    annotations: Annotations
+
+
+class ImageContent(SchemaDict, total=False, extra_items=Any):
+    type: Required[str]
+    data: Required[str]
+    mimeType: Required[str]
+    url: str
+    annotations: Annotations
+
+
+class AudioContent(SchemaDict, total=False, extra_items=Any):
+    type: Required[str]
+    data: Required[str]
+    mimeType: Required[str]
+    Annotations: Annotations
+
+
+class EmbeddedResourceText(SchemaDict, total=False, extra_items=Any):
+    uri: Required[str]
+    text: Required[str]
+    mimeType: str
+
+
+class EmbeddedResourceBlob(SchemaDict, total=False, extra_items=Any):
+    uri: Required[str]
+    blob: Required[str]
+    mimeType: str
+
+
+# https://agentclientprotocol.com/protocol/content#embedded-resource
+class EmbeddedResourceContent(SchemaDict, total=False, extra_items=Any):
+    type: Required[str]
+    resource: EmbeddedResourceText | EmbeddedResourceBlob
+
+
+class ResourceLinkContent(SchemaDict, total=False, extra_items=Any):
+    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, extra_items=Any):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["user_message_chunk"]]
+
+
+class AgentMessageChunk(SchemaDict, total=False, extra_items=Any):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["agent_message_chunk"]]
+
+
+class AgentThoughtChunk(SchemaDict, total=False, extra_items=Any):
+    content: Required[ContentBlock]
+    sessionUpdate: Required[Literal["agent_thought_chunk"]]
+
+
+class ToolCallContentContent(SchemaDict, total=False, extra_items=Any):
+    content: Required[ContentBlock]
+    type: Required[Literal["content"]]
+
+
+# https://agentclientprotocol.com/protocol/schema#param-diff
+class ToolCallContentDiff(SchemaDict, total=False, extra_items=Any):
+    newText: Required[str]
+    oldText: str | None
+    path: Required[str]
+    type: Required[Literal["diff"]]
+
+
+class ToolCallContentTerminal(SchemaDict, total=False, extra_items=Any):
+    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, extra_items=Any):
+    line: int | None
+    path: Required[str]
+
+
+type ToolCallId = str
+
+
+# https://agentclientprotocol.com/protocol/schema#toolcall
+class ToolCall(SchemaDict, total=False, extra_items=Any):
+    _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, extra_items=Any):
+    _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, extra_items=Any):
+    _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, extra_items=Any):
+    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, extra_items=Any):
+    _meta: dict
+    description: str | None
+    id: Required[SessionModeId]
+    name: Required[str]
+
+
+class SessionModeState(SchemaDict, total=False, extra_items=Any):
+    _meta: dict
+    availableModes: Required[list[SessionMode]]
+    currentModeId: Required[SessionModeId]
+
+
+type ModelId = str
+
+
+# https://agentclientprotocol.com/protocol/schema#modelinfo
+class ModelInfo(SchemaDict, total=False, extra_items=Any):
+    _meta: dict
+    description: str | None
+    modelId: Required[ModelId]
+    name: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#sessionmodelstate
+class SessionModelState(SchemaDict, total=False, extra_items=Any):
+    _meta: dict
+    availableModels: Required[list[ModelInfo]]
+    currentModelId: Required[ModelId]
+
+
+# https://agentclientprotocol.com/protocol/schema#param-plan
+class Plan(SchemaDict, total=False, extra_items=Any):
+    entries: Required[list[PlanEntry]]
+    sessionUpdate: Required[Literal["plan"]]
+
+
+class AvailableCommandInput(SchemaDict, total=False, extra_items=Any):
+    hint: Required[str]
+
+
+class AvailableCommand(SchemaDict, total=False, extra_items=Any):
+    description: Required[str]
+    input: AvailableCommandInput | None
+    name: Required[str]
+
+
+class AvailableCommandsUpdate(SchemaDict, total=False, extra_items=Any):
+    availableCommands: Required[list[AvailableCommand]]
+    sessionUpdate: Required[Literal["available_commands_update"]]
+
+
+class CurrentModeUpdate(SchemaDict, total=False, extra_items=Any):
+    currentModeId: Required[str]
+    sessionUpdate: Required[Literal["current_mode_update"]]
+
+
+class UsageUpdate(SchemaDict, total=False, extra_items=object):
+    sessionUpdate: Required[Literal["usage_update"]]
+    used: Required[int]
+    size: Required[int]
+    cost: Cost
+
+
+type SessionUpdate = (
+    UserMessageChunk
+    | AgentMessageChunk
+    | AgentThoughtChunk
+    | ToolCall
+    | ToolCallUpdate
+    | Plan
+    | AvailableCommandsUpdate
+    | CurrentModeUpdate
+    | UsageUpdate
+)
+
+
+class SessionNotification(TypedDict, total=False, extra_items=Any):
+    sessionId: str
+    update: SessionUpdate
+
+
+type PermissionOptionKind = Literal[
+    "allow_once", "allow_always", "reject_once", "reject_always"
+]
+type PermissionOptionId = str
+
+
+class PermissionOption(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+    kind: Required[PermissionOptionKind]
+    name: Required[str]
+    optionId: Required[PermissionOptionId]
+
+
+class OutcomeCancelled(TypedDict, total=False, extra_items=Any):
+    outcome: Literal["cancelled"]
+
+
+class OutcomeSelected(TypedDict, total=False, extra_items=Any):
+    optionId: Required[PermissionOptionId]
+    outcome: Literal["selected"]
+
+
+# https://agentclientprotocol.com/protocol/schema#requestpermissionoutcome
+type RequestPermissionOutcome = OutcomeSelected | OutcomeCancelled
+
+# ---------------------------------------------------------------------------------------
+# RPC responses
+
+
+class InitializeResponse(SchemaDict, total=False, extra_items=Any):
+    agentCapabilities: AgentCapabilities
+    authMethods: list[AuthMethod]
+    protocolVersion: Required[int]
+
+
+# https://agentclientprotocol.com/protocol/schema#newsessionresponse
+class NewSessionResponse(SchemaDict, total=False, extra_items=Any):
+    _meta: object
+    sessionId: Required[str]
+    # Unstable from here
+    models: SessionModelState | None
+    modes: SessionModeState | None
+
+
+# https://agentclientprotocol.com/protocol/schema#loadsessionresponse
+class LoadSessionResponse(SchemaDict, total=False, extra_items=Any):
+    _meta: object
+    modes: SessionModeState | None
+
+
+class SessionPromptResponse(SchemaDict, total=False, extra_items=object):
+    sessionId: Required[str]
+    stopReason: Required[
+        Literal[
+            "end_turn",
+            "max_tokens",
+            "max_turn_requests",
+            "refusal",
+            "cancelled",
+        ]
+    ]
+    usage: Usage
+
+
+# https://agentclientprotocol.com/protocol/schema#requestpermissionresponse
+class RequestPermissionResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+    outcome: Required[RequestPermissionOutcome]
+
+class AskUserResponse(TypedDict, total=False, extra_items=Any):
+    answer: str
+    cancelled: bool
+
+
+# https://agentclientprotocol.com/protocol/schema#createterminalresponse
+class CreateTerminalResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+    terminalId: Required[str]
+
+
+# https://agentclientprotocol.com/protocol/schema#killterminalcommandresponse
+class KillTerminalCommandResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+
+
+# https://agentclientprotocol.com/protocol/schema#terminaloutputresponse
+class TerminalOutputResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+    exitStatus: TerminalExitStatus | None
+    output: Required[str]
+    truncated: Required[bool]
+
+
+# https://agentclientprotocol.com/protocol/schema#releaseterminalresponse
+class ReleaseTerminalResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+
+
+# https://agentclientprotocol.com/protocol/schema#waitforterminalexitresponse
+class WaitForTerminalExitResponse(TypedDict, total=False, extra_items=Any):
+    _meta: dict
+    exitCode: int | None
+    signal: str | None
+
+
+# https://agentclientprotocol.com/protocol/schema#setsessionmoderesponse
+class SetSessionModeResponse(TypedDict, total=False, extra_items=Any):
+    meta: dict
+
+
+# ---------------------------------------------------------------------------------------
+
+
+# https://agentclientprotocol.com/rfds/session-usage#usage-fields
+class Usage(TypedDict, total=False, extra_items=Any):
+    total_tokens: Required[int]
+    input_tokens: Required[int]
+    output_tokens: Required[int]
+    thought_tokens: int
+    cached_read_tokens: int
+    cached_write_tokens: int

package/tui/agent.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+from textual.content import Content
+from textual.message import Message
+
+
+class AgentReady(Message):
+    """Agent is ready."""
+
+
+@dataclass
+class AgentFail(Message):
+    """Agent failed to start."""
+
+    message: str
+    details: str = ""
+    help: str = "fail"
+
+
+class AgentBase(ABC):
+    """Base class for an 'agent'."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root_path = project_root
+        super().__init__()
+
+    @abstractmethod
+    async def send_prompt(self, prompt: str) -> str | None:
+        """Send a prompt to the agent.
+
+        Args:
+            prompt: Prompt text.
+
+        Returns:
+            str: The stop reason.
+        """
+
+    async def set_mode(self, mode_id: str) -> str | None:
+        """Put the agent in a new mode.
+
+        Args:
+            mode_id: Mode id.
+
+        Returns:
+            str: The stop reason.
+        """
+
+    async def cancel(self) -> bool:
+        """Cancel prompt.
+
+        Returns:
+            bool: `True` if success, `False` if the turn wasn't cancelled.
+
+        """
+        return False
+
+    async def set_session_name(self, name: str) -> None:
+        """Set the session name.
+
+        Args:
+            name: New name for the session.
+        """
+
+    def get_info(self) -> Content:
+        return Content("")
+
+    async def stop(self) -> None:
+        """Stop the agent (gracefully exit the process)"""

package/tui/agent_schema.py

@@ -0,0 +1,76 @@
+from typing import TypedDict, Literal, NotRequired
+
+type Tag = str
+"""A tag used for categorizing the agent. For example: 'open-source', 'reasoning'."""
+type OS = Literal["macos", "linux", "windows", "*"]
+"""An operating system identifier, or a '*" wildcard, if it is the same for all OSes."""
+type Action = str
+"""An action which the agent supports."""
+type AgentType = Literal["coding", "chat"]
+"""The type of agent. More types TBD."""
+type AgentProtocol = Literal["acp"]
+"""The protocol used to communicate with the agent. Currently only "acp" is supported."""
+
+
+class Command(TypedDict):
+    """Used to perform an action associate with an Agent."""
+
+    description: str
+    """Describes what the script will do. For example: 'Install Claude Code'."""
+    command: str
+    """Command to run."""
+    bootstrap_uv: NotRequired[bool]
+    """Bootstrap UV installer (set to `true` if the command users `uv`)."""
+
+
+class Agent(TypedDict):
+    """Describes an agent which A2TUI can connect to. Currently only Agent Client Protocol is supported.
+
+    This information is stoed within TOML files, where the filename is the "identity" key plus the extension ".toml"
+
+    """
+
+    active: NotRequired[bool]
+    """If `True` (default), the agent will be shown in the UI. If `False` the agent will be removed from the UI."""
+    recommended: NotRequired[bool]
+    """Agent is in recommended set. Set to `True` in main branch only if previously agreed with Will McGugan."""
+    identity: str
+    """A unique identifier for this agent. Should be a domain the agent developer owns,
+    although it doesn't have to resolve to anything. Must be useable in a filename on all platforms. 
+    For example: 'claude.anthropic.ai'"""
+    name: str
+    """The name of the agent. For example: 'Claude Code'."""
+    short_name: str
+    """A short name, usable on the command line. Try to make it unique. For example: 'claude'."""
+    url: str
+    """A URL for the agent."""
+    protocol: AgentProtocol
+    """The protocol used by the agent. Currently only 'acp' is supported."""
+    type: "AgentType"
+    """The type of the agent. Currently "coding" or "chat". More types TBD."""
+    author_name: str
+    """The author of the agent. For example 'Anthropic'."""
+    author_url: str
+    """The authors homepage. For example 'https://www.anthropic.com/'."""
+    publisher_name: str
+    """The publisher's name (individual or organization that wrote this data)."""
+    publisher_url: str
+    """The publisher's url."""
+    description: str
+    """A description of the agent. A few sentences max. May contain content markup (https://textual.textualize.io/guide/content/#markup) if used subtly."""
+    tags: list[Tag]
+    """Tags which identify the agent. Should be empty for now."""
+    help: str
+    """A Markdown document with additional details regarding the agent."""
+    welcome: NotRequired[str]
+    """A Markdown document shown to the user when the conversation starts. Should contain a welcome message and any advice on getting started."""
+    run_command: dict[OS, str]
+    """Command to run the agent, by OS or wildcard."""
+    commands_prefix: NotRequired[str]
+    """Prefix for slash commands registered by this agent (e.g. `"onecode:"`)."""
+    commands_module: NotRequired[str]
+    """Python module path to a commands module with a `register_commands()` function.
+    If set, the TUI will import this module and call `register_commands()` to register
+    platform-specific slash commands (e.g. `onecode:mode`, `onecode:spec`)."""
+    actions: dict[OS, dict[Action, Command]]
+    """Scripts to perform actions, typically at least to install the agent."""

package/tui/agents.py

@@ -0,0 +1,45 @@
+from importlib.resources import files
+import asyncio
+
+from tui.agent_schema import Agent
+
+
+class AgentReadError(Exception):
+    """Problem reading the agents."""
+
+
+async def read_agents() -> dict[str, Agent]:
+    """Read agent information from data/agents
+
+    Raises:
+        AgentReadError: If the files could not be read.
+
+    Returns:
+        A mapping of identity on to Agent dict.
+    """
+    import tomllib
+
+    def read_agents() -> list[Agent]:
+        """Read agent information.
+
+        Stored in data/agents
+
+        Returns:
+            List of agent dicts.
+        """
+        agents: list[Agent] = []
+        try:
+            for file in files("tui.data").joinpath("agents").iterdir():
+                agent: Agent = tomllib.load(file.open("rb"))
+                if agent.get("active", True):
+                    agents.append(agent)
+
+        except Exception as error:
+            raise AgentReadError(f"Failed to read agents; {error}")
+
+        return agents
+
+    agents = await asyncio.to_thread(read_agents)
+    agent_map = {agent["identity"]: agent for agent in agents}
+
+    return agent_map

package/tui/ansi/__init__.py

@@ -0,0 +1 @@
+from tui.ansi._ansi import TerminalState as TerminalState