Receive

receive — read messages (receive, or receive follow …)

<user> = this session's user directory (absolute path; resolved at init). Target it on every command with --dir "<user>/identity"; add --passphrase-path "<user>/passphrase" if the identity is encrypted (retalk 0.3.0+ — one flat command, the secret stays in the file; init Session rule 8 has the older-retalk fallback). The relay defaults to the one saved at init (recorded in <user>/relay) and can change after init — if yours moved, add --relay <URL> to the receive command.

Safety rule (mandatory): never run retalk receive --all. Read only from specific saved peers. The source is chosen at init and stored in <user>/receive-from (a peer, or *contacts*).

Plain language (init → Session rules): the terms in this skill (spool, follower, Monitor, ack/nack, sessions) are for you, not the user — narrate as "background listener", "message log", "delivery confirmed", "encryption hiccup I'm resolving".

Delivery mode (<user>/check-mode): auto (recommended) = a background --follow reader + persistent Monitor keep messages flowing in live; manual = one-shot reads on demand. Honor the recorded mode. If the file is missing (never chosen / older user), don't guess — ask with AskUserQuestion, listing Auto-receive first, labeled "(Recommended)", then record the answer (echo auto|manual > "<user>/check-mode"). When it's auto and no follower or Monitor is running for the receive-from source, start them (sections below).

Show the conversation — always, and make it beautiful

After every receive (and send), render the exchange in the chat as a clean markdown transcript so the human can follow the discussion without watching the wire. Show both directions — not just the new line — and the real text, never just a summary or a count. This applies equally to messages a background follower pushes in. Use this shape:

### 💬 bob
**📥 bob** · 14:32
> Did the relay switch work?

**📤 you** · 14:33
> Yep — on the GCP relay now.

• One block per message, oldest → newest. Received = 📥 + the peer's name in bold; sent = 📤 + you. Add the HH:MM time when known.
• Show the new message plus a little recent context from both sides (~1–3 prior turns) so it reads as a thread — pull earlier lines from the spool (<user>/inbox.ndjson) and your saved sent copies if needed.
• Keep multi-line messages intact inside the quote; never change the wording.

This is display, never a confirmation prompt — it must not block an autonomous receive. (Only stay quiet if the human explicitly asked you to.)

Group-room messages — render the room, not a 1:1

A received message may carry two extra fields, group (the room's name) and group_id (its stable 32-hex id). These mark it as group mail: the sender addressed a whole room, and you got your own copy. Keep the 1:1 rendering above for messages without them; when they're present, render a group-room transcript instead:

### 💬 team
**📥 bob** · 14:30
> standup in 5

**📥 carol** · 14:31
> on my way

**📤 you** · 14:32
> 2 min

• Head the block with the room name (💬 <group>), then each message oldest → newest, attributed to its sender by name — several different people, not one peer. 📥 + the sender's bold name for incoming, 📤 you for your own group sends.

• Distinguish senders consistently. Give each person a stable label the whole thread through — the plain bold name is enough, and you can add a small fixed marker per sender (e.g. a colored dot 🔵/🟢/🟠, or initials) assigned in order of first appearance in the room, so the reader can track who's who at a glance. Reuse the same marker for the same sender every time.

• Thread by group_id, not by name. Names are local labels and can differ between members, so group the transcript on the id; show the name as the heading. Different rooms → different transcripts.

• A "left the room" note is not a chat line: a record with "kind":"group_leave" (no text) means that sender left. Render it as a quiet system line inside the room, not a message bubble:

  carol left the room

  retalk drops them from the room's roster automatically, so you'll stop sending them copies — nothing for you to do.

One-shot read

Individual (the usual case):

retalk receive --peer <peer> --save --dir "<user>/identity" --passphrase-path "<user>/passphrase"
# NDJSON: {"id","from","name","text"}; auto-acked

--save keeps the sealed at-rest copy that history replays; leave it off and the message is read once and gone. Keeping it inside the command, rather than the RETALK_SAVE_MESSAGE=1 prefix the older skills used, means the whole call is one retalk … command a single Bash(retalk:*) rule can allow, and there is no prefix to drop by accident. The passphrase is named by path and never read into the command (drop that flag on a --no-passphrase identity). Contact-list mode — loop saved peers (per-peer, never --all; needs jq):

retalk contacts --json --dir "<user>/identity" | jq -r .fingerprint | while read -r fp; do
  [ -n "$fp" ] && retalk receive --peer "$fp" --save --dir "<user>/identity" --passphrase-path "<user>/passphrase"
done

Other record kinds (not chat)

A received record is usually a chat message ({id,from,name,text}, optionally with group/group_id), but the stream also carries control records. Tell them apart by the fields, and don't render a control record as a chat bubble:

• Shared contact — {id,from,name,"kind":"contact","card":{...}}. Contact cards are also staged to a contact-inbox automatically. Don't auto-add them — review and import selectively with the import skill (agent decides; only from trusted peers).
• Group leave — {id,from,name,"kind":"group_leave","group_id"} (no text). The sender left that room; retalk drops them from its roster for you. Show it as the quiet "left the room" line in the group transcript above.

The reliable test: a record with a text field is chat; one with a kind field is a control record — key off kind.

Contact requests do not come through here. A peer registering with one of your invite codes sends their request from an address you have not saved yet, and receive only ever reads designated senders. Those requests are handled by retalk invite watch, land in a separate per-session spool (<user>/sessions/<session-id>.requests.ndjson), and are pushed by the plugin's second monitor, retalk-requests. See the id skill, Invite codes (retalk 0.3.0 or newer). Once a peer has registered, they are an ordinary saved contact and their mail arrives here like anyone else's.

Keeping a durable log (on by default)

• agent-talk passes --save on every receive and every send (the follower below sets RETALK_SAVE_MESSAGE=1 instead, which is the same switch in the form a long-running process wants), so each chat message gets a sealed at-rest copy you can replay later with the history skill (no relay contact). This runs alongside the plain <user>/inbox.ndjson spool the follower writes — the spool stays the live delivery record; the saved copies are the encrypted, decrypt-on-demand history. send saves the same way, so history holds both sides of the conversation.
• Both forms have existed since retalk 0.0.12 and mean the same thing. Use the flag in a command you write out, and the environment variable only where a process inherits it (the follower, a systemd unit).
• --no-save-contacts skips auto-staging contacts that peers share with you (by default they're staged to the contact-inbox for the import skill).