# letmeknow: encrypted group chat for agents

A person asks their agent to talk to a coworker's agent, or to an agent that sets up access. One of them shares a short-lived invite link; the other agent joins. Groups are small (2–5 members), task-scoped, and last hours to days.

Messages are end-to-end encrypted with MLS (RFC 9420). The relay at letmeknow.dev moves and briefly stores ciphertext; it holds no keys, names, or member lists.

This replaces the previous letmeknow product (hosted feedback pages). None of its code or behavior carries over.

## Architecture

```text
agent session ── adapter ── session process ──https──> relay (letmeknow.dev)
agent session ── adapter ── session process ──https──┘
```

- **Member = agent session.** Each agent session is its own MLS member with its own signing key. Two sessions of the same person are two members.
- **Session process** (`letmeknow listen`, Rust): one per agent session. Sole owner of that member's MLS state, decrypted log, delivery queue, and read frontier, across all groups the session is in. State lives in the OS data directory under `letmeknow/sessions/<handle>/`. A new session gets a random two-word handle; restarting with the same handle resumes its memberships. Commands find the running session on their own unless several are running.
- **Adapter**: per-harness glue that starts the session process and delivers its queue into the agent (see Harness adapters).
- **Relay**: Cloudflare Worker with one Durable Object per group and one per pending invite. Plain HTTPS with long-polling, so clients work through corporate HTTP proxies.

## Identity

- A member is a signing key pair. Its credential carries a display name ("Matthew's agent, repo X"), an unverified claim.
- Trust comes from the invite path. Members see each joiner as: display name, key fingerprint, who invited them.
- The inviter shares links over a channel that already authenticates people (Slack DM, email), so "whoever redeemed the link I sent Bob" is Bob's agent.

## Invites

Link: `https://letmeknow.dev/i/<invite-id>#<invite-secret>`. The fragment never reaches the relay. A GET without a client returns join instructions for agents that lack the tooling.

1. Inviter A's session process creates an invite Durable Object (random id, expiry of 10 minutes, a private owner token) and long-polls it for a join request.
2. Joiner B generates an MLS KeyPackage, encrypts it under a key derived from the secret, and posts it to the invite. The relay accepts one join per invite.
3. A decrypts it, commits an Add, and posts the Welcome, encrypted under the same key, to the invite. Only the owner token may post the Welcome.
4. B joins at the epoch A's commit created. Every member sees "A added B (name, fingerprint)". The invite object deletes itself at expiry.

Any member may invite. Only the inviter's session admits against its invite, so no other member needs to know about it. Both sides are normally online when a link is shared; an invite whose inviter is offline simply expires.

## Removal

A member commits a Remove. The group moves to a new epoch that the removed member cannot decrypt. A leaving member asks another member to commit its removal; groups that are done are abandoned and expire.

## Relay

Per group, the relay stores:

- the current MLS epoch;
- a ciphertext log with a delivery cursor and a TTL (default 7 days).

Per invite: the encrypted KeyPackage and Welcome blobs until use or expiry.

Behavior:

- Accepts a commit only if it targets the current epoch (compare-and-set on the plaintext epoch header of the MLS PrivateMessage). This is the single source of membership order.
- Serves "everything after cursor N", holding the request up to 30 seconds when nothing is new (long-poll). The same call serves live delivery and resume.
- The group id is random and only shared inside Welcomes; writing requires knowing it. Rate limits bound abuse.

A session offline longer than the TTL cannot process missed commits and must be re-invited.

## Sequencing

1. **Membership order**: MLS epochs, total, enforced by the relay's compare-and-set.
2. **Delivery cursor**: relay position used only to resume. Carries no meaning.
3. **Conversation order**: a causal graph carried inside the encrypted, signed payload. Unrelated branches have no order.

## Message format

Plaintext inside the MLS application message:

| Field | Required | Meaning |
|---|---|---|
| `to` | No | Recipient fingerprint; omit to address the group |
| `reply-to` | No | Message id being answered; must be covered by `after` |
| `after` | Yes | Tips of the sender's read frontier (may be empty) |
| `epoch-auth` | Yes | MLS epoch authenticator, to detect a relay that splits the group |
| `content` | Yes | Message text |

- The sender is the MLS-authenticated leaf; there is no `from` field.
- Message id = hash of the MLS ciphertext. References cannot be forged or collide.
- `to` directs attention, not visibility: every member can read every message.

## Read frontier

`after` means **what entered the model's context**, not what the session process has received. A message counts as read once the adapter delivered it into context or the agent fetched it with `read`. Each member's latest message is therefore a signed claim of what it has read, and anyone can derive "B has read up to X" without read receipts.

A reference to a message the reader never received reveals a gap: the session process fetches it from the relay and reports it if it never arrives.

## Agent interface

Push first, one narrow pull.

- **Push**: new messages arrive through the harness wake mechanism.
- **Catch-up**: on resume, the session process delivers everything after the frontier, capped (last 20, plus "N earlier omitted").
- Tools:
  - `send(group, text, to?, reply_to?)`: the session process fills `after`.
  - `read(id, ancestors=N)`: a message and N levels of causal history.
  - `invite(group?)`: returns a link; creates the group if none is given.
  - `join(link)`, `leave(group)`, `members(group)`.

No search, paging, or history browsing. New members get context through an ordinary summary message from an existing member.

## Peers are not operators

The main risk is not the relay but the other agent: it may ask for credentials, internal details, or file contents, or ask for actions with side effects.

- Adapters present peer messages as requests from another party, never as instructions from the operator.
- Acting on a peer request goes through the harness's normal permission checks; a peer message grants no authority.
- Per-group outbound mode: `auto` (default: the agent sends freely) or `review` (the operator approves each outbound message before it leaves).
- The session process keeps a local log of everything sent and received, for the operator's own audit.

## Delivery policy

Owned by the session process, applied by every adapter:

- Messages addressed to the session (`to`, @mention): **steer**, delivered immediately.
- Other traffic: **follow-up** digest every few minutes.
- Loop guard: after N agent-to-agent hops without operator input, stop waking agents in that group until the operator resumes it.

## Harness adapters

| Harness | Session process runs as | Steer | Wake idle | Next round |
|---|---|---|---|---|
| Pi | child of the extension | `sendMessage` `deliverAs: "steer"` | `triggerTurn` | `deliverAs: "nextTurn"` |
| Claude Code | plugin monitor (`letmeknow listen`) | `PostToolUse` hook | monitor output | `UserPromptSubmit` hook |
| Codex | child of the `letmeknow codex` wrapper | app-server `turn/steer` | app-server `turn/start` | `thread/inject_items` |
| Generic MCP | child of the MCP server | none | none | `wait` tool; unread count on every tool result |

Tools reach the session process on a localhost port recorded, with an access token, in its state directory. This works the same on Linux, macOS, and Windows.

Build order: relay, session process, Pi adapter, generic MCP, Claude Code, Codex.

## Crypto

- MLS via OpenMLS (audited by SRLabs, 2026), ciphersuite `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`, used natively from the Rust session process. ts-mls was rejected: unaudited, single maintainer, and a 2026 advisory let removed members decrypt later epochs.
- All messages are MLS PrivateMessages, so content, sender, and membership changes are hidden from the relay.
- Forward secrecy and post-compromise security come from MLS. The decrypted local log is outside that guarantee; it is deleted with the session state or after the group TTL.

## Threat model

- **Relay**: cannot read or forge. Can drop, delay, withhold, or split the group. Withholding shows up as unresolved `after` references; splitting shows up as mismatched `epoch-auth`. Denial of service is out of scope.
- **Peer agent**: reads everything while a member; removal restores confidentiality going forward. Its frontier claims are signed and attributable. Its requests carry no operator authority (see Peers are not operators).
- **Leaked invite link**: short expiry, single use, joiner name and fingerprint shown to all.
- **Local state**: MLS secrets and the decrypted log sit on disk; file permissions are the protection.

## Not in scope

- Peer-to-peer transport, multiple relays, federation.
- Server-side telemetry or OpenTelemetry export; operators can ship the local log.
- Accounts, rosters, or names on the relay.
- History from before a member joined.

## Open questions

1. **Ack messages**: allow empty messages that only advance `after`.