<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11.7-r8r-bridge -->

# r8r Bridge

- src/providers/quota.rs
- src/r8r_bridge/mod.rs

The **r8r Bridge** provides a bidirectional WebSocket integration between ZeptoClaw and the [r8r](https://github.com/qhkm/zeptoclaw/blob/2c743d31/r8r) workflow-automation engine [src/r8r_bridge/mod.rs1-4](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L1-L4) This integration allows ZeptoClaw to delegate deterministic, multi-step operations (like data pipelines or HTTP calls) to r8r, while r8r can call back into ZeptoClaw for AI-driven reasoning decisions or human-in-the-loop approvals.

## System Architecture

The bridge is implemented as a long-lived WebSocket client that connects to the r8r `/api/ws/events` endpoint [src/r8r_bridge/mod.rs44-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L44-L53) It handles automatic reconnection, at-least-once delivery through event deduplication, and structured event dispatching [src/r8r_bridge/mod.rs46-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L46-L50)

### Code Entity Map: Bridge Components

This diagram maps the logical bridge functions to their implementing classes and modules.

```

```

Sources: [src/r8r_bridge/mod.rs13-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L13-L20) [src/r8r_bridge/mod.rs51-64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L51-L64) [src/r8r_bridge/events.rs17-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L17-L23)

## Event Handling and Data Flow

The bridge communicates using a JSON-wrapped envelope system defined by `BridgeEventEnvelope` [src/r8r_bridge/events.rs17-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L17-L21) Every message sent or received includes a unique `id` for tracking and acknowledgment [src/r8r_bridge/events.rs19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L19-L19)

### BridgeEvent Types

The system supports several event variants for bidirectional communication:

Sources: [src/r8r_bridge/events.rs23-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L23-L96)

### Message Processing Flow

The bridge uses a split-task architecture to handle concurrent I/O. The `R8rBridge::connect` method initializes these tasks and manages the WebSocket lifecycle [src/r8r_bridge/mod.rs137-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L137-L185)

```

```

Sources: [src/r8r_bridge/mod.rs132-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L132-L136) [src/r8r_bridge/mod.rs183-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L183-L185) [src/r8r_bridge/events.rs17-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L17-L21)

## Approval Routing

When r8r hits an `ApprovalRequested` gate, the bridge routes this to the user via the active communication channel.

- Parsing : The parse_approval_response function converts free-text replies into an ApprovalDecision src/r8r_bridge/approval.rs 35-64
- Keywords : It recognizes keywords like approve , lgtm , yes for approvals, and reject , no , deny for rejections src/r8r_bridge/approval.rs 22-23
- Reasoning : Any text following the keyword is captured as the reason field in the decision src/r8r_bridge/approval.rs 52-59
- Timeouts : If a user does not respond within the workflow's configured window, r8r sends an ApprovalTimeout event, which the bridge formats into a notification src/r8r_bridge/events.rs 38-43

Sources: [src/r8r_bridge/approval.rs11-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/approval.rs#L11-L16) [src/r8r_bridge/approval.rs29-34](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/approval.rs#L29-L34) [src/r8r_bridge/events.rs26-43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/events.rs#L26-L43)

## Reliability and Health

### Deduplication

To ensure at-least-once delivery without processing the same event twice, the `Deduplicator` tracks `event_id` values [src/r8r_bridge/mod.rs58-59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L58-L59) It rejects any incoming event whose ID has already been seen and acknowledged during the reader loop [src/r8r_bridge/mod.rs134-135](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L134-L135)

### Reconnection and Backoff

The bridge implements automatic reconnection with exponential backoff logic to maintain a persistent connection to the r8r engine [src/r8r_bridge/mod.rs47-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L47-L48) The `connect` method handles the underlying `tokio-tungstenite` handshake and stream splitting [src/r8r_bridge/mod.rs137-158](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L137-L158) It also enforces a `MAX_WS_MESSAGE_SIZE` of 1 MiB to prevent memory exhaustion [src/r8r_bridge/mod.rs38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L38-L38)

### Health Monitoring

The `start_health_ping_loop` function spawns a background task that sends periodic `HealthPing` events to r8r every `interval_secs` [src/r8r_bridge/health.rs23-38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/health.rs#L23-L38) The bridge also maintains the latest `HealthStatus` from r8r in an `Arc<Mutex<Option<BridgeEvent>>>` [src/r8r_bridge/mod.rs60-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L60-L61)

Sources: [src/r8r_bridge/health.rs15-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/health.rs#L15-L22) [src/r8r_bridge/mod.rs110-118](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/r8r_bridge/mod.rs#L110-L118)

## R8r Tool Integration

While the bridge handles background events, the `R8rTool` allows agents to actively trigger workflows and interact with the engine [src/tools/r8r.rs47-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L47-L51)

- Endpoint : Defaults to http://localhost:8080 but can be configured via the R8R_ENDPOINT environment variable src/tools/r8r.rs 41-45 src/tools/r8r.rs 91-95
- Actions : Supports run (execute), list (available workflows), status (poll execution), emit (publish event), and create (define new workflow) src/tools/r8r.rs 189-211
- Quota Check : Before execution, the tool can check against provider quotas to ensure cost limits aren't exceeded src/providers/quota.rs 170-174

Sources: [src/tools/r8r.rs52-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L52-L55) [src/tools/r8r.rs151-170](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L151-L170) [src/tools/r8r.rs217-220](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L217-L220) [src/providers/quota.rs68-77](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/quota.rs#L68-L77)
