feat(desktop): add OpenClaw native ACP runtime

[vincentkoc]

Summary

• replace the Gateway-backed OpenClaw preset with a first-class builtin runtime
• discover and launch the dedicated openclaw-acp native stdio executable with zero arguments
• install/update OpenClaw through Buzz's existing managed npm path
• check model readiness with openclaw models status --check --json
• route model setup through Buzz's visible ACP terminal-auth flow

There is no OpenClaw Gateway lifecycle, URL/token handling, companion node, or OpenClaw-specific process manager in Buzz.

The temporary generic split PR, #4238, is closed. This PR is the self-contained Buzz change and includes the generic managed-runtime contracts required by the OpenClaw registration.

Runtime Contract

openclaw-acp is the native-capability marker. Its process owns the OpenClaw model loop and tools, so the dedicated agent's inherited BUZZ_* environment reaches permitted local tool execution and the Buzz CLI used to publish signed replies.

OpenClaw treats host-forwarded ACP prompts as non-owner ingress. Owner-only OpenClaw tools remain unavailable; exec and plugin operations use ACP permission requests and fail closed.

Older Gateway-only OpenClaw releases do not expose openclaw-acp and are not detected as compatible.

Migration Contract

At startup, Buzz rewrites only the exact previously shipped OpenClaw preset shape:

• command openclaw
• arguments ["acp"]
• no custom command override, or an override exactly equal to openclaw

That shape becomes openclaw-acp with zero arguments. Custom paths, custom arguments, and other user overrides remain untouched.

The visible terminal-auth launcher preserves Buzz's augmented PATH on macOS, Linux, and Windows so managed runtime binaries remain discoverable during authentication.

Dependency Stack

1. refactor(agents): allow process-local exec approval hosts openclaw/openclaw#116394 adds the process-local approval transport while preserving Gateway decision policy.
2. feat(acp): run OpenClaw as a native stdio agent openclaw/openclaw#116678 adds the non-owner native ACP host and openclaw-acp executable.
3. This PR registers that executable and supplies the Buzz managed-runtime contracts it needs.

Do not ship this PR until a compatible OpenClaw release is available.

Related Issue

• OpenClaw ACP agent can’t publish replies #4021

Testing

• cargo fmt --all -- --check
• git diff --check
• buzz-acp argument normalization: 1 passed
• desktop legacy migration: 2 passed
• terminal-auth PATH propagation: 1 passed
• changed frontend runtime/logo tests: 23 passed
• exact Biome check over changed frontend files: clean
• broad desktop frontend suite: 4,128 existing tests passed and exposed one stale preset-logo assertion; the runtime logo ownership was corrected and the affected tests then passed
• Semgrep OSS, zizmor, and DCO checks: passed on 61fadb7e4cd1525ab3f3c40eb813ee78a0d7bd6d

Remaining Live Proof

The OpenClaw dependency stack passes focused tests and changed-surface validation. A clean Testbox has no usable OpenAI authentication, so a real Buzz mention/signed-reply round trip remains required on an authenticated Crabbox before release.

[Chessing234]

big surface. could you split the install/verify bits from the catalog entry so the scary spawn-boundary changes are easier to review alone?

[vincentkoc]

split as requested.

• generic install/verify/spawn-boundary layer: feat(desktop): enforce managed ACP runtime contracts #4238
• OpenClaw-only upper layer: this branch's second commit
• exact incremental upper diff: vincentkoc/buzz@feat/managed-acp-runtime-contracts...feat/openclaw-acp-runtime

GitHub cannot select a fork branch as the base of an upstream PR, so #3868 must
temporarily show the combined stack. Once #4238 merges, this PR becomes the
OpenClaw-only diff without another rewrite.

[vincentkoc]

Final maintainer handover

This PR is the Buzz side of OpenClaw's native ACP integration:

• OpenClaw approval seam: refactor(agents): allow process-local exec approval hosts openclaw/openclaw#116394
• OpenClaw native ACP host: feat(acp): run OpenClaw as a native stdio agent openclaw/openclaw#116678
• Buzz runtime registration: feat(desktop): add OpenClaw native ACP runtime #3868

The temporary generic Buzz split, #4238, is closed. Review #3868 as the self-contained Buzz change; it includes the generic managed-runtime contracts required by the OpenClaw registration.

Buzz contract

• Discovery requires the dedicated openclaw-acp executable, so older Gateway-only OpenClaw installs are not misdetected.
• Buzz launches openclaw-acp with zero Gateway arguments.
• Install/update uses Buzz's existing managed npm path.
• Readiness uses openclaw models status --check --json.
• Model setup uses Buzz's visible ACP terminal-auth flow with the managed runtime PATH.
• Only the exact legacy openclaw + acp preset is migrated. Customized commands and arguments are preserved.
• The ACP child inherits the dedicated BUZZ_* identity, and permitted OpenClaw tools execute in that same process.
• Buzz owns no OpenClaw Gateway, URL, token, port, node, or service lifecycle.

Security and lifecycle

• OpenClaw treats ACP prompts as non-owner ingress.
• Permission responses authorize one requested operation; they do not attest user identity.
• Approval display data is sanitized, bounded, and immutable to the host. Raw environment values, argv, execution plans, and the enforcement policy remain inside OpenClaw.
• Approval timeout, cancellation, session interruption, and shutdown are fail-closed.
• Plugin approval authority is tied to the originating OpenClaw run.
• The native process fences new work, late thought events, replacement prompts, and active-turn teardown.
• Official OpenClaw Docker images expose and smoke-check the same openclaw-acp capability executable Buzz discovers.

Final heads and proof

• Buzz: 61fadb7e4cd1525ab3f3c40eb813ee78a0d7bd6d
• OpenClaw base: 46520d8ef9f4e70e47ec4cc9d13cb2286867cb05
• OpenClaw native host: 481a74ba6b1825ba7e77dde0bdfb2c25a1752d52
• Buzz Semgrep OSS, zizmor, and DCO checks: passed
• OpenClaw focused ACP/installer tests: 332 passed
• OpenClaw latest authority/lifecycle and image-contract regressions: 127 passed
• OpenClaw final native runtime extraction: 17 passed; oxlint and max-lines clean
• OpenClaw base exact-head CI: https://github.com/openclaw/openclaw/actions/runs/30896269705
• OpenClaw native ACP exact-head CI: https://github.com/openclaw/openclaw/actions/runs/30896617000

Do not ship the Buzz runtime until a compatible OpenClaw release containing openclaw-acp is available. The remaining release gate is a redacted authenticated Buzz mention -> model/tool turn -> signed reply and process-cleanup proof with dedicated QA credentials.

[Tony-ooo]

Authenticated macOS reproduction of the legacy bridge failure

This is a focused reproduction for the migration/acceptance path in this PR. It uses the existing legacy preset shape, openclaw acp, not the proposed native openclaw-acp executable.

Environment:

• Buzz Desktop 0.5.5
• OpenClaw 2026.7.2-beta.7 (dabe191)
• macOS arm64, local Gateway on loopback

The model-discovery command invoked by the create-agent UI fails:

$ buzz-acp models --agent-command openclaw --agent-args acp --json
gateway connect failed: GatewayClientRequestError: scope upgrade pending approval
ACP bridge failed: scope upgrade pending approval
error: agent communication failed: Agent process exited unexpectedly

Gateway logs show the spawned OpenClaw ACP client starts with operator.read and requests operator.admin; Gateway rejects the connection with pairing-required / scope-upgrade. The failure happens before session/new, so Buzz cannot obtain any ACP model metadata for the model dropdown.

This is not an empty OpenClaw catalog or an unhealthy Gateway: openclaw status --deep reports the Gateway reachable and running, while openclaw models list --json reports 46 local configured/discovered models, including available opencode-go/* and volcengine-plan/* entries.

This provides a concrete legacy regression/acceptance case for the native route proposed here: a real authenticated Buzz mention must reach a model/tool turn and produce a signed reply through openclaw-acp, without requiring a Gateway URL, token, or scope upgrade. Related: #4021.