Agent System

The core of Tribunus Desktop is a deterministic agent runtime that manages agent lifecycles through event-sourced sessions, a typed tool registry with ~200 built-in definitions, project-aware context management, and the Agent Communication Protocol (ACP) for inter-agent coordination. The runtime lives in the Electron main process and communicates with the SolidJS renderer over a secure IPC bridge defined in the preload layer.

Session Management

An agent session begins when the user or a parent agent sends a message to an agent identifier. The session manager — implemented at packages/runtime/src/session/ — binds the message to a session ID, loads the agent’s configuration (model backend, tool set, system prompt), and instantiates the agent runtime. The runtime processes messages through a perception–reasoning–action loop until the session is suspended, terminated, or yields control back to the caller.

Session state is persisted as an append-only event log. Each event captures the agent’s observation, the chosen action, and the resulting tool output or error. This log serves as both audit trail and crash-recovery source: a terminated session can be resumed by replaying its events into a fresh runtime. The event-sourced design provides:

• Full history and replay for debugging and post-mortem analysis.
• Time-travel — rewind to any prior event and fork execution from that point.
• Concurrent-safe writes — events are the single source of truth; no locking needed.
• Built-in audit trail for regulated environments.

Tool Execution

Agents interact with the system through a typed tool registry hosted in the main process. Each of the ~200 built-in tools declares its input schema, output schema, and execution mode: a local function call, a shell command dispatched through the embedded node-pty terminal, a sidecar process managed by the Valkey supervisor, or an ACP remote call. The agent runtime validates tool calls against the schema before dispatch and captures stdout, stderr, and exit codes in the event log.

Tools can be composed into workflows. A workflow step specifies a sequence of tool calls with conditional branching. The step engine tracks dependencies between calls and can parallelize independent branches automatically. Workflow steps can also chain into each other — one step’s output feeds the next step’s input — enabling multi-stage pipelines for code review, deployment, or data analysis.

Project-Aware Context Management

The agent runtime maintains awareness of the open project structure — file tree, language detection, dependency graph, and Git history. When constructing a prompt, the context manager selects relevant files based on the conversation state, recent edits, and the user’s cursor position. This reduces token usage and focuses the model on the code that matters. Context windows are configurable per agent and can be pinned to specific directories or file patterns.

ACP Protocol

The Agent Communication Protocol (ACP) is the wire format for agent-to-agent and agent-to-tool messages. ACP messages are JSON-encoded and carry a schema-versioned envelope with routing metadata, payload, and capabilities negotiation. Desktop uses ACP for delegating subtasks from an orchestrator agent to worker agents, querying tool availability across agent boundaries, and streaming intermediate results from long-running operations. ACP is extensible via middleware that intercepts, transforms, or routes messages based on content or origin.

Multi-Agent Orchestration

Desktop supports star, pipeline, and swarm topologies for multi-agent orchestration. A coordinating agent receives a top-level task, decomposes it into subtasks, and dispatches each to a worker agent via ACP. Workers execute independently and stream results back. The orchestrator merges partial results, requests clarification, or reassigns subtasks based on intermediate outcomes. Each agent operates in its own context with its own model, tools, and session state — cross-agent data sharing is explicit and intentional.

For implementation details, see packages/core/src/agent.ts for the core agent lifecycle and packages/runtime/src/session/ for session persistence and event sourcing.