Events

FlowLayer V1 emits server-initiated event messages over the same WebSocket used for commands.

Event catalog

Event name	Scope	When emitted
`hello`	Private (new connection only)	Immediately after WebSocket upgrade
`snapshot`	Private (new connection only)	Immediately after `hello`
`service_status`	Broadcast (all connected sessions)	On service state changes
`log`	Broadcast (all connected sessions)	On new service log lines

`hello`

hello advertises protocol version, server identity, and command capabilities.

{
  "type": "event",
  "name": "hello",
  "payload": {
    "protocol_version": 1,
    "server": "flowlayer",
    "capabilities": [
      "get_snapshot",
      "get_logs",
      "start_service",
      "stop_service",
      "restart_service",
      "start_all",
      "stop_all"
    ]
  }
}

`snapshot`

snapshot contains service statuses at connection time.

{
  "type": "event",
  "name": "snapshot",
  "payload": {
    "services": [
      { "name": "api", "status": "running" },
      { "name": "worker", "status": "ready" }
    ]
  }
}

Services in snapshot are emitted in deterministic name order.

`service_status`

service_status is broadcast whenever runtime status changes.

{
  "type": "event",
  "name": "service_status",
  "payload": {
    "service": "api",
    "status": "stopping",
    "timestamp": "2026-04-25T10:05:00Z"
  }
}

`log`

log carries live log lines with sequence number metadata.

{
  "type": "event",
  "name": "log",
  "payload": {
    "seq": 1042,
    "service": "api",
    "phase": "running",
    "stream": "stdout",
    "message": "listening on :3000",
    "timestamp": "2026-04-25T10:05:01Z"
  }
}

Private vs broadcast scopes

For protocol consumers:

Private per connection: hello, snapshot
Broadcast to all sessions: service_status, log

Related private response messages are documented in Message Envelopes: ack, result, error.

Log delivery model and continuity

Live log events are best-effort. Under burst load, log events may be dropped instead of blocking command/control traffic.

Use stream vs pull this way:

Need	Recommended source
Live tail in UI	`log` events
Recover after reconnect	`get_logs` with `after_seq`
Fill gaps after slow consumer periods	`get_logs` with last seen `seq`
Bounded history retrieval	`get_logs` with `limit`

get_logs returns entries, truncated, and effective_limit; use seq as the continuity marker.

See WebSocket Lifecycle for reconnect semantics and Reference for pull-command details.