better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/a2a.md

@@ -1,130 +0,0 @@
-# A2A (Agent-to-Agent)
-
-[A2A](https://a2a-protocol.org) is the open Agent2Agent protocol (v1.0, stewarded by the Linux Foundation) for communication between independent AI agents. The Hermes A2A plugin works in **both directions**: your agent can call other A2A agents as tools, and other agents can send tasks to your Hermes over HTTP.
-
-It interoperates with any A2A-compliant peer — another Hermes, LangChain, CrewAI, Google ADK agents, or anything built on the official `a2a-sdk`.
-
-## When to use A2A
-
-- **Hermes ↔ Hermes across machines** — let your desktop agent hand tasks to a Hermes on a server, or vice versa, each with its own memory, tools, and credentials.
-- **Delegating to specialist agents** — a peer that advertises `web_search`/`research`/`coding` skills on its Agent Card can be discovered and called mid-conversation.
-- **Being a callable service** — expose your Hermes so other frameworks' agents can send it tasks.
-
-When you want multiple agents on the **same machine**, prefer [delegation](../features/delegation.md) (in-process subagents) or the [kanban board](../features/kanban.md) (durable multi-profile work queue) — A2A is for crossing process/machine/framework boundaries.
-
-## Enable
-
-```bash
-hermes gateway setup      # pick A2A
-```
-
-Or in `~/.hermes/config.yaml`:
-
-```yaml
-gateway:
-  platforms:
-    a2a:
-      enabled: true
-      extra:
-        port: 9900
-```
-
-The outbound client tools ship as the `a2a` toolset, **off by default** — enable it per platform:
-
-```bash
-hermes tools enable a2a --platform cli        # CLI/TUI sessions
-hermes tools enable a2a --platform telegram   # or any messaging platform
-hermes tools enable a2a --platform a2a        # let inbound A2A tasks call peers (agent chaining)
-```
-
-The tools are available in every process type — CLI, TUI, gateway, and cron — without the inbound platform needing to be enabled.
-
-## Outbound: calling other agents
-
-With the `a2a` toolset enabled, the agent gets:
-
-| Tool | What it does |
-|---|---|
-| `a2a_discover(url)` | Fetch and summarize a peer's Agent Card |
-| `a2a_call(agent, message, context_id?)` | Send a task, get the reply; multi-turn via `context_id` |
-| `a2a_list()` | Configured peers, saved conversations, metrics |
-| `a2a_history(context_id)` | Recall a persisted A2A conversation |
-| `a2a_orchestrate(capability, message, mode?)` | Fan a task out to every peer advertising a capability (`all` / `first` / `best`) |
-
-Configure known peers in `config.yaml`:
-
-```yaml
-a2a_agents:
-  researcher:
-    url: "http://research-box.local:9900"
-    auth: { type: bearer, token: "..." }
-    timeout: 120
-    capabilities: [web_search, research]
-```
-
-Then just ask: *"Ask the researcher agent to summarize today's arXiv postings."* Direct URLs work too — `a2a_call` accepts any A2A endpoint.
-
-## Inbound: being callable
-
-With the platform enabled, Hermes serves:
-
-- **Agent Card** at `GET /.well-known/agent-card.json` (canonical v1.0 path; the legacy `agent.json` also answers) — advertises your agent's name, skills (derived from enabled toolsets), and auth requirements.
-- **JSON-RPC 2.0** at `POST /` — canonical v1.0 methods (`SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification config CRUD) plus the pre-1.0 path-style aliases (`message/send`, …).
-- **SSE streaming** for `SendStreamingMessage`, with spec-correct JSON-RPC-enveloped frames.
-- **Push notifications** (webhooks) for long-running tasks, HMAC-SHA256 signed.
-
-Inbound tasks are injected into a **live gateway session** — the same agent, memory, and tools that serve your other channels — and the final reply is returned to the caller as the task result. Conversations are keyed by the A2A `contextId`, so a peer can hold a multi-turn exchange.
-
-Interoperability is verified against the official Python `a2a-sdk` (card resolution, `SendMessage`, streaming).
-
-## Security model
-
-Secure by default; every widening step is explicit:
-
-- **No token ⇒ localhost only.** The server binds `127.0.0.1`. Remote exposure requires a bearer token **and** an explicit `A2A_HOST`.
-- **Per-peer tokens** — `A2A_PEER_TOKENS="alice:tok1,bob:tok2"` gives each peer its own credential; the authenticated name drives rate limiting, trust, and audit.
-- **Prompt-injection filtering** — inbound text is filtered and framed as untrusted peer input. Remote peers cannot invoke operator slash commands.
-- **Outbound redaction** — credential-shaped strings (API keys, JWTs, tokens) are scrubbed from replies.
-- **Audit log** — every exchange appends to `~/.hermes/a2a_audit.jsonl`.
-- **Anti-loop** — per-context turn caps stop two agents ping-ponging forever.
-
-## Configuration reference
-
-| Env var | Default | Meaning |
-|---|---|---|
-| `A2A_PEER_TOKENS` | _(unset)_ | Per-peer credentials `name:token,…` (preferred) |
-| `A2A_BEARER_TOKEN` | _(unset)_ | Shared token; identity falls back to caller IP |
-| `A2A_HOST` | `127.0.0.1` | Bind host — only widens when a token is set |
-| `A2A_PORT` | `9900` | Inbound port |
-| `A2A_AGENT_NAME` | hostname-derived | Name on the Agent Card |
-| `A2A_PUBLIC_URL` | _(unset)_ | Routable URL advertised on the card (reverse proxies / k8s) |
-| `A2A_TRUSTED_PEERS` | _(unset)_ | Allow-list of authenticated identities |
-| `A2A_ALLOW_ALL_USERS` | `false` | Allow any authenticated peer (dev only) |
-| `A2A_RATE_LIMIT` | `60` | Requests/minute per identity |
-| `A2A_MAX_PINGPONG_TURNS` | `5` | Anti-loop turn cap per context (max 20) |
-| `A2A_REPLY_TIMEOUT` | `300` | Seconds to wait for the agent's reply. The orphan-task sweep never fails a task before this window elapses (floor 300s), and never while a request is still waiting on it |
-| `A2A_PUSH_SECRET` | bearer token | HMAC secret for push-notification signing |
-| `A2A_ADVERTISED_TOOLSETS` | all registered | Restrict which skills appear on the Agent Card |
-
-Behind a reverse proxy or Kubernetes Service, set `A2A_PUBLIC_URL` (or rely on `X-Forwarded-Host`/`X-Forwarded-Proto`) so the Agent Card advertises a URL peers can actually call back.
-
-## Quick test
-
-```bash
-# From another machine / agent:
-curl http://your-host:9900/.well-known/agent-card.json
-
-curl -X POST http://your-host:9900/ \
-  -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer <token>' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage",
-       "params":{"message":{"messageId":"m1","role":"ROLE_USER",
-                 "parts":[{"text":"What tools do you have?"}]}}}'
-```
-
-## Troubleshooting
-
-- **Peers can't reach the card URL** — the card was advertising your bind address; set `A2A_PUBLIC_URL` to the externally routable URL.
-- **`401 Unauthorized`** — token mismatch; check `A2A_PEER_TOKENS`/`A2A_BEARER_TOKEN` on the server and the peer's `auth:` block.
-- **Server won't bind non-localhost** — by design: set a bearer token first, then `A2A_HOST=0.0.0.0`.
-- **Replies time out on long tasks** — raise `A2A_REPLY_TIMEOUT` (the orphan sweep follows it, so a late reply is stored, not discarded), or have the caller register a push-notification config and poll `GetTask`.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/bluebubbles.md

@@ -1,171 +0,0 @@
-# BlueBubbles (iMessage)
-
-Connect Hermes to Apple iMessage via [BlueBubbles](https://bluebubbles.app/) — a free, open-source macOS server that bridges iMessage to any device.
-
-## Prerequisites
-
-- A **Mac** (always on) running [BlueBubbles Server](https://bluebubbles.app/)
-- Apple ID signed into Messages.app on that Mac
-- BlueBubbles Server v1.0.0+ (webhooks require this version)
-- Network connectivity between Hermes and the BlueBubbles server
-
-## Setup
-
-### 1. Install BlueBubbles Server
-
-Download and install from [bluebubbles.app](https://bluebubbles.app/). Complete the setup wizard — sign in with your Apple ID and configure a connection method (local network, Ngrok, Cloudflare, or Dynamic DNS).
-
-### 2. Get your Server URL and Password
-
-In BlueBubbles Server → **Settings → API**, note:
-- **Server URL** (e.g., `http://192.168.1.10:1234`)
-- **Server Password**
-
-### 3. Configure Hermes
-
-Run the setup wizard:
-
-```bash
-hermes gateway setup
-```
-
-Select **BlueBubbles (iMessage)** and enter your server URL and password.
-
-Or set environment variables directly in `~/.hermes/.env`:
-
-```bash
-BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
-BLUEBUBBLES_PASSWORD=your-server-password
-```
-
-#### Optional: Require mentions in group chats
-
-By default, Hermes responds to every authorized BlueBubbles/iMessage DM or group message. To make group chats opt-in, enable mention gating:
-
-```yaml
-platforms:
-  bluebubbles:
-    enabled: true
-    extra:
-      require_mention: true
-```
-
-With `require_mention: true`, DMs still work normally, but group-chat messages are ignored unless they match a mention pattern. If you do not configure custom patterns, Hermes uses conservative defaults for `Hermes` and `@Hermes agent` variants.
-
-For a custom agent name, set regex patterns:
-
-```yaml
-platforms:
-  bluebubbles:
-    extra:
-      require_mention: true
-      mention_patterns:
-        - '(?<![\w@])@?amos\b[,:\-]?'
-```
-
-### 4. Authorize Users
-
-Choose one approach:
-
-**DM Pairing (recommended):**
-When someone messages your iMessage, Hermes automatically sends them a pairing code. Approve it with:
-```bash
-hermes pairing approve bluebubbles <CODE>
-```
-Use `hermes pairing list` to see pending codes and approved users.
-
-**Pre-authorize specific users** (in `~/.hermes/.env`):
-```bash
-BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567
-```
-
-**Open access** (in `~/.hermes/.env`):
-```bash
-BLUEBUBBLES_ALLOW_ALL_USERS=true
-```
-
-### 5. Start the Gateway
-
-```bash
-hermes gateway run
-```
-
-Hermes will connect to your BlueBubbles server, register a webhook, and start listening for iMessage messages.
-
-## How It Works
-
-```
-iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
-Hermes → BlueBubbles REST API → Messages.app → iMessage
-```
-
-- **Inbound:** BlueBubbles sends webhook events to a local listener when new messages arrive. No polling — instant delivery.
-- **Outbound:** Hermes sends messages via the BlueBubbles REST API.
-- **Media:** Images, voice messages, videos, and documents are supported in both directions. Inbound attachments are downloaded and cached locally for the agent to process.
-
-## Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `BLUEBUBBLES_SERVER_URL` | Yes | — | BlueBubbles server URL |
-| `BLUEBUBBLES_PASSWORD` | Yes | — | Server password |
-| `BLUEBUBBLES_WEBHOOK_HOST` | No | `127.0.0.1` | Webhook listener bind address |
-| `BLUEBUBBLES_WEBHOOK_PORT` | No | `8645` | Webhook listener port |
-| `BLUEBUBBLES_WEBHOOK_PATH` | No | `/bluebubbles-webhook` | Webhook URL path |
-| `BLUEBUBBLES_HOME_CHANNEL` | No | — | Phone/email for cron delivery |
-| `BLUEBUBBLES_ALLOWED_USERS` | No | — | Comma-separated authorized users |
-| `BLUEBUBBLES_ALLOW_ALL_USERS` | No | `false` | Allow all users |
-| `BLUEBUBBLES_REQUIRE_MENTION` | No | `false` | Require a mention pattern before responding in group chats |
-| `BLUEBUBBLES_MENTION_PATTERNS` | No | Hermes wake words | JSON array, newline-separated, or comma-separated regex patterns for group mention matching |
-
-Auto-marking messages as read is controlled by the `send_read_receipts` key under `platforms.bluebubbles.extra` in `~/.hermes/config.yaml` (default: `true`). There is no corresponding environment variable.
-
-## Features
-
-### Text Messaging
-Send and receive iMessages. Markdown is automatically stripped for clean plain-text delivery.
-
-### Rich Media
-- **Images:** Photos appear natively in the iMessage conversation
-- **Voice messages:** Audio files sent as iMessage voice messages
-- **Videos:** Video attachments
-- **Documents:** Files sent as iMessage attachments
-
-### Tapback Reactions
-Love, like, dislike, laugh, emphasize, and question reactions. Requires the BlueBubbles [Private API helper](https://docs.bluebubbles.app/helper-bundle/installation).
-
-### Typing Indicators
-Shows "typing..." in the iMessage conversation while the agent is processing. Requires Private API.
-
-### Read Receipts
-Automatically marks messages as read after processing. Requires Private API.
-
-### Chat Addressing
-You can address chats by email or phone number — Hermes resolves them to BlueBubbles chat GUIDs automatically. No need to use raw GUID format.
-
-## Private API
-
-Some features require the BlueBubbles [Private API helper](https://docs.bluebubbles.app/helper-bundle/installation):
-- Tapback reactions
-- Typing indicators
-- Read receipts
-- Creating new chats by address
-
-Without the Private API, basic text messaging and media still work.
-
-## Troubleshooting
-
-### "Cannot reach server"
-- Verify the server URL is correct and the Mac is on
-- Check that BlueBubbles Server is running
-- Ensure network connectivity (firewall, port forwarding)
-
-### Messages not arriving
-- Check that the webhook is registered in BlueBubbles Server → Settings → API → Webhooks
-- Verify the webhook URL is reachable from the Mac
-- Check `hermes logs gateway` for webhook errors (or `hermes logs -f` to follow in real-time)
-
-### "Private API helper not connected"
-- Install the Private API helper: [docs.bluebubbles.app](https://docs.bluebubbles.app/helper-bundle/installation)
-- Basic messaging works without it — only reactions, typing, and read receipts require it
-

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/buzz.md

@@ -1,162 +0,0 @@
-# Buzz
-
-The Buzz adapter connects Hermes to a [Buzz](https://github.com/block/buzz) community — Block's open-source human+agent collaboration platform built on the Nostr protocol — and relays messages between Buzz channels (or DMs) and the agent. Outbound traffic shells out to the `buzz` CLI binary ("JSON in, JSON out"); inbound uses a native Nostr WebSocket subscription (via the already-bundled `websockets` package) with CLI polling as fallback. **No extra Python packages are required** — just the `buzz` binary.
-
-Buzz renders markdown, so agent replies keep their formatting. Images are delivered as uploads (local files) or links (URLs). Replies can thread onto an existing message via its event id. When progress or status messages are enabled, they inherit the triggering Buzz event as their reply anchor instead of appearing as unrelated top-level channel posts.
-
-Files sent **to** the agent are fetched back off the relay with the agent's authenticated identity and cached locally, so tools receive a real file path rather than a `/media/…` URL that anonymous requests cannot read. Images, audio, video, and documents (PDFs and the like) are all handled.
-
-Inbound messages arrive over a persistent NIP-42-authenticated Nostr WebSocket subscription by default (near-instant delivery), with automatic fallback to CLI polling when the WebSocket can't be established. Outbound messages always go through the `buzz` CLI. Control it with `transport` / `BUZZ_TRANSPORT`: `auto` (default), `websocket` (require WS, fail otherwise), or `poll`. If your relay membership uses NIP-OA owner attestation, set `BUZZ_AUTH_TAG` to the four-string auth tag JSON.
-
-> Run `hermes gateway setup` and pick **Buzz** for a guided walk-through.
-
-## Prerequisites
-
-- The `buzz` CLI binary on your `PATH` (or point `BUZZ_CLI_PATH` at it) — build it from the [Buzz repo](https://github.com/block/buzz) with `cargo build --release -p buzz-cli`
-- A Buzz community relay URL (e.g. `https://mycommunity.communities.buzz.xyz`)
-- A Nostr private key (nsec or hex) whose identity is already a **member** of that community
-
-## Configure Hermes
-
-You can configure Buzz two ways — the `gateway` block in `config.yaml` (canonical) or environment variables (which override it). The private key is a **secret** and always belongs in `~/.hermes/.env`.
-
-### Option A — config.yaml
-
-```yaml
-gateway:
-  platforms:
-    buzz:
-      enabled: true
-      extra:
-        relay_url: https://mycommunity.communities.buzz.xyz
-        attachment_hosts: []         # additional exact HTTPS host[:port] origins for inbound files
-        channels:                  # channel UUIDs to watch (empty = all joined)
-          - ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
-        home_channel: ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
-        poll_interval: 4           # seconds between inbound poll sweeps
-        cli_path: ""               # buzz binary (default: PATH, then ~/bin/buzz)
-        credentials_file: ""       # JSON file with the nsec (BUZZ_PRIVATE_KEY fallback)
-        allowed_users: []          # empty = allow all; hex pubkeys or npubs
-```
-
-Plus, in `~/.hermes/.env`:
-
-```
-BUZZ_PRIVATE_KEY=nsec1...
-```
-
-### Option B — environment variables
-
-| Variable | Required | Description |
-|----------|:--------:|-------------|
-| `BUZZ_RELAY_URL` | ✅ | Base URL of the community relay |
-| `BUZZ_PRIVATE_KEY` | ✅ | Nostr private key (nsec or hex) — the only secret |
-| `BUZZ_CHANNELS` | — | Comma-separated channel UUIDs to watch (default: all joined channels) |
-| `BUZZ_HOME_CHANNEL` | — | Channel UUID for cron / notification delivery (defaults to the first watched channel) |
-| `BUZZ_ALLOWED_USERS` | — | Comma-separated npubs or hex pubkeys allowed to talk to the agent |
-| `BUZZ_ALLOW_ALL_USERS` | — | Allow any community member to talk to the agent |
-| `BUZZ_POLL_INTERVAL` | — | Seconds between inbound poll sweeps (default: 4) |
-| `BUZZ_CLI_PATH` | — | Path to the `buzz` binary (default: `buzz` on PATH, then `~/bin/buzz`) |
-| `BUZZ_CREDENTIALS_FILE` | — | JSON credentials file holding the nsec, used when `BUZZ_PRIVATE_KEY` is unset |
-
-## Recommended default settings
-
-When wiring up Buzz, set these defaults in `config.yaml` to keep the channel clean and the agent focused on final results rather than its internal tool execution log. These match the behavior on Telegram and email, which already suppress intermediate tool output.
-
-```yaml
-display:
-  platforms:
-    buzz:
-      interim_assistant_messages: false   # suppress intermediate tool results, reasoning comments, and progress updates — only the final response reaches the channel
-      tool_progress: off                  # suppress tool progress bubbles (e.g., "Running terminal command...", "Reading file...")
-gateway:
-  platforms:
-    buzz:
-      enabled: true
-      extra:
-        relay_url: https://mycommunity.communities.buzz.xyz
-        attachment_hosts: []         # additional exact HTTPS host[:port] origins for inbound files
-        channels:                         # channel UUIDs to watch (empty = all joined)
-          - ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
-        home_channel: ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
-        poll_interval: 4                  # seconds between inbound poll sweeps (default 4 — balances latency vs. relay load)
-        cli_path: ""                      # buzz binary (default: PATH, then ~/bin/buzz)
-        credentials_file: ""              # JSON file with the nsec (BUZZ_PRIVATE_KEY fallback)
-        allowed_users: []                 # empty = allow all if allow_all_users is true; otherwise restrict to listed npubs/hex pubkeys
-        require_mention: true             # in channels: only respond when addressed (@name, npub, or hex pubkey); DMs always dispatch regardless
-        allow_all_users: false            # set true for community mode (everyone can chat, only owner is admin); false for private mode (only allowed_users)
-```
-
-**Why these defaults:**
-
-- `interim_assistant_messages: false` — prevents intermediate tool results, reasoning comments, and progress updates from being posted as separate messages to the channel. Only the final response goes to the channel.
-- `tool_progress: off` — suppresses tool progress bubbles (e.g., "Running terminal command...", "Reading file..."). Keeps the channel focused on actual results, not process.
-- `poll_interval: 4` — balances inbound latency (up to 4s delay) against relay load. Lower values increase polling frequency; higher values reduce it.
-- `allowed_users: []` + `allow_all_users: false` — private mode by default. Only listed users can interact. Set `allow_all_users: true` for community mode where everyone can chat (admin tier still restricted to the owner).
-- `require_mention: true` — in channels, the agent only responds when addressed. DMs always dispatch regardless of this setting.
-
-**Rationale:** Channels are for final results and conversation, not for the agent's internal tool execution log. Users see the final answer, not the steps taken to get there. This matches the behavior on Telegram and email, which already have these defaults.
-
-**Exception:** If you want users to see tool progress (e.g., for long-running operations), set `tool_progress: all` — but `interim_assistant_messages` should still be `false` to avoid spamming with every tool result.
-
-## Mentions, channels, and DMs
-
-- In shared channels the agent only responds when **addressed** — by `@name`, its npub, or its hex pubkey. Everything else is ignored.
-- Direct messages always reach the agent, no mention needed.
-- The agent's own messages are never dispatched back to it (self-echo suppression by pubkey), and every event is de-duplicated by event id against a per-channel high-water mark.
-
-## Reply threading
-
-Replies are threaded by default: the agent's answer (and any enabled progress/status messages) is anchored to the message that triggered it. Anchoring is NIP-10 aware — when the triggering message was already **inside** a thread, the agent replies to that thread's *root*, so the answer joins the existing thread instead of nesting a new one-message sub-thread under every turn.
-
-To post replies flat at the channel level instead, set either of these (they are equivalent; `reply_in_thread` matches the key Slack uses):
-
-```yaml
-gateway:
-  platforms:
-    buzz:
-      reply_to_mode: off          # PlatformConfig-level, like Discord/Telegram
-      extra:
-        reply_in_thread: false    # Slack-style key; env: BUZZ_REPLY_IN_THREAD
-```
-
-The opt-out applies to **all** send paths — final answers, streamed updates, interim commentary, tool-progress bubbles, and out-of-process cron delivery (`deliver=buzz`).
-
-## Access control
-
-By default the allow-list is empty, which means every community member who mentions the agent gets a response only if `BUZZ_ALLOW_ALL_USERS=true`; otherwise restrict access by listing npubs or hex pubkeys in `BUZZ_ALLOWED_USERS` (or `allowed_users` in config.yaml). Community membership itself is enforced by the relay — only members can post.
-
-The allow-list also gates **inbound attachments**: relay media is fetched with the agent's own Buzz credentials, so a download only happens for a sender the gateway explicitly authorizes. A denied, missing, or failed authorization leaves the message text untouched and makes no credentialed request.
-
-Cron jobs and notifications (`deliver=buzz`) are delivered to the **home channel** — `BUZZ_HOME_CHANNEL` if set, otherwise the first watched channel — and work even when cron runs outside the gateway process.
-
-## Inbound attachments
-
-Buzz messages with native NIP-94 `imeta` tags can deliver images, audio,
-video, and documents to the agent. Hermes downloads attachments only after
-the message has passed self-echo, addressing, and sender authorization checks.
-Each file must use HTTPS and declare an exact byte size and SHA-256 digest;
-redirects, URL credentials, fragments, oversized payloads, and integrity
-mismatches are rejected.
-
-The relay's own HTTPS origin is trusted automatically. If a community stores
-media on another public origin, add its exact `host` or `host:port` to
-`attachment_hosts` under `gateway.platforms.buzz.extra`. Non-default ports
-must be listed explicitly. Protected media that requires authenticated
-retrieval through the Buzz CLI is not handled by this native public-URL path.
-
-## Run the gateway
-
-```bash
-hermes gateway start
-```
-
-Check status with `hermes gateway status` — Buzz connection state is reported there, including for env-only setups.
-
-## Notes and limitations
-
-- **`BUZZ_*` env vars are available in terminal tool children for Buzz sessions** — the agent can invoke the `buzz` CLI directly (e.g. `buzz messages send ...`) because `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`, `BUZZ_RELAY_URL`, and the other `BUZZ_*` variables are passed through to terminal subprocesses when the session's platform is `buzz` or the process is a Buzz Desktop managed agent (`BUZZ_MANAGED_AGENT`). Non-Buzz sessions on the same host, `execute_code`, and other non-terminal spawns remain sealed.
-- **Inbound streaming has a watchdog.** On the WebSocket transport a connection that goes quiet for five minutes, or whose socket the relay closed underneath us, is torn down and reconnected with backoff; while that happens the gateway health (`/health/detailed`, dashboard status) reports Buzz as `retrying`, not `connected`. On the `poll` transport the adapter polls `buzz messages get` per watched channel every `poll_interval` seconds (default 4), so expect up to one interval of latency.
-- On (re)connect the adapter seeds its high-water mark from the newest events, so channel history is never replayed into the agent.
-- New DM conversations are discovered automatically (every few poll sweeps).
-- The private key is passed to the CLI via the subprocess environment — it never appears in argv or logs.