feat: add fast-agent built-in adapter

[osolmaz]

Opened on behalf of Onur Solmaz (osolmaz). This PR is ready for review.

Summary

acpx did not have a friendly built-in name for EvalState fast-agent.
This change adds acpx fast-agent and points it at the fast-agent ACP entrypoint, uvx fast-agent-mcp acp.
The first convenience wrapper I tried, uvx fast-agent-acp, failed in a live startup test with a missing Python module, so the PR now uses the main fast-agent package command that actually initializes and serves ACP.
It also updates the supported-agent docs, the acpx skill, and tests so the new adapter is visible and verified like the other built-ins.

AI-assisted: yes.
I understand the change: it adds one registry mapping, documents the required uvx dependency, and tests that the CLI resolves the new built-in command correctly.

What Changed

The runtime registry now knows how to launch fast-agent through ACP.
The docs now list fast-agent anywhere the built-in registry is described.

• Added fast-agent -> uvx fast-agent-mcp acp to the built-in agent registry.
• Added registry and integration tests for the new built-in command path.
• Added agents/FastAgent.md and updated the README, docs site, install docs, acpx skill, and changelog.

Testing

This was tested with focused checks, full repo validation, and a real local fast-agent ACP run.
The live test used uvx, fast-agent-mcp 0.7.13, and a temporary fast-agent.yaml pointed at a local Ollama qwen2.5:0.5b model.

• pnpm run build:test && node --test dist-test/test/agent-registry.test.js dist-test/test/integration.test.js
• pnpm run check:docs
• pnpm run check
• Live startup failure found for the rejected command: node dist/cli.js --timeout 60 --format json fast-agent exec "Reply with exactly: acpx fast-agent live ok" when the built-in still used uvx fast-agent-acp; it failed before initialize with ModuleNotFoundError: No module named 'fast_agent_acp'.
• Live success for the final built-in command: with a temp cwd containing fast-agent.yaml (default_model: generic.qwen2.5:0.5b, local Ollama generic provider), node dist/cli.js --cwd "$tmp_cwd" --timeout 90 --format json fast-agent exec "Reply with exactly: acpx fast-agent live ok" initialized ACP, created a session, streamed assistant message chunks, and returned stopReason: end_turn.

Risks

The risk is low because this only adds a registry mapping and docs.
The main operational requirement is that users need uvx available on PATH and fast-agent model/provider configuration for real prompts.

[clawsweeper]

Codex review: found issues before merge. Reviewed May 29, 2026, 1:31 PM ET / 17:31 UTC.

Summary
The PR adds a fast-agent built-in adapter mapping to uvx fast-agent-mcp acp with matching docs, skill text, changelog, and registry/integration tests.

Reproducibility: not applicable. this is a feature PR rather than a bug report. The source check confirms current main lacks the built-in, and the PR body reports a live ACP startup proof for the new command.

Review metrics: 2 noteworthy metrics.

• PR surface: 10 files changed, +130/-37. The PR spans runtime registry, tests, main docs, per-agent docs, skill text, and changelog, so docs policy and compatibility review both matter.
• New built-in command: 1 registry name added. A new friendly agent name becomes stable user-facing API surface once released.

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 explicit maintainer approval or a compatibility path for reserving fast-agent.
• [P2] Fix the built-in docs ordering and move FastAgent-specific install detail out of the shared install overview.

Risk before merge

• [P2] Reserving fast-agent changes existing unknown-name fallback: current users with a local raw fast-agent ACP command would be routed to uvx fast-agent-mcp acp after upgrade.
• [P1] The new built-in introduces an operational dependency on uvx and external fast-agent configuration, which is a maintainer product decision for core.
• [P1] Docs still need policy cleanup so FastAgent does not break required built-in ordering or receive special placement in shared install docs.

Maintainer options:

1. Preserve raw command compatibility
   Change the approach so existing acpx fast-agent ... raw-command users keep a supported path before the built-in name is reserved.
2. Accept the reserved name intentionally
   Maintainers may approve the compatibility break if the fast-agent built-in name and uvx dependency are worth owning in core.
3. Defer to custom configuration
   If core should not own this convention yet, close or pause the PR and document FastAgent through per-user agents config instead.

Next step before merge

• [P2] Human maintainer review is needed because the central blocker is whether core should reserve the fast-agent convention and own the uvx dependency; the remaining docs fixes are secondary.

Security
Cleared: The diff adds an explicit user-invoked adapter command and docs/tests, with no workflow, secret, permission, lockfile, or publishing changes beyond the normal external-adapter execution model.

Review findings

• [P1] Preserve the raw fast-agent fallback before reserving it — src/agent-registry.ts:47
• [P2] Move FastAgent after the required prefix set — agents/README.md:29
• [P2] Keep FastAgent details out of the install overview — docs/install.md:24

Review details

Best possible solution:

Land a maintainer-approved built-in only after the compatibility decision is explicit and the docs follow the repository ordering and neutrality rules; otherwise keep FastAgent usage documented as a custom agent override.

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

Not applicable; this is a feature PR rather than a bug report. The source check confirms current main lacks the built-in, and the PR body reports a live ACP startup proof for the new command.

Is this the best way to solve the issue?

Unclear: the registry mapping is narrow, but the stable name reservation and uvx dependency require explicit maintainer approval before this is the best core solution.

Full review comments:

• [P1] Preserve the raw fast-agent fallback before reserving it — src/agent-registry.ts:47
  Today unknown positional agent names pass through as raw commands, so acpx fast-agent ... can launch a user's existing local ACP command. Adding this registry entry silently reroutes that same invocation to uvx fast-agent-mcp acp after upgrade; please add an explicit compatibility plan or get maintainer approval for the break before reserving the name.
  Confidence: 0.91
• [P2] Move FastAgent after the required prefix set — agents/README.md:29
  This harness-doc list is an example set of built-in agents, and AGENTS.md requires the pi, openclaw, codex, claude, gemini, cursor, copilot precedence not be broken. The new FastAgent entry lands before Cursor and Gemini, so reorder the list so the included required prefix is satisfied before adding the non-prefix tail.
  Confidence: 0.88
• [P2] Keep FastAgent details out of the install overview — docs/install.md:24
  The install overview is shared landing documentation, and the repo policy says non-primary harnesses must not receive special placement there. Move the uvx requirement to agents/FastAgent.md and the neutral agents reference instead of singling FastAgent out on the install page.
  Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live command evidence showing the final uvx fast-agent-mcp acp path initialized ACP and completed a prompt after the rejected wrapper failed.

Label justifications:

• P2: This is a normal-priority feature with limited blast radius, but it changes stable agent-name behavior.
• merge-risk: 🚨 compatibility: Merging reserves fast-agent, replacing the current raw unknown-name fallback for users who already invoke a local fast-agent ACP command.
• 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 (live_output): The PR body includes after-fix live command evidence showing the final uvx fast-agent-mcp acp path initialized ACP and completed a prompt after the rejected wrapper failed.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live command evidence showing the final uvx fast-agent-mcp acp path initialized ACP and completed a prompt after the rejected wrapper failed.

Evidence reviewed

What I checked:

• Repository policy applied: AGENTS.md was read fully; its guidance treats built-in names as stable product surface, requires scrutinizing naming conventions, and mandates the built-in example ordering prefix. (AGENTS.md:27, f6de6dd18aae)
• Current main lacks fast-agent: No fast-agent or FastAgent references exist in the current main tree, so the PR is not obsolete on main. (f6de6dd18aae)
• Registry mapping added by PR: The PR head reserves fast-agent as a built-in name resolving to uvx fast-agent-mcp acp. (src/agent-registry.ts:47, d8f053d0c4e3)
• Harness docs ordering issue remains: The PR inserts the FastAgent harness-doc entry before Cursor and Gemini in an example set where repository policy requires the built-in prefix order to be preserved. (agents/README.md:29, d8f053d0c4e3)
• Install docs single out fast-agent: The install page adds a FastAgent-specific uvx requirement in a shared install overview, which needs neutral placement or maintainer approval under the docs policy. (docs/install.md:24, d8f053d0c4e3)
• Real behavior proof in PR body: The PR body reports focused tests, full checks, a failed live startup for the rejected uvx fast-agent-acp command, and a successful live ACP startup using uvx fast-agent-mcp acp. (d8f053d0c4e3)

Likely related people:

• Peter Steinberger: Blame shows the current built-in registry and agents documentation baseline largely date to the v0.9.0 preparation commit. (role: registry and docs baseline author; confidence: high; commits: 00e4c9452290; files: src/agent-registry.ts, agents/README.md)
• osolmaz: Prior merged history shows Onur Solmaz authored Cursor ACP support, which is adjacent to adding another built-in adapter name. (role: adjacent built-in adapter contributor; confidence: medium; commits: 9141b63a4cc1; files: src/agent-registry.ts)
• GT: Recent history touched the built-in adapter range surface for Claude, adjacent to registry compatibility and launch behavior. (role: recent adapter registry contributor; confidence: medium; commits: fea7ee6e1456; files: 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f1a601d9d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Move FastAgent after the mandated prefix

In this harness-specific agent list, adding FastAgent here puts a non-prefix agent before cursor and gemini. The repo-level AGENTS.md Documentation Policy says that whenever multiple built-in agents appear in the same example set, the precedence pi, openclaw, codex, claude, gemini, cursor, copilot must not be broken, and PRs that introduce or preserve such ordering must be fixed before merge. Please place the new FastAgent entry after the mandated prefix order is satisfied.

Useful? React with 👍 / 👎.

[osolmaz]

closing so @evalstate can take over

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.