Events
CLI-JAW uses an SSE-first event channel for the Web UI, with legacy WebSocket fallback and provider-specific stream parsers behind it.
SSE Event Channel
GET http://localhost:3457/api/eventsThe preferred browser event transport is GET /api/events. It is a data-only SSE stream: the server does not set an SSE event: field. Each message carries topic and event inside the JSON payload.
| Behavior | Contract |
|---|---|
| Replay cursor | Last-Event-ID header or ?lastEventId= query |
| Replay buffer | 1000 events in src/core/event-bus.ts |
| Listener cap | 256 active SSE listeners; overflow returns 503 {error:"SSE_CAPACITY"} |
| Heartbeat | comment ping every 15 seconds |
| Replay gap | {"topic":"system","event":"replay_gap"} |
| Fallback | WebSocket is used only when SSE never opens, usually against an older server |
| Transient drop UX | Fast SSE reconnects stay silent; only a disconnect lasting longer than 8 seconds posts a disconnected message |
WebSocket Compatibility
ws://localhost:3457/wsThe WebSocket path is a client/TUI fallback for pre-X-01 servers where /api/events never opens. Current servers deliver public browser events through SSE only. Internal-only events are not delivered to public SSE clients.
Common Event Names
| Event | Description |
|---|---|
agent_status | Agent lifecycle status such as running, done, error, evaluating. |
agent_tool | Tool, thinking, search, command, or subagent progress step. |
agent_output | Live assistant text preview chunk. |
agent_done | Authoritative final response, error, and bounded tool log. |
agent_retry / agent_fallback | Transient retry and fallback-chain status. |
queue_update | Pending message queue length. |
new_message | Inbound or queued user message bubble. |
orc_state | PABCD/IPABCD state update. |
orchestrate_done / orchestrate_warning | Workflow completion or non-blocking warning. |
steer_started | Accepted steer prompt. |
goal_done / goal_cancel / goal_pause_detected / goal_pause_gate_pending | Persistent goal lifecycle events. |
session_switched / session_created / session_list | Multi-session updates. |
memory_status | Memory runtime/sidebar refresh signal. |
worker_stalled / worker_disconnected / worker_timeout | Distributed worker progress failure signals. |
schedule_wakeup / schedule_wakeup_failed | ScheduleWakeup lifecycle. |
Provider Streams
Provider CLIs still use their own stdout protocols internally. Claude, Codex, Cursor, Grok, and Copilot are normalized through src/agent/events/*. AGY uses plain-text print mode. The normalized events pass through src/core/bus.ts, which publishes public events to the SSE event bus and still fans out to internal collectors/forwarders.
Manager Worker SSE
The jaw dashboard serve React manager app reads manager HTTP endpoints by polling. Worker instance live progress is bridged server-side: src/manager/worker-events.ts and src/manager/worker-sse-client.ts subscribe to each worker's GET /api/events stream and update the latest-message cache.
Detailed source-of-truth: structure/stream-events.md and structure/server_api.md.