APIs and Protocols

Which interface uses which protocol (ADR-0018: REST for Stateless, WebSocket + JSON-RPC + MessagePack for Stateful).

Link

Protocol

Carries

UI → Core, UI → Knowledge

REST (JSON over HTTP)

CRUD and queries; snapshots after (re)connect

UI ↔ Core

WebSocket, JSON-RPC 2.0, MessagePack

Planner chat, sub-chats, live session output, board/inbox updates

Agent ↔ Core

WebSocket, JSON-RPC 2.0, MessagePack

Runs, human input, session events and output, results, liveness (Agents)

Agent → Core (tracker), Agent → Knowledge

MCP

Ticket context, progress, questions, proposals; knowledge search, read, write, lineage

Agent → LLM gateway → provider

Provider HTTP APIs

LLM requests, metered per run

Core ↔ git platform

Forge REST APIs and webhooks

Pull requests, review/CI/merge state

Prometheus → services

HTTP /metrics

Metrics

Stateful connections

  • Envelope: JSON-RPC 2.0 — requests/responses for commands, notifications for server push.

  • Encoding: WebSocket subprotocol ballet.v1.msgpack (default) or ballet.v1.json (debugging).

  • Authentication: the first message carries the access token (OIDC for humans, a service token for agents); refreshed in-band.

  • Subscriptions: clients subscribe to streams; every event has a sequence number.

  • Heartbeats: $/heartbeat notifications in both directions at a fixed interval; missing several closes the connection.

  • Resume: on reconnect, subscriptions resume from the last sequence number, or the server requests a resync and the client reloads the snapshot over REST.

        sequenceDiagram
  participant C as Client (UI)
  participant S as Core
  C->>S: WebSocket connect (ballet.v1.msgpack)
  C->>S: auth(token)
  C->>S: subscribe(session 42, from_seq=0)
  loop every interval
    C-->>S: $/heartbeat
    S-->>C: $/heartbeat
  end
  S-->>C: session.output (seq 1..n)
  Note over C,S: connection lost
  C->>S: reconnect + auth
  C->>S: subscribe(session 42, from_seq=n)
  S-->>C: session.output (seq n+1..) or resync_required