Agent Client Protocol (ACP) System
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Client Protocol (ACP) System provides the core infrastructure for Termul to interact with external AI coding agents. It manages the lifecycle of agent subprocesses, handles session persistence, and enables communication between the renderer and agents across desktop and web surfaces. Sources: src-tauri/src/acp/mod.rs, CONTEXT.md:3-5
Architecture Overview
The ACP system follows a client-server model where the Termul backend (Rust) acts as a host for ACP agents. The system utilizes a runtime-neutral contract, allowing the React/TypeScript renderer to communicate with agents via Tauri IPC on desktop or WebSocket (WS) on the web. Sources: AGENTS.md:7-9, src/renderer/lib/acp-api.ts:10-15
Core Components
| Component | Description |
|---|---|
AcpManager | Manages the lifecycle of agent subprocesses, including spawning, killing, and routing commands. |
AcpTransport | Abstracted transport layer that selects between Tauri IPC and WebSocket based on the runtime context. |
SessionPersistence | Handles the durable storage of session transcripts and event records. |
AcpCatalogService | Resolves available agents based on the host OS, architecture, and installation state. |
Sources: src-tauri/src/acp/mod.rs:37-70, src/renderer/lib/acp-api.ts:18-25, src/renderer/lib/tests/parity-checklist.test.ts:474-480
Communication Flow
The renderer sends commands (e.g., send_prompt, create_session) through the acpApi facade. These commands are routed via the selected transport to the Rust backend, which forwards them to the respective agent process. Events from the agent are fanned out back to the renderer. Sources: src/renderer/lib/acp-api.ts:25-30, src-tauri/src/web/ws/dispatch.rs:175-200
The diagram shows the command flow from the UI to the agent process and the event return path. Sources: src/renderer/lib/acp-api.ts:18-25, src-tauri/src/lib.rs:435-450
Session Management
Sessions represent individual conversations with agents. The system distinguishes between ephemeral sessions (warm-pool) and durable sessions (persisted to disk). Sources: CONTEXT.md:46-51, src-tauri/src/acp/manager/tests.rs:415-420
Lifecycle and Durability
- Creation:
acpNewSessionstarts a new session. It can be marked asephemeralorpromotable. - Promotion:
acpPromoteSessiontransitions a warm-pool session to a durable state by registering persistence metadata on the host. - Restoration:
acpLoadSessionoracpResumeSessionrestores a session's state, including modes, models, and configuration options. - Termination:
acpCloseSessionstops the agent process and finalizes the session record.
Sources: src/renderer/lib/acp-api.ts:427-485, src-tauri/src/acp/manager/tests.rs:520-535
Split-Brain Protection
The system prevents multiple agents from owning the same session simultaneously. If a resume_session request is made for a session already owned by another live agent mid-turn, the request is rejected with ACP_SESSION_OWNED_BY_OTHER. Sources: src-tauri/src/acp/manager/tests.rs:698-720, src-tauri/src/web/ws/dispatch.rs:245-250
Agent Catalog and Registry
The catalog provides a host-resolved view of available ACP agents. Sources: CONTEXT.md:7-15
Registry Types
- Bundled Registry: Snapshot shipped inside the application.
- Remote Snapshot: Advisory snapshot fetched from a CDN.
- Applied Registry: A remote snapshot explicitly opted into by the user.
Sources: CONTEXT.md:10-25, src-tauri/src/acp/mod.rs:42-47
Agent Status
The system computes a SupportedAcpAgentStatus for each agent based on:
- OS and Architecture availability.
- Runtime detection (e.g., presence of Node.js for JS-based agents).
- Installation state (Bundled vs. User-installed).
Sources: src/renderer/lib/tests/parity-checklist.test.ts:355-365, src-tauri/src/acp/manager/tests.rs:115-130
Event System
The ACP system uses a namespaced event pattern (acp:*) to stream data from agents to the client. Sources: src/renderer/lib/acp-api.ts:325-345
Key Events
| Event Name | Description |
|---|---|
acp:message_chunk | Partial text/thought chunks from the agent. |
acp:tool_call | Request from the agent to execute a tool (e.g., file read, terminal command). |
acp:agent_spawned | Notification that an agent process has successfully started and initialized. |
acp:agent_switch | Durable marker indicating the conversation was handed over to a different agent configuration. |
acp:permission_request | Request for user consent to perform a restricted action. |
Sources: src/renderer/lib/acp-api.ts:348-375, src/renderer/lib/tests/parity-checklist.test.ts:500-515
Replay Window
During session restoration, the system opens a "replay window." This window suppresses live event fan-out while the host replays historical events to the client, ensuring the client UI synchronizes without duplicate messages. Sources: src-tauri/src/acp/manager/tests.rs:885-910
The sequence diagram illustrates the history replay mechanism during session loading. Sources: src-tauri/src/acp/manager/tests.rs:955-980, src/renderer/lib/acp-api.ts:445-455
Security and Auth
ACP supports multiple authentication methods advertised by agents during initialization. Sources: src/renderer/lib/acp-api.ts:250-265
- Host-Managed Auth: The Termul host handles credentials (e.g., for Claude ACP).
- Agent-Managed Auth: The agent process handles its own login UX.
- Terminal Auth: The agent requests a real terminal for a TUI-based login flow.
Sources: src/renderer/lib/acp-api.ts:265-285, src-tauri/src/acp/manager/tests.rs:600-615
Timeouts and Caps
The system enforces several timeouts to prevent wedged agents:
- Idle Timeout: Rejects turns if the agent provides no activity for a set window.
- Hard Cap: Forcibly cancels turns exceeding a maximum wall-clock duration.
- Reopen Timeout: Bounds the time allowed for session loading/resuming.
Sources: src-tauri/src/acp/manager/tests.rs:340-365, src/renderer/lib/acp-api.ts:545-565
Conclusion
The ACP system is a robust, cross-platform infrastructure that decouples agent logic from the UI. By providing standardized transport, session durability, and a host-authoritative catalog, it enables consistent agent interactions across desktop and web clients while maintaining process safety through strict lifecycle management. Sources: CONTEXT.md:3-8, AGENTS.md:7-12