feat(mux): out-of-tree backend discovery via bmad_loop.mux_backends entry points by pbean · Pull Request #145 · bmad-code-org/bmad-loop

pbean · 2026-07-14T21:32:22Z

Summary

Adds the discovery seam that lets an adapter package co-installed with bmad-loop (uv tool install --with ... / same-venv pip) register its multiplexer backend with no config step: _select() and detect_multiplexers() scan the bmad_loop.mux_backends entry-point group after the builtin load and import each advertised module, whose import-time register_multiplexer() call does the rest.

This is the first of two PRs moving the herdr backend out-of-tree to pbean/bmad-loop-adapter-herdr (the extraction PR follows once this lands).

Design points

Builtins register first, so tmux keeps first-wins on a name collision and default selection is unchanged by merely installing an adapter.
A broken distribution can never break selection: each ep.load() failure (and a failing scan itself) is recorded in _EXTERNAL_ERRORS and surfaced — a warning: line under the bmad-loop mux table and a non-fatal advisory note in the validate preflight (external_backend_errors()).
Loaded-flag is set up front, unlike _BUILTINS_LOADED: a third-party import failure is not transient, and retrying would re-import (and re-fail) on every selection. Documented inline.

Tests

New tests/test_external_backends.py (8 tests): fake entry point registers a stub → listed by detect_multiplexers + selectable via BMAD_LOOP_MUX_BACKEND; ep.load() raises → tmux still selected, error recorded, mux output shows the warning; entry_points() itself raises → graceful degrade; externals-load-after-builtins ordering; plus one test placing a real *.dist-info on sys.path to prove the group/value convention against genuine packaging metadata.
fresh_registry extended to park _EXTERNALS_LOADED=True by default so installed adapters can't leak into builtin-selection tests; the discovery tests re-arm it explicitly.
Full suite: 2327 passed in both inside-tmux and TMUX-less environments; trunk check clean.

Docs

"Shipping out-of-tree" section in porting-to-a-new-os.md (+ authoring-guide cross-link) naming pbean/bmad-loop-adapter-herdr as the reference external adapter.

Summary by CodeRabbit

New Features
- Added support for automatically discovering multiplexer backends from separately installed packages.
- External backends are available without additional configuration and preserve built-in backend precedence.
- Backend loading failures no longer prevent selection; bmad-loop mux and validate now surface advisory warnings.
Documentation
- Added guidance for installing, registering, and troubleshooting external multiplexer backends.

…ntry points An adapter package co-installed with bmad-loop (uv tool install --with / same-venv pip) now registers its backend with no config step: _select() and detect_multiplexers() scan the bmad_loop.mux_backends entry-point group after the builtin load and import each advertised module, whose import-time register_multiplexer() call does the rest. Builtins register first, so tmux keeps first-wins on a name collision and default selection is unchanged by installing an adapter. A broken distribution can never break selection: each ep.load() failure (and a failing scan itself) is recorded in _EXTERNAL_ERRORS and surfaced — a warning line under the `bmad-loop mux` table and an advisory note in the validate preflight (external_backend_errors()). The loaded-flag is set up front, unlike _BUILTINS_LOADED: a third-party import failure is not transient, and retrying would re-import (and re-fail) on every selection. fresh_registry parks the scan as already-done (installed adapters must not leak into builtin-selection tests); the discovery tests re-arm it explicitly, and one exercises a real *.dist-info on sys.path to prove the group/value convention against genuine packaging metadata. Docs: 'Shipping out-of-tree' section in porting-to-a-new-os.md (+ authoring- guide cross-link) naming pbean/bmad-loop-adapter-herdr as the reference external adapter.

pbean · 2026-07-14T22:07:50Z

@CodeRabbit review

coderabbitai · 2026-07-14T22:08:03Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai · 2026-07-14T22:08:12Z

Warning

Review limit reached

@pbean, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 50 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9db9ec2-a357-43f8-b8ab-d5b29a718fb3

📥 Commits

Reviewing files that changed from the base of the PR and between 71c9583 and 200d861.

📒 Files selected for processing (1)

tests/test_external_backends.py

Walkthrough

Adds entry-point discovery for out-of-tree multiplexer backends, loading them before selection and recording import failures. CLI mux and validate commands surface those failures as warnings or notes, with tests covering discovery, precedence, degradation, isolation, and real package metadata.

Changes

External multiplexer backends

Layer / File(s)	Summary
Entry-point discovery and registration `src/bmad_loop/adapters/multiplexer.py`, `docs/...`, `CHANGELOG.md`	Scans `bmad_loop.mux_backends` entry points after builtins, registers loaded backends, and records import failures without raising.
CLI diagnostic reporting `src/bmad_loop/cli.py`	Reports failed external backend loads in `validate` notes and `mux` stderr warnings while preserving normal selection and table output.
Discovery isolation and coverage `tests/test_backend_registry.py`, `tests/test_external_backends.py`	Tests successful discovery, ordering, failure isolation, scan-once behavior, CLI reporting, and genuine package metadata discovery.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

bmad-code-org/bmad-loop#118: Both changes update multiplexer selection and CLI diagnostics around backend availability and precedence.

Suggested reviewers: dracic

Poem

I’m a rabbit who hops through the entry-point gate,
Registering backends before it’s too late.
If one import breaks, I leave a small note,
While good muxes still merrily float.
Warnings in stderr, validation bright—
The backend burrow is tidy tonight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.07% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: out-of-tree multiplexer backend discovery via entry points.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/mux-external-discovery

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

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

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 `@tests/test_external_backends.py`:
- Around line 166-186: Update test_mux_command_surfaces_load_failures to discard
the unused first value from scan_registry while retaining the arm helper used to
register the broken entry point; do not change the test’s assertions or command
behavior.

🪄 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

Run ID: b02c0d29-ce62-47c1-8b39-02dabeb19d2f

📥 Commits

Reviewing files that changed from the base of the PR and between 25c221d and 71c9583.

📒 Files selected for processing (7)

CHANGELOG.md
docs/adapter-authoring-guide.md
docs/porting-to-a-new-os.md
src/bmad_loop/adapters/multiplexer.py
src/bmad_loop/cli.py
tests/test_backend_registry.py
tests/test_external_backends.py

coderabbitai Bot reviewed Jul 14, 2026

View reviewed changes

Comment thread tests/test_external_backends.py

test: discard unused registry unpack in mux-command test (RUF059)

200d861

pbean merged commit 9d89efb into main Jul 14, 2026
9 checks passed

This was referenced Jul 14, 2026

refactor(mux)!: extract the herdr backend to pbean/bmad-loop-adapter-herdr #146

Merged

herdr: native-Windows launch surface (agent.start launch, pwsh parked dialect, Windows-host re-characterization) #140

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(mux): out-of-tree backend discovery via bmad_loop.mux_backends entry points#145

feat(mux): out-of-tree backend discovery via bmad_loop.mux_backends entry points#145
pbean merged 2 commits into
mainfrom
feat/mux-external-discovery

pbean commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

pbean commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Review limit reached

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

pbean commented Jul 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Design points

Tests

Docs

Summary by CodeRabbit

Uh oh!

pbean commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pbean commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading