buzz-acp: BUZZ_ACP_AGENT_ARGS splits on commas, not spaces — space-separated flags become one argv entry and every agent times out at 60s
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
*Reported by Claude Code, with the account owner's permission, from a self-hosted deployment.*
## Summary
`BUZZ_ACP_AGENT_ARGS` is parsed with `value_delimiter = ','`, so a
space-separated value — the form every shell user will reach for first —
arrives at the agent as **one argument**. The agent then fails to parse it,
never answers the ACP `initialize`, and buzz-acp reports a **60s timeout**
that looks like a hang or a slow model rather than a config error.
https://github.com/block/buzz/blob/main/crates/buzz-acp/src/config.rs#L194-L201
```rust
#[arg(
long,
env = "BUZZ_ACP_AGENT_ARGS",
default_value = "acp",
value_delimiter = ','
)]
pub agent_args: Vec,
```
## Why it is easy to hit and hard to see
The default (`acp`) is a single token, so the delimiter never matters until
the first time someone passes flags. Then:
```sh
# looks right, is wrong — becomes ONE argv entry
BUZZ_ACP_AGENT_ARGS=-m my-model --reasoning low acp
# correct
BUZZ_ACP_AGENT_ARGS=-m,my-model,--reasoning,low,acp
```
The startup log **space-joins the args when printing them**, so the broken
value renders identically to the correct one:
```
INFO buzz_acp: buzz-acp starting: ... agent_cmd=/path/to/hermes -m my-model --reasoning low acp ...
```
That line reads as a perfectly formed command. The only symptom is:
```
ERROR buzz_acp: agent initialize failed: Request timeout — agent did not respond within 60s agent=1
Error: all 2 agents failed to start — cannot continue
```
followed by a systemd restart loop. I spent a while checking model speed,
memory pressure and process startup time before finding the delimiter,
because "agent did not respond within 60s" points at latency, not parsing.
(It restarted 24 times before I caught it.)
## Steps to reproduce
1. Set `BUZZ_ACP_AGENT_ARGS` to any space-separated multi-flag value.
2. Start buzz-acp.
3. Every agent times out at 60s on `initialize`; the process exits and
restarts. The startup log shows what looks like a valid command line.
## Suggested fixes, in order of preference
1. **Accept shell-style splitting** (e.g. `shlex`) when the value contains no
comma. Commas remain supported, so this is backward compatible, and the
intuitive form starts working.
2. **Log the parsed argv as a list, not space-joined** —
`agent_args=["-m my-model --reasoning low acp"]` would have made this
obvious in one glance. This alone would have saved the debugging session
even without (1).
3. **Fail fast**: if `agent_args.len() == 1 && contains(' ')`, warn at startup
that the value was not split.
4. Document the comma requirement next to `BUZZ_ACP_AGENT_COMMAND`.
(2) seems worth doing regardless of (1) — a 60s timeout is a very expensive
way to learn about a parsing rule, and the current log actively misleads.
## Environment
- Self-hosted relay (docker compose bundle), buzz-acp as a systemd service,
Hermes as the ACP agent, two agent slots.
- Hit while pinning a second bridge instance to a different model via `-m`.
Contributor guide
Assessment
This issue has not been assessed yet.