@joe-broadhead/messaging 0.8.0 → 0.9.0

package/dist/lib/modules/core/agent/present.js

@@ -2,6 +2,7 @@ import { taskStateName } from "../agent-tools.js";
 import { MessagingError } from "../schema/errors.js";
 import { createFence, PEER_FENCE_TAG, provenanceOf } from "../peer-text.js";
 import { LIMITS } from "../schema/common.js";
+import { TASK_REFUSAL_CHARS, TASK_SIGN_IN_TOOL_CHARS } from "../schema/ipc.js";
 import { chainPath, EXPECT_TEXT, isSafeId, messageAttributes } from "./text.js";
 /** Per-part cap in tool outputs; the protocol caps a text part at 65,536 chars. */
 const PART_CHARS = LIMITS.toolTextChars;
@@ -171,6 +172,10 @@ export function presentTask(framer, record, consent) {
         state: taskStateName(record.task.status.state),
         ...(title !== undefined ? { title: shown(framer, titleAuthor, peerAttributes(record))(title, TITLE_CHARS), titleAuthor } : {}),
         ...(status !== undefined ? { status: shown(framer, statusAuthor, peerAttributes(record))(status, PART_CHARS), statusAuthor } : {}),
+        ...(record.signIn !== undefined
+            ? { signIn: { ...(record.signIn.tool !== undefined ? { tool: shown(framer, statusAuthor, peerAttributes(record))(record.signIn.tool, TASK_SIGN_IN_TOOL_CHARS) } : {}), by: record.signIn.by } }
+            : {}),
+        ...(record.refusal !== undefined ? { refusal: { reason: shown(framer, statusAuthor, peerAttributes(record))(record.refusal.reason, TASK_REFUSAL_CHARS) } } : {}),
         updatedAt: isoOf(record.updatedAt),
         ...(consent !== undefined && record.role === "executor" ? { consent } : {}),
         ...(record.chain !== undefined ? { chain: presentChain(framer, record.chain) } : {}),

package/dist/lib/modules/core/agent-tools.js

@@ -122,6 +122,7 @@ export const TOOL_REMEDIES = {
     login_denied: "tell your person: the sign-in at Jelly ID was denied.",
     log_conflict: "try again: their devices changed at the same time.",
     conv_conflict: "try again: the conversation changed at the same time.",
+    conflict: "tell your person: their settings changed at the same time; they choose again.",
     stale_epoch: "try again: the conversation's keys changed at the same time.",
     device_limit: "ask your person to remove one of their devices first.",
     admission_required: "ask your person to open Messaging in Jelly once: this device is not bound to their Jelly account yet.",
@@ -286,6 +287,17 @@ const Task = z.object({
     titleAuthor: Author.optional().describe("With title: who wrote the request; ours when you asked (mine)"),
     status: authored("The latest status message").optional(),
     statusAuthor: Author.optional().describe("With status: who wrote it; ours when you run the task (asked)"),
+    signIn: z
+        .object({
+        tool: authored("The tool the executor named").optional(),
+        by: z.enum(["you", "them"]).describe("Whose sign-in it is: you (your person, for an agent of theirs) or them (the other person); your Messaging daemon decides, never the peer"),
+    })
+        .optional()
+        .describe("auth_required only: the task waits on a sign-in; the tool was written by the executor, as statusAuthor says"),
+    refusal: z
+        .object({ reason: authored("The executor's reason") })
+        .optional()
+        .describe("rejected only: why the executor declined, in its words, as statusAuthor says"),
     createdAt: iso,
     updatedAt: iso,
     consent: ToolConsentSchema.optional(),

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

@@ -63,7 +63,19 @@ export function verifyConsentGrant(raw, ctx) {
 }
 /** The key one grant is stored under: its subject. One grant per subject. */
 export function grantSubjectKey(subject) {
-    return "person" in subject ? `person:${subject.person}` : `conv:${subject.conv}`;
+    return "person" in subject ? `person:${subject.person}` : "conv" in subject ? `conv:${subject.conv}` : `relation:${subject.relation}`;
+}
+/** The choices a person's two relation grants make; a grant absent (or not current) leaves its choice unset. */
+export function reachChoices(outside, org) {
+    const message = outside === undefined ? undefined : outside.chat === "open" ? "open" : outside.chat === "blocked" ? "never" : "ask";
+    const ask = org?.ask === "open" ? "open" : org?.ask === "request" ? "ask" : org?.ask === "no" ? "never" : undefined;
+    return { ...(message ? { message } : {}), ...(ask ? { ask } : {}) };
+}
+/** The relation grant subject and levels that record one choice: the inverse of `reachChoices`. */
+export function reachGrant(group, value) {
+    if (group === "message")
+        return { subject: { relation: "outside" }, levels: value === "open" ? { chat: "open" } : value === "never" ? { chat: "blocked" } : {} };
+    return { subject: { relation: "org" }, levels: { ask: value === "open" ? "open" : value === "never" ? "no" : "request" } };
 }
 /**
  * Of two copies of the grant for one subject, the one that counts (spec §6.9, "Merging"): the newer by `ts`, then
@@ -126,12 +138,28 @@ const DEFAULTS = {
 };
 const ASK_RANK = { no: 0, request: 1, open: 2 };
 /**
- * Spec §6.9, "Effective policy": each level is the person grant's when it sets one; otherwise, for `ask` and
- * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's
- * default. An expired `trustedUntil` reads as absent. The caller passes only grants whose signer is current.
+ * The level a relation starts from, under the person's reach choices (spec §6.9, "Reach choices"): `message` sets a
+ * stranger's `chat` (Open `open`, Ask me first `request_required`, Never `blocked`) and a contact's (Never `blocked`,
+ * else `open`: a contact has already been let in); `ask` sets the org's `ask`. Unset, the relation's default.
  */
-export function effectivePolicy(relation, person, channels, now) {
+function baseLevels(relation, reach) {
     const base = DEFAULTS[relation];
+    if (relation === "org")
+        return reach.ask === undefined ? base : { ...base, ask: reach.ask === "open" ? "open" : reach.ask === "never" ? "no" : "request" };
+    if (reach.message === "never")
+        return { ...base, chat: "blocked" };
+    if (relation === "stranger" && reach.message === "open")
+        return { ...base, chat: "open" };
+    return base;
+}
+/**
+ * Spec §6.9, "Effective policy": each level is the person grant's when it sets one; otherwise, for `ask` and
+ * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's level
+ * under the person's reach choices (`baseLevels`). An expired `trustedUntil` reads as absent. The caller passes only
+ * grants whose signer is current.
+ */
+export function effectivePolicy(relation, person, channels, now, reach = {}) {
+    const base = baseLevels(relation, reach);
     const channelAsk = channels.map((grant) => grant.ask).filter((level) => level !== undefined);
     const channelMail = channels.map((grant) => grant.agentMail).filter((level) => level !== undefined);
     const ask = person?.ask ?? (channelAsk.length > 0 ? channelAsk.reduce((a, b) => (ASK_RANK[b] > ASK_RANK[a] ? b : a)) : undefined);
@@ -149,27 +177,35 @@ export function effectivePolicy(relation, person, channels, now) {
  * Spec §6.9, "Enforcement": step 10 of the receiver order (§5), before the inbound policy of §8.3.
  * - The person's own traffic is delivered as `self`.
  * - Answers to the person's own traffic are delivered whatever the grants, so a change never strands a task.
- * - A `blocked` chat level refuses every other class from the sender.
- * - A `stranger` reaches the person only through a level a grant opened; otherwise `request_required`.
+ * - A `blocked` chat level from the person grant refuses every other class from the sender.
+ * - A `blocked` chat level from the reach choice Never refuses the sender's lines, message requests and channel
+ *   changes, `refused`; agent mail and asks follow their own levels, so a grant that opened them still counts.
+ * - A `stranger` reaches the person only through a level a grant or a choice opened; otherwise `request_required`.
  * - Lines follow `chat` (person) or `agentMail` (agent); `muted` delivers silently.
  * - Asks follow `ask`: `open` delivers guarded, or trusted while the person grant trusts the sender and every person
  *   in the delegation chain is the sender or the receiver; `request` holds; `no` refuses, `request_required` when
- *   it is the default of a `contact` or a `stranger`.
- * - A message request from a `stranger` is held for the person to accept; from anyone else it is a DM line.
+ *   it is the default of a `contact` or a `stranger` and the person has not chosen Never for messages.
+ * - A message request is held for the person while `chat` is `request_required` (a `stranger` under Ask me first);
+ *   otherwise it is a DM line.
  */
 export function decide(args) {
     const { inbound } = args;
     if (args.relation === "self" || args.sender === args.self)
         return { action: "deliver", consent: "self" };
-    const policy = effectivePolicy(args.relation, args.grant, args.channels, args.now);
+    const policy = effectivePolicy(args.relation, args.grant, args.channels, args.now, args.reach);
     const trusted = (chain) => policy.trustedUntil !== undefined && chain.every((person) => person === args.sender || person === args.self);
     if (inbound.kind === "answer")
         return { action: "deliver", consent: trusted([args.sender]) ? "trusted" : "guarded" };
-    if (policy.chat === "blocked")
+    const blocked = policy.chat === "blocked";
+    if (blocked && policy.granted.chat)
         return { action: "refuse", code: "refused" };
     const stranger = args.relation === "stranger";
+    // A default refusal invites a message request, unless the person chose Never for messages.
+    const defaultCode = (outside) => (outside && !blocked ? "request_required" : "refused");
     switch (inbound.kind) {
         case "op":
+            if (blocked)
+                return { action: "refuse", code: "refused" };
             if (stranger)
                 return { action: "refuse", code: "request_required" };
             return { action: "deliver", consent: "guarded" };
@@ -177,13 +213,17 @@ export function decide(args) {
             if (inbound.agent) {
                 if (policy.agentMail === "open")
                     return { action: "deliver", consent: "guarded" };
-                return { action: "refuse", code: stranger && !policy.granted.agentMail ? "request_required" : "refused" };
+                return { action: "refuse", code: defaultCode(stranger && !policy.granted.agentMail) };
             }
+            if (blocked)
+                return { action: "refuse", code: "refused" };
             if (policy.chat === "request_required")
                 return { action: "refuse", code: "request_required" };
             return policy.chat === "muted" ? { action: "deliver", consent: "guarded", silent: true } : { action: "deliver", consent: "guarded" };
         case "request":
-            if (stranger)
+            if (blocked)
+                return { action: "refuse", code: "refused" };
+            if (policy.chat === "request_required")
                 return { action: "hold" };
             return policy.chat === "muted" ? { action: "deliver", consent: "guarded", silent: true } : { action: "deliver", consent: "guarded" };
         case "ask":
@@ -191,7 +231,7 @@ export function decide(args) {
                 return { action: "deliver", consent: trusted(inbound.chain) ? "trusted" : "guarded" };
             if (policy.ask === "request")
                 return { action: "hold" };
-            return { action: "refuse", code: !policy.granted.ask && (stranger || args.relation === "contact") ? "request_required" : "refused" };
+            return { action: "refuse", code: defaultCode(!policy.granted.ask && (stranger || args.relation === "contact")) };
     }
 }
 function defined(value) {

package/dist/lib/modules/core/contact-card.js

@@ -61,10 +61,10 @@ export function verifyContactCard(raw, ctx) {
 }
 /**
  * What a card says for a sender of `relation` with the person grant `grant` (spec §6.9, "Contact cards"): the
- * person grant over the relation's defaults. Channel grants are not on a card: the sender knows its own channels.
+ * person grant over the relation's level under the person's reach choices. Channel grants are not on a card: the sender knows its own channels.
  */
-export function cardCan(relation, grant, now) {
-    const policy = effectivePolicy(relation, grant, [], now);
+export function cardCan(relation, grant, now, reach = {}) {
+    const policy = effectivePolicy(relation, grant, [], now, reach);
     return {
         chat: policy.chat === "open" || policy.chat === "muted",
         agentMail: policy.agentMail === "open",

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

@@ -35,7 +35,7 @@ export { MerkleLog, merkleLeafHash, verifyConsistency, verifyInclusion } from ".
 export { MAP_DEPTH, SparseMerkleTree, TOMBSTONE, emptyMapHash, mapKey, mapRootFromProof, mapValue, verifyMapProof } from "./directory/smt.js";
 export { parseAddress, formatAddress } from "./address.js";
 export { decodeAdmitCard, decodeTeamCard, encodeAdmitCard, encodeTeamCard, } from "./cards.js";
-export { decide, effectivePolicy, grantSubjectKey, levelsOf, preferGrant, resignGrant, restrictingLevels, signConsentGrant, verifyConsentGrant, wideningLevels, } from "./consent.js";
+export { decide, effectivePolicy, grantSubjectKey, levelsOf, preferGrant, reachChoices, reachGrant, resignGrant, restrictingLevels, signConsentGrant, verifyConsentGrant, wideningLevels, } from "./consent.js";
 export { cardCan, signContactCard, verifyContactCard } from "./contact-card.js";
 export { createGrant, verifyChain } from "./delegation.js";
 export { canTransition, isTerminal, isInterrupted } from "./task.js";

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

@@ -37,8 +37,11 @@ const VIEW_METHODS = [
     "people.search",
     "people.get",
     "grant.list",
+    "reach.get",
     "request.list",
     "sessions.list",
+    "tasks.list",
+    "tasks.get",
     "notice.subscribe",
     "notice.list",
     "device.list",

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

@@ -66,6 +66,8 @@ export const URI = {
     binding: "urn:messaging:binding:relay:v1",
     provenance: "urn:messaging:ext:provenance:v1",
     presence: "urn:messaging:ext:presence:v1",
+    /** An `AUTH_REQUIRED` status message's `metadata[URI.signIn]`: `{tool}`, the tool whose sign-in the task waits on (spec §6.2). */
+    signIn: "urn:messaging:ext:sign-in:v1",
 };
 export const Base64Url = z.string().regex(/^[A-Za-z0-9_-]*$/, "base64url without padding");
 /** Any 32-byte value in base64url, e.g. a raw public key. */

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

@@ -13,13 +13,20 @@ export const ChatLevel = z.enum(["open", "muted", "blocked"]);
 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 the verified participants of one conversation. */
-export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId })]);
+/**
+ * The relations a reach choice is about (spec §6.9, "Reach choices"): `outside`, the people of other orgs (`contact`
+ * and `stranger`), whose `chat` the person's "Who can message you" sets; `org`, the person's teammates, whose `ask`
+ * their "How agents may ask yours" sets.
+ */
+export const GrantRelation = z.enum(["outside", "org"]);
+/** Whom a grant is about: one person, the verified participants of one conversation, or one relation (a reach choice). */
+export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId }), z.strictObject({ relation: GrantRelation })]);
 /**
  * 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
  * grant with none is a clear. `trustedUntil` needs `ask: "open"` and is at most `ts + LIMITS.trustMaxMs`. A channel
- * grant sets only `ask` and `agentMail`. A grant about the person themself sets only `discoverable`.
+ * grant sets only `ask` and `agentMail`. A grant about the person themself sets only `discoverable`. A relation
+ * grant (a reach choice) sets only `chat` (`open` or `blocked`) for `outside`, and only `ask` for `org`.
  * `resignedAt` marks a grant re-signed by another device of the person (spec §6.9, "Signers"); it keeps `id` and
  * `ts`.
  */
@@ -58,6 +65,16 @@ export function grantProblem(grant) {
     if ("conv" in grant.subject && (grant.chat !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)) {
         return "a conversation grant sets only ask and agentMail";
     }
+    if ("relation" in grant.subject) {
+        if (grant.agentMail !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)
+            return "a relation grant sets only chat or ask";
+        if (grant.subject.relation === "outside" && grant.ask !== undefined)
+            return "the outside relation grant sets only chat";
+        if (grant.subject.relation === "outside" && grant.chat === "muted")
+            return "the outside relation grant sets chat open or blocked";
+        if (grant.subject.relation === "org" && grant.chat !== undefined)
+            return "the org relation grant sets only ask";
+    }
     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/conv-frames.js

@@ -8,7 +8,7 @@
  *   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
+ *   conv.caps {req, persons}                     → conv.capabilities {req, outdated, unknown?}   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.
@@ -82,8 +82,15 @@ export const ConvEntriesFrame = z.strictObject({
 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) });
+/**
+ * `conv.caps`'s answer: the named persons that cannot read conversations yet, and, only when there are any, the
+ * persons it says nothing about (`unknown`: unrelated persons past the asker's daily budget).
+ */
+export const ConvCapabilitiesFrame = z.strictObject({
+    t: z.literal("conv.capabilities"), req: Req,
+    outdated: z.array(PersonId).max(LIMITS.convOpParticipants),
+    unknown: z.array(PersonId).min(1).max(LIMITS.convOpParticipants).optional(),
+});
 /** 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 }),

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/errors.js

@@ -30,6 +30,7 @@ export const ErrorCode = z.enum([
     "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
@@ -39,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

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

@@ -7,6 +7,7 @@ import { LIMITS, MachineId, MachineLabel, Millis, PersonId, SessionAddress, Sess
 import { ConvId, ParticipantId } from "../conversation.js";
 import { AgentMailLevel, AskLevel, CardCan, ChatLevel } from "../consent.js";
 import { Email } from "../directory-frames.js";
+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 = {
@@ -43,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. */
@@ -56,6 +72,7 @@ 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
@@ -79,8 +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 });
+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`
@@ -93,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, 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"`
- * (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 message request's text: 1 to `LIMITS.requestChars` UTF-16 code units. */
 export const RequestText = z
     .string()
@@ -119,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() }),

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

@@ -6,6 +6,7 @@ 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";
+import { ActionToken, PersonTask } from "./shapes.js";
 const Count = z.number().int().nonnegative().safe();
 const Seq = z.number().int().nonnegative().safe();
 const Name = z.string().max(200);
@@ -33,7 +34,11 @@ 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 });
+/**
+ * `cancel`: the source-issued action that stops the task (spec §8.2, "Action tokens"), redeemed with
+ * `task.cancel {taskId, token}`. Only on a task this person's agent asked that has not ended, and only on the human tier.
+ */
+export const TaskView = z.object({ id: Ulid, state: TaskState, cancel: z.strictObject({ name: z.literal("cancel"), token: ActionToken }).optional() });
 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 }),
@@ -75,6 +80,8 @@ export const ConvStreamEvent = z.discriminatedUnion("type", [
     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 }),
+    /** Human tier, person-level `conv.sync` only (no session key): a task of this person's agents changed (spec §12.4). */
+    z.object({ type: z.literal("task"), pos: Seq, task: PersonTask }),
 ]).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

@@ -33,7 +33,11 @@ const OptionalSettings = { visibility: Visibility.optional(), history: HistoryPo
 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"]),
+    /**
+     * `resend`: a request sent before the cut-over and held unanswered; it must be sent again. `outdated`: the recipient
+     * accepted it on a client before conversations, which cannot open the dm; they update, then it is sent again (§8.3).
+     */
+    state: z.enum(["held", "pending-delivery", "resend", "outdated"]),
 });
 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;

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

@@ -52,6 +52,8 @@ export const DeviceChangeView = z.object({
     approver: MachineLabel.optional(),
     at: Millis,
 });
+/** A presence feature name, such as `tasks`, `conversations` or `reach`. */
+export const PresenceFeature = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, "a feature name");
 /** One device of this device's person. */
 export const DeviceListEntry = z.object({
     device: MachineId,
@@ -72,6 +74,11 @@ export const DeviceListEntry = z.object({
     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(),
+    /**
+     * The protocol features the device advertises (spec §8.2, "Devices"): this device's own, or the last verified presence
+     * of another device of the person. Absent when no presence of it has been seen, which is unknown, not none.
+     */
+    features: z.array(PresenceFeature).max(32).optional(),
 });
 /** A link request's text (`messaging-link.…`, spec §15.3): what a new device shows and its person's device reads. */
 const LinkText = z.string().min(1).max(2048);