Daemon architecture

Prime Agent uses a three-layer daemon architecture where the client owns only rendering and local UI preferences, a supervisor daemon handles routing and worker health, and independent session workers each own an AgentSessionRuntime with its kernels, scheduler, and all descendant sessions. The same execution and persistence path flows through the session queue regardless of prompt origin—user attachment, schedule, goal, or autonomous mode—so all input types use unified queuing, backpressure, and recovery. In the daemon architecture, backpressure is the mechanism by which a session worker signals callers that its queue is full, causing new inputs to be held or rejected until capacity becomes available.

In the prime-agent daemon architecture, three distinct layers each own a bounded set of concerns: the client (TUI or headless) owns rendering, keyboard input, and local UI preferences only — execution is owned by the session worker.[1] The daemon supervisor owns session discovery, routing, attachments, worker health, and cross-agent message delivery — not individual session logic.[1] Each session worker owns exactly one root AgentSessionRuntime, its scheduler, all kernels, and all descendant sessions below that root.[1] AgentSession owns provider calls, queues, tools, compaction, goals, child lifecycles, and transcript writes.[1] AgentSession serves as the single authority for agent-message admission logic, rather than distributing that responsibility across the daemon supervisor and worker periphery.

Workers and kernels run as separate processes for lifecycle and failure containment, not as security sandboxes — they normally run with the same OS permissions as the client.[1] From the session queue onward, the same execution and persistence path is used whether a prompt originates from a user attachment, heartbeat, cron schedule, goal continuation, autonomous mode, or another agent.[1] Peer subagent connections in the daemon are established on demand rather than eagerly, simplifying message-ordering and backpressure reasoning across concurrent sessions.

Four sub-documents elaborate the architecture: agent-connection.md (client/runtime boundary, snapshots, replay, reconnect), daemon.md (process ownership, leases, scheduling, backpressure, crash recovery), rlm-runtime.md (IPython host requests and recursive child execution), and long-running-agents.md (detached sessions, messages, goals, scheduled work).[1]

In v0.1.8, the long-lived daemon was changed to upgrade automatically when Prime Agent self-updates, so a new TUI no longer silently attaches to a stale daemon.[2] In v0.3.0, daemon and headless execution was changed to isolate each root session tree in a recoverable worker process, introducing protocol-v2 chunked snapshots, compact streaming, attachment-local backpressure, and session leases — while leaving print, JSON, and RPC interfaces unchanged.[3] In v0.3.2, all client modes — interactive, print, JSON, RPC, piped-stdin, and no-session — were changed to use the same daemon-owned runtime while preserving their existing commands, output protocols, and lifecycle behavior.[4] In v0.5.0, large daemon session loads were changed to stream JSONL history and avoid retaining a second full-file copy in memory.[5] In v0.6.1, the global idleEvictionMinutes daemon setting was documented, including its default, valid values, and eviction/passivation behavior.[6] In v0.7.1, retry_worker was fixed to clear saved stop markers so retried workers recover correctly instead of being stuck at "Session worker is not connected".[7]

Sources

Search

Daemon architecture