One event bus. Four backends.

01 The shape of the problem.

The native tool loop in llm-bawt streams text tokens as they arrive from OpenAI or xAI, executes tools inline, and continues streaming. The OpenClaw gateway runs on a remote host and pushes events over WebSocket. The Claude Code SDK spawns a child process and sends typed events over stdio. Codex talks JSON-RPC 2.0 over stdio to a Rust binary.

Four wildly different upstream protocols. One frontend. The bridges all collapse them into a single AgentEvent dataclass, publish to Redis, and let the main FastAPI app translate to whatever wire format the client wants — currently OpenAI streaming chat completions plus a sidecar event stream for tool activity that survives the page reload.

02 The unifying type: AgentEvent.

Every bridge translates its native upstream notifications into a single dataclass defined in src/agent_bridge/events.py. Nine kinds cover everything the frontend renders:

Each event carries a deterministic event_id — SHA-256 of session, kind, payload, and stream sequence — so the Postgres event store can dedupe on replay, and a provider string ("claude-code", "codex", "openclaw") stamped at the publish boundary. The provider is what the UI uses to dispatch tool rendering, since each harness has its own native tool vocabulary.

03 Redis stream keyspace.

The bridges and the main app coordinate through four families of Redis Streams, defined in openclaw_bridge/publisher.py:

The chat.send command on agent:commands carries a backend field; each bridge runs in its own consumer group (bridge, claude-code-bridge, codex-bridge) and ACKs commands that don't match its backend without processing them. This is what lets all three bridges hang off the same stream without stepping on each other.

The per-session stream (agent:events:{session_key}) is the canonical event log; the per-request stream (agent:run:{request_id}) is a short-lived response channel scoped to one HTTP request. The SSE handler in chat_streaming.py subscribes to the per-request stream so it doesn't accidentally pick up unrelated events from a long-lived session.

04 Three SSE spouts, not one.

The frontend actually consumes events over three different transports — each one solves a different problem:

1. OpenAI-compatible chat completion SSE

The primary chat stream. POST /v1/chat/completions with stream: true returns text/event-stream chunks in the standard OpenAI shape: {"choices":[{"delta":{"content":"..."}}]}. Tool calls come through as delta.tool_calls entries. This is what most third-party OpenAI clients can already consume — pointing the official Python client at http://localhost:8642/v1 Just Works.

2. Per-bot/per-user event stream

An EventSource connection scoped to events:{bot_id}:{user_id}. Tool start/end pairs, turn-complete signals, and animation hints flow here. The frontend uses this to drive the tool activity cards under the originating user message — bucketed by trigger_message_id, which every bridge stamps onto every event. The connection is in useUnifiedEventStream.ts and reconnects on visibility/focus/online.

3. Diagnostic gateway feed (admin-only)

A separate SSE endpoint at /v1/openclaw/ws exposes raw AgentEvents for the gateway dashboard at /tools/openclaw. It's debug instrumentation, not the user-facing surface.

05 Lifecycle of a single turn.

Tracing what happens when a user sends a message to a Claude Code bot:

1. Frontend POSTs to /api/chat/proxy/v1/chat/completions with stream: true and a frontend-generated user_message_id UUID.
2. BawtHub backend proxies to llm-bawt at http://host.docker.internal:8642.
3. ChatStreamingMixin.chat_completion_stream persists a turn-log row with status="streaming", builds the message list (history + memory + system prompt), and dispatches via AgentBackendClient.
4. ClaudeCodeBackend writes a chat.send command to agent:commands with backend: "claude-code" and a new request_id.
5. The Claude Code bridge picks it up (filtering by backend field), spawns or reuses an SDK query(), and the bundled Claude binary handles the conversation.
6. SDK events stream back: assistant deltas, tool calls, tool results. The bridge translates each into AgentEvents and publishes to agent:run:{request_id} and the per-session stream and (for tool events specifically) the unified events:{bot_id}:{user_id} stream.
7. The main app's SSE generator reads from the per-request stream and translates each event into a chat completion chunk. Tool starts/ends are also re-published to the unified event stream from the main app's worker thread — that way they reach Redis even if the SSE generator is cancelled because the user closed the tab.
8. ASSISTANT_DONE + RUN_COMPLETED arrive; the SSE generator emits a finish_reason: "stop" chunk and a [DONE] sentinel.
9. A turn_complete event is published to the unified stream with status, animation, and token_usage. The frontend uses this to flip the assistant bubble from streaming to final.
10. The turn-log row is finalized with the full response text, tool call details, and elapsed time.

06 Aborts and session keys.

Aborting a turn is a separate RPC: POST /v1/chat/abort with a turn_id. The handler looks up the agent_session_key stamped on the turn-log row and writes a chat.abort command to agent:commands. Each bridge tracks active streams keyed by that session_key.

There's a subtle wrinkle: the routing key for aborts is not the same as the persisted session_key for Claude Code and Codex. Those backends use SDK-internal thread/session UUIDs in agent_backend_config.session_key, while abort routing uses f"{bot_id}:{user_id}". OpenClaw uses the persisted session_key directly because its gateway-side abstraction matches that key 1:1. The chat-streaming code in chat_streaming.py resolves this per-backend before persisting the turn log.

07 Idempotency and replay.

Events are deduped at two layers:

• Redis Stream IDs — XADD returns a monotonic ID, and the Postgres event store keeps a per-session cursor (agent_session_state.last_event_id) so a restart replays only the gap, not the whole history.
• Event dedupe key — the event_id in AgentEvent is a SHA-256 hash of {session_key}:{kind}:{canonical_payload}:{stream_seq}. The agent_events table has a UNIQUE constraint on event_dedupe_key with ON CONFLICT DO NOTHING, so even a double-publish from a re-spawned bridge is harmless.

08 The in-process FanoutHub.

Before Redis, llm-bawt used an in-process FanoutHub (agent_bridge_fanout.py) — a dict of asyncio.Queue subscribers per session. It still exists for the in-process WebSocket gateway path: the WS client receives an event, persists it via the store, and broadcasts to local subscribers. With Redis enabled, that path is mostly inert; the main app subscribes via RedisSubscriber instead.

The FanoutHub is still useful for tests and for the rare case where someone runs llm-bawt without Redis. Both paths produce the same AgentEvents, so the consumers don't care which is wired up.

09 Token accounting passes through too.

Each backend reports per-turn token usage differently. Claude Code's SDK exposes a ResultMessage with usage + modelUsage. Codex doesn't surface cost at all. The OpenAI native loop captures usage from the upstream stream's final chunk. All of them land on ASSISTANT_DONE.token_usage as the same dict shape:

{
  "input_tokens": 1247,
  "cache_read_tokens": 892,
  "cache_creation_tokens": 0,
  "output_tokens": 318,
  "context_window": 200000,
  "total_cost_usd": null
}

The frontend reads it off the turn_complete sidecar event and renders the pill in the lower-right of the assistant bubble. total_cost_usd is None for Codex turns because the upstream doesn't report it — that's a known asymmetry.

10 Key files.