@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/tui/acp/protocol.py

@@ -0,0 +1,551 @@
+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]
+    # Custom (non-ACP) field: when set, this tool call was invoked *inside* a
+    # subagent and the TUI should mount/update the ToolCall card inside the
+    # owning SubAgent widget (subagentId = the parent Spawn toolCallId) rather
+    # than in the main conversation.
+    subagentId: str
+
+
+# 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]
+    subagentId: str
+
+
+# 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 AIDLCState(SchemaDict, total=False, extra_items=Any):
+    current_phase: Required[str]
+    completed_phases: Required[list[str]]
+    gate_results: Required[dict]
+    sessionUpdate: Required[Literal["aidlc_state"]]
+
+
+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 AwaitingUserInputUpdate(SchemaDict, total=False, extra_items=Any):
+    """The agent is waiting for user input but did not invoke AskUser.
+
+    Used when the agent asks a question via plain text output. The TUI
+    switches turn to "client" so the next user_input_submitted is treated
+    as a reply, not queued as a fresh prompt.
+    """
+    sessionUpdate: Required[Literal["awaiting_user_input"]]
+    promptPreview: str
+
+
+class AskUserUpdate(SchemaDict, total=False, extra_items=Any):
+    """The agent is asking the user a question (AskUser tool or auto-detected).
+
+    The server sends either ``question`` (single question, optional
+    ``options``) or ``questions`` (multi-question form). Missing members
+    are tolerated so every payload shape validates.
+    """
+    sessionUpdate: Required[Literal["ask_user"]]
+    question: str
+    context: str
+    options: list
+    questions: list
+    toolId: str
+
+
+class AskUserRemindUpdate(SchemaDict, total=False, extra_items=Any):
+    """Brief reminder that an AskUser prompt is still waiting for an answer."""
+    sessionUpdate: Required[Literal["ask_user_remind"]]
+    text: str
+    toolId: str
+
+
+class AskUserDefaultUsedUpdate(SchemaDict, total=False, extra_items=Any):
+    """Notify the TUI that the AskUser prompt timed out and a default was used."""
+    sessionUpdate: Required[Literal["ask_user_default_used"]]
+    answer: str
+    toolId: str
+
+
+class UsageUpdate(SchemaDict, total=False, extra_items=object):
+    sessionUpdate: Required[Literal["usage_update"]]
+    used: Required[int]
+    size: Required[int]
+    cost: Cost
+
+
+class SubAgentStart(SchemaDict, total=False, extra_items=Any):
+    sessionUpdate: Required[Literal["subagent_start"]]
+    subagentId: Required[str]
+    agentType: Required[str]
+    prompt: str
+
+
+class SubAgentChunk(SchemaDict, total=False, extra_items=Any):
+    sessionUpdate: Required[Literal["subagent_chunk"]]
+    subagentId: Required[str]
+    text: Required[str]
+
+
+class SubAgentThinking(SchemaDict, total=False, extra_items=Any):
+    sessionUpdate: Required[Literal["subagent_thinking"]]
+    subagentId: Required[str]
+    text: Required[str]
+
+
+class SubAgentEnd(SchemaDict, total=False, extra_items=Any):
+    sessionUpdate: Required[Literal["subagent_end"]]
+    subagentId: Required[str]
+    agentType: Required[str]
+    status: str
+    error: str
+
+
+type SessionUpdate = (
+    UserMessageChunk
+    | AgentMessageChunk
+    | AgentThoughtChunk
+    | ToolCall
+    | ToolCallUpdate
+    | Plan
+    | AvailableCommandsUpdate
+    | CurrentModeUpdate
+    | UsageUpdate
+    | SubAgentStart
+    | SubAgentChunk
+    | SubAgentThinking
+    | SubAgentEnd
+    | AIDLCState
+    | AwaitingUserInputUpdate
+    | AskUserUpdate
+    | AskUserRemindUpdate
+    | AskUserDefaultUsedUpdate
+)
+
+
+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."""