@joe-broadhead/messaging 0.7.1 → 0.8.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/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,9 +25,9 @@ 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
     "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
@@ -50,7 +51,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,12 @@
  * 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 })]);
+/** 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 +18,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,
@@ -61,13 +62,15 @@ export const AskRequest = z.object({
  * 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"]),
@@ -77,6 +80,7 @@ export const ContactRequestView = z.object({
     at: Millis,
     exp: Millis,
 });
+export const AgentInvitationRequest = z.strictObject({ kind: z.literal("agent-invitation"), id: Ulid, cid: ConvId, from: ParticipantId, to: ParticipantId, at: Millis });
 /**
  * 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`
@@ -91,7 +95,7 @@ export const ContactSuggestion = z.object({
     at: Millis,
 });
 /** 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]);
+export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion, AgentInvitationRequest]);
 /**
  * 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"`
@@ -152,7 +156,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 +173,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() }) },

package/dist/lib/modules/core/schema/ipc/conversation-views.js

@@ -0,0 +1,80 @@
+/** Rendered conversation projections for the future conversation IPC cut-over.
+ * Peer names, text and file names are untrusted; clients must fence or sanitize them.
+ * These schemas do not register a method on either socket.
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { LIMITS, Millis, SessionName, Ulid } from "../common.js";
+import { AgentContext, ConvId, ConvKind, ConvRole, HistoryPolicy, Mention, ParticipantId, RespondTo, Visibility } from "../conversation.js";
+import { TaskState } from "../a2a.js";
+const Count = z.number().int().nonnegative().safe();
+const Seq = z.number().int().nonnegative().safe();
+const Name = z.string().max(200);
+export const ParticipantView = z.object({
+    p: ParticipantId,
+    kind: z.enum(["person", "agent"]),
+    role: ConvRole,
+    state: z.enum(["member", "invited"]),
+    name: Name,
+    handle: z.string().max(64).optional(),
+    org: z.enum(["same", "other", "none"]),
+    presence: z.enum(["online", "away", "offline", "unknown"]),
+    agentState: z.enum(["idle", "busy", "kept"]).optional(),
+    respondTo: RespondTo.optional(),
+});
+/** Names travel with a notice so rendering it does not need one lookup per participant. */
+export const NoticeView = z.object({
+    op: z.enum(["create", "add", "accept", "join", "leave", "remove", "role", "seat", "settings", "archive", "meta", "policy"]),
+    by: ParticipantView.pick({ p: true, kind: true, name: true }),
+    participants: z.array(ParticipantView.pick({ p: true, kind: true, name: true })).max(LIMITS.convOpParticipants).optional(),
+    fields: z.array(z.enum(["name", "topic", "purpose", "visibility", "history", "retainDays", "post", "invite", "pins", "agentContext", "bridges"])).max(12).optional(),
+});
+/** A file projection deliberately excludes the key and nonce in the encrypted wire attachment. */
+export const FileView = z.object({
+    blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/),
+    name: z.string().max(255), mime: z.string().max(100), bytes: z.number().int().positive().max(LIMITS.blobBytes),
+});
+export const TaskView = z.object({ id: Ulid, state: TaskState });
+export const EventView = z.object({
+    cid: ConvId, id: Ulid, seq: z.number().int().positive().safe(), at: Millis,
+    author: ParticipantView.pick({ p: true, kind: true, name: true }),
+    kind: z.enum(["line", "task", "notice"]),
+    text: z.string().max(LIMITS.lineChars).optional(), format: z.enum(["plain", "md"]).optional(),
+    thread: Ulid.optional(), broadcast: z.boolean().optional(),
+    mentions: z.array(Mention).max(LIMITS.mentions).optional(), mentionsMe: z.boolean(),
+    files: z.array(FileView).max(LIMITS.files).optional(), edited: Millis.optional(), deleted: z.boolean().optional(),
+    reactions: z.array(z.object({ key: z.string().min(1).max(64), count: Count, mine: z.boolean() })).max(LIMITS.reactionsPerEvent).optional(),
+    pinned: z.boolean().optional(),
+    replies: z.object({ count: Count, lastAt: Millis, participants: z.array(ParticipantId).max(5), unread: Count.optional(), following: z.boolean().optional() }).optional(),
+    task: TaskView.optional(), notice: NoticeView.optional(),
+    delivery: z.enum(["pending", "sent", "delivered", "read", "failed"]).optional(),
+    clientId: z.string().min(1).max(200).optional(),
+}).refine((event) => !event.deleted || (event.text === undefined && event.files === undefined), {
+    message: "a deleted event contains no text or files",
+});
+export const ConvView = z.object({
+    cid: ConvId, kind: ConvKind, visibility: Visibility.optional(), history: HistoryPolicy,
+    retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax), agentContext: AgentContext,
+    name: z.string().max(80).optional(), topic: z.string().max(250).optional(), purpose: z.string().max(250).optional(),
+    archived: z.boolean(), role: ConvRole, participants: Count, dmWith: ParticipantView.optional(), last: EventView.optional(),
+    headSeq: Seq, readUpTo: Seq.optional(), unread: Count.optional(), mentions: Count.optional(), threadsUnread: Count.optional(),
+    notify: z.enum(["all", "mentions", "none"]).optional(), mutedUntil: Millis.optional(), draft: z.string().max(8000).optional(),
+});
+export const ActivityBody = z.object({
+    session: SessionName, turn: Ulid, seq: Seq,
+    source: z.object({ item: Ulid.optional(), cid: ConvId.optional(), task: Ulid.optional() }).optional(),
+    kind: z.enum(["turn_started", "step", "turn_ended", "error", "cancelled"]), summary: z.string().max(200).optional(),
+});
+export const ConvStreamEvent = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("event"), pos: Seq, event: EventView }),
+    z.object({ type: z.literal("event.update"), pos: Seq, cid: ConvId, id: Ulid,
+        change: z.enum(["edit", "delete", "react", "pin", "replies", "delivery", "task"]), event: EventView }),
+    z.object({ type: z.literal("conv"), pos: Seq, conv: ConvView }),
+    z.object({ type: z.literal("member"), pos: Seq, cid: ConvId, participant: ParticipantView,
+        change: z.enum(["added", "invited", "removed", "role", "seat", "presence"]) }),
+    z.object({ type: z.literal("read"), pos: Seq, cid: ConvId, readUpTo: Seq, unread: Count, mentions: Count }),
+    z.object({ type: z.literal("typing"), cid: ConvId, p: ParticipantId, thread: Ulid.optional(), until: Millis }),
+    z.object({ type: z.literal("activity"), body: ActivityBody }),
+    z.object({ type: z.literal("gap"), pos: Seq }),
+]).refine((entry) => entry.type !== "event.update" || (entry.cid === entry.event.cid && entry.id === entry.event.id), {
+    message: "event.update names the same conversation and event as its projection",
+});

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

@@ -0,0 +1,128 @@
+/** Conversation contracts, including later lanes. Only LIVE_CONVERSATION_METHODS registers IPC. */
+import { z } from "../../../vendor/zod/index.js";
+import { LIMITS, MachineId, Millis, PersonId, SessionName, Ulid } from "../common.js";
+import { AgentContext, Attachment, ContextAccess, ContextRules, ConvId, ConvKind, ConvMeta, ConvRole, HistoryPolicy, Mention, ParticipantId, Permit, RespondTo, Seat, Visibility } from "../conversation.js";
+import { PersonSummary } from "./surfaces.js";
+import { SessionKey } from "./shapes.js";
+import { ActivityBody, ConvStreamEvent, ConvView, EventView, ParticipantView } from "./conversation-views.js";
+const Empty = z.strictObject({});
+const Ok = z.object({ ok: z.literal(true) });
+const Count = z.number().int().nonnegative().safe();
+const Seq = z.number().int().nonnegative().safe();
+const Limit = z.number().int().min(1).max(50).optional();
+const Cursor = z.string().min(1).max(512).optional();
+const Key = SessionKey.optional(); // required by the daemon on an agent connection
+const Cid = { cid: ConvId };
+const Page = { limit: Limit, cursor: Cursor };
+const Id = { cid: ConvId, id: Ulid };
+const Text = z.string().min(1).max(LIMITS.lineChars);
+const CommonErrors = ["invalid_request", "forbidden", "not_found", "too_large", "internal", "no_identity", "unknown_session", "grant_required", "grant_invalid", "directory_unavailable", "directory_inconsistent"];
+const WriteErrors = [...CommonErrors, "invalid_state", "conv_conflict", "stale_epoch", "relay_unavailable", "rate_limited", "duplicate", "secret_refused", "refused", "declined", "request_required", "loop_guard", "unknown_device", "binding_invalid"];
+const ReadErrors = [...CommonErrors, "relay_unavailable"];
+const Write = (params) => ({ params, result: Ok, errors: WriteErrors });
+const Read = (params, result) => ({ params, result, errors: ReadErrors });
+const EventPage = z.object({ events: z.array(EventView).max(50), more: z.boolean(), cursor: Cursor });
+const ConvPage = z.object({ conversations: z.array(ConvView).max(50), cursor: Cursor });
+const PageParams = z.strictObject({ ...Cid, ...Page });
+const Hold = z.object({ stage: z.literal("held"), code: z.enum(["context", "audience"]), expect: z.literal("on_consent") });
+const LineFields = { text: Text, format: z.enum(["plain", "md"]).optional(), thread: Ulid.optional(), broadcast: z.boolean().optional(),
+    mentions: z.array(Mention).max(LIMITS.mentions).optional(), files: z.array(Attachment).max(LIMITS.files).optional() };
+const OptionalSettings = { visibility: Visibility.optional(), history: HistoryPolicy.optional(), retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax).optional(),
+    post: Permit.optional(), invite: Permit.optional(), pins: Permit.optional() };
+/** Explicit consent evidence and unconfirmed delivery are different states. */
+export const WaitingOnThemView = z.object({
+    id: Ulid, kind: z.enum(["message", "task", "contact"]), to: PersonId,
+    name: z.string().max(200), at: Millis, cid: ConvId.optional(), agent: SessionName.optional(),
+    state: z.enum(["held", "pending-delivery"]),
+});
+export const ConvListParams = z.strictObject({ key: Key, filter: z.strictObject({ unread: z.boolean().optional(), mentions: z.boolean().optional(), kind: ConvKind.optional(), archived: z.boolean().optional() }).optional(), ...Page });
+export const ConvListResult = ConvPage;
+export const ConvReadParams = z.strictObject({ key: Key, ...Cid, thread: Ulid.optional(), before: Seq.optional(), after: Seq.optional(), around: Ulid.optional(), limit: Limit, cursor: Cursor })
+    .refine((p) => [p.before, p.after, p.around, p.cursor].filter((v) => v !== undefined).length <= 1, "choose one page position");
+export const ConvReadResult = z.union([EventPage, Hold]);
+export const ConvSendParams = z.strictObject({ key: Key, cid: ConvId.optional(), to: ParticipantId.optional(), ...LineFields, answer: Ulid.optional(), clientId: z.string().min(1).max(200) })
+    .refine((p) => (p.cid === undefined) !== (p.to === undefined), "choose exactly one of cid or to")
+    .refine((p) => p.broadcast !== true || p.thread !== undefined, "broadcast needs a thread");
+export const ConvSendResult = z.union([z.object({ cid: ConvId, id: Ulid, clientId: z.string().min(1).max(200), stage: z.literal("pending") }), Hold]);
+export const ConvSyncParams = z.strictObject({ key: Key, after: Seq.optional(), waitMs: z.number().int().min(0).max(25_000).optional(), limit: Limit });
+export const ConvSyncResult = z.object({ events: z.array(ConvStreamEvent).max(50), pos: Seq });
+export const ConvCreateParams = z.strictObject({ kind: z.enum(["dm", "group", "channel"]), participants: z.array(Seat).min(1).max(LIMITS.convParticipants), visibility: Visibility.optional(), history: HistoryPolicy, retainDays: z.number().int().min(1).max(LIMITS.retainDaysMax), meta: ConvMeta.optional() })
+    .refine((p) => p.kind !== "dm" || p.participants.length === 2, "a dm has exactly two participants")
+    .refine((p) => p.kind !== "group" || (p.participants.length >= 3 && p.participants.length <= LIMITS.groupParticipants), "a group has 3 to 50 participants")
+    .refine((p) => p.kind === "channel" || p.visibility === undefined, "only a channel has visibility");
+export const ConvSeatParams = z.strictObject({ ...Cid, p: ParticipantId, device: MachineId.optional(), respondTo: RespondTo.optional() })
+    .refine((p) => p.p.includes("/"), "a seat names an agent");
+export const PeopleGetParams = z.strictObject({ people: z.array(PersonId).min(1).max(100).refine((p) => new Set(p).size === p.length, "each person once") });
+export const PeopleGetResult = z.object({ people: z.array(PersonSummary).max(100), missing: z.array(PersonId).max(100) });
+/** Socket tiers are declared alongside this table below. */
+export const CONVERSATION_METHODS = {
+    "conv.list": Read(ConvListParams, ConvListResult),
+    "conv.get": Read(z.strictObject({ key: Key, ...Cid }), ConvView),
+    "conv.members": Read(PageParams, z.object({ participants: z.array(ParticipantView).max(50), cursor: Cursor })),
+    "conv.read": Read(ConvReadParams, ConvReadResult),
+    "conv.threads": Read(z.strictObject({ ...Cid, filter: z.enum(["all", "unread", "following"]).optional(), ...Page }), EventPage),
+    "conv.send": { params: ConvSendParams, result: ConvSendResult, errors: WriteErrors },
+    "conv.react": Write(z.strictObject({ key: Key, ...Id, reaction: z.string().min(1).max(64), on: z.boolean() })),
+    "conv.edit": Write(z.strictObject({ key: Key, ...Id, text: Text, mentions: z.array(Mention).max(LIMITS.mentions).optional() })),
+    "conv.delete": Write(z.strictObject({ key: Key, ...Id })),
+    "conv.pin": Write(z.strictObject({ ...Id, on: z.boolean() })),
+    "conv.create": { params: ConvCreateParams, result: z.object({ cid: ConvId }), errors: WriteErrors },
+    "conv.add": Write(z.strictObject({ ...Cid, participants: z.array(Seat).min(1).max(LIMITS.convOpParticipants) })),
+    "conv.remove": Write(z.strictObject({ ...Cid, participants: z.array(ParticipantId).min(1).max(LIMITS.convOpParticipants) })),
+    "conv.role": Write(z.strictObject({ ...Cid, p: ParticipantId, role: ConvRole })),
+    "conv.seat": Write(ConvSeatParams),
+    "conv.settings": Write(z.strictObject({ ...Cid, ...OptionalSettings }).refine((p) => Object.values(p).some((v, i) => i > 0 && v !== undefined), "set at least one setting")),
+    "conv.meta": Write(z.strictObject({ ...Cid, meta: ConvMeta })),
+    "conv.archive": Write(z.strictObject({ ...Cid, on: z.boolean() })),
+    "conv.leave": Write(z.strictObject(Cid)),
+    "conv.join": Write(z.strictObject(Cid)),
+    "conv.accept": Write(z.strictObject(Cid)),
+    "conv.catalogue": Read(z.strictObject({ query: z.string().max(200).optional(), limit: Limit }), z.object({ channels: z.array(z.object({ cid: ConvId, name: z.string().max(80), topic: z.string().max(250).optional(), purpose: z.string().max(250).optional(), participants: Count })).max(50) })),
+    "conv.publish": Write(z.strictObject({ ...Cid, on: z.boolean() })),
+    "conv.markRead": Write(z.strictObject({ ...Cid, upTo: Seq, thread: Ulid.optional() })),
+    "conv.markUnread": Write(z.strictObject({ ...Cid, from: z.number().int().positive().safe() })),
+    "conv.prefs": Write(z.strictObject({ ...Cid, notify: z.enum(["all", "mentions", "none"]), muteUntil: Millis.optional(), receipts: z.boolean().optional(), typing: z.boolean().optional() })),
+    "conv.follow": Write(z.strictObject({ ...Cid, thread: Ulid, on: z.boolean() })),
+    "conv.save": Write(z.strictObject({ ...Id, on: z.boolean() })),
+    "conv.saved": Read(PageParams, EventPage),
+    "conv.draft": Write(z.strictObject({ ...Cid, thread: Ulid.optional(), text: z.string().max(8000) })),
+    "conv.schedule": { params: z.strictObject({ ...Cid, ...LineFields, at: Millis, clientId: z.string().min(1).max(200) }), result: z.object({ id: Ulid }), errors: WriteErrors },
+    "conv.scheduled": Read(z.strictObject(Page), z.object({ items: z.array(z.object({ id: Ulid, cid: ConvId, at: Millis, text: Text })).max(50), cursor: Cursor })),
+    "conv.unschedule": Write(z.strictObject({ id: Ulid })),
+    "conv.typing": Write(z.strictObject({ ...Cid, thread: Ulid.optional() })),
+    "conv.search": Read(z.strictObject({ key: Key, query: z.string().min(1).max(200), cid: ConvId.optional(), from: ParticipantId.optional(), after: Millis.optional(), before: Millis.optional(), thread: Ulid.optional(), has: z.enum(["file", "link"]).optional(), ...Page }), z.union([EventPage, Hold])),
+    "conv.context": Read(z.strictObject({ key: Key, ...Cid, event: Ulid, before: z.number().int().min(0).max(20).optional(), after: z.number().int().min(0).max(20).optional() }), z.union([z.object({ events: z.array(EventView).max(41), root: EventView.optional() }), Hold])),
+    "conv.access": Read(z.strictObject({ key: SessionKey, cid: ConvId.optional(), ...Page }), z.object({ conversations: z.array(z.object({ conv: ConvView, reason: z.enum(["seat", "allow", "ask"]), lookbackDays: z.number().int().positive().max(LIMITS.retainDaysMax), indexedFrom: Millis.optional(), complete: z.boolean() })).max(50), cursor: Cursor })),
+    "context.get": Read(Empty, z.object({ rules: ContextRules, defaults: ContextRules, effective: z.array(z.object({ agent: SessionName, cid: ConvId, access: ContextAccess })).max(500) })),
+    "context.set": Write(z.strictObject({ rules: ContextRules })),
+    "context.set.preview": Read(z.strictObject({ rules: ContextRules }), z.object({ changes: z.array(z.object({ agent: SessionName, cid: ConvId, from: ContextAccess, to: ContextAccess })).max(500) })),
+    "conv.policy": Write(z.strictObject({ ...Cid, agentContext: AgentContext })),
+    "conv.localRetention": Write(z.strictObject({ ...Cid, days: z.number().int().min(1).max(LIMITS.retainDaysMax) })),
+    "conv.backfill": { params: z.strictObject(Cid), result: z.object({ indexedFrom: Millis.optional(), complete: z.boolean() }), errors: WriteErrors },
+    "file.get": Read(z.strictObject({ ...Cid, blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/), offset: Count.optional(), limit: z.number().int().min(1).max(512 * 1024).optional() }), z.object({ data: z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/).max(699_052), offset: Count, more: z.boolean(), mime: z.string().max(100), name: z.string().max(255) })),
+    "session.activity": Write(z.strictObject({ key: SessionKey, body: ActivityBody })),
+    "turn.cancel": Write(z.strictObject({ device: MachineId, session: SessionName, turn: Ulid.optional() })),
+    "conv.sync": Read(ConvSyncParams, ConvSyncResult),
+    "people.get": Read(PeopleGetParams, PeopleGetResult),
+    "sessions.list": Read(Empty, z.object({ sessions: z.array(z.object({ agent: SessionName, state: z.enum(["idle", "busy", "kept"]), seats: z.array(ConvId) })) })),
+    "request.waiting": Read(z.strictObject(Page), z.object({ items: z.array(WaitingOnThemView).max(50), cursor: Cursor })),
+};
+/** Staged contracts have no live handler or socket tier until their owning lane ships. */
+export const STAGED_CONVERSATION_METHODS = [
+    "conv.catalogue", "conv.publish", "conv.markRead", "conv.markUnread", "conv.prefs", "conv.follow",
+    "conv.save", "conv.saved", "conv.draft", "conv.schedule", "conv.scheduled", "conv.unschedule", "conv.typing",
+    "context.get", "context.set", "context.set.preview", "conv.localRetention", "file.get", "session.activity", "turn.cancel",
+];
+export const LIVE_CONVERSATION_METHODS = Object.fromEntries(Object.entries(CONVERSATION_METHODS)
+    .filter(([name]) => !STAGED_CONVERSATION_METHODS.includes(name)));
+/** agent means both sockets, human means admin socket only. session.activity is runtime-only, not a model tool. */
+export const CONVERSATION_TIERS = {
+    "conv.list": "agent", "conv.get": "human", "conv.members": "human", "conv.read": "agent", "conv.threads": "human", "conv.send": "agent",
+    "conv.react": "agent", "conv.edit": "agent", "conv.delete": "agent", "conv.pin": "human", "conv.create": "human", "conv.add": "human",
+    "conv.remove": "human", "conv.role": "human", "conv.seat": "human", "conv.settings": "human", "conv.meta": "human", "conv.archive": "human",
+    "conv.leave": "human", "conv.join": "human", "conv.accept": "human", "conv.catalogue": "human", "conv.publish": "human", "conv.markRead": "human",
+    "conv.markUnread": "human", "conv.prefs": "human", "conv.follow": "human", "conv.save": "human", "conv.saved": "human", "conv.draft": "human",
+    "conv.schedule": "human", "conv.scheduled": "human", "conv.unschedule": "human", "conv.typing": "human", "conv.search": "agent", "conv.context": "agent",
+    "conv.access": "agent", "context.get": "human", "context.set": "human", "context.set.preview": "human", "conv.policy": "human", "conv.localRetention": "human",
+    "conv.backfill": "human", "file.get": "human", "session.activity": "agent", "turn.cancel": "human", "conv.sync": "agent", "people.get": "human", "request.waiting": "human", "sessions.list": "human",
+};

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

@@ -67,6 +67,8 @@ export const DeviceListEntry = z.object({
     via: z.enum(["host", "browser"]).optional(),
     current: z.boolean(),
     self: z.boolean(),
+    /** This local Jelly host has no attached person window. Unknown remote presence is omitted. */
+    away: z.literal(true).optional(),
     since: Millis.optional(),
     /** For a removed device of a directory realm: when, why and by which device. */
     unbound: z.object({ at: Millis, reason: UnbindReason, by: MachineId }).optional(),