Agent Management & Catalog
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Management & Catalog system facilitates the discovery, configuration, and lifecycle management of AI coding agents within the Termul environment. It enables the application to spawn external agents over the Agent Client Protocol (ACP), maintaining a consistent catalog across desktop and browser surfaces.
Termul treats agents as external processes that interface with the application through a registry-based system. This system distinguishes between bundled registry agents, remote snapshots from the CDN, and user-supplied custom agents.
Sources: CONTEXT.md:3-5, AGENTS.md:12-14
Architecture and Data Flow
The architecture relies on a multi-tier registry system that synchronizes agent definitions between the Rust runtime and the React renderer.
This diagram illustrates how agent definitions move from remote or bundled sources into the active catalog used for spawning processes.
Sources: CONTEXT.md:8-25, src/renderer/lib/tests/parity-checklist.test.ts:468-500
Registry Components
| Component | Description |
|---|---|
| ACP Registry | Upstream catalog of agents served via CDN. Governs distribution and versioning. |
| Bundled Registry | A frozen snapshot shipped inside the application as the default trusted source. |
| Applied Registry | A remote snapshot that the user has explicitly opted into using. |
| Agent Catalog | The host-resolved view of the active registry, including OS/arch availability and install state. |
| Persisted Agent Config | Saved launch configurations that take precedence over registry-derived data. |
Sources: CONTEXT.md:8-28
Agent Categories and Configuration
Termul categorizes agents based on their source and update capability.
Standard Registry Agents
These are well-known agents included in the bundled templates. They typically use specific distribution methods like npx. Standard templates default the terminal to off and use non-interactive flags (e.g., -y for npx).
| Template ID | Name | Default Command |
|---|---|---|
claude-acp | Claude ACP | npx |
gemini | Gemini CLI | (Template-specific) |
codex-acp | Codex ACP | (Template-specific) |
github-copilot-cli | GitHub Copilot CLI | (Template-specific) |
Sources: src/renderer/components/chat/agent-templates.test.ts:5-30
Custom Agents
Custom agents are user-supplied configurations created outside the registry.
- Identification: They are assigned IDs with a
custom-prefix. - Validation: Requires a non-empty name and command.
- Prompt Modes: Supports
positionalorflagmodes. Ifflagmode is selected, apromptFlagmust be provided. - Updateability: Custom agents have no version source and are never updatable by the registry system.
Sources: src/renderer/lib/agents/custom-agents.test.ts:32-60, CONTEXT.md:37-39
Lifecycle and Spawn Management
The AcpManager handles the runtime lifecycle of agents, ensuring that sessions are handled safely and that split-brain scenarios are avoided.
Split-Brain Prevention
Termul prevents multiple agents from controlling the same session simultaneously.
- Ownership Check: When a session is resumed, the manager checks if another live agent already owns that session.
- Turn Status: Rejection occurs if the current owner has an active turn in flight (mid-turn).
- Rejection Code: The system returns
ACP_SESSION_OWNED_BY_OTHERin these cases.
Sources: src-tauri/src/acp/manager/tests.rs:1145-1215
Agent Summaries
The manager provides identity-rich summaries to the renderer via IPC. Each summary contains:
id: Unique identifier for the live agent.name: The display name of the agent.configId: Optional reference to the source configuration.namespace: Stable namespace used for safe identity.ownsSession: A list of session IDs currently managed by the specific agent process.
Sources: src-tauri/src/acp/manager/tests.rs:125-170, src-tauri/src/acp/manager/tests.rs:1255-1285
Parity and Transports
Agent management features are implemented across multiple transports to ensure functional parity between the desktop (Tauri) and web clients.
The system uses isTauriContext() to branch between Tauri-specific commands and web-safe HTTP/WS routes.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:468-525
Catalog IPC Channels
| Action | Tauri Command | Web Route |
|---|---|---|
| List Catalog | acp_list_catalog | GET /acp/catalog |
| Set Opt-In | acp_set_catalog_opt_in | POST /acp/catalog/opt-in |
| Install Agent | acp_install_agent | POST /acp/install |
Sources: src/renderer/lib/tests/parity-checklist.test.ts:490-555
Conclusion
Agent Management & Catalog provides the infrastructure for a project-aware AI interaction layer. By maintaining a strict registry system and cross-platform parity, it ensures that AI agents can be deployed and managed consistently, whether running locally on a desktop or accessed via a remote browser client.