buzz/REPORT.md

# Serverless Mode — Design Report

**Branch:** `micn/serverless-mode`
**Status:** feature-complete, verified end-to-end against live public relays.

This report explains what serverless mode is, the design decisions behind it,
how each piece works, and the evidence that it works end-to-end without
affecting the existing server-bound ("sprout relay") behaviour.

---

## 1. What it is

Serverless mode (a.k.a. "sprout-lite") lets the Sprout desktop app and the agent
harness talk **directly to generic public Nostr relays** with **no Sprout
infrastructure** — no `sprout-relay`, no Postgres, no Redis, no Typesense, no
auth/membership server. It is a **degraded subset** of Sprout: channels, DMs,
private channels, messages, threading, and agents — all expressed as plain Nostr
events over standard relays.

A workspace is either:

- **`sprout` mode** — talks to a Sprout relay via the HTTP bridge (`/query`,
  `/events`) + NIP-98 auth + NIP-42 AUTH WebSocket. (Unchanged, the default.)
- **`serverless` mode** — talks to a comma-separated **list** of public relays
  over plain WebSocket (NIP-01 `REQ`/`EVENT`/`EOSE`/`OK`). No AUTH required.

Default relays when you enable serverless:
`wss://relay.damus.io, wss://nos.lol, wss://relay.nostr.band`.

---

## 2. Guiding design decisions

### 2.1 "It's still relays at the end of the day"

The core insight that shaped everything: **serverless is the same product with a
different transport.** The agent's brain (respond gate, threading, prompt
rendering, reply mechanism) and the desktop's feature surface are shared code.
Only the bottom transport layer swaps:

| Concern | `sprout` mode | `serverless` mode |
|---|---|---|
| Respond gate (owner-only default, allowlist, siblings) | shared | **shared** |
| Threading decision (NIP-10) | shared | **shared** |
| Prompt rendering / reply via `sprout` CLI | shared | **shared** |
| **Transport** | HTTP bridge + NIP-98 + NIP-42 | plain WS, multi-relay |
| Channel discovery | one relay (HTTP) | multi-relay union |
| Reply / message publish | one relay | multi-relay, first-accepts |
| Membership push (kind 44100) | relay side-effect | periodic re-discovery |

Everything new is **gated** behind `is_serverless()` / `if serverless`. Server
mode runs the exact same code paths it always has.

### 2.2 The standard Nostr client model (no exotic tricks)

Relays **do not gossip** — an event stored on relay B is invisible to a
subscriber on relay A. Every production Nostr client therefore:

1. **publishes to many** relays (succeed if any accepts), and
2. **subscribes to many** relays and **dedups by event id**.

This is exactly what damus (`RelayPool.swift`), nostr-tools (`SimplePool`), and
0xchat do. Serverless mode follows the same model. There is nothing bespoke.

### 2.3 Model the operations as Nostr events, not new endpoints

Per the project's "prefer Nostr events over new REST endpoints" rule, serverless
membership/channel operations are done by **writing the same addressable events**
the relay would have produced (kinds 39000 / 39002), rather than inventing new
flows. The server's command kinds (9007 create-channel, 9021 join, 44100
member-added, …) are **server side-effects** that a dumb relay never executes, so
serverless writes the resulting state events directly.

### 2.4 `nostr-relay-pool` for the agent, hand-rolled pool for the desktop

The **agent** (`sprout-acp`, a standalone binary) uses the official
`nostr-relay-pool` crate (rust-nostr SDK) for its relay layer — free
auto-reconnect, auto-resubscribe, and dedup. The **desktop** deliberately keeps
its own hand-rolled connection pool (`ws_pool.rs`) to avoid pulling a *second*
TLS/crypto stack into the Tauri process (which already runs aws-lc-rs rustls for
reqwest/media). Two rustls providers in one process risk a `CryptoProvider`
install panic. The desktop pool is serverless-only and already self-heals, so the
agent's old missed-message bug does not apply there. This asymmetry is documented
in `ws_pool.rs`.

---

## 3. How it works, piece by piece

### 3.1 Event kinds used

All standard Sprout kinds (defined in `sprout-core/src/kind.rs`):

- **39000** — channel metadata (addressable; `d` = channel id, `name`, `t`,
  `public`/`private`).
- **39002** — channel members (addressable; `p` tags, role as the 4th tag
  element: `["p", <pubkey>, "", "owner"|"member"]`).
- **9** (`KIND_STREAM_MESSAGE`) — a channel message, scoped by the `h` tag
  (NIP-29 group tag).
- **1059** — NIP-59 gift wrap (encrypted DMs / private channels).
- **20002** — typing indicator (ephemeral).
- **5** — NIP-09 deletion (used for channel delete, since the dumb relay won't
  process a delete command).

### 3.2 Channels & membership (desktop)

- **Create** (`commands/channels.rs`): publish 39000 (metadata) + 39002 (members,
  creator recorded as `owner`) directly to all relays. The `ChannelInfo` is built
  **locally** and returned immediately — no re-query race (this fixed the early
  "nothing happened" bug).
- **Join / leave / add / remove**: read the current 39002, modify the `p` list
  (preserving roles), and re-publish (read-modify-write). NIP-29 command kinds are
  no-ops on a dumb relay, so direct state writes are the only thing that works.
- **`get_channels`**: in serverless, skips the server's `limit:5000` network
  discovery (which pulled hundreds of unrelated public channels) and scopes to the
  user's own membership.
- **Critical fix:** nostr 0.44 strips self-`p` tags unless
  `.allow_self_tagging()` is set. Without it, the creator's own membership tag was
  dropped, so `get_channels` (`#p:[me]`) found nothing. All serverless membership
  builders set `.allow_self_tagging()`.

### 3.3 DMs & private channels (encryption)

- **DMs**: `open_dm` derives a deterministic UUIDv5 channel id from the two
  pubkeys (so both sides converge on the same id), then publishes 39000 + 39002.
- **Encryption (NIP-17 / NIP-59)**: a DM or private channel message is built as a
  normal kind-9 **rumor** (unsigned, carries the `h` tag), then **gift-wrapped
  (kind 1059) once per recipient** — every channel member plus self. Only the
  gift wraps hit the relay; the plaintext kind-9 never does. The `h` tag lives
  *inside* the encrypted rumor, so a relay query by `#h` returns nothing — the
  channel itself is hidden.
- **Threaded encrypted replies** (the privacy fix in this branch): replies in a
  private channel are **also** gift-wrapped, with the NIP-10 thread `e` tags
  placed *inside* the rumor. Previously replies fell through to the plaintext
  path and leaked the reply content to public relays. Now threading is preserved
  *and* encrypted. The thread root is resolved locally from already-decrypted
  messages (the parent rumor isn't queryable in plaintext on the relay).

### 3.4 Multi-relay transport

- **Desktop** (`ws_pool.rs` + `ws_relay.rs`): one long-lived WebSocket per relay,
  multiplexing all queries/publishes. Reads fan out and **merge + dedup by event
  id**; writes fan out and **succeed if any relay accepts** (with a retry if all
  rate-limit). Dropped connections are detected and reconnected on next use. This
  fixed the rate-limit storm (the original code opened a fresh socket per op) and
  the "message shows then disappears" split-brain (publish landed on relay B,
  live-read was on relay A).
- **Agent** (`serverless_relay.rs` wrapping `nostr-relay-pool`): a persistent
  multi-relay subscription with built-in auto-reconnect + auto-resubscribe. On
  reconnect the SDK re-sends the `REQ`, and the relay replays its stored matching
  events — so a message that arrived during a blip is recovered. Events are merged
  and deduped across relays automatically.

### 3.5 Agents (the headline capability)

Agents work the **same** as in server mode — the permission model is identical;
only the transport differs.

- **Launch**: managed agents launch with the **current workspace** relay list and
  `SPROUT_SERVERLESS=true`. A startup gate (`workspace_applied`) makes agent
  restore wait (up to 15s) for the frontend to apply the workspace, so agents
  never launch with stale relays or in the wrong mode.
- **Serverless detection**: the agent infers serverless from a comma-list relay
  URL (`SPROUT_RELAY_URL=wss://a,wss://b`) in both `sprout-acp` and the `sprout`
  CLI, so even the agent's reply (`sprout messages send`) takes the serverless
  path.
- **Discovery**: the agent finds channels it belongs to by querying 39002
  (`#p` = agent) across all relays. Because a dumb relay never emits the
  membership-added push (kind 44100), the agent **re-runs discovery every 20s** and
  subscribes to any newly-joined channels.
- **Receiving messages**:
  - *Public channels*: live `REQ` for kind 9 scoped by `#h` = channel.
  - *Private channels / DMs*: a **gift-wrap inbox** subscription (kind 1059,
    `#p` = agent). On each wrap the agent decrypts to the inner rumor, reads its
    `h` tag, and routes it to the right channel.
- **The respond gate** (unchanged from server mode): default **`owner-only`** —
  the agent only acts on messages from its **owner** (the npub that added it,
  resolved from the `SPROUT_AUTH_TAG` NIP-OA attestation), plus "siblings" (other
  agents launched by the same owner). Other modes: `allowlist`, `anyone`,
  `nobody`. The gate runs in the harness **before** the LLM sees the event.
- **Replying**: the agent posts its reply via the `sprout messages send` CLI
  (multi-relay, first-accepts). It addresses the asker by `@name` in the channel —
  it does **not** DM the owner. Threading mirrors the trigger: a reply to a
  top-level message is top-level; a reply inside a thread uses `--reply-to` and
  stays threaded.
- **Working cues**: while a turn is in flight the agent publishes a typing
  indicator (kind 20002, every 3s) and a `💬` reaction, so the UI shows "working…"
  during the (30–90s) LLM latency.

---

## 4. Bugs found and fixed on this branch

In rough order, each reproduced and then fixed (and most now covered by a test):

1. **"Join did nothing"** — membership via server command kinds is a no-op on a
   dumb relay → switched to direct 39002 read-modify-write; then `.allow_self_tagging()`.
2. **Rate-limit storm** — fresh socket per op → persistent connection pool.
3. **"Message shows then disappears"** — split-brain reads → multi-relay
   read/write/subscribe.
4. **Query flood** — `limit:5000` discovery pulled the whole public network → skip
   in serverless.
5. **Channel delete no-op** → NIP-09 kind-5 deletion.
6. **Agent DNS crash** — comma-list fed to a single connect → multi-relay connect.
7. **Agent didn't see new channels** (no 44100 push) → 20s re-discovery.
8. **Agent reconnect storm** — a paid relay's `auth-required` → drop that sub,
   don't reconnect-loop; removed paid relays from defaults.
9. **Agent launched in server mode / stale relays** → `workspace_applied` gate +
   serverless inference from comma-list.
10. **Agent reply lost to rate-limit** → multi-relay fan-out + backoff retry.
11. **Agent relay layer fragile** (missed messages on relay drop) → replaced with
    `nostr-relay-pool` (auto-reconnect/resubscribe/dedup).
12. **`💬` working-cue never landed** (500ms timeout too tight for a real WS
    round-trip) → 4s.
13. **Encrypted replies leaked plaintext** → gift-wrap replies too, NIP-10 tags
    inside the rumor.

---

## 5. Verification — evidence it works end-to-end

All run on `micn/serverless-mode` at the time of this report.

### Automated

- **Unit tests:** `sprout-acp` 272 ✅, `sprout-cli` 114 ✅, `sprout-sdk` 138 ✅,
  desktop backend 427 ✅ (all pass).
- **Clippy:** clean on every touched crate (acp, cli, sdk, desktop backend).
- **End-to-end against live public relays** (`crates/sprout-acp/tests/e2e_agent_responds.rs`,
  runs the **real** `sprout-acp` + **real** `sprout` CLI, no LLM stub):
  - `agent_responds_in_channel_e2e` — proves: receive @mention → reply #1 →
    **typing indicator (kind 20002)** during the turn → second message → reply #2
    (**cancel/redispatch** path). ✅
  - `agent_responds_in_private_channel_e2e` — proves: a **gift-wrapped (kind
    1059)** message is received, **decrypted**, routed by the inner `h` tag,
    gated, and replied to. ✅
  - Both pass reliably (run repeatedly) **even while damus returns 503** — the
    multi-relay fan-out fails over to another relay.
- **Encryption unit test** (`desktop/src-tauri/src/encrypted.rs`): a threaded
  reply in a private channel is gift-wrapped (kind 1059), the plaintext never
  appears on the wire, and the NIP-10 root/reply tags survive decryption. ✅

### Manual (live)

- Confirmed on the relays directly that a user's **private** channels show **zero
  plaintext kind-9** and only un-`h`-tagged gift wraps.
- Confirmed goose replies in **public** channels live (addresses the user by
  display name).

---

## 6. Will it break `main` (server mode)?

**No.** Risk is contained:

- **Every serverless behaviour is gated** behind `is_serverless()` (desktop) or
  `if serverless` / `Option<ServerlessRelay>` being `None` (agent). The
  `ServerlessRelay`/`nostr-relay-pool` path is only constructed inside
  `if serverless`. Server mode runs the original code paths unchanged.
- **New modules** (`ws_pool.rs`, `ws_relay.rs`, `encrypted.rs`,
  `serverless_relay.rs`, `ServerlessContext.tsx`, `defaultRelays.ts`) are reachable
  only from serverless branches.
- **The single shared, non-gated change** is `REACTION_TIMEOUT` (500ms → 4s). It
  only makes a best-effort reaction *more* tolerant; server mode's HTTP bridge
  responds well under 4s, so it cannot regress server behaviour.
- **Dependency additions** (`nostr-relay-pool`, rustls feature on the CLI) resolve
  to the same `nostr 0.44.3` already in the tree — no version conflict.
- The one failing workspace unit test (`git-sign-nostr::test_parse_envelope_rejects_invalid_oa_pubkey`)
  **also fails on `main`** — it is pre-existing and unrelated to this branch.

---

## 7. Known limitations / follow-ups

- **Public relays are unreliable stores.** They rate-limit, 503, and may not
  retain low-traffic events indefinitely. The multi-relay fan-out + auto-reconnect
  mitigates this, but serverless is inherently best-effort — appropriate for a
  "lite" mode, not a system of record.
- **Profile/display names** depend on the relays carrying kind-0 metadata; absent
  that, the agent may address users by raw npub.
- **Desktop `ws_pool.rs` is hand-rolled** (by deliberate choice, §2.4). If the
  desktop ever shows a concrete live-subscription recovery bug, that targeted path
  can be hardened without adopting a second TLS stack.
- **Server-mode integration suite** (`just test`, needs Postgres + Redis) was not
  run for this report; the serverless changes are gated so server paths are
  unaffected, but running it is the recommended final gate before merge.

---

## 8. Key files

| Area | File |
|---|---|
| Serverless detection / mode | `desktop/src-tauri/src/app_state.rs`, `commands/workspace.rs` |
| Desktop relay transport | `desktop/src-tauri/src/relay.rs`, `ws_relay.rs`, `ws_pool.rs` |
| Channels / DMs / messages | `desktop/src-tauri/src/commands/{channels,dms,messages}.rs` |
| Encryption (gift wrap) | `desktop/src-tauri/src/encrypted.rs`, `commands/encrypted.rs` |
| Agent relay (SDK pool) | `crates/sprout-acp/src/serverless_relay.rs`, `relay.rs` |
| Agent main loop / re-discovery / gate | `crates/sprout-acp/src/lib.rs` |
| Agent + CLI serverless detection | `crates/sprout-acp/src/config.rs`, `crates/sprout-cli/src/lib.rs` |
| CLI multi-relay client | `crates/sprout-cli/src/client.rs` |
| Shared event builders | `crates/sprout-sdk/src/builders.rs`, `desktop/src-tauri/src/events.rs` |
| Frontend serverless UI | `desktop/src/features/workspaces/*` |
| E2E proof | `crates/sprout-acp/tests/e2e_agent_responds.rs` |
| Deeper implementation map | `docs/SPROUT_LITE_MODE.md` |