Add fast-agent to the Agents list

[evalstate]

This is an update to PR #350 by @osolmaz to normalise the name to fast-agent and point directly to the fast-agent.ai website. Tested.

Original text below.

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:20 PM ET / 17:20 UTC.

Summary
The branch adds fast-agent as a built-in ACP adapter via uvx fast-agent-mcp acp, with registry/integration coverage and docs, then normalizes the fast-agent branding and links.

Reproducibility: yes. for the review findings: current-main source inspection shows unknown agent names fall through as raw commands, and the branch adds a fast-agent registry key. The docs ordering and install-page concerns are directly visible in the branch files.

Review metrics: 2 noteworthy metrics.

• Stacked PR diff: 5 files changed, 12 additions, 9 deletions. The visible PR diff mostly normalizes fast-agent naming and links on top of the previous branch.
• Combined main delta: 10 files affected from main to head. Landing the work on the default branch would still change runtime registry, tests, public docs, harness docs, skill text, and changelog.

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 reserving fast-agent or choose an upgrade-safe alternative.
• [P2] Fix the shared docs ordering and remove non-primary harness setup detail from the install overview.
• Retarget or squash the stacked branch so maintainers can review the exact default-branch merge result.

Risk before merge

• [P2] Adding fast-agent as a built-in changes the current unknown-name fallback for users who already run a local raw fast-agent ACP command through acpx fast-agent ....
• [P1] The PR currently targets the closed codex/add-fast-agent-support branch rather than main, so maintainers need a retarget, squash, or branch-landing plan before it reaches the default branch.
• [P1] Docs policy issues remain in the combined branch: the harness-doc list preserves the required-order violation, and the install overview singles out a non-primary harness dependency.

Maintainer options:

1. Approve and document the reserved name
   Maintainers can intentionally reserve fast-agent and document the --agent fast-agent or config override path for users who need the raw command.
2. Choose a non-conflicting built-in path
   Before merge, rename or gate the built-in so existing raw fast-agent command users keep their current behavior by default.
3. Pause until the stack lands cleanly
   Because this PR targets the closed takeover branch, maintainers can pause or retarget it before reviewing the default-branch merge result.

Next step before merge

• [P2] Manual review is needed because the remaining blocker is a stable built-in name/product decision and stacked-branch landing plan, not only a mechanical docs edit.

Security
Cleared: No hidden security or supply-chain change was found beyond the explicit new uvx fast-agent-mcp acp command that runs only when users invoke the new built-in.

Review findings

• [P1] Preserve raw fast-agent users before reserving the name — src/agent-registry.ts:47
• [P2] Reorder the harness-doc list before adding fast-agent — agents/README.md:29
• [P2] Keep fast-agent setup details out of the install overview — docs/install.md:24

Review details

Best possible solution:

Land this only after maintainers explicitly accept the reserved fast-agent name, fix the shared-doc ordering and neutral-placement issues, and retarget or squash the combined branch onto main; otherwise keep fast-agent as custom agent configuration or harness-specific documentation.

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

Yes for the review findings: current-main source inspection shows unknown agent names fall through as raw commands, and the branch adds a fast-agent registry key. The docs ordering and install-page concerns are directly visible in the branch files.

Is this the best way to solve the issue?

Unclear: the implementation is narrow and the PR body includes live startup proof, but reserving a new positional name is a maintainer product decision. If maintainers accept the name, the docs ordering and neutral-placement issues should be repaired before merge.

Full review comments:

• [P1] Preserve raw fast-agent users before reserving the name — src/agent-registry.ts:47
  Current main treats unknown positional agents as raw commands, so acpx fast-agent ... can spawn a local fast-agent ACP command today. Adding fast-agent to AGENT_REGISTRY reroutes that token to uvx fast-agent-mcp acp; either get explicit maintainer approval with upgrade docs or choose a non-conflicting built-in name.
  Confidence: 0.88
• [P2] Reorder the harness-doc list before adding fast-agent — agents/README.md:29
  AGENTS.md requires the pi, openclaw, codex, claude, gemini, cursor, copilot precedence in every multi-agent example set. This changed harness-doc list still places Copilot, Droid, and fast-agent before Cursor and Gemini, so the PR preserves a docs-policy violation that must be fixed before merge.
  Confidence: 0.9
• [P2] Keep fast-agent setup details out of the install overview — docs/install.md:24
  The install page is a main landing doc, and AGENTS.md says non-primary harness details must not be singled out there. Move the uvx requirement to the harness-specific FastAgent doc or a neutral registry table before landing the combined branch.
  Confidence: 0.75

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a bounded feature PR with normal priority, but it changes stable user-facing registry behavior and docs.
• add merge-risk: 🚨 compatibility: The branch changes a currently raw positional token into a built-in mapping, which can break existing scripts using a local fast-agent command.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes concrete after-fix CLI proof: the rejected command, final live command, temporary configuration, and observed ACP session completion.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body includes concrete after-fix CLI proof: the rejected command, final live command, temporary configuration, and observed ACP session completion.

Label justifications:

• P2: This is a bounded feature PR with normal priority, but it changes stable user-facing registry behavior and docs.
• merge-risk: 🚨 compatibility: The branch changes a currently raw positional token into a built-in mapping, which can break existing scripts using a local fast-agent 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 concrete after-fix CLI proof: the rejected command, final live command, temporary configuration, and observed ACP session completion.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes concrete after-fix CLI proof: the rejected command, final live command, temporary configuration, and observed ACP session completion.

Evidence reviewed

What I checked:

• Repository policy read and applied: AGENTS.md makes agent names and documentation ordering product surface; it requires the built-in precedence order in every multi-agent example set and says PRs preserving violations must be fixed before merge. (AGENTS.md:142, f6de6dd18aae)
• Current main lacks fast-agent and falls back to raw commands: Current main has no fast-agent registry entry, and resolveAgentCommand returns the original token when no registry or alias match exists. (src/agent-registry.ts:106, f6de6dd18aae)
• Combined branch reserves the fast-agent name: The base branch this PR builds on adds "fast-agent": "uvx fast-agent-mcp acp" to the built-in registry, changing the behavior of that positional token from raw command fallback to built-in mapping. (src/agent-registry.ts:47, feec748d3fe8)
• Stacked PR diff is mostly naming cleanup: Against its stacked base, this PR changes 5 docs/changelog files with 12 additions and 9 deletions, normalizing the name and links rather than adding the registry entry itself. (95c0328e797f)
• Related predecessor was closed for handoff: The related predecessor at feat: add fast-agent built-in adapter #350 was closed unmerged after a member comment saying evalstate would take over, so it is not a safe superseding merge target.
• PR body includes live behavior proof: The PR body gives the rejected command, the final live command, the temporary fast-agent configuration shape, and the observed ACP initialization/session/end_turn result for uvx fast-agent-mcp acp. (95c0328e797f)

Likely related people:

• Peter Steinberger: Current blame for the materialized registry, agent docs, and repository policy surfaces points to the v0.9.0 preparation commit. (role: recent area contributor; confidence: high; commits: 00e4c9452290; files: src/agent-registry.ts, agents/README.md, docs/agents.md)
• GT: Recent main history changed the built-in adapter package ranges and tests in the same registry area. (role: adjacent registry contributor; confidence: medium; commits: fea7ee6e1456; files: src/agent-registry.ts, test/agent-registry.test.ts, CHANGELOG.md)

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.