feat: add coder/mux built-in adapter

[ThomasK33]

Summary

Adds mux (coder/mux) as a built-in ACP agent. acpx mux resolves to npx -y mux@^0.26.0 acp (version-pinned), launching coder/mux's ACP stdio bridge — no global install required.

mux exposes a real ACP agent via mux acp (built on @agentclientprotocol/sdk, stdio JSON-RPC) and ships as the unscoped npm package mux, so it slots into the existing npx-backed adapter pattern as a registry entry with no core changes. The version is pinned through ACP_ADAPTER_PACKAGE_RANGES, exactly like pi/codex/claude.

Changes

• src/agent-registry.ts — add mux to ACP_ADAPTER_PACKAGE_RANGES (^0.26.0) and the registry (npx -y mux@^0.26.0 acp, alphabetical between kiro and opencode)
• test/agent-registry.test.ts — registry resolution + ordering test
• agents/Mux.md — agent doc (mirrors the fast-agent template)
• docs/agents.md — registry table row + per-agent section
• README.md, docs/install.md, agents/README.md, skills/acpx/SKILL.md — registry/doc entries
• CHANGELOG.md — Unreleased entry

(Docs show the unversioned npx -y mux acp per the existing pi/codex/claude convention; the pin lives in code.)

Live verification (mux v0.26.1)

Ran end-to-end against a locally-configured mux (anthropic:claude-opus-4-8); the acpx adapter itself needs no provider key. Verbatim run:

$ acpx --approve-all --verbose --timeout 120 mux exec "Reply with exactly: ACPX-MUX-OK and nothing else."
[acpx] spawning agent: npx -y mux@^0.26.0 acp
[client] initialize (running)
[acp] Connecting to mux server…
[acp] Found lockfile, connecting to server at http://127.0.0.1:<port>
[acp] Connected to server at http://127.0.0.1:<port>
[acp] Starting ACP adapter — reading stdin
[acpx] initialized protocol version 1

[client] session/new (running)
ACPX-MUX-OK

[done] end_turn

Full path confirmed: acpx mux → spawns npx -y mux@^0.26.0 acp → ACP initialize (protocol v1) → mux auto-starts its in-process server → session/new → real prompt round-trips (model returned ACPX-MUX-OK, end_turn). mux installs cleanly via npx.

Notes (addressing the automated review)

• Version pinned: mux@^0.26.0 via ACP_ADAPTER_PACKAGE_RANGES (same mechanism as pi/codex/claude), so npx resolves a locked range rather than "latest" — the supply-chain mitigation the review asked for. A future bump is a one-line range change.
• Provider/key: the acpx adapter needs no key of its own; mux uses its configured provider. One-time mux setup: the project must be trusted (mux api projects set-trust) before session/new succeeds — a mux-side workspace gate, not an acpx concern.
• CHANGELOG: kept per AGENTS.md (add entries under CHANGELOG.md, grouped with the PR) and consistent with the prior fast-agent PR (feat: add fast-agent built-in adapter #350).
• SDK skew: mux bundles @agentclientprotocol/sdk ^0.14.1 vs acpx's ^0.22.1; both negotiate ACP protocol v1 at initialize (verified above).

Testing

• node --test dist-test/test/agent-registry.test.js → 16/16 pass (incl. new mux test + listBuiltInAgents ordering)
• markdownlint, oxfmt --check, oxlint --type-aware clean; pre-commit build (tsdown) passes

🤖 Generated with Claude Code

[clawsweeper]

Codex review: found issues before merge. Reviewed June 4, 2026, 9:43 AM ET / 13:43 UTC.

Summary
The PR adds mux as a built-in agent command, registry test coverage, harness docs, install docs, acpx skill docs, and a changelog entry.

Reproducibility: not applicable. as a bug reproduction: this is a feature PR adding a new built-in adapter. The PR body gives a concrete live terminal proof path for the new behavior.

Review metrics: 3 noteworthy metrics.

• Changed surface: 9 files, +34/-1. The patch touches runtime registry, tests, shared docs, harness docs, skill docs, install docs, and changelog, so both product-surface and docs policy matter.
• New built-in command: 1 added: mux -> npx -y mux@^0.26.0 acp. A built-in command becomes stable user-facing product surface and controls what acpx executes by default.
• External install hook: 1 postinstall script in mux@0.26.1 metadata. The package currently satisfying the range runs install-time lifecycle code, which maintainers should accept deliberately before blessing it as a built-in.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Get maintainer approval for mux as a core built-in and for the npm launch boundary.
• Remove the CHANGELOG.md edit and keep release-note context in the PR body.
• [P2] Reorder the touched harness docs list so it follows the required built-in precedence.

Risk before merge

• [P1] Merging this PR makes mux a stable user-facing keyword and default command, so future compatibility depends on coder/mux provider setup, project trust behavior, and ACP compatibility outside acpx.
• [P1] The default command would auto-fetch and execute mux@^0.26.0; the currently resolving package metadata includes a postinstall lifecycle script and broad dependencies, so maintainers need to accept that supply-chain boundary explicitly.
• [P1] The PR still needs low-risk policy cleanup in release-owned changelog handling and the touched harness-doc list ordering before it is merge-ready.

Maintainer options:

1. Approve the built-in launch boundary (recommended)
   Have a maintainer explicitly decide that mux belongs in core and that the mux@^0.26.0 npm execution boundary is acceptable before merge.
2. Rework the launch model first
   If maintainers want deterministic acpx-owned launch behavior, rework the adapter into explicit built-in launch metadata with focused tests instead of adding only a loose registry command string.
3. Keep mux outside core for now
   If the supply-chain or setup boundary is too broad for a core keyword, pause or close this PR and point users to a custom agent command until policy changes.

Next step before merge

• [P2] Maintainers need to decide the core built-in and third-party package execution policy; automation can clean up the P3 docs/changelog issues after that decision but should not choose the product or supply-chain boundary.

Security
Needs attention: No malicious behavior is evident, but the PR adds a new third-party npm execution path as a built-in command and needs maintainer supply-chain acceptance.

Review findings

• [P3] Remove the release-owned changelog edit — CHANGELOG.md:14
• [P3] Reorder the touched harness docs list — agents/README.md:34

Review details

Best possible solution:

Land the adapter only if maintainers explicitly approve mux as a core built-in and accept its launch boundary, with the release-owned changelog edit removed and the touched docs ordered according to repo policy.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature PR adding a new built-in adapter. The PR body gives a concrete live terminal proof path for the new behavior.

Is this the best way to solve the issue?

Unclear until maintainer policy is settled: the registry and docs patch is narrow and live-proofed, but adding a core keyword for this npm execution path is a product and supply-chain decision.

Full review comments:

• [P3] Remove the release-owned changelog edit — CHANGELOG.md:14
  The ClawSweeper/OpenClaw release-note review contract treats CHANGELOG.md as release-owned for normal PRs, so this feature PR should keep release-note context in the PR body instead of adding an Unreleased line.
  Confidence: 0.86
• [P3] Reorder the touched harness docs list — agents/README.md:34
  AGENTS.md requires built-in example sets to preserve the pi, openclaw, codex, claude, gemini, cursor, copilot precedence. While adding Mux in this touched list, also move the existing Gemini and Cursor entries ahead of Copilot so the PR does not preserve the ordering violation.
  Confidence: 0.78

Overall correctness: patch is correct
Overall confidence: 0.84

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 1522159f9fd8.

Label changes

Label justifications:

• P2: This is a normal-priority built-in adapter feature with limited blast radius but real product and supply-chain review needs.
• merge-risk: 🚨 compatibility: The new mux keyword and default command become stable product surface and depend on mux-side provider/trust behavior outside acpx.
• merge-risk: 🚨 security-boundary: The default command downloads and executes a third-party npm package that currently declares install-time lifecycle behavior.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body includes after-change terminal output showing acpx mux spawning npx -y mux@^0.26.0 acp, completing ACP initialize/session creation, returning the expected prompt text, and ending the turn.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-change terminal output showing acpx mux spawning npx -y mux@^0.26.0 acp, completing ACP initialize/session creation, returning the expected prompt text, and ending the turn.

Evidence reviewed

Security concerns:

• [medium] Accept third-party package execution as a built-in — src/agent-registry.ts:50
  Adding mux makes acpx mux auto-fetch and run mux@^0.26.0; the current npm metadata for the resolving package includes a postinstall script and broad dependencies, so this should be an explicit maintainer decision before merge.
  Confidence: 0.9

What I checked:

• Repository policy read: Read AGENTS.md fully; its guidance that built-in names are product surface, example ordering is mandatory, harness docs must be synchronized, and registry-name changes require full checks is relevant to this PR. (AGENTS.md:41, 1522159f9fd8)
• Current main lacks mux: Current main has no mux built-in or docs entry; the local mux hits are unrelated TMUX/trust references and package-exec implementation details. (src/agent-registry.ts:38, 1522159f9fd8)
• PR diff adds built-in command: The PR head adds mux to ACP_ADAPTER_PACKAGE_RANGES and maps AGENT_REGISTRY.mux to npx -y mux@^0.26.0 acp, creating a new user-facing built-in keyword. (src/agent-registry.ts:50, 82ffbc8e8a03)
• Live behavior proof: The updated PR body includes terminal output for acpx --approve-all --verbose --timeout 120 mux exec ... showing spawn, ACP initialize, session creation, the expected ACPX-MUX-OK response, and end_turn. (82ffbc8e8a03)
• Supply-chain metadata: The npm registry metadata for mux@0.26.1, which satisfies the PR's ^0.26.0 range, declares a postinstall lifecycle script and a large dependency surface, making the built-in launch path a concrete supply-chain boundary.
• Launch ownership context: The in-repo launch ownership note says acpx should own built-in adapter package, version, resolution, and launch behavior; it treats implicit npx-style fallback as a compatibility bridge rather than the ideal end state. (docs/2026-04-06-built-in-agent-launch-ownership.md:28, 1522159f9fd8)

Likely related people:

• steipete: Git blame shows the current registry baseline and initial supported-agent docs came from the repository import/changelog preparation history. (role: introduced registry and docs baseline; confidence: high; commits: 00e4c9452290; files: src/agent-registry.ts, README.md, agents/README.md)
• osolmaz: Recently authored the merged fast-agent built-in adapter change across the same registry, tests, docs, skill, and changelog surfaces. (role: recent adjacent contributor; confidence: high; commits: e4d0e3a2f4a9; files: src/agent-registry.ts, test/agent-registry.test.ts, agents/FastAgent.md)
• dutifulbob: Authored the built-in launch ownership work and documentation that is directly relevant to adding another npx-backed built-in adapter. (role: launch ownership contributor; confidence: medium; commits: 1d61d4b23102; files: docs/2026-04-06-built-in-agent-launch-ownership.md, src/acp/client.ts, src/agent-registry.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.