Native ZeroClaw ACP runtime with agent alias configuration
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Motivation**
Buzz Desktop can run ZeroClaw successfully through a custom ACP runtime, but the setup currently requires users to understand implementation details from both products:
- Manually register a custom harness with command `zeroclaw` and argument `acp`.
- Configure a persistent ZeroClaw `[acp].default_agent` because a generic stdio ACP client does not send ZeroClaw's `agentAlias` extension.
- Put a ZeroClaw agent alias such as `fable` into model-shaped UI even though the alias selects an agent, not an underlying model.
- Diagnose an invalid `session/new` request only after the managed agent starts.
This makes an otherwise working integration difficult to discover and easy to misconfigure.
**Proposed solution**
Add ZeroClaw as a native managed-agent runtime alongside the existing runtime presets.
- Register a preset that launches `zeroclaw acp`, with the ZeroClaw ACP documentation and supported installation guidance.
- Expose a runtime-specific **Agent alias** field instead of treating the alias as a provider or model.
- Keep provider, model, tools, and security configuration authoritative in ZeroClaw rather than duplicating those settings in Buzz.
- Pass the selected alias through a process-scoped ZeroClaw selector when available. For older ZeroClaw versions, show an actionable instruction to set the ACP default agent.
- Run an ACP readiness check that covers `initialize` and `session/new`, then surface the selected runtime and alias in the managed-agent summary or logs.
- Hide provider/model requirements that do not apply to the ZeroClaw runtime.
The first version can accept a manually entered alias. Optional alias discovery can be added when ZeroClaw exposes a stable machine-readable listing contract.
**Alternatives considered**
- Keep using a custom harness JSON file. This works, but it leaves discovery, validation, and field semantics to the user.
- Create one custom runtime entry per ZeroClaw agent. This duplicates launcher configuration and still lacks readiness validation.
- Continue overloading the model field with the agent alias. This obscures which product owns model selection and makes runtime self-reporting misleading.
- Require a global ZeroClaw default agent. This prevents independent Buzz runtime entries from selecting different ZeroClaw agents cleanly.
**Additional context**
The custom integration has been exercised end to end with Buzz Desktop 0.5.3 and ZeroClaw ACP 0.8.3. No existing Buzz issue or pull request matching a native ZeroClaw runtime was found.
PR #3868 is the expected implementation foundation for this issue. Its first-class runtime catalogue, compatibility and authentication probes, readiness handling, and onboarding hooks should be reused rather than creating a parallel ZeroClaw-specific path. ZeroClaw should remain a separate follow-up instead of expanding #3868's OpenClaw scope.
Related but separate work:
- #4157 tracks linked built-in agents discarding provider/model edits.
- #2270 and #2375 track participation-based thread following.
- #3696 is prior art for adding native managed-agent runtime adapters.
ZeroClaw's current ACP alias-selection contract is documented here:
https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/book/src/channels/acp.md#sessionnew
Contributor guide
Research direction
Start by reading PR #3868 for the first-class runtime catalogue, compatibility and authentication probes, readiness handling, and onboarding hooks; review issue #3696 for prior runtime-adapter work. Trace how existing runtime presets expose configuration, then verify that a native ZeroClaw entry launches `zeroclaw acp`, handles alias selection and older-version guidance, performs `initialize` and `session/new` checks, and reports the runtime and alias without duplicating provider or model settings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- desktop, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100