Hybrid relay-broker integration: best of #412 + #404

[khaliqgant]

Summary

Integrates the Rust relay-broker into the main repo using a hybrid approach that combines the best code quality from PR #412 with the backward compatibility of PR #404.

• Adds relay-broker/ Rust binary from PR start broker integration #404 (additive, preserves all existing TS packages)
• Applies 5 critical bug fixes cherry-picked from PR Migrate Relay-broker into relay main #412's superior Rust codebase
• Remediates committed live API key found in PR start broker integration #404
• Adds backward-compatibility shims so relay-dashboard and relay-cloud continue to work without changes

Bug fixes from PR #412:

1. Security: sender identity spoofing — agents could name themselves human:... to bypass release ACL checks
2. URL double-path — Relaycast WS URLs with /stream base produced invalid host/stream/v1/stream
3. Function name typo — ensure_reaycast_mcp_config → ensure_relaycast_mcp_config
4. Unbounded message coalescing — added 32 KiB MAX_COALESCED_BODY_SIZE cap
5. Code duplication — exported terminate_child as pub instead of duplicating inline

Compatibility shims:

• @agent-relay/utils/relay-pty-path re-exported as alias for agent-relay-path
• RelayPtyOrchestrator re-exported as alias for RelayBrokerOrchestrator
• AGENT_RELAY_BINARY env var with legacy RELAY_PTY_BINARY fallback

Security:

• ACTION REQUIRED: Rotate leaked key rk_live_b00fd0ddeca96468d72140c9c4b3a910 (was committed in PR start broker integration #404, removed in this PR but still in git history)

Validation Matrix

Repo	Check	Status
relay	Rust broker tests (139)	✅ PASS
relay	Utils shim tests (37)	✅ PASS
relay-cloud	npm build	✅ PASS
relay-cloud	TypeScript compile	✅ PASS
relay-cloud	Runtime import checks	✅ PASS
relay-dashboard	Server build	✅ PASS
relay-dashboard	Runtime alias imports	✅ PASS
relay-dashboard	Full UI build (Next prerender)	⚠️ Pre-existing issue, unrelated

Context: Why hybrid?

• PR Migrate Relay-broker into relay main #412 had better Rust code (telemetry, SDK, security fixes) but deleted 178K lines of TS packages, breaking both relay-dashboard and relay-cloud
• PR start broker integration #404 was more incremental but had bugs, merge conflicts, a leaked API key, and was 11 commits behind main
• This PR branches from main, takes the relay-broker structure from start broker integration #404, applies Migrate Relay-broker into relay main #412's fixes, and adds compatibility shims — shipping quality code today without downstream breakage
• PR Migrate Relay-broker into relay main #412 remains the v3 migration track for the eventual full Rust transition

Collaborators

This PR was produced by a multi-agent team coordinated via Agent Relay:

Agent	Role	Model	Harness
Broker-1	PR analysis, Rust fix backports, secret remediation, test validation	Claude Opus 4.6	Agent Relay (claude)
Broker-2	Cross-repo dependency analysis, compatibility shims, smoke test matrix	GPT-5	Codex CLI + Agent Relay
Dashboard	Coordination, approval, task direction	—	Agent Relay Dashboard

Decisions and reasoning recorded via trail — see .trajectories/ for full trajectory.

Test plan

• Rust broker tests pass (139/139)
• Utils shim tests pass (37/37)
• relay-cloud builds and compiles
• relay-dashboard server builds
• Runtime import alias checks pass
• Rotate leaked API key
• Manual end-to-end: spawn agent via broker, send messages, verify dashboard

🤖 Generated with Claude Code

[devin-ai-integration]

Devin Review found 3 potential issues.

🐛 1 issue in files not directly in the diff

🐛 Panic on multi-byte UTF-8 in listen-mode message truncation (relay-broker/src/main.rs:1168)

In main.rs listen mode, relay message text is truncated using byte-level slicing &mapped.text[..120] which will panic if byte 120 falls in the middle of a multi-byte UTF-8 character.

Root Cause

At relay-broker/src/main.rs:1167-1168, the code checks mapped.text.len() > 120 (byte length) and then slices at byte 120:

if mapped.text.len() > 120 {
    format!("{}…", &mapped.text[..120])  // PANIC if byte 120 is mid-character
}

The mapped.text field contains user-generated relay messages which commonly include emoji (👋, 🚀), CJK characters, or other multi-byte UTF-8 content. When such a message exceeds 120 bytes, the byte-level slice will panic with byte index 120 is not a char boundary.

Note that the codebase already has a floor_char_boundary helper function defined at relay-broker/src/main.rs:2864-2873 that correctly handles this case, but it's not used here.

Impact: Any relay message in listen mode containing multi-byte UTF-8 characters that exceeds 120 bytes will crash the broker.

View 11 additional findings in Devin Review.