refactor(broker): group Relaycast integration modules

[willwashburn]

Summary

• Move broker Relaycast auth/session, websocket/HTTP transport, event and command mapping, and multi-workspace session code under relaycast::*.
• Update runtime and worker callers to import through relay_broker::relaycast.
• Keep thin compatibility re-exports for the previous top-level module paths.

Closes #877

Verification

• cargo check
• cargo test
• cargo fmt -- --check
• cargo clippy -- -D warnings
• cargo test --release
• npm run -w @agent-relay/sdk check
• npm test (rerun outside sandbox; sandboxed run only failed on localhost bind / ~/.relay permissions)

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR reorganizes Relaycast broker integration code under a dedicated crates/broker/src/relaycast/ module tree with submodules for auth, WebSocket/HTTP, event mapping, and multi-workspace sessions. Old modules become re-exports; all internal callers update to the unified relay_broker::relaycast import path. Trajectory metadata documents the refactor.

Changes

Relaycast module restructuring

Layer / File(s)	Summary
Module structure and public API boundary crates/broker/src/lib.rs, crates/broker/src/relaycast/mod.rs	lib.rs adds pub mod relaycast; to export the relaycast module tree. relaycast/mod.rs declares six public submodules (auth, bridge, dm_participants, identity, workspace, ws) and re-exports all key types: auth/session/cache structs, WebSocket/HTTP clients, event mapping functions, workspace session types, and identity/cache helpers.
Authentication and credential management crates/broker/src/relaycast/auth.rs	Implements full Relaycast auth client with credential data models supporting multiple JSON shapes (current, legacy single, legacy array, workspace-source objects). Provides async startup flows for single/multi-workspace sessions with optional strict agent naming, environment configuration parsing (RELAY_WORKSPACES_JSON, RELAY_DEFAULT_WORKSPACE), workspace creation with UUID-suffixed conflict retry, agent registration with request-name handling, token rotation with 404 fallback, and workspace key liveness probing. Includes 519 lines of comprehensive async tests using httpmock covering registration flows, naming conflicts, token rotation, and liveness behavior.
WebSocket and HTTP client implementation crates/broker/src/relaycast/ws.rs	Implements RelaycastWsClient with reconnecting websocket loop that enables workspace streaming, manages per-channel subscriptions with reference counting, merges websocket events to JSON, and emits connection status updates. Implements RelaycastHttpClient with workspace/agent client caching, token lifecycle (seeding, registration, rotation), agent offline marking, DM/channel message sending with injection mode mapping, workspace stream/channel provisioning (with 409 conflict handling), DM/channel message history retrieval, and DM participant list fetching. Includes registration retry helpers and unit tests for retryability and preregistration error formatting.
Event mapping and command parsing crates/broker/src/relaycast/bridge.rs	Implements map_ws_event to convert Relaycast WS events to InboundRelayEvent with multi-candidate extraction for sender/target/text across nested JSON shapes, DM conversation rewriting, event-kind parsing, and synthetic ID generation via hashing. Implements map_ws_broker_command to extract /spawn and /release commands with typed SpawnParams/ReleaseParams. Adds EventNesting abstraction for navigating nested event payloads. Includes 573 lines of tests covering accessor reads, event shape variants, DM/thread/channel routing, sender identity normalization, reaction handling, malformed event dropping, and command parsing behavior.
Multi-workspace session management crates/broker/src/relaycast/workspace.rs	Introduces WorkspaceInboundMessage (JSON payload plus workspace identity) and WorkspaceSessionHandle (per-workspace HTTP/websocket client, self metadata). MultiWorkspaceSession::new constructs one handle per authenticated membership, merges per-workspace websocket output into single inbound stream via spawned tasks, optionally augments self_names from .mcp.json using MCP environment pointer. Provides is_multi_workspace(), membership_summaries() with default selection, handle_by_selector() (ID or case-insensitive alias), default_handle(), and http_clients_by_workspace_id() query methods.
Cache and identity helper visibility expansion crates/broker/src/relaycast/dm_participants.rs, crates/broker/src/relaycast/identity.rs	Widens DM_PARTICIPANT_CACHE_TTL/FAILURE_TTL, DmParticipantsCacheEntry, DmParticipantsCache, and resolve_dm_participants_cached from pub(crate) to pub; updates HTTP client parameter type from relay_broker::relaycast_ws::RelaycastHttpClient to super::RelaycastHttpClient. Exposes agent_name_eq and is_self_name as pub.
Old module conversions to re-exports crates/broker/src/auth.rs, crates/broker/src/message_bridge.rs, crates/broker/src/multi_workspace.rs, crates/broker/src/relaycast_ws.rs, crates/broker/src/main.rs	auth.rs, message_bridge.rs, multi_workspace.rs, and relaycast_ws.rs become single-line pub use crate::relaycast::<submodule>::*; re-exports, removing ~2,680 lines of implementation. main.rs removes mod relaycast; declaration since relaycast is now a public crate module.
Import path updates across the broker crates/broker/src/cli_mcp_args.rs, crates/broker/src/listen_api.rs, crates/broker/src/runtime/mod.rs, crates/broker/src/runtime/tests.rs, crates/broker/src/spawner.rs, crates/broker/src/worker.rs, crates/broker/src/wrap.rs	Nine files update imports to pull relaycast items from relay_broker::relaycast instead of scattered modules (message_bridge, multi_workspace, relaycast_ws, snippets), consolidating fragmented dependencies into a single integration boundary.
Trajectory and completion metadata .trajectories/completed/2026-05/traj_5qbla7w4kzoi.json, .trajectories/completed/2026-05/traj_5qbla7w4kzoi.md, .trajectories/index.json	Adds completed trajectory record documenting issue #877 fix, including task metadata, completion timestamps, and a summary of the Relaycast broker integration refactoring. Updates the trajectories index with new entry metadata.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• AgentWorkforce/relay#907: Refactors relaycast module code, specifically updating shared dm_participants.rs cache representation and identity.rs name comparison helpers used by both PRs.
• AgentWorkforce/relay#835: Updates Relaycast authentication strict-name handling logic via the register_or_get_agent SDK flow, which this PR now exports under crates/broker/src/relaycast/auth.rs.

Suggested reviewers

• khaliqgant
• barryollama

---

🐰 Relaycast now lives in one neat tree,
No more scattered modules to see!
Auth, bridge, and WS in their place,
Clear boundaries grace the crate's space. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: refactoring Relaycast integration modules under a unified namespace.
Description check	✅ Passed	The description includes a summary section, verification steps, and links the PR to issue #877, meeting the template requirements.
Linked Issues check	✅ Passed	The PR implements all acceptance criteria from issue #877: groups Relaycast code under relaycast::*, provides a clear import surface via relay_broker::relaycast, moves tests alongside modules, and maintains protocol behavior.
Out of Scope Changes check	✅ Passed	All changes are directly related to issue #877 objectives. The trajectory files (.trajectories/) document the completed work but are metadata artifacts, not code changes.
Docstring Coverage	✅ Passed	Docstring coverage is 83.44% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-877-relaycast-module

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.trajectories/completed/2026-05/traj_5qbla7w4kzoi.json:
- Line 51: Replace the absolute local path value for the JSON key "projectId"
with a repo-relative or neutral identifier (e.g., "relay" or "./relay") so the
metadata is portable and doesn't leak user-specific info; locate the "projectId"
entry in the trajectory JSON and change the value from
"/Users/will/Projects/AgentWorkforce/relay" to a repo-relative slug or
environment-driven placeholder (e.g., "relay" or "${REPO_NAME}") and ensure any
generator/saver that writes this file uses a repo-relative value instead of an
absolute home path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 433b6f06-90a5-45ff-9921-88502b7f43a2

📥 Commits

Reviewing files that changed from the base of the PR and between 9b20510 and cd8864d.

📒 Files selected for processing (23)

• .trajectories/completed/2026-05/traj_5qbla7w4kzoi.json
• .trajectories/completed/2026-05/traj_5qbla7w4kzoi.md
• .trajectories/index.json
• crates/broker/src/auth.rs
• crates/broker/src/cli_mcp_args.rs
• crates/broker/src/lib.rs
• crates/broker/src/listen_api.rs
• crates/broker/src/main.rs
• crates/broker/src/message_bridge.rs
• crates/broker/src/multi_workspace.rs
• crates/broker/src/relaycast/auth.rs
• crates/broker/src/relaycast/bridge.rs
• crates/broker/src/relaycast/dm_participants.rs
• crates/broker/src/relaycast/identity.rs
• crates/broker/src/relaycast/mod.rs
• crates/broker/src/relaycast/workspace.rs
• crates/broker/src/relaycast/ws.rs
• crates/broker/src/relaycast_ws.rs
• crates/broker/src/runtime/mod.rs
• crates/broker/src/runtime/tests.rs
• crates/broker/src/spawner.rs
• crates/broker/src/worker.rs
• crates/broker/src/wrap.rs

💤 Files with no reviewable changes (1)

• crates/broker/src/main.rs

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Avoid committing absolute local paths in trajectory metadata.

Line 51 embeds a machine-specific path (/Users/will/...), which leaks local user identity and makes metadata non-portable across environments. Prefer repo-relative identifiers/paths.

Proposed fix

-  "projectId": "/Users/will/Projects/AgentWorkforce/relay",
+  "projectId": "AgentWorkforce/relay",

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"projectId": "/Users/will/Projects/AgentWorkforce/relay",
	"projectId": "AgentWorkforce/relay",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.trajectories/completed/2026-05/traj_5qbla7w4kzoi.json at line 51, Replace
the absolute local path value for the JSON key "projectId" with a repo-relative
or neutral identifier (e.g., "relay" or "./relay") so the metadata is portable
and doesn't leak user-specific info; locate the "projectId" entry in the
trajectory JSON and change the value from
"/Users/will/Projects/AgentWorkforce/relay" to a repo-relative slug or
environment-driven placeholder (e.g., "relay" or "${REPO_NAME}") and ensure any
generator/saver that writes this file uses a repo-relative value instead of an
absolute home path.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.