CLI and library

TypeScript packages for the Rendezvous agent-to-agent contact protocol, built toward the two-agent dinner demo in PLAN.md. impl/ is an npm workspace:

demo/ holds the showpiece script (demo/SCRIPT.md), a calendar generator and relay-dump.mjs (what the relay stores: ciphertext).

Core never depends on the CLI, the A2A layer, MCP or LLM code. a2a has no runtime dependencies at all; the CLI glues the two together. The MCP server builds on the CLI's library entry (@rendezvous/cli/lib: home dir, lock, inbound loop), so rdv and rdv-mcp share profiles.

@rendezvous/core#

import { Agent, NostrTransport } from '@rendezvous/core';

const relays = ['wss://relay.example'];
const john = Agent.create((key) => new NostrTransport({ key, relays }), {
  rendezvous: [{ type: 'nostr', relay: relays[0], pref: 1 }],
  discovery: { addresses: [{ type: 'email', value: 'john@doe.com' }], public_pointer: false },
});
john.on('request', (p) => john.grant(p.request.id, { tier: 'friend' })); // the human decides here
john.on('message', (from, payload) => console.log(from, payload));
john.start();

// On another machine:
await omer.requestContact('john@doe.com', "Omer's agent would like to plan dinner.");
omer.once('contact', () => omer.send(john.id, { type: 'a2a/message', text: 'Thursday 20:00?' }));

Relays. DEFAULT_RELAYS is the public set rdv init uses when no relay is given: wss://nos.lol, wss://relay.primal.net, wss://relay.nostr.net, wss://nostr.oxtr.dev (checked live, NOTES 11a). A publish counts as delivered when one relay answers OK true. Transient failures are retried twice with jittered backoff. A relay that answers blocked, restricted or banned is skipped for 30 minutes. Events are paced per relay (a burst of 6, then 3 per second). Each tunable is a NostrTransportOptions field (NOTES 69). An envelope's plaintext is at most 32 KiB (MAX_PLAINTEXT_BYTES, SPEC §6.4).

Discovery mirrors (NOTES 81). An agent listens on a few relays, and its envelopes go only there. Its card can also be mirrored to more relays, so a peer that asks other relays still finds it: NostrTransportOptions.mirrorRelays. fetchTopic (so Agent.lookup) asks the mirrors too, at most lookupConcurrency (4) at a time, each within the lookup timeout. mirrorTopics() (Agent.mirrorPointers()) publishes the card to our relays and then each mirror strictly one at a time: a pause between relays (1.5 s), one try each with a timeout (6 s), cooling relays skipped, then a read-back per relay. It returns accepted / rejected (with the relay's reason) / timeout / skipped and served per relay. DEFAULT_MIRROR_RELAYS is the vetted public set (13 relays, from deploy/mirror-survey.mjs; never relay.damus.io). Agent.setRelays() re-signs the card with other relays and moves the transport (setRelays()), subscriptions included.

Agent state serializes with agent.toJSON() and loads with Agent.fromJSON(). packages/core/vectors/v1.json holds interop test vectors: fixed keys, IDs, discovery topics, a signed card and contact request, and a sample envelope that another implementation should be able to open.

@rendezvous/a2a#

PLAN.md §5.1–5.2, SPEC.md §7. Payloads a2a/message (an A2A v0.3 Message) and a2a/task-update (a TaskStatusUpdateEvent) travel inside envelopes. The verb sits in the message's data part (data.rdv): meeting/propose, meeting/counter, meeting/accept, meeting/confirm, meeting/decline, meeting/cancel, rdv/cancel.

Policy: an offer carries up to 3 free slots (one per day first); the receiver accepts the first offered slot that is free and inside its window, else counters with 3 of its own; after 3 offers the task ends rejected. Task states: submitted → input-required / working → completed | rejected | canceled. Agreement is a handshake: the accepter holds the slot tentatively and sends meeting/accept; the offerer checks it is still free, sends meeting/confirm and completes; the accepter completes on the confirm. A tentative hold is released when the task is canceled, declined or expires, and every hold is busy for all other tasks. Unless ctx.autoConfirm, the engine waits for its human before each of those two steps (confirmMeeting). Messages are deduplicated by messageId; rdv/cancel is honored while pending; an agreed meeting is called off with meeting/cancel (cancelMeeting, our human only), which the peer honors only for that completed task and slot, freeing it in both calendars; meeting verbs need may_propose_meetings in the grant, and may_access_calendar: none blocks them. A peer can hold at most 32 tasks with us. Details and open questions: NOTES.md items 28–37, 58, 61.

--window (local time = a fixed offset; weeks run Monday–Sunday; an evening is 19:00–23:00; everything is clipped to start no earlier than now):

Calendar file: { "timezone": "+02:00", "busy": [ { "start": "…", "end": "…", "title": "optional" } ] }. Held slots are added to busy: Dinner (tentative, rdv <task>) while the handshake runs, then Dinner (rdv <task>); a tentative hold that falls through is removed.

rdv (the CLI)#

npm install && npm run build              # from impl/
npm run rdv -- --help                     # or: node packages/cli/dist/src/bin.js --help

npx rdv … also works once npm install has run after the first build (npm links the binary only when dist/ exists).

State lives in a directory: --home <dir>, else $RDV_HOME, else ~/.rendezvous/<profile> (--profile, default default).

| lock | held while a command reads and writes state | | listener.lock | held for its lifetime by the home's one inbound consumer (rdv listen or rdv-mcp) |

Output is human text by default and one JSON object per line with --json. Exit codes: 0 ok, 1 error, 2 usage error. Every command except listen and inbox --follow loads state under the lock, runs, saves, and exits. listen takes the lock only while it handles one inbound item, so a bot can run rdv contact grant against the same home while listen is running; it prints an event only after the state behind it is saved.

One inbound consumer per home. Two processes subscribed for the same home would split inbound events between them (whichever handles an envelope first wins; the other never sees it). So whoever consumes holds listener.lock (O_EXCL file with pid, host and role, mtime touched every minute; broken when its pid is gone on this host, or after 10 minutes without a touch from another host) and appends every event it handles to events.jsonl, after the state behind it is saved. A second rdv listen exits 1 naming the holder. A second rdv-mcp runs attached: it opens no subscriptions, still sends (grant, send, negotiate), and its rdv_inbox follows events.jsonl by cursor, so every server on the home sees each event once with the same cursor. When the holder exits, an attached server takes the lock within a second and starts consuming; the relays' lookback replays what arrived meanwhile, and the channels drop what was already handled. Negotiation follows the consumer: run rdv listen --negotiate (or give the consuming rdv-mcp a calendar) if an attached server should get answers to its dinner proposals.

With --json, negotiation steps print as {"event":"dinner","kind":…,"task":…,"peer":…,"state":…} (kinds: proposed, offer-received, countered, confirm-needed, accepted, completed, meeting-canceled, released, rejected, canceled, expired, status, duplicate, ignored, invalid). In text mode the peer's text parts and decline reasons are shown as untrusted and cleaned.

PowerShell quoting for send: rdv send <id> --json '{\"type\":\"a2a/message\",\"text\":\"hi\"}' (Windows PowerShell 5 strips bare inner quotes; PowerShell 7.3+ accepts the bash form).

Tasks and files: an example (user guide: docs/tasks.md)#

Omer asks John's agent for a document review; John's side runs rdv listen.

# Omer: ask (John's grant to Omer must allow request/v1)
rdv task request rdv1:… --text "Please review the attached Q4 plan"

# John, in his own terminal: see what waits, with the codes
rdv task list
rdv task approve <task-id> --code <code>          # start gate: now his agent may act

# John's agent drafts; John prepares a file, uploads the .bin, and attaches it
rdv file prepare ./q4-review.pdf                  # prints the sha256 and the copy to upload
rdv task submit <task-id> --text "Notes attached" --file <sha256>=https://files.example.com/q4 --complete
rdv task list                                     # shows the draft and the file in full
rdv task release <task-id> --code <code>          # release gate: only now does it leave

# Omer: fetch it (only for a task he requested, or one he started)
rdv file fetch <task-id> --file 1

# Later: what passed without asking, and a trusted contact on auto-approve
rdv audit --since 7d
rdv owner-secret set                              # once, in your own terminal
rdv contact auto-approve john@doe.com all --until 7d
rdv contact auto-approve john@doe.com off

The dinner scenarios (PLAN §5.3)#

packages/cli/scenarios/dinner.ts: Omer and John each run rdv listen --negotiate with their own JSON calendar; Omer runs rdv dinner propose. Variants: overlap (John, then Omer, confirms with rdv dinner confirm; both completed on the same slot, one hold each), no-overlap (rejected after 3 rounds), cancel (John offline while Omer proposes and cancels; both canceled), cancel-hold (Omer cancels while John's agent holds a slot for John; the hold is released), duplicate (--auto-confirm bots, then every envelope replayed and a message re-sent; nothing changes), reverse (John, who granted the contact, proposes: refused until Omer runs rdv contact grant <john-id>, which sends John a reverse grant; then both confirm and complete), cancel-agreed (--auto-confirm bots agree, then John runs rdv dinner cancel; both calendars free the evening and both end canceled). All seven run in npm test; overlap runs in npm run test:live; by hand:

node packages/cli/dist/scenarios/dinner.js --relay ws://… [--variant overlap] [--variant …].

The microsite scenario (design B.5, issue #79)#

packages/cli/scenarios/microsite.ts: Omer, John and Dana, three rdv processes. Omer is John's and Dana's contact; John and Dana never meet. Omer creates a group, John joins (members may ask him for request/v1; newcomers trust-admin), Dana joins (ask) and approves John. Omer puts an open task on the board; Dana claims it and Omer assigns it to her (John's attempt to assign it is refused by his own board); Dana's human approves the start and releases the copy, which the release gate shows going to Omer and John. Omer then asks John for a review referring to the copy: John's start gate shows that the input is Dana's result ("not your contact, named by the admin as Dana"). John leaves: his assigned proofread reopens and his open request is canceled on the others' boards; Dana drops her channel with him, Omer keeps his. Omer hands the admin role to Dana and leaves. It runs in npm test on the in-memory relay; by hand: node packages/cli/dist/scenarios/microsite.js --relay wss://… [--timeout ms] [--keep].

The contact scenario (PLAN §4.5)#

packages/cli/scenarios/contact.ts drives real rdv processes with separate homes: John listens, Omer requests by email, John grants, Omer sends, John's inbox shows it, each step asserted with a timeout. It runs:

• against the in-memory relay as part of npm test;
• against real relays with npm run test:live (below);
• by hand against any relays, e.g. from two machines' worth of setup: node packages/cli/dist/scenarios/contact.js --relay wss://relay.example [--relay …] [--timeout 30000] [--keep].

Crash safety: state is saved right before each envelope leaves (Agent.beforeSend), so a crash after a send never reuses a seq (issue #4).

rdv-mcp (the MCP server)#

PLAN §6.1. Tools rdv_init, rdv_status, rdv_addresses, rdv_relays, rdv_publish_card, rdv_discover, rdv_request_contact, rdv_pending_requests, rdv_grant, rdv_revoke, rdv_send, rdv_inbox, rdv_negotiate, and the rdv://inbox resource (subscribable). rdv_grant needs the human: an MCP elicitation form, or a confirm phrase shown only in their terminal. Peer text comes back only as untrusted_peer_text. Details, consent threat model and client config: packages/mcp/README.md, demo/SCRIPT.md.

node packages/mcp/dist/src/bin.js --home ~/.rendezvous/omer --calendar cal.json --tz +02:00

rdv-gateway (cloud assistants, issue #12)#

The same tools as rdv-mcp, minus the owner's setup (rdv_init, address and relay changes, turning auto-approve on, local file paths), for assistants that only reach a public URL. It runs on your own machine, beside rdv / rdv-mcp on the same home (it attaches like a second rdv-mcp when another process receives), and listens on 127.0.0.1; put your own HTTPS tunnel in front of it. Nothing is approved through the assistant: a step that needs you returns {"status": "awaiting_human", "approve_url": …}, and you decide on the gateway's PIN-locked page. Threat model: packages/gateway/THREAT-MODEL.md; design choices: NOTES 89.

node packages/gateway/dist/src/bin.js pin set --home ~/.rendezvous/omer
node packages/gateway/dist/src/bin.js token create --name chatgpt --scope read,send,contact:request --home ~/.rendezvous/omer
node packages/gateway/dist/src/bin.js serve --home ~/.rendezvous/omer --public-url https://rdv.example.com --client-ip-header cf-connecting-ip
# MCP: https://rdv.example.com/mcp   REST: /api/v1/tools/<tool>   OpenAPI: /openapi.json   approvals: /approve

Develop#

Run from impl/ (works the same in PowerShell and bash):

npm install
npm run typecheck        # every workspace
npm test                 # core, a2a, cli (commands + scenarios), mcp (two servers end to end); local relay, no network
npm run build            # tsc -b -> packages/*/dist
npm run test:vectors:update   # regenerate vectors (deliberate wire-format changes only)

One package or one file: npm test -w @rendezvous/core, or cd packages/core && npx vitest run test/unit.test.ts -t envelope. CLI tests spawn the built rdv, so the CLI's test script builds first.

Live relays. npm run test:live runs only *.live.test.ts, and those skip unless RDV_LIVE_RELAYS lists relays. They are never part of npm test. The live files run one at a time, since public relays limit connections per IP. Keep the volume modest: relay.damus.io banned the test pubkey after a few runs.

RDV_LIVE_RELAYS=wss://nos.lol,wss://relay.primal.net,wss://relay.nostr.net,wss://nostr.oxtr.dev npm run test:live

$env:RDV_LIVE_RELAYS='wss://nos.lol,wss://relay.primal.net,wss://relay.nostr.net,wss://nostr.oxtr.dev'; npm run test:live; Remove-Item Env:RDV_LIVE_RELAYS

Pre-push hook (replaces CI). Enable it once per clone, from the repo root:

git config core.hooksPath .githooks

.githooks/pre-push runs npm run typecheck && npm test in impl/ and blocks the push if either fails.

See NOTES.md for wire-format decisions and the places where this implementation departs from or fills gaps in SPEC.md.