feat(cli): external-agent realtime path (#2663)

[Bartok9]

Closes direction toward #2663 (full external/OpenClaw CLI path). Keep #2933 open as the small users me slice.

Ships

• Option B: buzz listen — NIP-42 WS, NDJSON events, --channel / --mentions-of-me, reconnect+SIGINT, optional --webhook (Option A)
• Gap Initial release — Sprout Nostr relay with enterprise extensions #2: messages get --format compact keeps pubkey + tags
• Gaps feat: add desktop app #3–docs(readme): clarify desktop setup #4: buzz agents publish kind:30177 + client schema validation + docs/cli-external-agents.md
• Gap Dependency Dashboard #1: buzz users me included so this PR is E2E-complete (sibling feat(cli): add buzz users me for external-agent identity #2933)

Residual

• Gap Initial backend revisions, workflow expansion #5 @-mention selector (Desktop) — follow-up
• Option C generic ACP — BYOH feat(acp): bring your own harness (BYOH) — generic ACP runtime seam + settings gallery #2773, not here

Tests

cargo test -p buzz-cli --lib (264 ok) · cargo test -p buzz-ws-client --lib (3 ok)

[dspury]

I’ve been validating the resident/external-agent path against Buzz’s current relay subscription rules before opening any overlapping PR. I’m sharing the resulting branches here first so we can coordinate rather than compete with #2942/#2933.

The tested changes are split into three harness-neutral slices:

1. Identity/compact prerequisites — Lunar-Park:buzz-pr-identity (561add554, 341b37114)

   • buzz users me
   • compact pubkey/tags
   • subprocess proof that identity resolution performs no relay I/O and never prints the private key

2. Listen v1 contract — Lunar-Park:buzz-pr-listen (dbf564f2f, 7ce55d055)

   • one single-#h subscription per resolved channel, preserving the relay’s host/community security classification and live channel fan-out
   • mention-only channel discovery, aggregated EOSE, CLOSE on SIGINT/SIGTERM
   • retryable WebSocket transport failures are machine-classified as exit code 2; auth/config/protocol failures remain fatal
   • process tests for scoped multi-channel delivery, mention-only discovery, network refusal, and both shutdown signals

3. Executable conformance fixtures — Lunar-Park:buzz-pr-fixtures (dbfef894f, c723de94b)

   • exact normalization checks for schema, channel/thread validation, mentions, author policy, self-suppression, lifecycle ordering, malformed JSON, and replay deduplication

Validation on the full stack passes cargo fmt --all -- --check, cargo clippy -p buzz-cli --all-targets -- -D warnings, and cargo test -p buzz-cli (267 unit tests plus the identity, listen, and fixture process/contract tests).

Would you prefer these as suggested commits on #2942/#2933, a split of #2942 into the smaller identity/listen units, or another coordination path? I’ll hold off on opening a competing upstream PR until we agree on the cleanest route.

[dspury]

I rewrote #3964 as a single upstream-focused commit: 0ba5a8662.

Since this PR already owns the baseline identity/listening surface, the potentially reusable pieces from #3964 are now isolated to:

• canonical event-id and signature verification before output
• explicit h / p filter validation
• bounded catch-up with an explicit overflow error
• reconnect/shutdown and stable transport-error behavior
• safe local key generation
• implementation-independent wire fixtures

#3964 is draft and does not add directory publication, routing policy, process management, or deployment behavior. I’m happy for those hardening pieces to be folded here or kept separate, whichever is easier to review.

[Bartok9]

Thanks for the rewrite note on #3964 — appreciated, and good call keeping it draft/upstream-focused.

Preference: keep the hardening slices in #3964 (or a thin follow-up) rather than folding them into this PR.

• feat(cli): external-agent realtime path (#2663) #2942 should stay the baseline identity + listen surface so review stays scoped to the realtime path and the existing test/process contracts.
• The pieces you listed (canonical event-id/sig verify before output, explicit h/p filter validation, bounded catch-up + overflow, reconnect/shutdown + stable transport errors, safe local keygen, wire fixtures) are the right hardening layer on top of that baseline. Landing them separately avoids bloating this diff and makes bisect/review cleaner.
• If anything in feat(cli): add verified long-running client primitives #3964 is blocked on a missing hook from feat(cli): external-agent realtime path (#2663) #2942, call it out and I can expose a small extension point here; otherwise I’d rather not cherry-pick across until this lands or gets a clear maintainer direction.

Happy to review #3964 against this branch once the baseline is settled. No objection to you holding the draft as the staging ground for those checks.