Skip to content

feat(desktop): add zcode-acp preset to the harness catalog - #4889

Open
jpalmae wants to merge 1 commit into
block:mainfrom
jpalmae:feat/add-zcode-acp-preset
Open

feat(desktop): add zcode-acp preset to the harness catalog#4889
jpalmae wants to merge 1 commit into
block:mainfrom
jpalmae:feat/add-zcode-acp-preset

Conversation

@jpalmae

@jpalmae jpalmae commented Aug 5, 2026

Copy link
Copy Markdown

Following up on #3131 (closed as superseded by the harness catalog shipped in v0.5.0 / #2773), this adds zcode-acp as a tier-2 preset so ZCode is one-click discoverable in the Desktop runtime gallery — the data-entry PR @wpfleger96 suggested in #3131 (comment).

What

zcode-acp is a standalone ACP adapter (mirroring amp-acp / hermes-acp) that drives the ZCode CLI through its stdio app-server. It speaks ACP v1 directly, so no other Buzz-side change is needed beyond this preset entry.

  • Adapter repo: https://github.com/jpalmae/zcode-acp (Apache-2.0)
  • ACP parity with codex-acp: streaming text + reasoning, tool calls (tool.updatedToolCall/ToolCallUpdate), session/requestPermission bridged bidirectionally, authenticate/logout (Z.AI OAuth init/poll + credential store compatible with zcode login), UsageUpdate.

Changes (small data-entry, as suggested)

File Change
desktop/src-tauri/src/managed_agents/discovery/presets.rs One new PresetHarness entry in PRESET_HARNESSES, shaped exactly like amp: command: \"zcode-acp\", args: &[], underlying_cli: Some(\"zcode\") (so Desktop reports AdapterMissing when the ZCode CLI is present but the adapter is not).
desktop/src/features/onboarding/ui/RuntimeIcon.tsx Map \"zcode-acp\"/harness-logos/zcode-acp.svg in PRESET_LOGOS (satisfies presetLogos.test.mjs).
desktop/public/harness-logos/zcode-acp.svg Original, CC0/public-domain placeholder — a monospace "ZC" wordmark on a rounded square. Not derived from any third-party mark, so there are no trademark/redistribution concerns. Happy to swap in an official Z.ai mark under redistribution terms if/when one is provided.
desktop/public/harness-logos/CREDITS.md Provenance row for the placeholder.

Why underlying_cli: Some(\"zcode\")

zcode-acp is an adapter that spawns node zcode.cjs ... — i.e. it wraps a separately-installed vendor bundle. Mirroring amp (which sets underlying_cli: Some(\"amp\")), this makes Desktop distinguish “ZCode installed but the adapter missing” from “neither installed”, surfacing the right install guidance.

Verification

  • presetLogos.test.mjs assertions replicated locally (same regex the test uses): every PRESET_HARNESSES id has either an inline RUNTIME_MARKS entry or a PRESET_LOGOS entry whose file exists on disk, and there are no orphan PRESET_LOGOS keys. ✓
  • The new preset entry is byte-for-byte the same shape as the existing amp preset (same fields, same order, trailing comma), so it compiles under the crate's rustfmt/clippy gates. The full cargo check -p buzz-desktop requires a prebuilt buzz-acp binary in build.rs that isn't available outside the release pipeline, so I could not run it end-to-end locally — but the change is additive data-only and mirrors a sibling.

Out of scope

  • The placeholder logo is intentionally neutral. If maintainers prefer a different treatment (e.g. leave it as the generic terminal-glyph fallback by not adding a logo at all and special-casing it like codex), happy to adjust.
  • Headless buzz-acp already works without this PR (per feat(buzz-acp): register zcode-acp as a known ACP agent #3131 feedback); this PR is purely about Desktop discoverability.

Following up on block#3131 (closed as superseded by the harness catalog shipped
in v0.5.0 / block#2773), this adds `zcode-acp` as a tier-2 preset so ZCode is
one-click discoverable in the Desktop runtime gallery.

`zcode-acp` is a standalone ACP adapter (mirroring amp-acp / hermes-acp)
that drives the ZCode CLI through its stdio app-server. It speaks ACP v1
directly, so no other Buzz-side change is needed:
https://github.com/jpalmae/zcode-acp

- New PresetHarness entry: command=zcode-acp, args=[], underlying_cli=zcode
  (so Buzz reports AdapterMissing when the ZCode CLI is present but the
  adapter is not — same shape as the amp preset).
- Mapped logo in PRESET_LOGOS and an original CC0 placeholder SVG so the
  presetLogos coverage guard passes. Happy to swap in an official Z.ai
  mark under redistribution terms if/when available.
- CREDITS.md row recording the placeholder provenance.

Signed-off-by: jpalmae <39507014+jpalmae@users.noreply.github.com>
@jpalmae
jpalmae requested a review from a team as a code owner August 5, 2026 14:01

@wesbillman wesbillman left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed on Wes's behalf at head 8b03aaf9bad2513e0d86b98a65d98b48b5c7ec63.

The Buzz-side data entry is mechanically consistent, but I don't think we should promote this adapter into the built-in Desktop catalog yet. The catalog entry turns an external executable into a first-class recommendation; the linked adapter has not established the runtime compatibility or distribution/maintenance baseline that recommendation implies.

At the adapter's current sole commit (jpalmae/zcode-acp@f1c02830d96f26bd4117fd4a1a46f6ec72591630):

  • it has one commit, one contributor, no tags/releases, no CI workflows, no stars/forks, and no LICENSE file (despite the Cargo manifest declaring Apache-2.0);
  • its documented E2E uses tests/fake-app-server.cjs, not a released ZCode build and real model provider;
  • the README explicitly says the private ZCode protocol and credential format were reverse-engineered, but the referenced “in-repo research notes” are absent;
  • compatibility is therefore coupled to an undocumented vendor-private protocol with no version/support matrix or fail-closed version guard.

There is also contrary implementation evidence worth resolving before promotion: supermomonga/zcode-acp documents real macOS and headless-Linux tests against ZCode 3.3.6 / CLI 0.15.2 and reports that directly launching zcode.cjs app-server --stdio yields zero model providers, requiring the official host service instead. This proposed adapter uses the direct node zcode.cjs app-server path and has only fake-server validation, so a passing ACP simulation does not establish that a real user can complete a turn.

Demand is currently submitter-only in the Buzz tracker: #3131 and #4889 are from the adapter author, and repository issue/PR search found no independent ZCode request. That is exactly what the custom-harness tier shipped in #2773 is for; ZCode users can register zcode-acp today without Buzz carrying a built-in endorsement.

Please establish at minimum a reproducible real-ZCode E2E against supported released versions (including provider/auth, prompt, tool permission, and completion), resolve the direct-app-server provider conflict, add normal licensing/release/install artifacts and CI, and document a compatibility/maintenance policy. Independent user demand or adoption would then justify reconsidering catalog inclusion. Until then, recommendation: keep this as a custom harness rather than a built-in preset.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants