paseo/docs/daemon-session-connection-architecture-spec.md

Daemon Session and Connection Architecture Specification

Status: Draft for implementation
Owner: App + Server + Relay
Last updated: 2026-02-20

1. Purpose

This spec defines the connection and session model across:

• Client app
• Relay
• Daemon server

The goal is to remove drift, make invalid states impossible, and move lifecycle decisions into explicit state machines outside React.

2. Scope

In scope:

• Session identity and lifetime
• Connection identity and lifetime
• Daemon client/transport ownership rules
• Host runtime manager behavior
• Relay responsibilities and protocol shape
• React integration boundaries
• UX loading contracts tied to machine state
• Required tests

Out of scope:

• Agent business logic (tool calls, model behavior)
• New UI visual design

3. Terminology

• serverId: stable daemon identity.
• clientSessionKey: stable client identity for one app install/profile. Persists across app restarts.
• session: daemon-side logical session associated with one clientSessionKey.
• connection: one physical socket path (direct or relay).
• transport: adapter that owns exactly one physical connection.
• DaemonClient: connection actor that owns one transport.
• HostRuntimeManager: per-host orchestrator that owns active and probe daemon clients.
• probe client: ephemeral daemon client used for latency/health probing only.

4. Non-Negotiable Invariants

1. Daemon session is keyed by clientSessionKey, not by transport.
2. Session survives disconnects and client restarts.
3. Client may open and close many connections over time for the same session.
4. DaemonClient owns exactly one transport; transport owns exactly one connection.
5. No separate ad-hoc isConnected state outside DaemonClient connection state.
6. Host runtime is the only source of truth for per-host connectivity in the app.
7. React does not coordinate connection lifecycle; React only renders machine snapshots and dispatches intents.
8. Probe clients never mutate active connection/session state.
9. No silent fallback identities. Missing required identity inputs are explicit errors.

5. Identity Model

5.1 Session Identity

• Required on every app->daemon connection (direct or relay): clientSessionKey.
• Daemon canonical external key:
  • externalSessionKey = session:${clientSessionKey}
• If a socket reconnects with same key, daemon reattaches to existing session.
• If socket disconnects, daemon keeps session alive for reconnect grace period.

5.2 Connection Identity

• Connection identity is per-socket and ephemeral.
• Connection identity is not the session identity.
• A transport instance never needs a separate protocol-level connectionId to identify itself on disconnect; instance ownership is local and explicit.

6. Component Responsibilities

6.1 DaemonClient

• Owns one transport instance.
• Exposes one connection machine.
• Supports clean terminal disposal.
• Must not be resurrected after disposal.
• Emits typed connection state changes.

6.2 Transport

• Owns one connection (WebSocket or equivalent).
• No multiplexing of multiple peer connections in one transport instance.
• Must expose open, message, error, close.
• Must enforce connect timeout and report typed failure reason.

6.3 HostRuntimeManager (per host)

• Owns per-host source of truth snapshot.
• Owns active DaemonClient.
• May create many probe clients in parallel; they are ephemeral and isolated.
• Can switch active client cleanly by:
  1. creating next client,
  2. subscribing,
  3. promoting snapshot generation,
  4. disposing previous client.
• Serializes transitions so stale async completions cannot patch current state.

6.4 Relay

• Relay routes bytes; it does not own logical session policy.
• Control plane reports connected client sessions.
• Data plane maps one daemon data peer per client session key.
• Relay may have many client sockets for same clientSessionKey concurrently.

6.5 Daemon Server

• Owns canonical session map keyed by externalSessionKey.
• Reattaches sockets to existing session on reconnect.
• Session continuity must work identically for direct and relay.

7. State Machines

7.1 DaemonClient Machine

States:

• idle
• connecting
• connected
• disconnected
• disposed (terminal)

Events:

• CONNECT_REQUEST
• TRANSPORT_OPEN
• TRANSPORT_CLOSE(reason)
• TRANSPORT_ERROR(reason)
• CONNECT_TIMEOUT
• RECONNECT_TIMER
• DISPOSE

Rules:

• disposed is terminal. All events except idempotent DISPOSE are ignored.
• ensureConnected is no-op in disposed.
• connecting has bounded timeout.
• Any disconnect clears in-flight waiters tied to that connection.

7.2 HostRuntimeManager Machine (per host)

States:

• booting
• no_connections
• selecting_active_connection
• connecting_active
• online
• degraded (active exists but not connected)
• error
• stopped

Context:

• activeClientRef
• activeConnectionRef
• generation
• probeResults
• lastError

Rules:

• All async side effects are generation-guarded.
• Snapshot only changes through machine transitions.
• Probe transitions cannot directly mutate active client state.
• Active switch is atomic with generation increment.

7.3 Agent Directory Sync Machine (per host session mirror)

States:

• idle
• initial_loading
• ready
• revalidating
• error_before_first_success
• error_after_ready (non-blocking)

Rules:

• After first success, errors are non-blocking.
• Sidebar skeleton/loading is tied to this machine, not ad-hoc React flags.

8. Relay Contract

8.1 Required Behavior

• Client connects with clientSessionKey.
• Relay control reports client session presence changes.
• Daemon establishes peer data connection per clientSessionKey.
• Multiple client sockets with same clientSessionKey are allowed; relay does not enforce single client socket.

8.2 Prohibited Behavior

• Enforcing one client socket per clientId when that clientId is used as session identity.
• Treating replacement of one socket as session replacement.

8.3 Protocol Notes

• Keep protocol focused on session keys and control events.
• Do not introduce protocol connectionId for disconnect ownership.
• Internal debug correlation IDs are allowed in logs, not required on the wire.

9. React Integration Contract

1. React reads runtime snapshots via external store subscription.
2. React never mirrors connection state into local useState/useRef.
3. React never calls connection lifecycle APIs except explicit user intent events.
4. Complex transition logic stays in machines/reducers, not effects.

10. UX Contract

10.1 Agent First Open

• If agent history has never been loaded for that agent in this session:
  • show full overlay spinner (centered, no text).
  • do not show "refreshing history" toast.
  • do not show empty "start chatting..." placeholder simultaneously.

10.2 Already Loaded Agent Revalidation

• Show existing toast for refresh/revalidation.
• Do not block with overlay.

10.3 Optimistic Agent Creation

• No loading overlay during optimistic create flow.

10.4 Errors

• Non-blocking indicator for revalidation failures after first successful load.

11. Retry and Timeout Policy

• Client connect timeout: bounded and explicit.
• Relay handshake timeout: bounded and explicit.
• Backoff retry for recoverable disconnects.
• Terminal disposed state disables retries.
• Retry reasons are typed and machine-readable.

12. Observability Requirements

Every connection/session event must log:

• serverId
• clientSessionKey (or hashed form)
• machine state transition (from, to, event)
• connection path (direct/relay)
• generation id (host runtime)
• typed reason/error code

13. Test Requirements

13.1 Unit

• DaemonClient transitions including terminal disposed.
• Host runtime generation guards prevent stale async writes.
• Agent directory sync machine transition coverage.

13.2 Integration

• Session continuity across disconnect/reconnect for direct.
• Session continuity across disconnect/reconnect for relay.
• Session continuity when switching active path direct <-> relay.
• Probe clients running in parallel do not affect active client/session.

13.3 E2E

• App can remain connected while switching network paths without losing agents.
• Sidebar and connection status converge correctly (no stuck connecting drift).
• First-open agent overlay contract and toast gating.

14. Migration Plan

1. Introduce and persist clientSessionKey on client.
2. Require session key for both direct and relay socket attach paths.
3. Update daemon session attach to use unified externalSessionKey.
4. Split relay daemon manager into:
   • control manager
   • per-peer connection instances
5. Remove single-client-socket relay enforcement for same session key.
6. Add disposed terminal state to DaemonClient.
7. Move remaining connection lifecycle logic from React effects into machines.
8. Add/expand tests before deleting legacy paths.
9. Delete legacy dual-state paths and fallback identity behavior.

15. Acceptance Criteria

• One canonical source of truth per host in runtime manager snapshot.
• No mirrored connection flags in React.
• No stuck connecting without timeout path.
• Session survives app restart and transport switch.
• Client can create/use many connections over time for same session.
• First-open loading UX follows overlay/toast contract exactly.