packages web server daemon runtime

Daemon runtime

Active contributors: Zachary BENSALEM

Purpose

web/server/src/daemon-runtime.ts connects Fleet to the stock Prime Agent daemon. It resolves the effective session store, starts or reuses a compatible daemon, creates resident workers, attaches DaemonAgentConnection, lists saved sessions, and deletes saved transcripts.

Connection lifecycle

ensureFleetDaemonRunning probes the default socket before spawning. The probe accepts only the exact daemon name and protocol version exported by the pinned runtime. An unrelated or newer daemon on the same socket is rejected. Startup promises are memoized per socket and cleared after completion so a failed attempt can be retried.

createDaemonWebAgentConnection sends a create request with lifecycle: "resident" and a runtime config containing the workspace root, agent directory, effective session directory, disabled telemetry, thinking level, and optional OpenUI prompt. It attaches the resulting worker through DaemonAgentConnection.attach.

Session directories

sessionDirectoryForCwd follows the same precedence as the CLI: PRIME_AGENT_SESSION_DIR, then PRIME_AGENT_CODING_AGENT_SESSION_DIR, then cwd-scoped settings, then the Fleet agent directory's sessions folder. The directory is passed explicitly to daemon list/create calls so a daemon previously started with a private directory cannot expose unrelated sessions.

Reconfigurable connections

The daemon fixes appendSystemPrompt when a worker starts. Fleet's createReconfigurableConnection wraps the connection and reopens the same persisted session at an idle boundary when OpenUI mode or artifact prompting changes. It preserves subscriptions and invalidation listeners across the replacement. PrimeBridge uses this when the chat mode changes between agent, plan, and harness requests.

sequenceDiagram
    participant Bridge as PrimeBridge
    participant Probe as Daemon probe
    participant Daemon as Prime daemon
    participant Connection as DaemonAgentConnection
    Bridge->>Probe: inspect socket
    Probe-->>Bridge: compatible or unreachable
    Bridge->>Daemon: spawn if needed
    Bridge->>Daemon: create resident worker
    Daemon-->>Connection: active session ID
    Connection-->>Bridge: supported connection seam
    Bridge->>Connection: prompt / subscribe / state

Loading

Catalog operations

listDaemonSessions requests all sessions from the effective store and checks the returned summaries before exposing them to web/server/src/handlers/. deleteDaemonSavedSession performs catalog deletion without requiring a live session context, which lets Fleet remove listed but unresumable transcripts.

Entry points for modification

Change socket identity or worker configuration in web/server/src/daemon-runtime.ts, and update PRIME_AGENT_RUNTIME.json and the runtime compatibility tests if the upstream release changes. Do not patch or vendor Prime Agent source into this repository. Follow docs/guides/upstream-runtime.md and the dependency reference when the pin changes.

Key source files

File	Purpose
web/server/src/daemon-runtime.ts	Daemon lifecycle and connection wrapper
PRIME_AGENT_RUNTIME.json	Runtime archive and checksum
web/server/package.json	Server-side runtime package references
packages/fleet-web/package.json	Published runtime references
web/server/src/__tests__/daemon-runtime.test.ts	Deterministic daemon behavior tests
docs/guides/upstream-runtime.md	Upgrade procedure

See architecture for the ownership boundary.