1 changed files with 14 additions and 0 deletions
@@ -54,6 +54,10 @@ The following standards are integrated into the architecture:

    CleverAgents adopts the external **Agent-to-Agent (A2A) Protocol** standard ([a2a-protocol.org](https://a2a-protocol.org)) as the **sole** communication protocol for all client-server interaction. A2A is the successor to the Agent Client Protocol (ACP), which is now deprecated; A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation. A2A is built on **JSON-RPC 2.0** (with additional gRPC and REST bindings available) and defines the **fundamental boundary between the Presentation and Application layers** — every client operation flows through A2A regardless of deployment mode. The standard provides operations for messaging (`message/send`, `message/stream`), task lifecycle management, streaming updates via SSE, and **Agent Card**-based capability discovery. CleverAgents extends the standard with `_cleveragents/`-prefixed extension methods (declared via the A2A extension mechanism) for platform operations: plan lifecycle, registry CRUD, entity sync, namespace management, and diagnostics. In local mode, A2A flows over **stdio** via the JSON-RPC binding (agent as subprocess) with platform operations resolved in-process via `A2aLocalFacade`. In server mode, A2A flows over **HTTP** to the CleverAgents server. Both transports use the A2A Python SDK. All clients — CLI, TUI, IDE plugin, and third-party — communicate exclusively through A2A. See [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md), and [Server and Client Architecture](#server-and-client-architecture) for the full detail.

+!!! note "TUI Local-Mode Exception"
+
+    In **local mode**, TUI slash commands (e.g., `/session:export`, `/persona:list`) invoke application services directly via the DI container rather than routing through A2A. This is a performance optimization — the TUI process is co-located with the application layer, making the A2A serialization boundary unnecessary for command dispatch. The orchestrator actor’s conversational message flow (`message/send`, `message/stream`) still routes through A2A in all modes. In **server mode**, all TUI operations (including slash commands) route through A2A over HTTP.
+
 ??? info "Model Context Protocol (MCP) -- Details"

    The standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers.
@@ -29019,6 +29023,16 @@ The TUI (Terminal User Interface) is the second Presentation-layer surface for C

 The TUI communicates with the Application layer exclusively through A2A (ADR-026). It subscribes to A2A events for real-time updates and uses the existing Output Rendering Framework (ADR-021) via a `TuiMaterializer` that maps `ElementHandle` events to Textual widget operations — enabling all CLI command producers to render in the TUI without modification.

+#### TUI Input Pipeline
+
+User input in the TUI prompt is processed by `InputModeRouter`, which classifies input into three modes:
+
+- **Command mode** (`/` prefix): Strips the `/` and routes to `TuiCommandRouter` for slash command dispatch. In local mode, `TuiCommandRouter` dispatches directly to application services via the DI container. In server mode, commands are forwarded via A2A.
+- **Shell mode** (`!` prefix): Strips the `!` and executes via `ShellExecutor` with safety confirmation.
+- **Normal mode**: Parsed for `@resource` references, then forwarded to the orchestrator actor via A2A `message/send`.
+
+**Key ADRs**: ADR-044 (TUI Architecture), ADR-045 (Persona System), ADR-046 (Reference/Command System)
+
 Key architectural principles:

 - **Direct-to-chat launch** — no launcher screen; opens directly to the main chat interface