85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# Buzz integration
|
|
|
|
## Product boundary
|
|
|
|
Buzz is Lumbridge's first-class collaboration surface, not its control plane.
|
|
Lumbridge remains useful offline, owns its local workspace state, and never
|
|
requires a Buzz account to open a terminal or run an agent.
|
|
|
|
The initial integration provides:
|
|
|
|
- connect an existing Buzz identity using an OS credential-store reference;
|
|
- bind one or more Buzz channels to a Lumbridge workspace;
|
|
- read and post channel messages and replies from a collaboration pane;
|
|
- surface Buzz agents attached to a bound channel without pretending they are
|
|
local processes;
|
|
- share an approved pane image to an explicitly selected channel.
|
|
|
|
## Protocol shape
|
|
|
|
The pinned upstream is Block's Apache-2.0 Buzz repository at commit
|
|
`cb3144999bebc4939cb15b2200b373281d493b52`. `buzz-sdk` constructs typed Nostr
|
|
events and broker actions but deliberately owns neither identity keys nor
|
|
network connections. Lumbridge follows that separation:
|
|
|
|
```text
|
|
Lumbridge collaboration pane
|
|
| typed local command
|
|
lumbridge-buzz
|
|
| Buzz SDK event/broker action
|
|
identity signer + Buzz transport adapter
|
|
| signed WebSocket / HTTPS upload
|
|
Buzz relay and attachment storage
|
|
```
|
|
|
|
The exact revision stays pinned until an audited upgrade. We use Buzz's signed
|
|
protocol and SDK types rather than a parallel webhook format.
|
|
|
|
## Identity and local data
|
|
|
|
SQLite stores the account label, relay URL, public key, and an opaque secret
|
|
store handle. The Nostr private key stays in macOS Keychain or Linux Secret
|
|
Service. It must never enter SQLite, command arguments, crash reports, pane
|
|
history, logs, or Git configuration.
|
|
|
|
An installed Buzz CLI identity may be imported only through an explicit user
|
|
flow that transfers it into the OS credential store. Lumbridge must not search
|
|
the filesystem for keys. Buzz's current NIP-AB device-pairing tooling is marked
|
|
for interoperability testing upstream, so it is not a production login promise.
|
|
|
|
## Pane-image sharing
|
|
|
|
Sharing is a user-visible state machine:
|
|
|
|
1. Capture the selected pane only, excluding application chrome by default.
|
|
2. Detect likely secrets and render a local preview with proposed redactions.
|
|
3. Let the user adjust redactions, caption, and destination channel.
|
|
4. Require confirmation of that exact preview and destination.
|
|
5. Encode PNG or WebP, hash it, upload with the authenticated Buzz attachment
|
|
flow, and receive a canonical URL.
|
|
6. Build a kind-9 Buzz message with Markdown plus an `imeta` tag, sign it using
|
|
the OS-held identity, and publish it.
|
|
7. Persist only the resulting event ID, attachment metadata, destination, and
|
|
local audit outcome. Never persist the unredacted capture.
|
|
|
|
Any change to the pixels, caption, or destination invalidates confirmation. A
|
|
failed upload or publish is retryable but never reported as sent.
|
|
|
|
## Agent integration
|
|
|
|
Buzz agents and Lumbridge harnesses are different entities. A Buzz agent may be
|
|
shown in the collaboration pane and may exchange messages through Buzz's broker
|
|
contract. A local or remote Lumbridge harness remains owned by the Lumbridge
|
|
runtime and communicates through ACP or a supervised PTY. Linking the two later
|
|
requires an explicit capability grant, visible identity, and revocation path.
|
|
|
|
## Test plan
|
|
|
|
- deterministic unit tests for channel IDs, content limits, media metadata, and
|
|
the review/confirmation gate;
|
|
- signature tests with generated fixture identities only;
|
|
- integration tests against a disposable local Buzz relay and attachment store;
|
|
- disconnect, duplicate-delivery, cursor-resume, and publish-retry tests;
|
|
- rendered tests proving destination and redactions remain visible at confirm;
|
|
- a real-account smoke test only in a manually enabled, non-CI test profile.
|