ippadmin/itpp-infrastructure
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: nest 19 files into audit/ clients/ infrastructure/ monitoring/ projects/ super-search/

Browse Source
This commit is contained in:
root
2026-08-08 13:04:55 -04:00
parent 11a1110b81
commit a522d11c35
20 changed files with 927 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/buzz-agent-integration-spec.md
+587
View File
@@ -0,0 +1,587 @@
# Server-Side Agent Integration with Buzz
**Status:** Speculative / Research
**Date:** 2026-08-07
**Author:** Sho'Nuff
**Relay:** `wss://buzz.iamgmb.com` (app3, Docker Compose)
## Executive Summary
Buzz's native agent integration model (`buzz-acp`) is **desktop-centric**: it spawns ACP-compliant agent binaries as local subprocesses via stdio. Hermes is server-side (Core VPS) and cannot be spawned as a local binary on a user's laptop. This spec evaluates four integration paths to make Hermes a first-class participant in Buzz channels — able to receive @mentions and post replies — and recommends a Nostr-native WebSocket client approach modeled after the proven OpenClaw Buzz plugin.
---
## 1. ACP Protocol Research
### 1.1 What is ACP?
The **Agent Client Protocol (ACP)** is an open standard hosted at [agentclientprotocol.com](https://agentclientprotocol.com/), governed by a spec repo at [github.com/agentclientprotocol/agent-client-protocol](https://github.com/agentclientprotocol/agent-client-protocol). It is modeled after LSP (Language Server Protocol) and standardizes communication between code editors/IDEs and AI coding agents.
**Protocol fundamentals:**
- **Wire format:** JSON-RPC 2.0 over stdio (primary transport today)
- **Roles:** Client (editor/IDE/harness) ↔ Agent (AI coding tool)
- **Lifecycle:** `initialize` → `session/new` → `session/prompt` → `session/update` (streaming) → `StopReason`
- **Concepts:** Sessions, tool calls, cancellation, context window updates, authentication
- **Rust crate:** [`acp-sdk`](https://crates.io/crates/acp-sdk) provides typed wire messages
**Key ACP methods:**
| Method | Direction | Purpose |
|--------|-----------|---------|
| `initialize` | Client → Agent | Handshake, negotiate protocol version + capabilities |
| `session/new` | Client → Agent | Create session, pass cwd + MCP server configs |
| `session/prompt` | Client → Agent | Send user prompt, agent loops LLM + tool calls |
| `session/cancel` | Client → Agent | Cancel ongoing session |
| `session/close` | Client → Agent | Close session, free resources |
| `session/update` | Agent → Client | Streaming updates: tool calls, text chunks, usage |
| `authenticate` | Client → Agent | Auth before session creation |
**AGENT NOTIFICATION — `buzz-agent` implementation:**
- Single binary, ACP-compliant. Speaks MCP to tools (stdio only, no HTTP MCP).
- Up to 8 concurrent sessions per process.
- Non-streaming HTTP POST to LLM providers (Anthropic, OpenAI, OpenRouter).
- Not persistent (in-memory per process), no `session/load`.
### 1.2 Remote Transport Status
**ACP remote transports are in active development but NOT shipped yet:**
- An RFD (Request for Discussion) exists at [agentclientprotocol.com/rfds/streamable-http-websocket-transport](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport)
- A **Transports Working Group** has been formed, co-led by Block/Goose and JetBrains
- The RFD proposes:
- **Streamable HTTP** (HTTP/2, long-lived GET streams, `Acp-Connection-Id` + `Acp-Session-Id` headers)
- **WebSocket** (`GET /acp` with `Upgrade: websocket` header)
- Unified `/acp` endpoint routing
- This is an RFD, not implemented. No timeline published.
**Current reality:** ACP is stdio-only for production use. Remote agents are a documented goal, not a working feature.
### 1.3 How Buzz Uses ACP
Buzz's agent harness is **`buzz-acp`** — a Rust binary that bridges the Buzz relay to AI agents:
```
┌──────────────┐ WebSocket ┌──────────┐ stdio ACP ┌───────────────┐
│ Buzz Relay │ ◄────────────────► │ buzz-acp │ ◄───────────────► │ Agent Binary │
│ (Nostr) │ (NIP-01 events) │ (harness)│ (JSON-RPC 2.0) │ (goose,codex, │
└──────────────┘ └──────────┘ │ claude-code) │
└───────────────┘
```
**How `buzz-acp` works (from `.env.example` + source analysis):**
1. **Connects to relay** via WebSocket using `BUZZ_PRIVATE_KEY` (Nostr keypair, NIP-42/98 auth)
2. **Subscribes to events** where the agent's pubkey appears in `p` tags (i.e., @mentions)
- `BUZZ_ACP_SUBSCRIBE=mentions` (default) — subscribe only to events mentioning agent
- `BUZZ_ACP_SUBSCRIBE=all` — subscribe to all channel events
- `BUZZ_ACP_SUBSCRIBE=config` — rule-based via TOML config file
3. **Spawns agent binary** as subprocess (Goose, Codex, Claude Code, or any ACP agent)
- `BUZZ_ACP_AGENT_COMMAND` / `BUZZ_ACP_AGENT_ARGS`
4. **Forwards prompts** to agent via ACP `session/prompt`, streams results back to relay
5. **Manages presence** (kind 20001 online/offline), typing indicators (kind 20002), dedup
**Key insight:** `buzz-acp` itself IS the WebSocket-to-stdio bridge. It doesn't expose a remote API — it IS the client that connects to the relay and spawns agents. There is **no existing `buzz-acp` HTTP API** to connect remote agents to.
### 1.4 The @mention Mechanism
In Buzz/Nostr, "mentioning" an agent means including its Nostr pubkey as a `p` tag in a channel message event. The relay's subscription registry fans out matching events to all subscribed WebSocket clients. `buzz-acp` subscribes with a filter like `{"#p": [agent_pubkey]}` and receives all events that tag that pubkey. There is **no special server-side routing** — it's standard Nostr subscription fan-out.
---
## 2. Integration Architecture Options
### 2.1 Option A: Bridge Agent (Stdio ACP Proxy)
Deploy a lightweight binary on Core (or app3) that:
1. Implements the ACP client side (speaks JSON-RPC 2.0 over stdio to a dummy agent)
2. OR implements the ACP agent side (so `buzz-acp` can spawn it) that proxies to Hermes
```
┌──────────┐ WS ┌──────────┐ stdio ACP ┌──────────────┐ HTTP/WS ┌──────────┐
│ Relay │◄─────►│ buzz-acp │◄──────────►│ Bridge Binary │◄────────►│ Hermes │
└──────────┘ └──────────┘ └──────────────┘ └──────────┘
(runs on Core)
```
**How it works:**
- `buzz-acp` spawns the bridge binary as an ACP agent subprocess
- Bridge binary receives ACP `session/prompt` containing the user's message
- Bridge forwards it to Hermes via REST API or WebSocket
- Hermes processes, returns response
- Bridge sends response back through ACP `session/update` notifications
**Pros:**
- Uses Buzz's native agent machinery (presence, typing, turn lifecycle)
- Agent appears in Buzz Desktop's agent panel naturally
- Gets @mention routing for free via `buzz-acp`
**Cons:**
- `buzz-acp` must run on a machine that can reach Hermes (not a laptop — would need to run on Core or app3)
- Stdio bridge is fragile (subprocess lifecycle, crash recovery, binary distribution)
- ACP is designed for local coding agents, not remote conversational agents — impedance mismatch
- Bridge must implement full ACP agent spec (initialize, sessions, tool calls, cancellation)
- `buzz-acp` is a desktop-side component — running it headless on a VPS is an off-label use
- Requires compiling and maintaining a Rust binary (ACP SDK crate)
**Effort:** High. Requires implementing an ACP-compliant agent from scratch.
### 2.2 Option B: Nostr-Native WebSocket Client (RECOMMENDED)
Hermes connects directly to the Buzz relay as a Nostr WebSocket client with its own keypair — exactly how `buzz-acp` and the Buzz Desktop app connect.
```
┌──────────┐ WebSocket (NIP-01/42/98) ┌──────────┐
│ Relay │◄─────────────────────────────────────►│ Hermes │
└──────────┘ Signed Nostr events (kind 9) └──────────┘
@mentions via p-tag subscriptions
```
**How it works:**
1. Hermes generates or is assigned a Nostr keypair (pubkey = Buzz identity)
2. Hermes connects to `wss://buzz.iamgmb.com` via WebSocket
3. Hermes authenticates via NIP-42 (signed AUTH challenge) or NIP-98 (HTTP auth)
4. Hermes subscribes to events with `{"#p": [hermes_pubkey]}` — receives all @mentions
5. When a mention arrives, Hermes routes it to its AI pipeline, generates a response
6. Hermes publishes a signed Nostr event (kind 9 or 40002) back to the same channel
7. Hermes manages presence (kind 20001) and typing indicators (kind 20002)
**Proof of concept: OpenClaw Buzz Plugin**
[OpenClaw's Buzz channel plugin](https://docs.openclaw.ai/channels/buzz) does exactly this. It connects an OpenClaw gateway (server-side agent platform) to Buzz as a Nostr client. Key details from their docs:
- Connects to relay via WebSocket with a dedicated Nostr keypair
- Bot identity must be added to rooms with **Bot** role via `buzz channels add-member --role bot`
- Subscribes to room events, handles kind 9 (normal messages), kind 40002 (rich-content), kind 40008 (structured diffs)
- Publishes presence every 30 seconds
- Sends typing indicators (kind 20002) while processing
- Supports NIP-27 native mentions in replies
- Handles reconnection, dedup, and stale session recovery
- One identity can serve many rooms
**Pros:**
- **Architecturally correct** — Buzz IS a Nostr relay. Connecting as a Nostr client is the first-class path.
- No desktop dependency — runs entirely server-side
- Proven pattern (OpenClaw already does this successfully)
- Hermes gets full Buzz citizenship: presence, typing, reactions, profile, DMs
- Uses standard protocols: WebSocket + JSON (NIP-01), Schnorr signatures
- No ACP impedance mismatch — Hermes processes messages its own way
- Can be implemented in Python (websockets + nostr-py or `secp256k1` bindings)
- Coexists with other agents — Hermes is just another pubkey in the channel
- Reuses Hermes's existing AI pipeline, tools, and skills
**Cons:**
- Must implement Nostr protocol handling (event signing, subscription management, NIP-42 auth)
- Does NOT use Buzz's native ACP agent panel UI — Hermes appears as a "bot" member, not a managed agent
- No turn lifecycle management (ACP's `session/prompt` → `end_turn` model)
- Must handle WebSocket reconnection, event dedup, and subscription state
- Nostr python libraries are less mature than JS/Rust ecosystems
**Effort:** Medium. Requires a Nostr client module in Python (~500-800 lines).
### 2.3 Option C: Webhook Adapter (Buzz Workflows)
Use Buzz's YAML workflow engine to detect @mentions and fire webhooks to Hermes's REST API.
```
┌──────────┐ Buzz Workflow ┌─────────────┐ HTTP POST ┌──────────┐
│ Relay │────────►────────►│ Workflow │────────────►│ Hermes │
│ (event) │ trigger on │ Engine │ webhook │ REST API │
└──────────┘ kind 9 + p-tag └──────┬───────┘ └────┬─────┘
│ │
┌──────▼───────┐ ┌──────▼─────┐
│ Response │◄─────────│ AI reply │
│ back to │ REST API │ generated │
│ channel │ └────────────┘
└──────────────┘
```
**How it works:**
1. Create a Buzz workflow YAML that triggers on new messages in specific channels
2. Workflow filter matches events where `p` tag includes Hermes's pubkey
3. On match, workflow fires a `webhook` action to Hermes's REST API
4. Hermes processes the message and generates a response
5. Response is posted back to the channel via `buzz-cli` or relay REST API (NIP-98 signed)
**Buzz workflow capabilities (from ARCHITECTURE.md):**
- Triggers: message, reaction, schedule, webhook
- Actions: send message, add reaction
- `send_dm` and `set_channel_topic` actions are stubbed (return `NotImplemented`)
- Approval gates partially wired (WF-08: runs hitting approval gates fail)
**Pros:**
- Zero new protocol code — uses HTTP webhooks and REST API
- Leverages existing Buzz features (workflows are YAML-defined, relay-managed)
- Simple mental model — "when someone @mentions Hermes, POST to this URL"
- Hermes's existing REST API can be the webhook target
- No Nostr key management for Hermes (workflow signs events on its behalf)
**Cons:**
- **Workflow engine has gaps:** `send_dm` and `set_channel_topic` return `NotImplemented` (ARCHITECTURE.md §9, WF-07). Approval gates are partially broken (WF-08). Unknown if webhook→Hermes→response path works end-to-end.
- Workflow execution latency — not real-time; workflow engine processes events on a schedule
- Workflows can only react to events, not participate — no typing indicators, presence, or ongoing conversation state
- Hermes would not have its own Nostr identity — it's the workflow acting on its behalf
- No conversational context — each @mention is a fresh workflow run
- The workflow engine is undergoing active development; breaking changes possible
- Rate limiting unknown for workflow-triggered actions
**Effort:** Low to prototype, high risk of hitting engine limitations.
### 2.4 Option D: Future ACP Remote Transport
Wait for the ACP Transports Working Group to ship the Streamable HTTP / WebSocket remote transport, then have Hermes implement the ACP agent side over that transport.
**Status:** RFD stage — no timeline, no implementation.
**Pros:**
- Eventually the "right" answer — fully standards-compliant
- Hermes would be a first-class managed agent in Buzz Desktop
- Remote transport is being designed for exactly this use case
**Cons:**
- **Does not exist yet.** Building anything that depends on it today is blocked.
- Timeline unknown — could be months or years
- Would still need to implement ACP agent protocol (not just transport)
- ACP is coding-agent-optimized; conversational agents are a secondary concern
**Effort:** Blocked. Cannot proceed until spec is finalized and implemented.
---
## 3. Comparison Matrix
| Criterion | Bridge Agent (A) | Nostr-Native (B) | Webhook (C) | Future ACP (D) |
|-----------|:---:|:---:|:---:|:---:|
| **Works today** | ⚠️ Off-label | ✅ Proven (OpenClaw) | ⚠️ Workflow gaps | ❌ Doesn't exist |
| **Deployment complexity** | High (Rust binary) | Medium (Python module) | Low (YAML + HTTP) | Unknown |
| **Latency** | Low (WebSocket → stdio) | Low (WebSocket native) | Medium-High (workflow poll) | Low |
| **Reliability** | Medium (subprocess mgmt) | High (direct WS) | Low (engine gaps) | Unknown |
| **Buzz agent UX** | Full (ACP panel) | Bot member (no ACP panel) | None (workflow) | Full (ACP panel) |
| **Hermes identity** | Via buzz-acp key | Own Nostr keypair | Relay-owned (workflow) | Own ACP identity |
| **Presence/typing** | ✅ | ✅ | ❌ | ✅ |
| **Conversational context** | Via ACP sessions | App-level state | ❌ (per-invocation) | Via ACP sessions |
| **Maintenance burden** | High | Medium | Low (but fragile) | Unknown |
| **Protocol maturity** | ACP v1 (stable) | NIPs (stable) | Buzz workflows (beta) | ACP remote (pre-RFC) |
| **Coexists w/ other agents** | ✅ | ✅ | ✅ | ✅ |
---
## 4. Recommended Path: Nostr-Native WebSocket Client
### 4.1 Justification
The Nostr-native approach is recommended for the following reasons:
1. **Architectural correctness.** Buzz IS a Nostr relay. Connecting as a Nostr client is the protocol's first-class integration path. The relay doesn't distinguish between "human," "agent," or "bot" — all are Nostr keypairs publishing signed events. Hermes joining as another keypair is exactly how Buzz was designed to work.
2. **Proven in production.** OpenClaw's Buzz plugin has already solved this exact problem — connecting a server-side AI agent platform to Buzz channels via WebSocket. Their docs describe a working implementation with presence, typing indicators, mention handling, and reconnection logic.
3. **No desktop dependency.** This approach runs entirely on Core. No `buzz-acp` binary needed. No ACP stdio bridge. No subprocess lifecycle management.
4. **Full Buzz citizenship.** Hermes gets its own Nostr identity, can have a profile (kind 0), presence status, typing indicators, and can participate in any channel it's added to.
5. **No blocking dependencies.** The Nostr protocol is stable (NIP-01, NIP-42, NIP-98). The ACP remote transport is not.
6. **Leverages existing Hermes infrastructure.** Hermes already has a REST API, Telegram integration, MCP tools, and an AI pipeline. The Nostr client becomes another input/output channel alongside those.
7. **Coexistence.** If Buzz later ships remote ACP transport, a Nostr-native Hermes can operate alongside ACP-managed agents. The two approaches are complementary, not mutually exclusive.
**Trade-offs accepted:**
- Hermes appears as a "Bot" member in Buzz, not in the managed-agent ACP panel
- No turn lifecycle management from Buzz's perspective (Hermes manages its own conversational state)
- Must maintain WebSocket connection health (but this is standard infrastructure)
### 4.2 What "Bot" Member Means in Practice
In Buzz, a bot member with a Nostr keypair:
- Can be @mentioned like any other member
- Can post messages, reactions, and edits
- Has an online/offline presence indicator
- Shows typing indicators while processing
- Can be added to or removed from channels
- Has a profile (display name, avatar)
- Appears in the member list with a "Bot" role badge
- Cannot be spawned/managed via ACP (no agent panel controls)
This is functionally equivalent to how Slack bots, Discord bots, or Telegram bots work — they're members of the room, not subprocesses managed by the client.
---
## 5. Implementation Outline
### 5.1 Components
```
┌──────────────────────────────────────────────────────────────┐
│ Core (Hermes VPS) │
│ │
│ ┌─────────────────┐ ┌──────────────────────────────┐ │
│ │ Hermes Core │◄───►│ Buzz Nostr Client Module │ │
│ │ (AI pipeline, │ │ │ │
│ │ tools, skills) │ │ ┌──────────┐ ┌───────────┐ │ │
│ │ │ │ │ WS Conn │ │ Event Sign │ │ │
│ │ │ │ │ Manager │ │ er (Schnorr│ │ │
│ │ │ │ └──────────┘ └───────────┘ │ │
│ │ │ │ ┌──────────┐ ┌───────────┐ │ │
│ │ │ │ │ Sub Mgmt │ │ Presence │ │ │
│ │ │ │ └──────────┘ └───────────┘ │ │
│ └─────────────────┘ └──────────────┬───────────────┘ │
│ │ │
└─────────────────────────────────────────┼─────────────────────┘
│ WebSocket (WSS)
│ NIP-01 events
┌─────▼──────┐
│ Buzz Relay │
│ (app3) │
└────────────┘
```
**New components:**
1. **`buzz_client.py`** — Nostr WebSocket client module (~500 lines)
- WebSocket connection management (connect, reconnect, heartbeat)
- NIP-42 authentication (sign AUTH challenge)
- Event signing (Schnorr signatures via `secp256k1` or `nostr-py`)
- Subscription management (REQ, CLOSE, EVENT delivery)
- Event publishing (EVENT → relay)
2. **`buzz_channel.py`** — Hermes channel adapter (~200 lines)
- Bridges Buzz events ↔ Hermes message pipeline
- Filters events (ignore self, dedup by event ID)
- Converts Nostr events to Hermes internal message format
- Routes Hermes responses back to Buzz channels
- Manages presence updates (30s interval)
3. **Buzz identity** — one Nostr keypair
- Generated via `buzz-admin generate-key` on app3
- Private key stored in Hermes secrets/env
- Public key added to relay membership and target channels
### 5.2 Protocols & Wire Format
**Connection:**
```
Client Relay (wss://buzz.iamgmb.com)
│ WebSocket connect │
│─────────────────────────────────────────►│
│ ← AUTH challenge │
│◄─────────────────────────────────────────│
│ AUTH response (signed challenge) │
│─────────────────────────────────────────►│
│ ← AUTH OK │
│◄─────────────────────────────────────────│
```
**Subscription (NIP-01 REQ):**
```json
["REQ", "hermes-mentions", {"#p": ["<hermes_pubkey_hex>"], "kinds": [9, 40002], "since": <last_seen_timestamp>}]
```
**Message format (kind 9 — NIP-29 group chat):**
```json
{
"id": "<sha256>",
"pubkey": "<sender_pubkey>",
"kind": 9,
"tags": [
["h", "<channel_uuid>"],
["p", "<hermes_pubkey>"],
["e", "<thread_root>", "", "reply"]
],
"content": "{\"text\": \"@Hermes what's the status of the backup?\"}",
"sig": "<schnorr_sig>",
"created_at": 1234567890
}
```
**Response message (kind 9):**
```json
{
"id": "<sha256>",
"pubkey": "<hermes_pubkey>",
"kind": 9,
"tags": [
["h", "<channel_uuid>"],
["e", "<thread_root>", "", "reply"],
["p", "<requester_pubkey>"]
],
"content": "{\"text\": \"The backup completed successfully at 03:00 UTC. Latest snapshot: backup-2026-08-07.tar.gz\"}",
"sig": "<schnorr_sig>",
"created_at": 1234567895
}
```
**Presence (kind 20001, ephemeral, not stored):**
```json
["EVENT", {
"kind": 20001,
"content": "{\"status\": \"online\"}",
"tags": [],
...
}]
```
**Typing indicator (kind 20002, ephemeral):**
```json
["EVENT", {
"kind": 20002,
"content": "",
"tags": [["h", "<channel_uuid>"]],
...
}]
```
### 5.3 Auth Model
**Nostr keypair:**
- Generate via `buzz-admin generate-key` on app3 (or `openssl rand -hex 32` for privkey → derive pubkey via secp256k1)
- Hermes holds the private key (nsec or hex) in environment/secrets
- Public key (64-char hex) is used for:
- Relay membership: `./run.sh add-member <hermes_pubkey> --role member`
- Channel membership: `buzz channels add-member --channel <uuid> --pubkey <hermes_pubkey> --role bot`
- NIP-98 HTTP auth for REST API calls (if using REST fallback)
**NIP-42 authentication flow:**
1. Relay sends `["AUTH", "<challenge_string>"]` on WebSocket connect
2. Hermes constructs a kind 22242 auth event: `{"kind": 22242, "tags": [["challenge", challenge], ["relay", "wss://buzz.iamgmb.com"]], "content": "", ...}`
3. Hermes signs the event with its private key (Schnorr)
4. Hermes sends `["AUTH", <signed_event>]` to relay
5. Relay verifies signature and pubkey membership → connection authenticated
**API token alternative:**
Buzz supports API tokens as an alternative to NIP-42/NIP-98 for service accounts. This would replace the WebSocket auth dance with a static bearer token. However, API tokens are less documented and may not support all event kinds.
### 5.4 Deployment
| Component | Location | Details |
|-----------|----------|---------|
| Buzz Nostr client module | Core (Hermes VPS) | Python module imported by Hermes; runs in-process |
| Nostr keypair | Core (secrets) | Private key in `.env` or HashiCorp Vault |
| Relay membership | app3 | `./run.sh add-member` once during setup |
| Channel membership | app3 (via buzz-cli) | `buzz channels add-member --role bot` per channel |
| WebSocket connection | Core → app3:443 | WSS through CloudPanel Nginx |
**Note:** The WebSocket connection goes through CloudPanel's Nginx reverse proxy (`wss://buzz.iamgmb.com`). CloudPanel already includes WebSocket upgrade headers — no Nginx config changes needed.
### 5.5 Python Dependencies
| Package | Purpose |
|---------|---------|
| `websockets` | Async WebSocket client |
| `secp256k1` (or `coincurve`) | Schnorr signature signing/verification |
| `cryptography` | SHA-256 hashing for event IDs |
| `bech32` | npub/nsec encoding (optional, for UX) |
**Or:** Use `nostr-py` / `python-nostr` if they're mature enough. Research needed.
### 5.6 Effort Estimate
| Phase | Work | Est. Days |
|-------|------|-----------|
| **Prototype** | Nostr event signing + WebSocket connect + basic REQ/EVENT | 2-3 |
| **Channel adapter** | Message routing, dedup, mention detection, response posting | 2-3 |
| **Polish** | Presence, typing indicators, reconnection, error handling | 2-3 |
| **Integration** | Wire into Hermes's message pipeline + tool access | 2-3 |
| **Testing** | Multi-channel, concurrent mentions, reconnect scenarios | 2-3 |
| **Total** | | **10-15 days** |
This assumes the developer is familiar with Nostr protocol basics and Python async programming.
### 5.7 Alternate: Use `buzz-cli` as a Thin Proxy
As a lower-effort starting point, Hermes could use the existing `buzz-cli` binary for outbound messaging (posting replies) instead of implementing Nostr event signing from scratch:
```python
# Post a reply via buzz-cli
subprocess.run([
"buzz", "messages", "send",
"--channel", channel_uuid,
"--content", response_text,
"--reply-to", thread_event_id
], env={"BUZZ_RELAY_URL": "wss://buzz.iamgmb.com", "BUZZ_PRIVATE_KEY": hermes_nsec})
```
This avoids implementing Schnorr signing in Python but still requires a separate mechanism for **listening** to inbound mentions (since `buzz-cli` is request-response, not a persistent listener). The WebSocket subscription must still be implemented.
---
## 6. Open Questions
### 6.1 Must-Answer Before Building
| # | Question | How to Answer |
|---|----------|---------------|
| Q1 | **Does `buzz-cli` support a persistent listen/subscribe mode?** Current docs show only REST commands. If it has a hidden `buzz listen` or `buzz stream` mode, the implementation simplifies dramatically. | Search `buzz-cli/src/` for listen/stream/subscribe; test with `buzz help` |
| Q2 | **What Python Nostr library is production-ready?** `nostr-py`, `python-nostr`, `nostr-sdk`? We need WebSocket client + Schnorr signing + NIP-42 auth. | Test each library against `wss://buzz.iamgmb.com` with a test keypair |
| Q3 | **Can a non-ACP agent get the "Bot" role and appear in the member list?** OpenClaw does this, but need to verify exact permissions/UX. | Test with a manually-generated keypair added via `buzz channels add-member --role bot` |
| Q4 | **What happens when an agent is @mentioned in a channel it hasn't joined?** Does the relay deliver the event anyway? Does Buzz Desktop show it? | Test by subscribing to #p tag without channel membership |
| Q5 | **How does message threading work for agents?** Can Hermes reply in-thread by including the root event tag? | Examine OpenClaw's threading implementation; test manually |
| Q6 | **What's the rate limit for agent-standard tier?** Config defaults show 120 messages/min, but enforcement is stubbed (`AlwaysAllowRateLimiter`). | Check if rate limiting is enforced in our relay version |
### 6.2 Would-Be-Nice Answers
| # | Question |
|---|----------|
| Q7 | When will the ACP remote transport ship? (Informs whether to invest in Nostr-native or wait for ACP) |
| Q8 | Can Buzz workflows be used as a reliable event bridge, or are the `NotImplemented` stubs blocking? |
| Q9 | Does the relay's REST API support subscribing to events via long-poll or SSE? (Alternative to WebSocket for listening) |
| Q10 | Can Hermes's profile (kind 0) include custom metadata that Buzz Desktop renders (e.g., "AI Assistant" badge)? |
| Q11 | How does agent-to-agent communication work in Buzz? Can Hermes @mention another agent? |
| Q12 | What's the multi-community story? If we host multiple Buzz communities on the same relay, can one Hermes identity participate in all? |
---
## 7. References
| Resource | URL |
|----------|-----|
| Buzz GitHub | https://github.com/block/buzz |
| Buzz README | https://github.com/block/buzz/blob/main/README.md |
| Buzz Architecture | https://github.com/block/buzz/blob/main/ARCHITECTURE.md |
| Buzz Agent Vision | https://github.com/block/buzz/blob/main/VISION_AGENT.md |
| buzz-acp crate | https://github.com/block/buzz/tree/main/crates/buzz-acp |
| buzz-cli crate | https://github.com/block/buzz/tree/main/crates/buzz-cli |
| buzz-agent crate | https://github.com/block/buzz/blob/main/crates/buzz-agent/README.md |
| ACP Specification | https://agentclientprotocol.com/ |
| ACP Schema | https://agentclientprotocol.com/protocol/v1/schema |
| ACP Remote Transport RFD | https://agentclientprotocol.com/rfds/streamable-http-websocket-transport |
| ACP GitHub | https://github.com/agentclientprotocol/agent-client-protocol |
| Buzz .env.example | https://github.com/block/buzz/blob/main/.env.example |
| OpenClaw Buzz Plugin | https://docs.openclaw.ai/channels/buzz |
| Buzz Self-Host Guide | https://engineering.block.xyz/blog/run-your-own-buzz-relay |
| Buzz Skill (internal) | `~/.hermes/skills/devops/buzz-self-hosted-relay/SKILL.md` |
| Our relay deployment | `/opt/buzz/deploy/compose` on app3 (152.53.241.111) |
---
## Appendix A: Nostr NIPs Used by Buzz
From ARCHITECTURE.md and source analysis:
| NIP | Name | Buzz Usage |
|-----|------|------------|
| NIP-01 | Basic protocol | Event format, REQ/EVENT/CLOSE messages |
| NIP-02 | Contact list | User contacts/follows |
| NIP-05 | DNS-based identity | `/.well-known/nostr.json` |
| NIP-11 | Relay info | `GET /` returns relay metadata |
| NIP-16 | Replaceable events | Profile (kind 0), channel metadata |
| NIP-25 | Reactions | Kind 7 emoji reactions |
| NIP-27 | Text note references | `nostr:npub1...` and `nostr:note1...` |
| NIP-29 | Group chat | Kind 9 stream messages |
| NIP-34 | Git hosting | Repository announcements, patches |
| NIP-38 | User statuses | Profile status text+emoji |
| NIP-42 | Auth | `AUTH` challenge-response on WebSocket |
| NIP-98 | HTTP Auth | Schnorr-signed kind 27235 for REST API |
## Appendix B: Buzz Custom Event Kinds
| Kind | Name | Description |
|------|------|-------------|
| 9 | Stream message | Channel chat message (NIP-29) |
| 7 | Reaction | Emoji reaction (NIP-25) |
| 20001 | Presence | Ephemeral online/away status |
| 20002 | Typing | Ephemeral typing indicator |
| 22242 | Auth | NIP-42 authentication event |
| 27235 | HTTP Auth | NIP-98 HTTP authentication |
| 40002 | Stream message v2 | Rich-content channel message |
| 40003 | Stream message edit | Edit of a previous message |
| 40008 | Structured diff | Code diff with metadata |
| 43001 | Job request | Agent job request (ACP) |
| 40100 | Canvas | Channel canvas content |