@joe-broadhead/messaging 0.7.1 → 0.9.0

package/dist/lib/modules/core/schema/conversation.js

@@ -16,6 +16,8 @@ import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent, Part } from ".
 import { Base64Url, ChannelName, EncKey, Hash, Key32, LIMITS, MachineId, Millis, PersonId, PROTOCOL, SessionName, Ulid } from "./common.js";
 import { DelegationChain, DelegationGrant } from "./delegation.js";
 import { RealmId } from "./realm.js";
+import { ActivationProof } from "./contact-request.js";
+import { GuestInvitation } from "./guest-invitation.js";
 // ---- identifiers (spec §16.1) ----
 /** A person, or one agent of a person (`person/agent`). Every agent belongs to one person. */
 export const ParticipantId = z
@@ -44,6 +46,17 @@ const Sig = z.string().regex(/^[A-Za-z0-9_-]{86}$/, "Ed25519 signature, base64ur
 /** An AES-GCM nonce: 12 bytes. */
 const Nonce = z.string().regex(/^[A-Za-z0-9_-]{16}$/, "12-byte nonce, base64url");
 const isAgent = (p) => p.includes("/");
+// ---- linked channels (spec §16.10; reserved: validated, no daemon behaviour yet) ----
+/** An outside channel a person may link as an alias of themselves. Telegram first, then Slack. */
+export const LinkChannel = z.enum(["telegram", "slack"]);
+/** What a linked channel may do: Jelly's `chat` and `view` action classes (spec §8.11), never more. */
+export const LinkAuthority = z.enum(["chat", "view"]);
+/** Who may mirror a conversation to a linked channel: nobody (the default), its owners and admins, or any member. */
+export const BridgePolicy = z.enum(["none", "admins", "members"]);
+/** The kinds of a `self` conversation's `setting` op: the person's settings, which never expire (spec §16.3). */
+export const SettingKind = z.enum(["prefs", "grant", "context", "localRetention", "link"]);
+/** A sealed op content: base64url(nonce ‖ AES-256-GCM ciphertext ‖ tag), at most a share's size. */
+const SealedState = Base64Url.min(38).max(Math.ceil(((LIMITS.convPlaintextBytes + 28) * 4) / 3));
 // ---- ops (spec §16.2, "Ops") ----
 /** A participant record as an op states it. `device` and `respondTo` are for agent participants only. */
 export const Seat = z
@@ -65,9 +78,13 @@ export const ConvOp = z.discriminatedUnion("op", [
         pins: Permit.optional(),
         /** JCS(`ConvMeta`) sealed under the creator's epoch-0 message key 0 (spec §16.5). */
         sealedMeta: Base64Url.max(2048).optional(),
+        /** External human DM: no content or shares until the permanent activation proof. */
+        admission: z.literal("request").optional(),
     }),
     z.strictObject({ op: z.literal("add"), participants: z.array(Seat).min(1).max(LIMITS.convOpParticipants) }),
-    z.strictObject({ op: z.literal("accept") }),
+    z.strictObject({ op: z.literal("accept"), invitation: GuestInvitation.optional() }),
+    z.strictObject({ op: z.literal("activate"), proof: ActivationProof }),
+    z.strictObject({ op: z.literal("request.complete"), request: Ulid, seq: z.number().int().min(2), digest: Hash }),
     z.strictObject({ op: z.literal("join") }),
     z.strictObject({ op: z.literal("leave") }),
     z.strictObject({ op: z.literal("remove"), participants: z.array(ParticipantId).min(1).max(LIMITS.convOpParticipants) }),
@@ -83,7 +100,19 @@ export const ConvOp = z.discriminatedUnion("op", [
         pins: Permit.optional(),
     }),
     z.strictObject({ op: z.literal("archive"), on: z.boolean() }),
-    z.strictObject({ op: z.literal("rekey"), epoch: z.number().int().min(1), cause: RekeyCause }),
+    z.strictObject({ op: z.literal("rekey"), epoch: z.number().int().min(1), cause: RekeyCause, device: MachineId.optional(), until: Seq.optional() })
+        .refine((op) => op.cause === "device" ? op.device !== undefined : op.device === undefined && op.until === undefined, { message: "only a device rekey names a device and optional cutoff" }),
+    /**
+     * The agent-context policy and the linked-channel `bridges` policy (spec §16.8, §16.10), in plaintext: an op, so it
+     * never expires, and a joiner who holds no earlier keys still knows it. In a dm or a group, the author's vote.
+     */
+    z
+        .strictObject({ op: z.literal("policy"), agentContext: AgentContext.optional(), bridges: BridgePolicy.optional() })
+        .refine((p) => p.agentContext !== undefined || p.bridges !== undefined, { message: "a policy sets agentContext, bridges or both" }),
+    /** A group's or channel's name, topic and purpose: JCS(`ConvMeta`) sealed under the author's key (`epoch`, `idx`). */
+    z.strictObject({ op: z.literal("meta"), epoch: Seq, idx: Seq, sealed: SealedState }),
+    /** A setting of the person's `self` conversation: JCS(`SettingBody` of `kind`) sealed under (`epoch`, `idx`). */
+    z.strictObject({ op: z.literal("setting"), kind: SettingKind, epoch: Seq, idx: Seq, sealed: SealedState }),
 ]);
 /** The plaintext of `create.sealedMeta` and of a `meta` body's fields. */
 export const ConvMeta = z.strictObject({
@@ -110,13 +139,6 @@ export const Attachment = z.strictObject({
     name: z.string().max(255),
     thumb: Base64Url.max(16_384).optional(),
 });
-// ---- linked channels (spec §16.10; reserved: validated, no daemon behaviour yet) ----
-/** An outside channel a person may link as an alias of themselves. Telegram first, then Slack. */
-export const LinkChannel = z.enum(["telegram", "slack"]);
-/** What a linked channel may do: Jelly's `chat` and `view` action classes (spec §8.11), never more. */
-export const LinkAuthority = z.enum(["chat", "view"]);
-/** Who may mirror a conversation to a linked channel: nobody (the default), its owners and admins, or any member. */
-export const BridgePolicy = z.enum(["none", "admins", "members"]);
 /** A line's provenance when its person wrote it from a linked channel. Signed and sealed with the event. */
 export const Via = z.strictObject({ channel: LinkChannel });
 /**
@@ -179,10 +201,24 @@ export const ContextRules = z
 export const KeyShare = z.strictObject({ epoch: Seq, device: MachineId, idx: Seq, ck: Key32 });
 /** The plaintext of one recipient's sealed share in a `keys` event. */
 export const KeySharePayload = z.strictObject({ shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) });
-/** The `self` conversation's bodies (spec §16.3, "The self conversation"). The last writer wins by `seq`. */
+/**
+ * The `self` conversation's passing state (spec §16.3, "The self conversation"), in `sync` message bodies: it expires
+ * with the conversation's retention. The last writer wins by `seq`.
+ */
 export const SyncBody = z.discriminatedUnion("s", [
     z.strictObject({ s: z.literal("read"), cid: ConvId, upTo: Seq, thread: Ulid.optional() }),
     z.strictObject({ s: z.literal("unread"), cid: ConvId, from: z.number().int().min(1) }),
+    z.strictObject({ s: z.literal("follow"), cid: ConvId, thread: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("save"), cid: ConvId, target: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("draft"), cid: ConvId, thread: Ulid.optional(), text: z.string().max(8000) }),
+    z.strictObject({ s: z.literal("joined"), cid: ConvId, on: z.boolean() }),
+    z.strictObject({ s: z.literal("keys"), cid: ConvId, shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) }),
+]);
+/**
+ * The person's settings, each sealed in a `setting` op of their `self` conversation (spec §16.3): ops never expire,
+ * so a setting outlives the retention. `s` is the op's `kind`. The last writer wins by `seq`.
+ */
+export const SettingBody = z.discriminatedUnion("s", [
     z.strictObject({
         s: z.literal("prefs"),
         cid: ConvId,
@@ -191,15 +227,10 @@ export const SyncBody = z.discriminatedUnion("s", [
         /** dms only; absent is off. */
         receipts: z.boolean().optional(),
     }),
-    z.strictObject({ s: z.literal("follow"), cid: ConvId, thread: Ulid, on: z.boolean() }),
-    z.strictObject({ s: z.literal("save"), cid: ConvId, target: Ulid, on: z.boolean() }),
-    z.strictObject({ s: z.literal("draft"), cid: ConvId, thread: Ulid.optional(), text: z.string().max(8000) }),
-    z.strictObject({ s: z.literal("joined"), cid: ConvId, on: z.boolean() }),
     /** A consent grant (spec §6.9), verified with `verifyConsentGrant` over this raw value. */
     z.strictObject({ s: z.literal("grant"), grant: z.record(z.string(), z.unknown()) }),
     z.strictObject({ s: z.literal("context"), rules: ContextRules }),
     z.strictObject({ s: z.literal("localRetention"), cid: ConvId, days: RetainDays }),
-    z.strictObject({ s: z.literal("keys"), cid: ConvId, shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) }),
     z.strictObject({ s: z.literal("link"), link: LinkRecord }),
 ]);
 /** The plaintext of a `msg` event. */
@@ -228,15 +259,6 @@ export const MsgBody = z.discriminatedUnion("t", [
     z.strictObject({ t: z.literal("pin"), target: Ulid, on: z.boolean() }),
     z.strictObject({ t: z.literal("task"), task: TaskEventBody }),
     z.strictObject({ t: z.literal("receipt"), target: Ulid, stage: ReceiptStage }),
-    z.strictObject({
-        t: z.literal("meta"),
-        name: ChannelName.optional(),
-        topic: z.string().max(250).optional(),
-        purpose: z.string().max(250).optional(),
-    }),
-    z
-        .strictObject({ t: z.literal("policy"), agentContext: AgentContext.optional(), bridges: BridgePolicy.optional() })
-        .refine((p) => p.agentContext !== undefined || p.bridges !== undefined, { message: "a policy sets agentContext, bridges or both" }),
     z.strictObject({ t: z.literal("sync"), sync: SyncBody }),
 ]);
 // ---- events and the log (spec §16.2) ----
@@ -266,6 +288,8 @@ export const ConvMsgEvent = z.strictObject({
     idx: Seq,
     /** Own-person wake hint only: sessions of `by.person` that this event may wake. */
     wake: z.array(SessionName).min(1).max(LIMITS.wakeHints).optional(),
+    /** The accepted request reservation. Only a sealed request.import can use it. */
+    request: Ulid.optional(),
     body: SealedBody,
     sig: Sig,
 });
@@ -276,17 +300,27 @@ export const SealedShare = z.strictObject({
     nonce: Nonce,
     ct: Base64Url.max(Math.ceil(((LIMITS.keyShares * 160 + 16) * 4) / 3)),
 });
-export const KeysBody = z.strictObject({
-    shares: z
-        .array(SealedShare)
-        .min(1)
-        .max(LIMITS.keySharesPerEvent)
-        .refine((shares) => new Set(shares.map((s) => s.to.device)).size === shares.length, { message: "one share per device" }),
-});
-/** Sender-key and history shares, sealed pairwise; the relay serves each share only to its recipient. */
+/** A `keys` event's body: one share, to one recipient device. */
+export const KeysBody = SealedShare;
+/**
+ * A sender-key or history share to one recipient device (spec §16.6). It is signed like every event but is not an
+ * entry of the log: the relay keeps it for its recipient alone and serves it to no one else (`ConvShareEntry`).
+ */
 export const ConvKeysEvent = z.strictObject({ ...header, class: z.literal("keys"), body: KeysBody, sig: Sig });
-export const ConvEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent, ConvKeysEvent]);
+/** The events of the log: ops and messages. */
+export const ConvEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent]);
+/** Every signed conversation event: the log's, and key shares. */
+export const ConvAnyEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent, ConvKeysEvent]);
 /** An event as the relay stores and serves it. The relay does not sign it; members verify the chain. */
 export const ConvLogEntry = z.strictObject({ seq: z.number().int().min(1), prev: Hash, event: ConvEvent });
+/**
+ * A `msg` entry whose body the relay pruned after the retention (spec §16.4): its seq, its prev and the digest
+ * SHA-256(JCS(event)), so the chain stays verifiable (`ConvLog.applyExpired`). An op is never served this way.
+ */
+export const ConvExpiredEntry = z.strictObject({ seq: z.number().int().min(2), prev: Hash, digest: Hash });
+/** What `conv.fetch` serves for one seq: the entry, or its digest once expired. */
+export const ConvServedEntry = z.union([ConvLogEntry, ConvExpiredEntry]);
+/** A key share as the relay serves it to its recipient: `n` orders the recipient's shares of one conversation. */
+export const ConvShareEntry = z.strictObject({ n: z.number().int().min(1), event: ConvKeysEvent });
 /** A log position: a seq and h(seq). */
 export const ConvHead = Position;

package/dist/lib/modules/core/schema/directory-frames.js

@@ -23,7 +23,7 @@
  *   dir.watch {req, persons}              → dir.ok {req}; then dir.changed {persons, sth} pushes
  *   presence.watch {req, persons}         → dir.ok {req}
  *   dir.erase {req, entries, token}       → dir.ok {req}
- *   wake.arm {req, url, ticket, agents, awaiting} → dir.ok {req}   a Jelly host's device, before it sleeps (§7, "Wake tickets")
+ *   wake.arm {req, url, ticket, agents, awaiting, dms?} → dir.ok {req}   a Jelly host's device, before it sleeps (§7, "Wake tickets")
  *   wake.disarm {req}                     → dir.ok {req}
  *   relay → dir.unbound {entry, sth}      this device's own unbind, just before close 4003
  *
@@ -36,6 +36,7 @@ import { Base64Url, Hash, HostedPersonId, LIMITS, Millis, RELAY_PROTOCOL, Sessio
 import { EpochProof } from "./directory.js";
 import { RealmId } from "./realm.js";
 import { DeviceId, KeyRotation, KeysStatement, LogEntry, PersonHead, PersonView, STH } from "./directory.js";
+import { ConvId } from "./conversation.js";
 import { Jws } from "./jelly.js";
 const Req = z.string().min(1).max(64);
 const Size = z.number().int().positive();
@@ -150,6 +151,8 @@ export const DirEraseFrame = z.object({
 /** Most agents a wake ticket's filter names, and most awaited task requests (spec §7, "Wake tickets"). */
 export const WAKE_AGENTS = 64;
 export const WAKE_AWAITING = 500;
+/** Most dm conversations a wake ticket's filter names (spec §7, "Wake tickets", "a peer's dm"). */
+export const WAKE_DMS = 256;
 /** Most bytes of a wake ticket, and its longest life: Jelly's `jelly-wake+jwt` lives at most seven days. */
 export const WAKE_TICKET_BYTES = 4096;
 export const WAKE_TICKET_MAX_S = 7 * 24 * 60 * 60;
@@ -159,8 +162,9 @@ export const WakeUrl = z.string().max(2048).regex(/^https?:\/\/[^/?#@\s]+\/hosts
  * A Jelly host's device arms a wake ticket before the host sleeps (spec §7, "Wake tickets"). `url` is Jelly ID's wake
  * endpoint for this device's host; `ticket` the host's single-use `jelly-wake+jwt`, which the relay never verifies
  * (Jelly ID does) and reads only for its `exp`; `agents` the local sessions whose own person's mail may wake the host;
- * `awaiting` the request envelope ids of the tasks those agents wait on, whose updates (`replyTo`) may wake it. A new
- * arm replaces the device's previous one.
+ * `awaiting` the request envelope ids of the tasks those agents wait on, whose updates (`replyTo`) may wake it; `dms`
+ * the dm conversations whose other participant's events may wake it (absent: none), which the host's daemon chose. A
+ * new arm replaces the device's previous one.
  */
 export const WakeArmFrame = z.object({
     t: z.literal("wake.arm"),
@@ -169,6 +173,7 @@ export const WakeArmFrame = z.object({
     ticket: Jws.refine((ticket) => ticket.length <= WAKE_TICKET_BYTES, { message: `at most ${WAKE_TICKET_BYTES} bytes` }),
     agents: z.array(SessionName).max(WAKE_AGENTS),
     awaiting: z.array(Ulid).max(WAKE_AWAITING),
+    dms: z.array(ConvId).max(WAKE_DMS).optional(),
 });
 /** The relay forgets this device's wake ticket. */
 export const WakeDisarmFrame = z.object({ t: z.literal("wake.disarm"), req: Req });

package/dist/lib/modules/core/schema/envelope.js

@@ -5,11 +5,12 @@
  */
 import { z } from "../../vendor/zod/index.js";
 import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "./a2a.js";
-import { AgentKind, Base64Url, ChannelName, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, PROTOCOL, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "./common.js";
+import { AgentKind, Base64Url, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, PROTOCOL, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "./common.js";
 import { CardData, CardGetData, GrantSync } from "./consent.js";
 import { DelegationChain } from "./delegation.js";
 import { ErrorCode } from "./errors.js";
 import { Anchor, RealmId } from "./realm.js";
+import { PortableRequest } from "./contact-request.js";
 export const EnvelopeType = z.enum(["message", "task.status", "task.artifact", "task.cancel", "receipt", "presence"]);
 export const SEAL_ALG = "x25519-hkdf-sha256-a256gcm";
 /**
@@ -62,22 +63,6 @@ export const Envelope = z.object({
     sig: Base64Url,
 });
 // ---- Decrypted body payloads, by envelope type ----
-/** A channel's persons: roster person names, or hosted `p_…` ids in a directory realm (spec §6.8). */
-const ChannelPersons = z.array(PersonId).min(1).max(LIMITS.channelPersons);
-/**
- * A channel change or post (spec §6.8), on a `kind: "message"` envelope sealed to a device with no recipient agent.
- * `create`: the full channel record with the person who created it, to every member device and to each later
- * invitee. `invite`: persons added, to the existing members. `leave`: the sender left. `remove`: persons removed by
- * the creator or an admin, to every member device. `post`: a line in the channel. `name` is always the channel's own
- * name. A DM line has no `conv` (spec §5, "Meaning").
- */
-export const ChannelConv = z.discriminatedUnion("op", [
-    z.object({ kind: z.literal("channel"), op: z.literal("create"), id: Ulid, name: ChannelName, persons: ChannelPersons, creator: PersonId }),
-    z.object({ kind: z.literal("channel"), op: z.literal("invite"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
-    z.object({ kind: z.literal("channel"), op: z.literal("leave"), id: Ulid, name: ChannelName }),
-    z.object({ kind: z.literal("channel"), op: z.literal("remove"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
-    z.object({ kind: z.literal("channel"), op: z.literal("post"), id: Ulid, name: ChannelName }),
-]);
 /**
  * Sync between two devices of one person (spec §6.9, "Sync"): `grant` carries grants the person set or re-signed,
  * `snapshot` every current grant, for a device of the person that is new to the sender. The message carries exactly
@@ -88,14 +73,14 @@ export const SelfConv = z.object({ kind: z.literal("self"), what: z.enum(["grant
  * A message request (spec §6.9, "Message requests"), on an envelope of class `request` from a person to a person:
  * its message carries exactly one text part of at most `LIMITS.requestChars`.
  */
-export const RequestConv = z.object({ kind: z.literal("request") });
+export const RequestConv = z.object({ kind: z.literal("request"), proof: PortableRequest.optional() });
 /**
  * A contact card between two persons (spec §6.9, "Contact cards"): `card` carries one data part `{card}`, the signed
  * card; `get` asks for the receiver's card and carries one data part `{get: true}`.
  */
 export const CardConv = z.object({ kind: z.literal("card"), what: z.enum(["card", "get"]) });
 /** The conversation a `message` belongs to when its ends alone do not say (spec §5, "Meaning"). */
-export const Conv = z.discriminatedUnion("kind", [ChannelConv, SelfConv, RequestConv, CardConv]);
+export const Conv = z.discriminatedUnion("kind", [SelfConv, RequestConv, CardConv]);
 /**
  * type "message". `kind: "task"` asks the recipient to run `message` as a new A2A task;
  * the sender assigns `message.taskId` (a ULID) and `message.contextId`.
@@ -109,11 +94,7 @@ export const MessagePayload = z
     wake: z.boolean().optional(),
     /** Required on `kind: "task"`, absent otherwise: the signed chain from the root requester to this hop (spec §6.7). Receivers run `verifyChain`. */
     delegation: DelegationChain.optional(),
-    /**
-     * The conversation, when the ends do not say it (spec §5, "Meaning"): a channel change or post (§6.8).
-     * `message.messageId` is a ULID shared by every copy; `message.contextId`, when set, is the ULID `messageId` of
-     * the thread's first line.
-     */
+    /** Device-addressed consent sync, portable contact request or contact card. */
     conv: Conv.optional(),
 })
     .refine((p) => (p.kind === "task" ? p.message.taskId !== undefined : true), { message: "a task message needs message.taskId" })
@@ -123,6 +104,9 @@ export const MessagePayload = z
 })
     .refine((p) => p.conv?.kind !== "request" || requestMessage(p.message), {
     message: `a message request carries one text part of 1 to ${LIMITS.requestChars} characters, and nothing else`,
+})
+    .refine((p) => p.conv?.kind !== "request" || p.conv.proof === undefined || (p.message.messageId === p.conv.proof.descriptor.id && p.message.parts[0]?.text === p.conv.proof.opening.text), {
+    message: "a portable request's message id and text match its signed opening",
 })
     .refine((p) => p.conv?.kind !== "card" || cardMessage(p.message, p.conv.what), {
     message: "a card message carries one data part, the card or the request for one, and nothing else",

package/dist/lib/modules/core/schema/errors.js

@@ -11,6 +11,7 @@ export const ErrorCode = z.enum([
     "refused", // recipient policy refuses this sender
     "declined", // the recipient's person declined a held request (spec §6.9)
     "request_required", // the recipient's person has not accepted this sender: a message request comes first (spec §6.9)
+    "peer_outdated", // the other person's devices run a Messaging from before conversations: they need to update first
     "rate_limited", // too many envelopes; retry later
     "loop_guard", // agent-to-agent loop guard tripped
     "too_large", // size limit exceeded
@@ -24,11 +25,12 @@ export const ErrorCode = z.enum([
     "guarded_turn", // a guarded peer turn tried to send outside its allowance (client-side; never on the wire)
     "roster_conflict", // roster entry does not extend the current head; resync and retry
     "invite_invalid", // unknown, expired, revoked, used or mismatched invite
-    "no_identity", // daemon has no identity/team yet
+    "no_identity", // daemon has no usable team identity or bound directory device with published keys
     "binding_invalid", // a device binding, log entry or its authority failed verification (hosted realms)
-    "jelly_unavailable", // Jelly ID's key set or key history could not be fetched; never reported as invalid
+    "jelly_unavailable", // Jelly ID unreachable or an unusable response for keys or sign-in; never reported as invalid
     "log_conflict", // a device-log entry does not extend the log's head; resync and retry
     "conv_conflict", // a conversation event does not extend the log, or its op head is not the current one; re-read and retry
+    "conflict", // a person's setting changed since the caller read it (a stale revision, reach.set); nothing changed: read again
     "stale_epoch", // a conversation message is sealed under an epoch that is not the current one, or a rekey is due; re-seal and retry
     "device_limit", // the person already has LIMITS.devicesPerPerson current devices
     "admission_required", // dir.bind without a Jelly-vouched bind of the connecting device
@@ -38,8 +40,8 @@ export const ErrorCode = z.enum([
     "directory_unavailable", // the key directory could not be reached to verify a person's devices within the freshness bound
     "login_unsupported", // Jelly ID offers no device sign-in for this realm's resource (no v1.2 device sign-in in its metadata)
     "login_denied", // the person denied the sign-in at Jelly ID, or the account is disabled or being deleted
-    "grant_required", // deployment "jelly": a human- or admin-tier call carried no action grant (spec §8.11)
-    "grant_invalid", // deployment "jelly": the action grant did not verify, is for another call, expired or was spent
+    "grant_required", // deployment "jelly": a human- or admin-tier call carried no action grant (spec §8.11), or request.answer no action token (§8.2)
+    "grant_invalid", // the action grant (deployment "jelly") or an action token (§8.2) did not verify, is for another call, expired or was spent
     "ticket_required", // deployment "jelly": session.register carried no session ticket
     "ticket_invalid", // deployment "jelly": the session ticket did not verify, expired, or names another session or agent
     "daemon_unavailable", // client could not reach the local daemon socket
@@ -50,7 +52,7 @@ export const ErrorCode = z.enum([
 /**
  * The exit status of a messagingd or messaging-relay that refuses its store and changes nothing (spec §8.8): `EX_CONFIG`
  * of sysexits(3), for either reason. messagingd also prints one stderr line,
- * `messagingd: store_refused: <reason>: <why and how to start over>`. A client matches this status, the code and the
+ * `messagingd: store_refused: <reason>: <why and the remedy>`. A client matches this status, the code and the
  * reason, never the wording.
  */
 export const STORE_REFUSED_EXIT = 78;

package/dist/lib/modules/core/schema/guest-invitation.js

@@ -0,0 +1,13 @@
+/** A bounded, sealed preview. Its signature is portable; the guest accepts exactly this op head and exposure. */
+import { z } from "../../vendor/zod/index.js";
+import { Hash, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
+import { RealmId } from "./realm.js";
+export const GuestInvitation = z.strictObject({
+    v: z.literal(PROTOCOL), realm: RealmId, cid: z.string().regex(/^c_[0-7][0-9A-HJKMNP-TV-Z]{25}$/),
+    id: Ulid, to: PersonId, inviter: PersonId, by: MachineId,
+    head: z.strictObject({ seq: z.number().int().min(1), hash: Hash }), issuedAt: Millis, expiresAt: Millis,
+    kind: z.enum(["channel", "group"]), history: z.enum(["shared", "none"]),
+    agentContext: z.enum(["members", "seats", "none"]), bridges: z.enum(["members", "admins", "none"]),
+    audience: z.array(z.strictObject({ p: z.string().min(1).max(100), person: PersonId, role: z.enum(["owner", "admin", "member", "guest"]), state: z.enum(["member", "invited"]) })).min(1).max(LIMITS.convParticipants),
+    sig: z.string().regex(/^[A-Za-z0-9_-]{86}$/),
+});

package/dist/lib/modules/core/schema/index.js

@@ -14,3 +14,8 @@ export * from "./ipc.js";
 export * from "./ipc/device.js";
 export * from "./ipc/consent.js";
 export * from "./conversation.js";
+export * from "./conv-frames.js";
+export * from "./contact-request.js";
+export * from "./guest-invitation.js";
+export * from "./ipc/conversation-views.js";
+export * from "./ipc/conversations.js";

package/dist/lib/modules/core/schema/ipc/consent.js

@@ -3,11 +3,13 @@
  * socket refuses them, and agents never set or read a person's grants. Spread into `IPC_METHODS`.
  */
 import { z } from "../../../vendor/zod/index.js";
-import { ChannelName, LIMITS, MachineId, MachineLabel, Millis, PersonId, RoomRef, SessionAddress, SessionName, Ulid } from "../common.js";
+import { LIMITS, MachineId, MachineLabel, Millis, PersonId, SessionAddress, SessionName, Ulid } from "../common.js";
+import { ConvId, ParticipantId } from "../conversation.js";
 import { AgentMailLevel, AskLevel, CardCan, ChatLevel } from "../consent.js";
 import { Email } from "../directory-frames.js";
-/** A grant's subject as a person names it: a person, or a channel by its name here. */
-export const GrantTarget = z.union([z.strictObject({ person: PersonId }), z.strictObject({ channel: ChannelName })]);
+import { ActionToken } from "./shapes.js";
+/** A grant's subject: a person, or a verified conversation id. */
+export const GrantTarget = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId })]);
 const Levels = {
     chat: ChatLevel.optional(),
     agentMail: AgentMailLevel.optional(),
@@ -17,7 +19,7 @@ const Levels = {
 };
 /** A grant as this device holds it. A channel subject carries the channel's id and, while this person is in it, its name here. */
 export const GrantView = z.object({
-    subject: z.union([z.object({ person: PersonId }), z.object({ channel: Ulid, name: ChannelName.optional() })]),
+    subject: GrantTarget,
     ...Levels,
     id: Ulid,
     ts: Millis,
@@ -42,6 +44,21 @@ export const GrantReview = z.object({
  * level it is a clear. `trust: true` trusts for `LIMITS.trustDefaultMs`; `trustedUntil` names the end instead.
  */
 export const GrantSetParams = z.strictObject({ subject: GrantTarget, ...Levels, trust: z.literal(true).optional() });
+/**
+ * For an ask: `once` delivers it, guarded; `always` sets the sender's grant to `ask: "open"` (keeping its other
+ * levels), then delivers it, guarded. For a message request: `accept` sets the sender's grant to `chat: "open"`
+ * (keeping its other levels), files the request as their first line and sends them a card. For both: `decline`
+ * refuses it (`declined`); `block` sets the sender's grant to `chat: "blocked"` (keeping its other levels), then
+ * declines it. For a suggestion: `decline` dismisses it.
+ */
+export const RequestAnswer = z.enum(["once", "always", "accept", "decline", "block"]);
+/**
+ * A source-issued action on a held request (spec §8.2, "Action tokens"): `name` is the answer it gives, redeemed with
+ * `request.answer {id, answer: name, token}` on the connection that read it.
+ */
+export const RequestAction = z.strictObject({ name: RequestAnswer, token: ActionToken });
+/** One per answer the request's kind takes; only on the human tier, only while the request is pending. */
+const Actions = { actions: z.array(RequestAction).max(4).optional() };
 /** A request this device holds for its person to answer (spec §6.9, "Holds"): mail or a task to one of their agents. */
 export const AskRequest = z.object({
     /** The envelope id. */
@@ -55,19 +72,22 @@ export const AskRequest = z.object({
     at: Millis,
     /** When the request expires, unanswered. */
     exp: Millis,
+    ...Actions,
 });
 /**
  * A message request this device holds for its person (spec §6.9, "Message requests"): a person of another org asks to
  * write to them. `name`, `email` and `org` are the realm's verified profile of the sender, never the request's text.
  */
 export const ContactRequestView = z.object({
-    /** The envelope id. */
+    /** The portable request id; old unsigned requests explicitly require a resend. */
     id: Ulid,
     kind: z.literal("contact"),
+    cid: ConvId.optional(),
+    state: z.enum(["pending", "answering", "accepted", "resend"]),
     from: z.object({
         person: PersonId,
         device: MachineId,
-        label: MachineLabel,
+        label: MachineLabel.optional(),
         name: z.string().max(200),
         email: z.string().max(320).optional(),
         org: z.enum(["same", "other", "none"]),
@@ -76,7 +96,9 @@ export const ContactRequestView = z.object({
     text: z.string().max(LIMITS.requestChars),
     at: Millis,
     exp: Millis,
+    ...Actions,
 });
+export const AgentInvitationRequest = z.strictObject({ kind: z.literal("agent-invitation"), id: Ulid, cid: ConvId, from: ParticipantId, to: ParticipantId, at: Millis, ...Actions });
 /**
  * A contact one of this person's agents asks them to make (spec §6.9, "Message requests"): `send {to: "me", request:
  * {contact}}`. Only the person sends a message request, with `contact.request`; answering this one `decline`
@@ -89,17 +111,10 @@ export const ContactSuggestion = z.object({
     agent: SessionName,
     email: Email,
     at: Millis,
+    ...Actions,
 });
 /** What `request.list` lists: asks to the person's agents, message requests, and contacts their agents suggest. */
-export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion]);
-/**
- * For an ask: `once` delivers it, guarded; `always` sets the sender's grant to `ask: "open"` (keeping its other
- * levels), then delivers it, guarded. For a message request: `accept` sets the sender's grant to `chat: "open"`
- * (keeping its other levels), files the request as their first line and sends them a card. For both: `decline`
- * refuses it (`declined`); `block` sets the sender's grant to `chat: "blocked"` (keeping its other levels), then
- * declines it. For a suggestion: `decline` dismisses it.
- */
-export const RequestAnswer = z.enum(["once", "always", "accept", "decline", "block"]);
+export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion, AgentInvitationRequest]);
 /** A message request's text: 1 to `LIMITS.requestChars` UTF-16 code units. */
 export const RequestText = z
     .string()
@@ -115,10 +130,74 @@ export const RequestText = z
  */
 export const PersonReach = z.object({ person: PersonId, can: CardCan, source: z.enum(["card", "default"]), at: Millis.optional(), devicesChangedAt: Millis.optional() });
 /** `request.answer`'s params, which `request.answer.preview` takes too (spec §8.2, "Previews"). */
-export const RequestAnswerParams = z.strictObject({ id: Ulid, answer: RequestAnswer, all: z.boolean().optional() });
+/**
+ * `request.answer`'s params. `token` is the request's action for this `answer` (`RequestAction`); it answers that one
+ * request, so it never comes with `all`. Under a Jelly host it is required.
+ */
+export const RequestAnswerParams = z
+    .strictObject({ id: Ulid, answer: RequestAnswer, all: z.boolean().optional(), token: ActionToken.optional() })
+    .refine((p) => p.token === undefined || p.all !== true, "an action token answers one request: drop all");
 /** `contact.request`'s params; its preview takes them with `text` optional (it reads only `email`). */
 export const ContactRequestParams = z.strictObject({ email: Email, text: RequestText, suggestion: Ulid.optional() });
+/** A reach question (spec §6.9, "Reach choices"): `message` is "Who can message you", `ask` "How agents may ask yours". */
+export const ReachGroupId = z.enum(["message", "ask"]);
+/** An answer: Open, Ask me first (the default), Never. */
+export const ReachValue = z.enum(["open", "ask", "never"]);
+export const ReachOption = z.object({ value: ReachValue, label: z.string().max(40), description: z.string().max(300) });
+/**
+ * One question with its options. `value` is the person's choice, or null while they have made none and the relation
+ * defaults apply. `lapsed` is a choice a removed device of the person made, which lapsed with it (§6.9, "Signers")
+ * and waits for the person to choose again.
+ */
+export const ReachGroup = z.object({
+    id: ReachGroupId,
+    label: z.string().max(80),
+    options: z.array(ReachOption).length(3),
+    value: ReachValue.nullable(),
+    lapsed: ReachValue.optional(),
+});
+/** `reach.get`'s result, and `reach.set`'s: both questions, and a `revision` that changes whenever either choice does. */
+export const ReachSnapshot = z.object({ revision: z.string().min(1).max(64), available: z.boolean(), groups: z.array(ReachGroup).length(2) });
+/** `reach.set`'s params, which `reach.set.preview` takes too: the `revision` read, and only the declared answers that change. */
+export const ReachSetParams = z.strictObject({
+    revision: z.string().min(1).max(64),
+    changes: z.strictObject({ message: ReachValue.optional(), ask: ReachValue.optional() }),
+});
+/** The fixed words of the two questions, in `reach.get`'s order. */
+export const REACH_QUESTIONS = [
+    {
+        id: "message",
+        label: "Who can message you",
+        options: [
+            { value: "open", label: "Open", description: "Anyone outside your org may message you." },
+            { value: "ask", label: "Ask me first", description: "People outside your org send a message request first, and you accept or decline it. People you have accepted may message you." },
+            { value: "never", label: "Never", description: "No one outside your org may message you or send you a request. Your org, and people you have let message you, still can." },
+        ],
+    },
+    {
+        id: "ask",
+        label: "How agents may ask yours",
+        options: [
+            { value: "open", label: "Open", description: "Your teammates' agents may ask your agents without asking you. Their requests run guarded." },
+            { value: "ask", label: "Ask me first", description: "Each request from a teammate's agent to yours waits for your answer." },
+            { value: "never", label: "Never", description: "Your teammates' agents may not ask yours. Agents of people outside your org never may." },
+        ],
+    },
+];
 export const CONSENT_METHODS = {
+    /**
+     * The person's two reach choices (spec §6.9, "Reach choices"), each with its options and the current value (null:
+     * none made, the defaults apply), and a revision. Read-only.
+     */
+    "reach.get": { params: z.strictObject({}), result: ReachSnapshot },
+    /**
+     * Records the declared answers in `changes` as the person's relation grants, signed by this device and sent to
+     * their other devices, in one transaction; returns the new snapshot. `conflict` when `revision` is not the current
+     * one: nothing is changed, and the caller reads again.
+     */
+    "reach.set": { params: ReachSetParams, result: ReachSnapshot },
+    /** What `reach.set` with these params would do, in one fixed sentence; checks them the same way (`conflict` too); changes nothing. */
+    "reach.set.preview": { params: ReachSetParams, result: z.object({ sentence: z.string().max(500) }) },
     /** This person's grants, newest first, and the review list. With `subject`, only that subject's. */
     "grant.list": {
         params: z.strictObject({ subject: GrantTarget.optional() }),
@@ -152,7 +231,7 @@ export const CONSENT_METHODS = {
     "request.answer.preview": {
         params: RequestAnswerParams,
         result: z.object({
-            kind: z.enum(["message", "task", "contact", "suggestion"]),
+            kind: z.enum(["message", "task", "contact", "suggestion", "agent-invitation"]),
             from: z.object({ name: z.string().max(200), email: z.string().max(320).optional(), org: z.enum(["same", "other", "none"]) }),
             agent: SessionName.optional(),
             to: SessionName.optional(),
@@ -169,7 +248,7 @@ export const CONSENT_METHODS = {
      */
     "contact.request": {
         params: ContactRequestParams,
-        result: z.object({ id: Ulid, conversation: RoomRef, person: PersonId }),
+        result: z.object({ id: Ulid, cid: ConvId, person: PersonId }),
     },
     /** Whether `contact.request` would find a person for `email`; counts against the directory's lookup limits. Sends nothing. */
     "contact.request.preview": { params: ContactRequestParams.partial({ text: true }), result: z.object({ found: z.boolean() }) },