@joe-broadhead/messaging 0.7.0 → 0.8.0

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

@@ -1,10 +1,15 @@
 // Wire contracts (frozen; change only with a spec update and new test vectors).
 export * from "./schema/index.js";
+export * from "./conversation-agent-tools.js";
 // Protocol logic; see docs/spec/messaging-v1.md §9.
 export { b64u } from "./b64u.js";
 export { VERSION } from "./version.js";
 export { canonicalize } from "./jcs.js";
 export { parseWire } from "./wire.js";
+export * from "./conversation/requests.js";
+export * from "./conversation/request-log.js";
+export * from "./conversation/request-seal.js";
+export * from "./conversation/guest-invitation.js";
 export { sha256 } from "./hash.js";
 export { ulid } from "./ulid.js";
 export { Identity, IdentityFile, generateIdentity, exportIdentity, importIdentity } from "./identity.js";
@@ -37,8 +42,17 @@ export { canTransition, isTerminal, isInterrupted } from "./task.js";
 export { TERMINAL_STATES } from "./schema/a2a.js";
 export { cleanPeerText, createFence, terminalSafe, displayWidth, HOST_TAGS, PEER_FENCE_TAG, PEER_DATA_NOTICE, provenanceOf } from "./peer-text.js";
 // The agent tool contract shared by the OpenCode plugin and messaging-mcp (spec §11, "Agent tools").
-export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, conversationOf, decodeToolCursor, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, } from "./agent-tools.js";
+export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, STORE_REFUSED_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, } from "./agent-tools.js";
 // The agent tools' operations and presenters, shared by the plugin and messaging-mcp (spec §11).
 export { Operations, } from "./agent/operations.js";
-export { agentCan, consentOf, conversationOfPeer, followUpRead, isoOf, presentAgent, presentConvEntry, presentInboxItem, presentLine, presentMail, presentSent, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
+export { agentCan, consentOf, followUpRead, isoOf, presentAgent, presentInboxItem, presentTaskEnvelope, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
 export { chainPath, compact, delegated, delegationPrompt, EXPECT_TEXT, isSafeId, messageAttributes, validatedAddress, } from "./agent/text.js";
+// Conversations (spec §16): ids, events and the log's hash chain, sender keys and sealing, the log as a pure
+// reducer, and context-rule resolution. Fixed-randomness sealing for vectors lives in `@messaging/core/testing`.
+export { dmConvId, selfConvId, participantOf, participantPerson, participantAgent } from "./conversation/ids.js";
+export { admitConvEvent, convEntryHash, convEventDigest, convEventHeader, convEventSigned, convGenesisHash, convLinkHash, signConvEvent, verifyConvEvent, } from "./conversation/event.js";
+export { chainStep, ReceiverChains, ReceiverChainsState, SenderChain, SenderChainState } from "./conversation/ratchet.js";
+export { openConvMeta, openConvMsg, openConvState, openKeyShares, sealConvMeta, sealConvMsg, sealConvState, sealKeyShare, } from "./conversation/seal.js";
+export { ConvLog, } from "./conversation/log.js";
+export { checkVia, currentLinks, linkReader } from "./conversation/link.js";
+export { CONTEXT_DEFAULTS, contextKindOf, matchContextRule, resolveContext, seatReads, } from "./conversation/context.js";

package/dist/lib/modules/core/jelly-host.js

@@ -22,7 +22,7 @@ export const SESSION_TICKET_MAX_S = 7 * 24 * 60 * 60;
 /** The clock skew allowed on `iat` and `exp`. */
 export const JELLY_HOST_SKEW_S = 5;
 /** `chat`: the person's own lines and read state. */
-const CHAT_METHODS = ["person.send", "conv.markRead", "notice.ack"];
+const CHAT_METHODS = ["conv.send", "conv.edit", "conv.delete", "conv.react", "notice.ack"];
 /**
  * `view`: the read-only methods a Jelly section reads with (`section.rpc`): the read-only human-tier methods, and
  * `device.list`, the one admin-tier read a section shows. A preview is not one of them: it takes its action's class
@@ -32,13 +32,13 @@ const CHAT_METHODS = ["person.send", "conv.markRead", "notice.ack"];
 const VIEW_METHODS = [
     "conv.list",
     "conv.read",
-    "conv.subscribe",
+    "conv.sync", "conv.get", "conv.members", "conv.threads", "conv.search", "conv.context", "conv.access",
+    "request.waiting",
     "people.search",
     "people.get",
     "grant.list",
     "request.list",
-    "agents.list",
-    "agents.read",
+    "sessions.list",
     "notice.subscribe",
     "notice.list",
     "device.list",
@@ -46,7 +46,7 @@ const VIEW_METHODS = [
 const classOf = (method) => CHAT_METHODS.includes(method) ? "chat" : VIEW_METHODS.includes(method) ? "view" : "local";
 /**
  * The class a method grant must name in `cls` for each human- and admin-tier method (spec §8.11): `chat` for
- * `person.send`, `conv.markRead` and `notice.ack`, `view` for the read-only human-tier methods, `local` for every
+ * line mutations and `notice.ack`, `view` for the read-only human-tier methods, `local` for every
  * other. A plugin's `jelly` declaration gives each action and read the same class; a test there checks one against
  * the other.
  */

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

@@ -42,6 +42,24 @@ export const DOMAIN = {
     epoch: "messaging/1/epoch\n",
     /** Hosted realms (spec §15.6): an epoch-key rotation, signed by the old key and by the new over JCS(rotation without sigs). */
     dirKey: "messaging/1/dir-key\n",
+    /** Conversations (spec §16.4): a conversation event, signed by `by.device` over JCS(event without sig). */
+    convEvent: "messaging/1/conv-event\n",
+    /** Conversations (spec §16.4): the prefix of a conversation log's genesis hash h(0), over JCS(cid). */
+    convGenesis: "messaging/1/conv-genesis\n",
+    /** Conversations (spec §16.1): the prefix of the hash that derives a dm's id, over JCS of its two sorted participants. */
+    dm: "messaging/1/dm\n",
+    /** Conversations (spec §16.1): the prefix of the hash that derives a person's `self` conversation id, over JCS(person). */
+    self: "messaging/1/self\n",
+    /** Conversations (spec §16.5): HKDF `info` for a sender chain's message key. */
+    convMsg: "messaging/1/conv-msg",
+    /** Conversations (spec §16.5): HKDF `info` for a sender chain's next chain key. */
+    convChain: "messaging/1/conv-chain",
+    request: "messaging/1/contact-request\n",
+    requestContent: "messaging/1/contact-request-content\n",
+    requestDigest: "messaging/1/contact-request-digest\n",
+    requestDecision: "messaging/1/contact-request-decision\n",
+    contactAuthorization: "messaging/1/contact-authorization\n",
+    guestInvitation: "messaging/1/guest-invitation\n",
 };
 /** A2A extension and binding URIs owned by Messaging. */
 export const URI = {
@@ -69,8 +87,6 @@ export const HostedPersonId = z.string().regex(/^p_[a-z2-7]{26}$/, "hosted perso
 export const PersonId = z.union([PersonName, HostedPersonId]);
 /** A channel's name (spec §6.8). Unique among the channels one machine holds, not across the team. */
 export const ChannelName = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, "lowercase channel name");
-/** A chat room (spec §6.8): `dm:<person>` for a direct human message, `channel:<name>` for a channel. */
-export const RoomRef = z.string().regex(/^(?:dm:(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})|channel:[a-z][a-z0-9-]{0,31})$/, "dm:<person> or channel:<name>");
 export const SessionName = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "lowercase session name");
 export const MachineLabel = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/, "lowercase machine label");
 export const TeamName = z.string().min(1).max(64);
@@ -78,7 +94,7 @@ export const TeamName = z.string().min(1).max(64);
 export const AgentKind = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "lowercase agent kind");
 /**
  * The agent kind of the human `messaging` command line (spec §8.2, §8.3): never kept or expired on
- * disconnect, refused as a task executor, and the only sender of group addresses.
+ * disconnect and refused as a task executor. No sender can use group addresses.
  */
 export const CLI_AGENT = "cli";
 /** Milliseconds since the Unix epoch. */
@@ -122,6 +138,8 @@ export const LIMITS = {
     plaintextBytes: 262_144,
     /** Max characters in a single text part. */
     textPartChars: 65_536,
+    /** Existing model-visible per-part cap, shared with fenced conversation events. */
+    toolTextChars: 32_768,
     /** Max parts in one message. */
     partsPerMessage: 16,
     /** Default and max envelope TTL, and the max invite lifetime (`expires − ts`). */
@@ -232,6 +250,70 @@ export const LIMITS = {
     a2hPerHour: 30,
     /** Max lines one person's agents send to another person in a day, summed over the agents (spec §6.9, "Pacing"). */
     a2hPerDay: 100,
+    /** Conversations (spec §16): max participants (persons and agents) of a channel. */
+    convParticipants: 1000,
+    /** Max participants (persons and agents) of a group. A group has at least 3. */
+    groupParticipants: 50,
+    /** Max participants one `add` or `remove` op names. */
+    convOpParticipants: 100,
+    /** Max UTF-8 bytes of one conversation event (JCS), signature and body included. */
+    convEventBytes: 262_144,
+    /** Max UTF-8 bytes of one message body's plaintext (JCS) before it is sealed. */
+    convPlaintextBytes: 65_536,
+    /** Max UTF-16 code units of one conversation line's text. */
+    lineChars: 40_000,
+    /** Max mentions in one line or edit. */
+    mentions: 50,
+    /** Max attachments in one line. */
+    files: 10,
+    /** Max delegation grants one line carries for the agents it mentions (spec §16.3). */
+    agentMentions: 5,
+    /** Max bytes of one attached file, encrypted. */
+    blobBytes: 26_214_400,
+    /** Max distinct reaction keys on one event. */
+    reactionsPerEvent: 50,
+    /** Max pinned events in one conversation. */
+    pins: 100,
+    /** Retention of a conversation that sets none, in days. */
+    retainDaysDefault: 90,
+    /** Max `retainDays` of a conversation, and max lookback of a context rule. */
+    retainDaysMax: 365,
+    /** Max message keys a receiver keeps for one sender chain to open messages that arrive out of order. */
+    skippedKeys: 1000,
+    /** A sender starts a new chain after this many messages on one chain... */
+    chainMessages: 500,
+    /** ...or this long after it started the chain, whichever comes first. */
+    chainMaxMs: 7 * 24 * 60 * 60 * 1000,
+    /** An epoch older than this may be ended by a `rekey` with cause `schedule`. */
+    rekeyScheduleMs: 30 * 24 * 60 * 60 * 1000,
+    /** Max chain keys in one sealed key share, and in one `keys` sync of the `self` conversation. */
+    keyShares: 512,
+    /** Max agents one event's `wake` hint names. */
+    wakeHints: 5,
+    /** Max context rules a person holds (spec §16.8). */
+    contextRules: 500,
+    /** Relay (spec §7, "Conversation frames"): appends one device makes to one conversation, a burst of this many... */
+    convAppendBurst: 20,
+    /** ...refilled at this many a minute. */
+    convAppendsPerMinute: 60,
+    /** Appends to one conversation from all its devices, a minute (burst and refill). */
+    convAppendsPerConvPerMinute: 600,
+    /** `rekey` ops with a cause the log cannot prove (`device`, `schedule`) per device per conversation, an hour. */
+    convRekeysPerHour: 4,
+    /** Conversations one device takes part in, through its person (create, add and join refuse past it). */
+    convsPerDevice: 5000,
+    /** Conversations one device creates, an hour (burst and refill). */
+    convCreatesPerHour: 60,
+    /** Key-share events in one `conv.share` frame. */
+    convSharesPerFrame: 100,
+    /** Key shares one sender device holds at the relay for one recipient device in one conversation. */
+    convSharesPerPair: 256,
+    /** Key shares one device sends to one conversation, a burst of this many, refilled per minute. */
+    convSharesPerMinute: 10_000,
+    /** Entries (and shares) in one `conv.entries` reply. */
+    convFetchEntries: 500,
+    /** Conversations named in one `conv.head`, and heads in one `conv.heads` reply. */
+    convHeads: 500,
 };
 const LOOPBACK_HOST = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/;
 /**

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

@@ -6,14 +6,15 @@
 import { z } from "../../vendor/zod/index.js";
 import { Base64Url, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
 import { RealmId } from "./realm.js";
+import { ConvId } from "./conversation.js";
 /** H2H lines from the subject: `muted` delivers with no notification and no unread mark; `blocked` refuses every class from them. */
 export const ChatLevel = z.enum(["open", "muted", "blocked"]);
 /** Lines from the subject's agents to the person (A2H). */
 export const AgentMailLevel = z.enum(["open", "blocked"]);
 /** Mail and tasks from the subject or their agents to the person's agents: `request` holds each one for the person to answer. */
 export const AskLevel = z.enum(["open", "request", "no"]);
-/** Whom a grant is about: one person, or every member of one channel (by its id). */
-export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ channel: Ulid })]);
+/** Whom a grant is about: one person, or the verified participants of one conversation. */
+export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId })]);
 /**
  * A grant, signed by `by`, a device of `person`: `sig = Ed25519(by, "messaging/1/grant\n" || JCS(grant without sig))`.
  * Every level is optional: an absent level is the default for the relation (spec §6.9, "Effective policy"), and a
@@ -54,8 +55,8 @@ export const GrantSync = z.strictObject({ grants: z.array(z.record(z.string(), z
 /** The rules of a grant that its schema alone cannot say. */
 export function grantProblem(grant) {
     const own = "person" in grant.subject && grant.subject.person === grant.person;
-    if ("channel" in grant.subject && (grant.chat !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)) {
-        return "a channel grant sets only ask and agentMail";
+    if ("conv" in grant.subject && (grant.chat !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)) {
+        return "a conversation grant sets only ask and agentMail";
     }
     if (own && (grant.chat !== undefined || grant.agentMail !== undefined || grant.ask !== undefined || grant.trustedUntil !== undefined)) {
         return "a grant about its own person sets only discoverable";

package/dist/lib/modules/core/schema/contact-request.js

@@ -0,0 +1,22 @@
+/** Portable same-realm contact requests (spec §16.11). All proofs are strict and domain-separated. */
+import { z } from "../../vendor/zod/index.js";
+import { Hash, Key32, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
+import { RealmId } from "./realm.js";
+const Dm = z.string().regex(/^d_[a-z2-7]{26}$/);
+const Sig = z.string().regex(/^[A-Za-z0-9_-]{86}$/);
+const Req = z.string().min(1).max(64);
+const route = { v: z.literal(PROTOCOL), realm: RealmId, cid: Dm, from: PersonId, to: PersonId };
+export const RequestDescriptor = z.strictObject({ ...route, id: Ulid, issuedAt: Millis, expiresAt: Millis, commitment: Hash, by: MachineId, sig: Sig });
+export const RequestOpening = z.strictObject({ salt: Key32, text: z.string().min(1).max(LIMITS.requestChars) });
+export const PortableRequest = z.strictObject({ descriptor: RequestDescriptor, opening: RequestOpening });
+/** A block is conveyed as decline. The first valid terminal answer is sequenced in the recipient mailbox. */
+export const RequestDecision = z.strictObject({ ...route, id: Ulid, descriptor: Hash, answer: z.enum(["accept", "decline"]), at: Millis, by: MachineId, sig: Sig });
+export const RequestActivation = z.strictObject({ descriptor: RequestDescriptor, decision: RequestDecision });
+/** Existing contacts authorize the exact human DM on both sides, under their current local grants. */
+export const ContactAuthorization = z.strictObject({ ...route, at: Millis, by: MachineId, sig: Sig });
+export const ActivationProof = z.union([RequestActivation, z.strictObject({ contacts: z.tuple([ContactAuthorization, ContactAuthorization]) })]);
+export const RequestImport = z.strictObject({ t: z.literal("request.import"), ...RequestActivation.shape, opening: RequestOpening });
+/** No opening or request text is sent to the relay. */
+export const RequestSettleFrame = z.strictObject({ t: z.literal("request.settle"), req: Req, ...RequestActivation.shape });
+export const RequestStateFrame = z.strictObject({ t: z.literal("request.state"), req: Req, descriptor: RequestDescriptor });
+export const RequestSettledFrame = z.strictObject({ t: z.literal("request.settled"), req: Req, id: Ulid, decision: RequestDecision.optional() });

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

@@ -0,0 +1,94 @@
+/**
+ * Conversation frames (spec §7, "Conversation frames"; spec §16): the frames a relay speaks after `hello` to carry
+ * conversation logs, in a roster realm and in a directory realm alike. They follow the frame rules of §7: one JSON
+ * object per text frame, discriminated by `t`; requests carry `req`, replies echo it, and a refusal is the relay
+ * binding's `nack {id: req, code, message}` (with `retryAfterMs` for `rate_limited`). Every frame is strict.
+ *
+ *   conv.append {req, event}                     → conv.ok {req, cid, seq, hash}        an op or a msg, sequenced
+ *   conv.share {req, events}                     → conv.shared {req, cid, count}        key shares, one recipient each
+ *   conv.fetch {req, cid, after, limit?, sharesAfter?} → conv.entries {req, cid, head, entries, shares, more}
+ *   conv.head {req, cids? | after?}              → conv.heads {req, heads, more}
+ *   conv.caps {req, persons}                     → conv.capabilities {req, outdated}   who cannot read conversations yet
+ *   relay → conv.push {cid, entry} | {cid, share}   a new entry to the members' online devices; a share to its recipient
+ *
+ * The relay sequences and filters; members verify everything (spec §16.4, §16.7). It never signs an entry.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { LIMITS, PersonId } from "./common.js";
+import { ConvEvent, ConvHead, ConvId, ConvKeysEvent, ConvLogEntry, ConvServedEntry, ConvShareEntry } from "./conversation.js";
+const Req = z.string().min(1).max(64);
+const Count = z.number().int().min(0);
+// ---- client → relay ----
+/** Appends an op or a msg to its conversation (`event.cid`). The relay answers `conv.ok` once the entry is stored. */
+export const ConvAppendFrame = z.strictObject({ t: z.literal("conv.append"), req: Req, event: ConvEvent });
+/**
+ * Stores key shares (spec §16.6): each event to one recipient device, all of one conversation and by the sending
+ * device. All or none are stored; the relay answers `conv.shared` once they are.
+ */
+export const ConvShareFrame = z.strictObject({
+    t: z.literal("conv.share"),
+    req: Req,
+    events: z.array(ConvKeysEvent).min(1).max(LIMITS.convSharesPerFrame),
+});
+/**
+ * The entries of `cid` after `after`, in seq order, at most `limit` (and `LIMITS.convFetchEntries`) and as many as
+ * fit in a frame. `sharesAfter`: also the shares to this device after that `n`; absent, no shares.
+ */
+export const ConvFetchFrame = z.strictObject({
+    t: z.literal("conv.fetch"),
+    req: Req,
+    cid: ConvId,
+    after: Count,
+    limit: z.number().int().min(1).max(LIMITS.convFetchEntries).optional(),
+    sharesAfter: Count.optional(),
+});
+/**
+ * The heads of the named conversations, or, without `cids`, of every conversation this device's person takes part in,
+ * by cid after `after`, at most `LIMITS.convHeads`.
+ */
+export const ConvHeadFrame = z
+    .strictObject({
+    t: z.literal("conv.head"),
+    req: Req,
+    cids: z.array(ConvId).min(1).max(LIMITS.convHeads).optional(),
+    after: ConvId.optional(),
+})
+    .refine((f) => f.cids === undefined || f.after === undefined, { message: "cids or after, not both" });
+/**
+ * Which of these persons cannot read conversations yet: every current device of theirs whose latest presence the
+ * relay holds names no `conversations` feature (a daemon before the cut-over). A person with no such presence is not
+ * named. A hint from the relay: it can only make a sender refuse, never admit anything.
+ */
+export const ConvCapsFrame = z.strictObject({ t: z.literal("conv.caps"), req: Req, persons: z.array(PersonId).min(1).max(LIMITS.convOpParticipants) });
+// ---- relay → client ----
+/** `conv.append` stored: the entry's seq and h(seq), which the author recomputes. */
+export const ConvOkFrame = z.strictObject({ t: z.literal("conv.ok"), req: Req, cid: ConvId, seq: z.number().int().min(1), hash: ConvHead.shape.hash });
+/** `conv.share` stored: how many shares. */
+export const ConvSharedFrame = z.strictObject({ t: z.literal("conv.shared"), req: Req, cid: ConvId, count: z.number().int().min(1).max(LIMITS.convSharesPerFrame) });
+/**
+ * `conv.fetch`'s answer: the relay's head, the entries (an expired `msg` as its digest, `ConvExpiredEntry`) and this
+ * device's shares. `more`: ask again after the last entry (and the last share).
+ */
+export const ConvEntriesFrame = z.strictObject({
+    t: z.literal("conv.entries"),
+    req: Req,
+    cid: ConvId,
+    head: ConvHead,
+    entries: z.array(ConvServedEntry).max(LIMITS.convFetchEntries),
+    shares: z.array(ConvShareEntry).max(LIMITS.convFetchEntries),
+    more: z.boolean(),
+});
+/** One conversation's position at the relay: its head, its op head, and the last share `n` for this device (0: none). */
+export const ConvHeadView = z.strictObject({ cid: ConvId, head: ConvHead, opHead: ConvHead, shares: Count });
+/** `conv.head`'s answer. A named conversation this device's person is not in is left out, as one that does not exist. */
+export const ConvHeadsFrame = z.strictObject({ t: z.literal("conv.heads"), req: Req, heads: z.array(ConvHeadView).max(LIMITS.convHeads), more: z.boolean() });
+/** `conv.caps`'s answer: the named persons that cannot read conversations yet. */
+export const ConvCapabilitiesFrame = z.strictObject({ t: z.literal("conv.capabilities"), req: Req, outdated: z.array(PersonId).max(LIMITS.convOpParticipants) });
+/** A new entry, to the online devices of the conversation's participant persons; or a new share, to its recipient. */
+export const ConvPushFrame = z.union([
+    z.strictObject({ t: z.literal("conv.push"), cid: ConvId, entry: ConvLogEntry }),
+    z.strictObject({ t: z.literal("conv.push"), cid: ConvId, share: ConvShareEntry }),
+]);
+/** The conversation frames' types, for the relay's dispatch and `/metrics`. */
+export const CONV_FRAMES = ["conv.append", "conv.share", "conv.fetch", "conv.head", "conv.caps"];
+export const CONV_REPLIES = ["conv.ok", "conv.shared", "conv.entries", "conv.heads", "conv.capabilities", "conv.push"];