Add a configurable ACP runtime registry (or document how to attach a 3rd-party runtime like omp acp)

[rubicks-112]

Summary

Buzz desktop's runtime registry is hardcoded to 5 entries (node, node-tools, codex-acp, claude-agent-acp, claude-code-acp). There is no way to attach a third-party ACP-compatible agent such as oh-my-pi/omp (omp acp) through the UI today, even though the underlying plumbing (acp_command="buzz-acp", agent_command="<runtime>", agent_args=[...]) is generic and would accept any bin name on PATH.

Evidence

String-scan of D:\Apps\Buzz\buzz-desktop.exe at offset 55350058:

…
BUZZ_AGENT_PROVIDER…
Buzzruntimesnodenode-toolscodex-acpclaude-agent-acpclaude-code-acp
npmwin-x64binv24.11.0node.exe…

That comma-joined tail after Buzzruntimes is the runtime registry. The same 5 names appear nowhere else in any of the 5 binaries in D:\Apps\Buzz\. A direct Buffer-level grep across buzz-desktop.exe, buzz-acp.exe, buzz-agent.exe, buzz.exe, buzz-dev-mcp.exe for omp-acp, oh-my-pi, minimax, agentclientprotocol/omp, omx-acp returns zero hits.

I built and globally installed a working bridge as a sanity check:

• npm package: @agentclientprotocol/omp-acp (local, Apache-2.0)
• bin name: omp-acp (sits next to codex-acp, claude-code-acp)
• implementation: child_process.spawn("omp.cmd", ["acp", ...argv], { stdio: "inherit" }) — a thin stdio proxy, ~50 lines, no protocol translation because omp acp already speaks Agent Client Protocol over stdio (verified via direct initialize handshake: protocolVersion=1, agentInfo={name:"oh-my-pi", version:"17.1.7"} with full loadSession/mcpCapabilities/sessionCapabilities).

After installing it, I appended a fresh persona to managed-agents.json:

{
  "name": "OMP-Probe",
  "display_name": "OMP-Probe",
  "slug": "omp:probe",
  "acp_command": "buzz-acp",
  "agent_command": "omp-acp",
  "agent_args": [],
  "is_active": true,
  ...
}

Restarting Buzz desktop preserved agent_command: "omp-acp" verbatim — so the file-level path works. Only the UI runtime picker is closed.

What I am asking for

One of the following, in order of preference:

1. Make the runtime registry configurable. Move the 5-name list out of the binary into something user-editable — config file, BUZZ_RUNTIMES env var, or a runtime-discoverable convention (any bin on PATH matching <name>-acp whose path resolves). I would expect this to be a small change touching crates/buzz-desktop/ near where Buzzruntimes lives.
2. Document the supported runtimes + add omp-acp to the same list. Less flexible for the long tail but unblocks the immediate use case (goose's env contract is the source of the broken-API-key reports, see goose + provider openai: the API key never reaches the agent (401 every turn) #3395 — giving users an alternative runtime that doesn't need the bundled provider-key path would also help there).
3. At minimum: a per-persona custom_runtime field whose agent_command is honored without going through the registry (effectively what I have working today via direct managed-agents.json editing, but it currently has no UI path and is not documented).

Reproduction (Windows 11, D:\Apps\Buzz\, omp 17.1.7 installed)

# 1. install the bridge anywhere on disk
mkdir omp-acp-adapter && cd omp-acp-adapter
#   omp-acp.js : transparent stdio proxy to `omp acp`
npm install -g .

# 2. confirm bin on PATH and ACP handshake
where omp-acp
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":2,"clientInfo":{"name":"probe","version":"0.0.1"}}}' \
  | omp-acp
# -> {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"oh-my-pi","version":"17.1.7"},...}}

# 3. open Buzz desktop, click "connect", look at the runtime list
# -> node, node-tools, codex-acp, claude-agent-acp, claude-code-acp
#    no omp-acp, no way to add one

Environment

• Buzz D:\Apps\Buzz\, all 5 binaries from Jul 25 17:08 / 17:23
• omp 17.1.7 already on PATH at C:\Users\oabdu\AppData\Roaming\npm
• node 24.11.0, npm 11.6.2

Related

• goose + provider openai: the API key never reaches the agent (401 every turn) #3395 — bundled goose runtime hits 401 because Buzz does not translate OPENAI_COMPAT_API_KEY to OPENAI_API_KEY. Unblocking an alternative runtime (this issue) does not fix that, but it gives users an escape hatch while it is being triaged.

[bradhallett]

A fix is up in #3804. It resolves this by deriving the per-runtime launch args from the single-source PRESET_HARNESSES table in resolve_effective_harness_descriptor, so an agent pinned to this runtime (e.g. via agent_command_override with no runtime id) launches its ACP/stdio mode instead of the bare command/TUI that timed out at initialize.

[patrick-xin]

Just want to +1 this and share a working data point: I built a pi-acp adapter using exactly the custom-harness mechanism you describe, and it runs against a live relay with no source changes — just a pi.json dropped into custom_harnesses/.

The pattern works well. The one thing I learned the hard way (in case it saves you time with omp): the custom harness approach is necessary but not sufficient. The adapter itself has to handle a few Buzz-specific behaviors to avoid silent failures:

1. Once you return configOptions from session/new, Buzz switches to session/set_config_option (configId "model") instead of session/set_model. If the adapter only ACKs this without applying, the session deadlocks on the default model.
2. The session/update discriminator is sessionUpdate (not type) — if you tag notifications with type, the desktop renders them as unknown and drops everything except the final reply.
3. Tool calls must carry an arguments object (not a content.text string) to render as tool cards.

These are all ACP-spec compliant — just not obvious until you hit them. Full writeup in the README.

A configurable runtime registry or even just official docs covering these wire-level details would make 3rd-party runtime onboarding much smoother.