WebSocket State Hub

The state hub provides real-time session state to all connected clients via WebSocket. When an agent's state changes, the Board UI and any other listeners receive the update instantly.

Endpoints

OptimalOS has three WebSocket endpoints:

Endpoint	Purpose
/ws/terminal	PTY terminal sessions (see Terminal).
/ws/state	Real-time orchestration state broadcast. Also bridges Morning Ritual events (triage_run_completed, triage_run_failed) to a window-level triage:updated CustomEvent for widgets like TODAY.
/ws/loom	Live workflow strand events: run.started, step.started, step.completed, step.failed, run.finished. Used by the Loom tab for real-time strand animation. Code: optimalOS/src/server.ts:189-226 plus optimalOS/src/loom/event-hub.ts.

State WebSocket

wss://optimal.miami/ws/state?token=<your-auth-token>

Authentication uses the same session token as the REST API, passed as a query parameter. Invalid tokens result in an immediate close with code 4001.

Protocol: Snapshot + Delta

The state WebSocket uses a snapshot-then-delta protocol:

1. Snapshot (on connect)

When a client connects, the server immediately sends the full state of all tracked sessions:

{
  "type": "snapshot",
  "sessions": [
    {
      "id": "session-1",
      "taskId": "task-uuid",
      "agentType": "claude-code",
      "tmuxSession": "agent-login-fix",
      "state": "running",
      "label": "Fix login timeout",
      "prompt": "Fix the login timeout bug",
      "lastActivity": "2026-03-27T14:30:00.000Z",
      "lastEvent": "tool_use",
      "createdAt": "2026-03-27T14:28:00.000Z",
      "dependsOn": []
    }
  ],
  "timestamp": "2026-03-27T14:30:05.000Z"
}

2. Delta (ongoing)

State changes are batched with a 150ms debounce and sent as delta messages:

{
  "type": "delta",
  "changes": [
    {
      "type": "session_updated",
      "id": "session-1",
      "data": {
        "state": "awaiting_review",
        "lastEvent": "notification",
        "lastActivity": "2026-03-27T14:31:00.000Z"
      },
      "timestamp": "2026-03-27T14:31:00.000Z"
    }
  ]
}

Change Types

Type	When sent
session_added	A new session was created (data contains the full session object)
session_updated	A session's state changed (data contains the changed fields)
session_removed	A session was deleted (data is null)
service_updated	A service status changed
task_updated	A kanban task was updated

Client Behavior

The client (board.ts) does not send messages on the state WebSocket. The onMessage handler on the server is a no-op. All communication is server-to-client.

Connection Lifecycle

• On connect, the server validates the auth token and sends the snapshot
• The server sends delta messages whenever the StateHub's pub/sub fires
• If a ws.send() fails (broken connection), the client is removed from the broadcast set
• On disconnect, the Board UI reconnects with a 3-second delay

How the Board Uses It

The orchestration board connects to /ws/state on initialization. When updates arrive:

1. Snapshot: The board rebuilds its session list and renders all session cards
2. Delta (session_added): A new card is created and placed in the correct column
3. Delta (session_updated): The affected card's DOM is patched in place -- status dot, activity time, and column position update without re-rendering the entire board
4. Delta (session_removed): The card is removed from the DOM

This means multiple browsers or devices viewing the board all stay in sync without polling.

Terminal WebSocket

The terminal WebSocket at /ws/terminal is documented in the Terminal page. It uses a different protocol optimized for PTY I/O (binary data + JSON control messages).

Connect parameters:

/ws/terminal?token=<token>&mode=<shell|tmux-attach>&session=<name>&cols=120&rows=40