block / block/buzz

Native ZeroClaw ACP runtime with agent alias configuration

Open
#4,161 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.