pi-nostr

· Coracle Git

6 min read Original article ↗

Nostr for pi and pi-durable: direct messages (NIP-17), rooms (NIP-29), and public notes and comments (kinds 1 and 1111), built on welshman.

Run an agent

The first run asks which identity the agent uses (a new key, an nsec, a bunker:// link or a nostrconnect:// signer), its name, what it answers and from whom, its relays, the model and its API key, and its instructions. It then publishes the agent's relay list to the indexers, its direct message relays, its profile and requests to join its rooms, and starts. Every run after that starts it straight away.

Command
npx @pi-nostr/cli Set up the first time, then start
npx @pi-nostr/cli setup Ask the questions again, starting from the answers given
npx @pi-nostr/cli sync Publish the relay lists, profile and room joins again
npx @pi-nostr/cli start Start without asking anything
npx @pi-nostr/cli status Say what is set up

Everything is kept in ~/.pi-nostr, or the directory --dir or PI_NOSTR_HOME names, and any file missing there is made with its defaults:

File
config.json What it answers and from whom, the model, the instructions, the profile and the relays. Safe to edit by hand.
account.json The identity: a key, or how to reach a remote signer. Readable by its owner alone.
auth.json The model provider's credential, in pi's format, so the setup can copy pi's. Readable by its owner alone.
session.sqlite The conversations, which a restart picks up without answering anything twice.

A start whose identity has no relay list on the indexers syncs first, and a changed model or instructions reach the conversations already going.

Package For What it does
@pi-nostr/cli — The program above, which runs the durable bridges below
@pi-nostr/core both The account (nsec or NIP-46 signer), a welshman app per account, the nostr operations, and every tool, defined once; /pi and /durable register them with each host
@pi-nostr/pi-nip17 pi The direct message tools, and the shared tools
@pi-nostr/pi-nip29 pi The room tools, and the shared tools
@pi-nostr/pi-notes pi The shared tools alone: notes, comments, profile and relay list
@pi-nostr/durable-nip17 pi-durable The same tools, plus a bridge that answers incoming direct messages
@pi-nostr/durable-nip29 pi-durable The same tools, plus a bridge that answers messages in rooms
@pi-nostr/durable-notes pi-durable The shared tools, plus a bridge that answers public mentions, replies and comments
Tools
Shared nostr_profile_read, nostr_profile_set (kind 0), nostr_relays_set (kind 10002, to the indexers), nostr_note_post (kind 1), nostr_comment_post (kind 1111), nostr_notes_read, nostr_replies_read, and nostr_publish_event, which signs and publishes any event
Direct messages nostr_dm_relays_set (kind 10050), nostr_dm_send, nostr_dm_conversations, nostr_dm_read
Rooms nostr_room_list, nostr_room_read, nostr_room_post, nostr_room_join, nostr_room_leave, nostr_room_members

The pi packages only act when asked: answering whatever arrives is the durable bridges' job, since a durable conversation survives a restart and answers each message once.

Room moderation (kinds 9000–9008) is left out on purpose.

pi

Then, in pi:

  • /nostr-login takes an nsec, a bunker:// link, or shows a nostrconnect:// link for a signer app. With a remote signer, only a client key is stored. /nostr-login generate makes a new key, kept only in the account file, and replacing or forgetting a key held there asks first.
  • /nostr-relays [urls...] publishes the account's relay list (kind 10002) to the indexers and the relays it names.
  • /nostr-dm-relays [urls...] publishes where it receives direct messages (kind 10050).

The agent treats the identity as its own, and knows to publish its relay list to the indexers before anything else; every publish says so while the list is missing.

Default relays

Where nothing is configured, the relays are the ones flotilla hands a new account (core/src/relays.ts):

Indexers purplepag.es, relay.damus.io, indexer.coracle.social
Outbox, and fallback reads relay.damus.io, relay.primal.net, nostr.mom
Direct messages auth.nostr1.com, relay.keychat.io, relay.ditto.pub
Remote signer (nostrconnect) ephemeral.snowflare.cc, bucket.coracle.social

/nostr-relays, /nostr-dm-relays, nostr_relays_set and nostr_dm_relays_set publish these when given no relays.

  • /nostr-whoami shows the account.

The account lives in ~/.pi/agent/nostr/account.json, or wherever PI_NOSTR_ACCOUNT points. Both packages read the same file, and whichever loads first registers the account commands and the shared tools.

Every write is signed and then published, and in a durable conversation what was signed is kept first, so a tool call rerun after a crash publishes the same event rather than a second one.

pi-durable

A pi-durable host installs each package's extension and starts its bridge:

  • The NIP-17 bridge gives each set of participants its own conversation and answers only the pubkeys in from. Anybody can address a gift wrap to the account, so from: "anyone" hands the agent to every stranger.
  • The NIP-29 bridge gives each room one conversation. mention: true answers only messages that mention the account, and from narrows who is answered.
  • The notes bridge listens on the read relays of the account's kind 10002 for notes and comments that tag it, and answers those addressed to it: ones that name it, start a thread tagging it, or answer one of its own events. A reply elsewhere in a thread it once took part in tags it too, and is left alone. Each thread is one conversation, comments on a thread's notes included, and a note is answered with a threaded reply (NIP-10) and a comment with a comment (NIP-22). Like direct messages, from is required, since anybody can tag the account.
  • Each answer is a durable task that submits the message, waits for the run, signs once and publishes until a relay takes it. A signer that is slow or offline delays a reply rather than losing it, and a restart resumes where it stopped.

@pi-nostr/cli is such a host, configured by its setup (packages/cli).

Development

The tests run against an in-memory relay and a NIP-46 signer in test/support, and a faux model for the durable bridges. Workspace packages export their sources under the @pi-nostr/source condition, which the tests and tsc use.

Waiting on welshman

These are worked around here and belong upstream:

  • Relay-list lookups ask the indexers and configured relays directly, because welshman's router drops ws:// and localhost relays (core/src/lists.ts).
  • Proof of work for gift wraps, mined to each relay's NIP-11 min_pow_difficulty, and delivery reported per recipient (core/src/nip17.ts); sendWrapped has neither.
  • A publish that reports which relays accepted and refused, and a request held open per relay that reconnects (core/src/app.ts).