WebSocket protocol

Protocol version: v1. See wire protocol concept for the narrative; this page is the schema reference.

Endpoint

wss://<brain>/ws
Authorization: Bearer <agent-token>

Subprotocol: none (plain WS + JSON frames).

Frame envelope

Every frame:

{
  "type": "<string>",
  ...type-specific fields...
}

Agent → Brain frames

hello

{
  type: "hello",
  protocol: "v1",
  agent_name: string,
  framework: "django" | "flask" | "fastapi" | "bare",
  framework_version: string,
  engines: string[],
  schedulers: string[],
  capabilities: Record<string, EngineCapabilities | SchedulerCapabilities>,
  metadata: { hostname: string, pid: number, ... }
}

event_batch

{
  type: "event_batch",
  seq: number,    // monotonic per agent
  events: TaskEvent[]
}

TaskEvent:

{
  event_type: "task_sent" | "task_started" | "task_succeeded"
            | "task_failed" | "task_retry" | "task_cancelled"
            | "task_expired",
  task_id: string,
  engine: string,
  ts: string,           // RFC 3339
  name: string,
  args_redacted: any[],
  kwargs_redacted: Record<string, any>,
  queue?: string,
  routing_key?: string,
  error?: { exc_type: string, exc_msg: string, traceback_redacted: string },
  group_id?: string,
  parent_id?: string,
  retry_of?: string
}

heartbeat

{ type: "heartbeat", ts: string }

command_result

{
  type: "command_result",
  cmd_id: string,
  ok: boolean,
  error?: { code: string, message: string },
  result?: any
}

schedule_snapshot

Full schedule list; sent after hello and every 5 minutes.

{
  type: "schedule_snapshot",
  scheduler: string,
  schedules: Schedule[]
}

schedule_update

Delta update.

{
  type: "schedule_update",
  scheduler: string,
  added?: Schedule[],
  modified?: Schedule[],
  removed?: string[]   // schedule ids
}

Brain → Agent frames

ack

Acknowledges an event_batch.

{ type: "ack", seq: number }

command

{
  type: "command",
  cmd_id: string,                 // UUID
  cmd: "retry_task" | "cancel_task" | "bulk_retry" | "purge_queue"
     | "schedule_create" | "schedule_update" | "schedule_delete"
     | "schedule_pause" | "schedule_resume"
     | "restart_agent" | "query_state",
  args: Record<string, any>
}

error

Fatal protocol error; brain will close the socket.

{ type: "error", code: string, message: string }

Close codes

Code	Meaning
1000	Normal closure
4001	Protocol version mismatch
4002	Invalid token
4003	Agent revoked
4004	Agent name conflict
4005	Malformed frame

Reconnect

Agents should reconnect with exponential backoff on 1006 / 1011 / 4005 and similar transient codes. On 4001 / 4002 / 4003, stop and log - these are configuration errors.