Skip to content

Commit 46e6ca4

Browse files
wpfleger96npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7tlongwell-blockDawn (sprout agent)Tyler Longwell
authored
feat(acp): bring your own harness (BYOH) — generic ACP runtime seam + settings gallery (#2773)
## What Implements a "bring your own harness" (BYOH) generic ACP mechanism — replacing per-harness backend code with a data-driven 3-tier system: - **Tier 1 (compiled-in builtins):** goose, claude, codex, buzz-agent — unchanged behavior - **Tier 2 (bundled presets):** cursor, omp, grok, opencode, kimi, amp, hermes, openclaw, and any future additions — defined in `PRESET_HARNESSES`, no code duplication, icons stay TerminalSquare/bundled-asset-only - **Tier 3 (user-defined custom):** JSON definitions saved to `custom_harnesses/` under app data; managed via Settings → Agents UI ## Changes ### Core data model - `HarnessDefinition` — id, label, command, args, env, install URL/hint - `PRESET_HARNESSES` static table — single source of truth for all presets; `preset_harness_ids()` derives reserved IDs (D-11: no hand-maintained copy) - `source: "builtin" | "preset" | "custom"` tagging on every catalog entry ### Persistence (B-4, B-6) - `save_custom_harness_to_dir(dir, definition, rename_old_id)` — backup-swap atomic write (backs up target → .bak, commits temp → target, restores .bak on failure, removes .bak on success); safe on Windows where `fs::rename` over an existing file is "access denied" - `save_and_warm` / `delete_and_warm` — hold `PERSIST_MUTEX` for the write + registry-warm pair, eliminating the lost-update race (B-6) where two concurrent saves could interleave their warm calls and leave a stale registry snapshot - Validate-before-mutate: both IDs and env validated before any filesystem mutation ### Env validation boundary (B-3) - `validate_harness_definition_pub` calls `validate_user_env_keys` on definition env at save AND load - Rejects malformed keys (BUZZ_AUTH_TAG=x forgery shape), reserved keys (BUZZ_MANAGED_AGENT etc.), NUL bytes, oversized values ### TypeScript boundary (B-2 / Thufir CRITICAL) - `RawAcpRuntimeCatalogEntry` now declares `definition_env?: Record<string,string>` and `source: "builtin" | "preset" | "custom"` - `fromRawAcpRuntimeCatalogEntry` maps `definition_env → definitionEnv` (camelCase); absent field defaults to `{}` - Edit form reads `entry.definitionEnv` — env no longer erased on save-then-edit cycle ### Unified descriptor (Phase A / Thufir F4) - `EffectiveHarnessDescriptor { command, args, env }` in `readiness.rs` - `resolve_effective_harness_descriptor()` — single resolver used by spawn, spawn_hash, summary, get_agent_models (both saved and unsaved), and readiness - No competing arg-resolution forms ### Other fixes - B-5: stop freezing `runtime.defaultArgs` into `record.agent_args` on normal create paths - B-7: readiness exec-check — `MissingBinary` variant for custom commands not found on PATH - B-8: onboarding transition — `setTimeout(0)` removed, parent-owned route intent via `navigateAfterComplete` prop - C-9: collector-discriminating sweep tests with injectable filters - C-10: `HarnessManagementCard` uses `harnessGalleryLogic` helpers (killed duplicate filter/sort) - D-11: `BUILTIN_IDS` derived from `PRESET_HARNESSES` (no hand-maintained copy) - D-12: `mobile/pubspec.lock` churn reverted - D-13: false ownership fast-path comment fixed - D-14: URL scheme validation for `installInstructionsUrl` - D-15: OpenClaw Gateway env-locus README line ### Tests added **B-4 persistence (6 tests):** `save_to_dir_create_writes_file_and_loads_back`, `save_to_dir_same_id_edit_replaces_content`, `save_to_dir_backup_is_cleaned_up_after_same_id_edit`, `save_to_dir_rename_removes_old_file_and_creates_new`, `save_to_dir_rename_nonexistent_old_id_is_non_fatal`, `save_to_dir_roundtrip_with_env_preserves_values` **B-3 env validation (6 tests):** `validate_rejects_malformed_key_with_equals_sign`, `validate_rejects_reserved_key_buzz_managed_agent`, `validate_rejects_reserved_key_case_insensitive`, `validate_rejects_nul_byte_in_value`, `validate_rejects_value_over_per_value_size_limit`, `validate_accepts_well_formed_env` **B-2 API boundary (4 TS tests in tauri.test.mjs):** `fromRawAcpRuntimeCatalogEntry maps definition_env to definitionEnv`, `defaults definitionEnv to {} when absent`, `preserves source preset`, `env round-trips through edit payload shape` ## Preset catalog | ID | Label | Command | |----|-------|---------| | `cursor` | Cursor | `cursor-agent acp` | | `omp` | Oh My Pi | `omp acp` | | `grok` | Grok Build | `grok agent --always-approve stdio` | | `opencode` | OpenCode | `opencode acp` | | `kimi` | Kimi Code | `kimi acp` | | `amp` | Amp | `amp-acp` | | `hermes` | Hermes Agent | `hermes-acp` | | `openclaw` | OpenClaw | `openclaw acp` | ## Review-fix pass (2026-07-26, Eva) Fixes from the three-way review (Wren / Dawn / Eva) in the buzz-generic-acp-harnesses thread, pushed as new commits (no rewrite): 1. **installHint edit round-trip** — form seeding extracted to `formValuesFromCatalogEntry` (single source of truth), input rendered, full-definition lossless round-trip regression. 2. **Dangling-delete coherence** — delete allowed; confirm counts referencing agents (direct pin + persona-inherited); summary rows render `harness (deleted): <id>`; spawn errors become actionable sentences (`user_facing_harness_error`); composed delete→summary→start test. 3. **Comma-in-args** — rejected at `validate_harness_definition` (shared by save AND disk load), mirrored inline in the form. 4. **Registry publish race** — collision/dup filtering moved into `load_custom_harnesses` (both loaders inherit shadowing rules); discovery publishes by re-reading the dir under `persist_mutex` (lock scoped to publish only); deterministic interleaving regressions for save-during-discovery and delete-during-discovery. 5. **Mechanical** — discarded `belongs_to_us` sweep arg deleted, `load_global_agent_config` hoisted out of the per-record summary loop, duplicated doc paragraph + stray SAFETY comment removed. 6. **PGID test de-flaked** — leader kept alive through the assertion. Known follow-up (filed in review, not blocking): file-size split-outs queued in `check-file-sizes.mjs` entries. ## Gate table — head `cf6c2b441` | Gate | Result | |------|--------| | `cargo test --lib` (desktop/src-tauri) | **1701 passed**, 0 failed, 14 ignored | | desktop JS suite (`pnpm test`) | **3605 passed**, 0 failed | | `tsc --noEmit` | clean | | `biome check` + file-size/px/pubkey checks | clean | | `cargo clippy --lib -- -D warnings` | clean | | `cargo fmt --check` | clean | PR head: `cf6c2b44131a24ed462c7d04dab31687e48b4b6b` — includes merge of origin/main (`62a5c3c9b`, conflicts in agent_models composed with #2890's live Databricks discovery) --------- Signed-off-by: Will Pfleger <[email protected]> Signed-off-by: tlongwell-block <[email protected]> Signed-off-by: Tyler Longwell <[email protected]> Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz> Co-authored-by: tlongwell-block <[email protected]> Co-authored-by: Dawn (sprout agent) <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@sprout-oss.stage.blox.sqprod.co> Co-authored-by: Tyler Longwell <[email protected]> Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
1 parent 6c0e93e commit 46e6ca4

72 files changed

Lines changed: 7048 additions & 275 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎crates/buzz-acp/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,65 @@ Each channel has at most one prompt in flight. Multiple channels can be processe
261261

262262
> **Note:** On startup, the harness replays all unprocessed @mentions since the last run. Expect a burst of activity if there are stale events in the channel.
263263
264+
## Bring Your Own Harness (BYOH)
265+
266+
Buzz Desktop supports registering any ACP-speaking agent tool as a selectable runtime without a PR.
267+
268+
### How it works
269+
270+
**Tier-1 — compiled-in runtimes** (Goose, Claude Code, Codex, Buzz Agent): have auto-installers, auth probes, and first-class onboarding. Their IDs (`goose`, `claude`, `codex`, `buzz-agent`) are reserved and cannot be overridden.
271+
272+
**Tier-2 — preset catalog** (Cursor, Oh My Pi, Grok Build, OpenCode, Kimi Code, Amp, Hermes Agent, OpenClaw): static `HarnessDefinition` entries in `desktop/src-tauri/src/managed_agents/discovery.rs` (`PRESET_HARNESSES`). They are always present in the runtime catalog, PATH-probed for availability, not editable or deletable by the user. Displayed with bundled logos; if not installed, a docs link appears instead.
273+
274+
> **Note — OpenClaw:** `openclaw acp` is a Gateway-backed bridge; PATH availability shows "Available" even when the OpenClaw Gateway daemon is not running. This is expected tier-2 semantics (same class as a preset with unconfigured auth). The Gateway URL is configured via `OPENCLAW_GATEWAY_URL` (or the equivalent env var from OpenClaw's docs) — set it in the agent's **env vars** in Edit Agent, not in the definition env (the preset definition carries no env entries). Note that `openclaw acp` executes tools inside the Gateway daemon, not the Desktop process, so Desktop-injected `BUZZ_*` env vars do NOT reach the execution locus unless you also set them on the Gateway's own environment.
275+
276+
**Tier-3 — user custom harnesses**: JSON files in `<app-data>/custom_harnesses/` that the user can create from the Settings UI or drop in directly. Each file describes one harness — no install scripts.
277+
278+
### Custom harness JSON schema
279+
280+
```json
281+
{
282+
"id": "my-agent",
283+
"label": "My Agent",
284+
"command": "my-agent-bin",
285+
"args": ["acp"],
286+
"env": {
287+
"MY_AGENT_MODE": "acp"
288+
},
289+
"installInstructionsUrl": "https://example.com/docs",
290+
"installHint": "Download from example.com"
291+
}
292+
```
293+
294+
Fields:
295+
- `id` — `[a-z0-9_][a-z0-9_-]*` (used as the runtime picker value and file name)
296+
- `label` — human-readable name shown in the UI
297+
- `command` — the executable name or absolute path (must be non-empty)
298+
- `args` — optional default CLI arguments (array); instance-level args override this when non-empty
299+
- `env` — optional environment variables injected at spawn time (definition env is a floor; user/persona/global env overrides it; Buzz-reserved keys like `BUZZ_MANAGED_AGENT` are always stripped and cannot be overridden)
300+
- `installInstructionsUrl` / `installHint` — shown when the binary is not on PATH
301+
302+
Invalid files (bad JSON, unknown id, empty command) are skipped with a warning and do not break discovery for other entries.
303+
304+
### Security guarantees
305+
306+
- No install shell commands in preset or custom definitions — only the user's own PATH is consulted.
307+
- `can_auto_install` is always `false` for preset and custom entries.
308+
- No user-supplied icon URLs — icons are bundled assets keyed by id in `RuntimeIcon.tsx`.
309+
- `BUZZ_MANAGED_AGENT` and other Buzz identity keys cannot be overridden by `env` in a custom definition; they are stripped before merging.
310+
311+
### Adding a preset (contributor guide)
312+
313+
To add a new runtime to the tier-2 gallery:
314+
315+
1. **Verify the ACP entrypoint** from the vendor's own documentation — do not rely on a PR description alone. Test with the actual binary.
316+
2. **Add a `HarnessDefinition` entry** to the `PRESET_HARNESSES` slice in `desktop/src-tauri/src/managed_agents/discovery.rs`. Fill `id`, `label`, `command`, `args`, `install_instructions_url`, `install_hint`. Leave `env` empty unless the harness requires a specific env var to enable ACP mode.
317+
3. **Add the preset id to `BUILTIN_IDS`** in `desktop/src-tauri/src/managed_agents/custom_harnesses.rs` so custom JSON files cannot shadow it.
318+
4. **Add a bundled logo** (64×64 PNG or optimised SVG) to `desktop/public/harness-logos/<id>.png` and add a corresponding entry to `PRESET_LOGOS` in `desktop/src/features/onboarding/ui/RuntimeIcon.tsx`. Record the source and license in `desktop/public/harness-logos/CREDITS.md`. Only bundle a mark whose upstream license permits redistribution; skipping this step is caught by `presetLogos.test.mjs`, which asserts every `PRESET_HARNESSES` id has a mapped logo that exists on disk.
319+
5. Run `cargo test --lib` and `just desktop-typecheck` to verify everything compiles.
320+
321+
The built-in `BUILTIN_IDS` set (`goose`, `claude`, `codex`, `buzz-agent`, and all current preset ids) is the reserved namespace; every other id is available for custom harnesses.
322+
264323
## Using Any ACP Agent
265324

266325
The harness works with any agent that implements the [ACP spec](https://agentclientprotocol.com/) over stdio. The requirements are:

‎desktop/playwright.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ export default defineConfig({
120120
"**/inbox-live-update.spec.ts",
121121
"**/mesh-compute.spec.ts",
122122
"**/observer-archive-policy.spec.ts",
123+
"**/harness-management.spec.ts",
123124
],
124125
use: {
125126
...devices["Desktop Chrome"],
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Preset harness logos — provenance
2+
3+
Third-party marks bundled to identify tier-2 preset harnesses in the runtime
4+
gallery (`PRESET_LOGOS` in `desktop/src/features/onboarding/ui/RuntimeIcon.tsx`).
5+
Nominative use only — each mark identifies its own vendor's harness.
6+
7+
Add a row here when adding a preset logo; only bundle marks whose upstream
8+
license permits redistribution.
9+
10+
| File | Upstream | Commit | License | Source path | Modifications |
11+
|---|---|---|---|---|---|
12+
| `hermes.png` | [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) | `6ad632b` | MIT © 2025 Nous Research | `website/static/img/logo.png` | Cropped the baked-in border frame, padded to square, resized to 64×64, quantised to a 16-colour palette |
13+
| `openclaw.svg` | [openclaw/openclaw](https://github.com/openclaw/openclaw) | `b06f40a` | MIT © 2026 OpenClaw Foundation | `ui/public/favicon.svg` | Removed the SMIL animation elements (renders the upstream rest pose statically — verified pixel-identical to the upstream frame at t=0); minified paths |
14+
| `omp.svg` | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) | `667111575ebba136dadfd6989379e7f67e0d40d9` | MIT © 2025 Mario Zechner; © 2025–2026 Can Bölük | `assets/icon.svg` | None |
15+
| `kimi.png` | [MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) | `4a550effdfcb29a25a5d325bf935296cc50cd417` | Apache-2.0; NOTICE: Kimi Code CLI © 2025 Moonshot AI | `web/public/logo.png` | None |
16+
| `grok.svg` | [SpaceXAI brand guidelines](https://x.ai/legal/brand-guidelines) | Retrieved 2026-07-25 | xAI Brand Guidelines: marks may be used to accurately refer to xAI or its services; logos must be used exactly as provided | `SpaceXAI_Grok_Assets.zip` → `Grok_Logomark_Dark.svg` | None |
17+
18+
`amp.png` and `opencode.svg` predate this file; their provenance was not
19+
recorded when they were added. Cursor intentionally uses the generic terminal
20+
fallback: Cursor's official brand page offers downloadable assets, but neither
21+
that page nor its Terms of Service grants third parties permission to
22+
redistribute them. The previous unproven `cursor.png` was removed.
2.16 KB
Loading
Lines changed: 4 additions & 0 deletions
Loading
1.66 KB
Loading
11.2 KB
Loading
Lines changed: 16 additions & 0 deletions
Loading
Lines changed: 16 additions & 0 deletions
Loading
Lines changed: 7 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)