//DOCS Buzz Bridge

Buzz Bridge Operations

Punk accepts verified ordinary Buzz kind-9 mentions into a tenant-scoped durable inbox. The bridge derives relay, channel, author, app, agent, subject, membership, and allowed actions from the current server-owned managed mapping. Event content and caller-supplied Punk identity headers never select execution authority.

The repository includes isolated relay, inbox, terminal-outbox, and publisher workers. The operator API reports their health as not_reported until a deployment supplies a concrete health handshake; queue movement is evidence, not a process heartbeat. Buzz native job kinds 43001 through 43006 remain unsupported.

Configure A Community

Deploy or obtain a Buzz community first. Create and admit a dedicated service signer there, then store it as a buzz-nostr signer in Punk's credential vault. Settings > Buzz becomes visible to tenant-wide administrators after that provisioning step. Use it or POST /api/v1/buzz/mappings to connect the existing deployment. Punk does not create the Buzz deployment, relay, community, or signer. Private signer material is never accepted by the mapping API:

{
  "connectorInstanceId": "buzz-company",
  "expectedHost": "buzz.example.com",
  "dashboardBaseUrl": "https://punk.example.com/",
  "appId": "buzz",
  "relayUrl": "wss://buzz.example.com/",
  "signerCredentialId": "cred_buzz_signer",
  "signerPubkey": "64-lowercase-hex-characters",
  "channels": [{
    "channelId": "11111111-1111-4111-8111-111111111111",
    "agentId": "crew",
    "agentPubkey": "64-lowercase-hex-characters",
    "workflowId": "wf_crew"
  }],
  "actors": [{
    "pubkey": "64-lowercase-hex-characters",
    "subject": "person-stable-id",
    "memberships": [{
      "channelId": "11111111-1111-4111-8111-111111111111",
      "agentId": "crew",
      "role": "member",
      "allowedActions": ["workflow.invoke"],
      "scopeVersion": "scope-v1"
    }]
  }],
  "reason": "connect the governed Crew channel"
}

Mappings are immutable, versioned, and audited. Updates use expected-version checks; disconnect, signer rotation, and revocation append new versions rather than overwriting evidence. Configuration fails closed on unknown fields, overlapping channel ownership, malformed identities, inactive credentials, or unbounded values.

Create a non-admin, app-pinned Punk key for the configured appId. Use optimize only after observe-mode validation:

{
  "name": "Buzz runtime",
  "appId": "buzz",
  "mode": "optimize",
  "admin": false
}

Operator Dashboard

Open Settings > Buzz. The page shows only communities owned by the current tenant and, for app-pinned callers, only communities for that app.

The page includes:

• expected community host, connector id, and accepted kind;
• agent public identity, channel mappings, and actor-to-subject mappings;
• exact inbox and outbox queue counts, oldest queued item, and dead letters;
• last received and last successfully published timestamps;
• app-pinned optimize/observe key posture;
• recent event status and bounded Punk run, workflow, receipt, evidence, and

outbox references when worker audit evidence contains those links;

• an admin-only retry control for dead-lettered inbox events.

The API and dashboard never return intake secrets, private keys, credentials, lease tokens, stored message content, raw tags, reply content, unrestricted worker errors, or another tenant's records. Error presence is shown as a boolean; detailed failures stay in restricted server logs.

Operator API

The internal intake API is independently authenticated with the configured community secret:

Acceptance

Before production traffic:

1. Verify relay TLS and the exact expected host.
2. Admit only approved actor public keys and channels.
3. Use a non-admin app-pinned Punk key in observe mode.
4. Send one signed ordinary kind-9 mention.
5. Confirm one inbox row, an audit-only accepted state, no outbox message, and no duplicate on replay.
6. Start the separately deployed inbox worker and publisher.
7. Confirm run, workflow, receipt, and outbox correlation in Settings > Buzz.
8. Confirm exactly one signed terminal reply is published and lastPublishedAt advances.
9. Exercise one dead-letter retry and retain its audit record.
10. Switch the app-pinned key to optimize only after policy and response review.

Queue movement alone does not prove a relay subscription or worker is healthy. Operational deployment should add explicit process heartbeats before changing the corresponding dashboard capability status from not_reported.

Ordinary conversational work keeps accepted and queued state in Punk's durable audit ledger and publishes only one terminal reply. The reply links to the exact run using the mapping's validated dashboardBaseUrl; failure and reconciliation outcomes use the same descriptive link and never expose a bare internal run id. Approval-required work may additionally publish its explicit approval request and decision outcome. Punk does not publish generic permanent accepted/queued progress messages.

Buzz's relay currently returns EOSE without consistently retaining the live REQ. Punk therefore renews the canonical subscription once per second on the same authenticated WebSocket. This keeps owner-authored mentions prompt without using connection churn as polling. relayTransport.idleTimeoutMs only defines when a successful session resets reconnect backoff. Real disconnects retain bounded replay and durable relay-event-id deduplication.