refactor(broker): narrow public crate API

[willwashburn]

Summary

• narrow the Rust broker crate public surface to protocol, snippets, and run_cli
• route the broker binary through the library so implementation modules can be pub(crate)
• move broad broker and worker tests into colocated module test blocks
• document the Rust API break in the changelog

Closes #878

Verification

• cargo fmt --check
• cargo clippy -- -D warnings
• cargo test --release

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 77fe18f5-b24e-4e35-a355-3a8b4117d33b

📥 Commits

Reviewing files that changed from the base of the PR and between c54e118 and 10454ed.

📒 Files selected for processing (27)

• .trajectories/completed/2026-05/traj_zqwco4gl76g3.json
• .trajectories/completed/2026-05/traj_zqwco4gl76g3.md
• .trajectories/index.json
• CHANGELOG.md
• crates/broker/src/broker.rs
• crates/broker/src/broker_tests.rs
• crates/broker/src/cli/mod.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/pty_worker.rs
• crates/broker/src/relaycast/mod.rs
• crates/broker/src/relaycast/ws.rs
• crates/broker/src/routing.rs
• crates/broker/src/runtime/delivery.rs
• crates/broker/src/runtime/event_loop.rs
• crates/broker/src/runtime/init.rs
• crates/broker/src/runtime/maintenance.rs
• crates/broker/src/runtime/mod.rs
• crates/broker/src/runtime/session.rs
• crates/broker/src/runtime/tests.rs
• crates/broker/src/spawner.rs
• crates/broker/src/wait.rs
• crates/broker/src/worker.rs
• crates/broker/src/worker_tests.rs
• crates/broker/src/wrap.rs

💤 Files with no reviewable changes (2)

• crates/broker/src/worker_tests.rs
• crates/broker/src/broker_tests.rs

---

📝 Walkthrough

Walkthrough

This PR implements issue #878 by narrowing the relay_broker crate's public API to only protocol, snippets, and a new run_cli() function, making all implementation modules crate-private, consolidating unit tests into inline #[cfg(test)] blocks, and updating internal imports to use local crate:: paths. The broker binary is simplified to call the library's public entry point.

Changes

Broker Crate Public API Narrowing

Layer / File(s)	Summary
Public API surface definition crates/broker/src/lib.rs	lib.rs module declarations reduce public exports to only pub mod protocol and pub mod snippets; all other modules become pub(crate) or are removed entirely. A new pub async fn run_cli() entry point forwards execution to the internal CLI module, establishing the intended public API boundary.
Binary entrypoint through public API crates/broker/src/main.rs, crates/broker/src/cli/mod.rs	main.rs is simplified to call relay_broker::run_cli().await instead of invoking a local cli::run(), removing module declarations and test wiring. CLI module imports are adjusted to reference crate::protocol and crate::telemetry instead of relay_broker:: paths.
Test consolidation and inline test modules crates/broker/src/broker.rs, crates/broker/src/worker.rs, crates/broker/src/listen_api.rs	Unit tests move from standalone broker_tests.rs and worker_tests.rs files into colocated #[cfg(test)] mod tests blocks within broker.rs (covering BrokerState default initialization, JSON persistence, missing-file handling, and reap_dead_agents() semantics) and worker.rs (covering WorkerRegistry initialization, lookups, path traversal rejection, and environment value resolution). Test imports throughout the codebase are updated to use local crate:: paths.
Internal module import path updates crates/broker/src/ (16 files)	All internal files update imports from relay_broker::* to crate::* across protocol types, relaycast utilities, types, snapshot, events, crash_insights, supervisor, and other modules. This follows the public API narrowing by using local paths for now-private modules in: broker.rs, cli_mcp_args.rs, pty_worker.rs, routing.rs, runtime/delivery.rs, runtime/event_loop.rs, runtime/init.rs, runtime/maintenance.rs, runtime/mod.rs, runtime/session.rs, runtime/tests.rs, spawner.rs, and wrap.rs.
Submodule and re-export visibility narrowing crates/broker/src/relaycast/mod.rs, crates/broker/src/relaycast/ws.rs, crates/broker/src/wait.rs	Relaycast submodules (auth, bridge, dm_participants, identity, workspace, ws) are changed from pub mod to pub(crate) mod. Re-export lists are narrowed to only essential internal symbols, removing public auth::{AuthSession, AuthSessionSet, CredentialCache, CredentialSet}, bridge::to_inject_request, ws::{registration_is_retryable, RelaycastWsClient}, and MCP config helpers; test-only re-exports are guarded with #[cfg(test)]. The for_cli module in wait.rs becomes pub(crate) instead of pub.
Release notes and trajectory documentation CHANGELOG.md, .trajectories/completed/2026-05/*, .trajectories/index.json	A breaking-change entry in 6.2.2 documents that relay_broker now exposes only protocol, snippets, and run_cli. Trajectory artifacts record the completed implementation, including decisions to consolidate tests, narrow submodule visibility, and verify formatting/linting/tests.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• AgentWorkforce/relay#870: Refactors snapshot types and routing, which is directly updated in this PR to use local crate::snapshot::Snapshot imports.
• AgentWorkforce/relay#907: Preceding refactor of broker internals into focused modules whose visibility is now restricted in this PR via the pub(crate) narrowing pattern.
• AgentWorkforce/relay#908: Subsequent PR that further restricts relaycast re-exports and registration helper visibility to test-only scopes.

Suggested reviewers

• khaliqgant
• barryollama

---

🐰 In burrows where the modules hide,
We've narrowed down the public side—
Just protocol and snippets bright,
Tests cozy in their homes tonight. 🏠
The binary hops through one clean door,
And Rust API breaks, forevermore! 🚪✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'refactor(broker): narrow public crate API' clearly and concisely summarizes the main objective of narrowing the broker crate's public API surface.
Description check	✅ Passed	The PR description covers the main objectives (narrow public API, route binary through library, move tests, document API break) and includes verification steps, though it could be more detailed about testing additions.
Linked Issues check	✅ Passed	The PR successfully implements all acceptance criteria from issue #878: narrows public API to protocol/snippets/run_cli, makes implementation modules pub(crate), moves broad tests into colocated test blocks, and documents the breaking change.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the scope of narrowing the broker crate public API and colocating tests; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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/878-narrow-broker-api

---

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.}

[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 4 additional findings.