@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,189 @@
+/**
+ * The IPC methods a Jelly host needs (spec §8.2, §8.11; design §13.6, §13.10-§13.12), served in every deployment:
+ *
+ * - Agent tier: `daemon.health`, a cheap status with no secrets and no counts.
+ * - Human tier: `agents.list` and `agents.read` (the person's view of their own agents' traffic on this device),
+ *   `notice.subscribe`, `notice.list` and `notice.ack` (notices in fixed categories), and the read-only preview
+ *   `device.remove.preview`.
+ *
+ * Spread into `IPC_METHODS`; `HOST_SCOPE_METHODS` (in `ipc.ts`) is what a host-scope action grant allows.
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { MachineId, MachineLabel, Millis, SessionName } from "../common.js";
+import { WAKE_AGENTS, WAKE_TICKET_BYTES, WakeUrl } from "../directory-frames.js";
+import { Jws } from "../jelly.js";
+import { DeviceKind } from "../directory.js";
+import { DeviceChangeView, DeviceRemoveParams } from "./device.js";
+import { ConvCursor, ConvEntry } from "./shapes.js";
+import { ConversationRef } from "./surfaces.js";
+/**
+ * A notice's id, stable per source: `m_<line id>` (a line), `r_<request id>` (a held request), `a_<id>` (an alert).
+ * A replay repeats the same ids, so a host rings once.
+ */
+export const NoticeId = z.string().regex(/^[mra]_[0-9A-Za-z]{1,64}$/, "notice id");
+/** Most characters of a notice's `line`. */
+export const NOTICE_LINE_CHARS = 120;
+/**
+ * An alert about another device of this person (design §2.8): the change, as `DeviceChangeView` gives it, with
+ * `device` the device the person may want to remove (for `replaced`, the successor; `replaces` is the device it
+ * replaced). `current`: whether that device is current now. `remove`: how this device removes it: `token` with a
+ * fresh Jelly token from its host (`device.remove {device, token}`), `sign-in` with a fresh sign-in through the
+ * browser (`device.login {remove: {device}}`), `team` as the roster's admin (`team.remove`); absent when it cannot
+ * (it is not current, or this device was approved by link and removes no device).
+ */
+export const NoticeDevice = DeviceChangeView.extend({
+    replaces: z.object({ device: MachineId, label: MachineLabel }).optional(),
+    current: z.boolean(),
+    remove: z.enum(["token", "sign-in", "team"]).optional(),
+});
+/**
+ * One notice (design §13.11). `message`: a line in a DM or a channel from another person or their agent, or an
+ * agent's line to its own person; `request`: a request held for the person; `alert`: an alarm of this device, a
+ * change of the person's other devices (with `device`), or trust the person gave that ends within 7 days (with `from`).
+ * `line` is the first line of a message, through `cleanPeerText`, only when the caller asked for lines; alerts carry
+ * fixed text. `from.name` and `from.email` are untrusted text in a hosted realm.
+ */
+export const Notice = z.object({
+    id: NoticeId,
+    category: z.enum(["message", "request", "alert"]),
+    conversation: ConversationRef.optional(),
+    from: z.object({ name: z.string().max(200), email: z.string().max(320).optional(), org: z.enum(["same", "other", "none"]) }).optional(),
+    line: z.string().max(NOTICE_LINE_CHARS).optional(),
+    device: NoticeDevice.optional(),
+    at: Millis,
+});
+/** What the person's badges count: unread lines in their conversations, and requests held for them. */
+export const NoticeCounts = z.object({ unread: z.number().int().nonnegative(), requests: z.number().int().nonnegative() });
+/** `daemon.health` (spec §8.2): the daemon's state, with no secrets and no counts. */
+export const DaemonHealth = z.object({
+    state: z.enum(["starting", "running", "stopping"]),
+    relay: z.enum(["connected", "connecting", "offline"]),
+    /** `ok` in a roster realm, and in a directory realm whose directory answers; `alarm` when it contradicted itself. */
+    directory: z.enum(["ok", "unavailable", "alarm"]),
+    alarm: z.enum(["restored", "keys_missing", "directory"]).nullable(),
+    /** True while items wait that no registered session's client has been handed yet. */
+    busy: z.boolean(),
+    version: z.string().max(64),
+    storeSchema: z.number().int().positive(),
+});
+/** One local agent (a registered or kept session) and its traffic on this device. */
+export const AgentSummary = z.object({
+    agent: SessionName,
+    /** Other agents it has mail or tasks with. */
+    conversations: z.number().int().nonnegative(),
+    /** Mail it received and has not read. */
+    unread: z.number().int().nonnegative(),
+    lastAt: Millis.optional(),
+    state: z.enum(["idle", "busy", "kept"]),
+});
+const AgentConversation = z.object({ conversation: ConversationRef, unread: z.number().int().nonnegative(), lastAt: Millis });
+export const JELLY_METHODS = {
+    /**
+     * Agent tier. A cheap status for a host that polls: the daemon's state, the relay, the directory, an alarm, and
+     * whether it is busy. No counts: they are the person's (`notice.list`).
+     */
+    "daemon.health": { params: z.strictObject({}), result: DaemonHealth },
+    /** Human tier. This person's local agents on this device, most recent first. Read-only. */
+    "agents.list": { params: z.strictObject({}), result: z.object({ agents: z.array(AgentSummary) }) },
+    /**
+     * Human tier. One local agent's traffic: without `conversation`, the other agents it has mail or tasks with, most
+     * recent first; with `conversation` (`agent:<person>/<agent>`), a page of its entries, as `conv.read` gives them to
+     * the agent, latest first unless `before` names an entry. Changes no stage and sends no receipt. Peer text is
+     * untrusted: a client cleans it for display.
+     */
+    "agents.read": {
+        params: z.strictObject({
+            agent: SessionName,
+            conversation: ConversationRef.refine((c) => c.startsWith("agent:"), { message: "a conversation with an agent: agent:<person>/<agent>" }).optional(),
+            before: ConvCursor.optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        result: z.discriminatedUnion("kind", [
+            z.object({ kind: z.literal("conversations"), conversations: z.array(AgentConversation) }),
+            z.object({ kind: z.literal("entries"), conversation: ConversationRef, entries: z.array(ConvEntry), more: z.boolean() }),
+        ]),
+    },
+    /**
+     * Human tier; host scope in `deployment: "jelly"`. Replays the unacknowledged notices after `after` (all of them
+     * without it), oldest first, as `notice` events on this connection, then sends each new one. With `lines`, a
+     * message carries its first line. A subscription under a host-scope grant ends when the grant expires.
+     */
+    "notice.subscribe": {
+        params: z.strictObject({ after: NoticeId.optional(), lines: z.boolean().optional() }),
+        result: z.object({ replayed: z.number().int().nonnegative() }),
+    },
+    /** Human tier; host scope in `deployment: "jelly"`. The unacknowledged notices, newest first, and the badge counts. */
+    "notice.list": {
+        params: z.strictObject({ lines: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional() }),
+        result: z.object({ notices: z.array(Notice), counts: NoticeCounts }),
+    },
+    /** Human tier. Marks notices seen; unknown ids are ignored. */
+    "notice.ack": { params: z.strictObject({ ids: z.array(NoticeId).min(1).max(200) }), result: z.object({ ok: z.literal(true) }) },
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's M-3). The host sends it after the machine wakes from sleep:
+     * the daemon retries its relay link at once instead of at its backoff, runs its sweep, sends presence, and disarms a
+     * wake ticket it armed (`wake.disarm`), which this wake spent or no longer needs.
+     */
+    "daemon.woke": { params: z.strictObject({}), result: z.object({ ok: z.literal(true) }) },
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's M-4). Whether a window of the person is visible on this
+     * host. While it is not, under a Jelly host, this device's presence says `away` (spec §6.5), and the person's
+     * contacts see that device as away. Before the first call a Jelly host's device is away; elsewhere never.
+     */
+    "person.attached": { params: z.strictObject({ attached: z.boolean() }), result: z.object({ ok: z.literal(true) }) },
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's A5). Before the host sleeps: the daemon hands its relay the
+     * host's wake ticket (`jelly-wake+jwt`, for `url`, Jelly ID's wake endpoint of this host), the sessions in `agents`
+     * whose own person's mail may wake the host, and the tasks those sessions await (their unfinished requests). The relay
+     * presents the ticket once, for such traffic only, while this device is offline (spec §7, "Wake tickets"). `relay`:
+     * `armed` once the relay holds it, `pending` while it is not connected (it is sent at the next connection);
+     * `awaiting`: how many task requests the relay may wake for. A directory realm only.
+     */
+    "wake.arm": {
+        params: z.strictObject({
+            url: WakeUrl,
+            ticket: Jws.refine((ticket) => ticket.length <= WAKE_TICKET_BYTES, { message: `at most ${WAKE_TICKET_BYTES} bytes` }),
+            agents: z.array(SessionName).max(WAKE_AGENTS),
+        }),
+        result: z.object({ relay: z.enum(["armed", "pending"]), awaiting: z.number().int().nonnegative() }),
+    },
+    /** Admin tier; host scope in `deployment: "jelly"`. The relay forgets this device's wake ticket (`pending` until connected). */
+    "wake.disarm": { params: z.strictObject({}), result: z.object({ relay: z.enum(["disarmed", "pending"]) }) },
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's backup proposal, design §13.9). `{}` writes a consistent
+     * copy of the home while the daemon runs into `folder`, `<run>/snapshot` (the socket folder), and holds it there:
+     * the store (`messaging.db`, by SQLite `VACUUM INTO`), `config.json` and `manifest.json`. Never a private key:
+     * `identity.json` is not copied. `{done: true}` releases it (deletes the folder); a held snapshot is also released
+     * after an hour and when the daemon starts. `invalid_state` while one is held.
+     */
+    "daemon.snapshot": {
+        params: z.strictObject({ done: z.literal(true).optional() }),
+        result: z.union([
+            z.object({
+                folder: z.string().max(4096),
+                files: z.array(z.object({ name: z.string().max(64), bytes: z.number().int().nonnegative(), sha256: z.string().regex(/^[0-9a-f]{64}$/) })).max(8),
+                storeSchema: z.number().int().positive(),
+                at: Millis,
+                /** When the daemon releases it unasked. */
+                until: Millis,
+            }),
+            z.object({ released: z.boolean() }),
+        ]),
+    },
+    /**
+     * Human tier, read-only. What removing `device` would remove, for a confirmation: its label, kind and vouch, and
+     * whether it is current. `not_found` for a device that is not this person's.
+     */
+    /** `device.remove`'s input (spec §8.2, "Previews"); `reason` and `token` are not used, and `token` is never logged. */
+    "device.remove.preview": {
+        params: DeviceRemoveParams,
+        result: z.object({
+            label: MachineLabel,
+            kind: DeviceKind.optional(),
+            vouch: z.enum(["jelly", "device", "admin"]),
+            current: z.boolean(),
+            self: z.boolean(),
+            since: Millis.optional(),
+        }),
+    },
+};

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

@@ -0,0 +1,185 @@
+/**
+ * Shapes the local API's methods share (spec §8.2): session keys, inbox items, task records, send
+ * results, directory entries, conversation entries and chat lines. Each lane's method file under
+ * `schema/ipc/` imports them from here, and `schema/ipc.ts` re-exports them, so no method file
+ * imports `ipc.ts` (which spreads their tables).
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { Task, TaskState } from "../a2a.js";
+import { AgentKind, DeliveryStage, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "../common.js";
+import { DelegationSummary } from "../delegation.js";
+import { ErrorCode } from "../errors.js";
+/** Opaque, client-chosen session key, stable for the life of a client session, e.g. "opencode:<sessionID>". */
+export const SessionKey = z.string().min(1).max(200);
+/**
+ * When the recipient will likely see a message (spec §8.2): a hint from its machine's last presence
+ * at send time, never a promise.
+ * - `next_turn`: a live push session that is busy; its client shows the message after its next tool call or at its next turn.
+ * - `wake`: an idle push session, or a kept one its host can load again, whose machine acts on wake hints; the
+ *   client may start a turn for it, within its own budget.
+ * - `next_prompt`: a live push session that is idle and will not be woken; it sees the message when next prompted.
+ * - `on_read`: a pull session; its agent sees the message when it checks its inbox.
+ * - `kept`: no client holds the session; the message waits for one to register it again.
+ * - `offline`: the recipient machine is not connected; the relay holds the envelope until it connects or it expires.
+ */
+export const SendExpect = z.enum(["next_turn", "wake", "next_prompt", "on_read", "kept", "offline"]);
+/** One agent session of a person, as this device knows it: `agent` is its name, `client` its client kind. */
+export const DirectoryEntry = z.object({
+    address: SessionAddress,
+    person: PersonId,
+    agent: SessionName,
+    device: MachineId,
+    label: MachineLabel,
+    client: AgentKind,
+    repo: z.string().optional(),
+    branch: z.string().optional(),
+    state: SessionState,
+    doing: z.string().optional(),
+    tier: DeliveryTier,
+    online: z.boolean(),
+    lastSeen: Millis,
+    self: z.boolean().describe("true for sessions registered on this machine"),
+    /**
+     * When a message sent to this session now, with the wake hint set, would likely be seen: the
+     * same `SendExpect` a `msg.send` result carries (spec §8.2). Absent when no presence lists it.
+     */
+    expect: SendExpect.optional(),
+});
+/** Chat text, at most `LIMITS.chatChars` UTF-16 code units (`max` would count code points). */
+export const ChatText = z.string().refine((text) => text.length <= LIMITS.chatChars, { message: `at most ${LIMITS.chatChars} UTF-16 code units` });
+/**
+ * A position in this machine's chat order (spec §6.8): every filed line and every chat change takes
+ * the next one. Local: another machine numbers the same line differently. 0 is before the first.
+ */
+export const ChatSeq = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** One transcript line (spec §6.8). `id` is the line's `messageId`, the same on every machine. */
+export const ChatLine = z.object({
+    id: Ulid,
+    /** This machine's filing order of the line: the cursor for `conv.read` paging and `conv.markRead`. */
+    seq: ChatSeq,
+    at: Millis,
+    person: PersonId,
+    /** The sending agent, when an agent posted it; absent on the person's own line. */
+    agent: SessionName.optional(),
+    direction: z.enum(["in", "out"]),
+    body: ChatText,
+    /** The `id` of the thread's first line; absent on a first line. */
+    thread: Ulid.optional(),
+    /**
+     * On a line this machine sent to other persons (spec §6.8): `sent` until every person has a
+     * delivered copy, `delivered` then, `refused` once some person's every copy was rejected or expired.
+     * `held` while every person still to deliver it holds it for their person to answer: a message request
+     * waiting to be accepted (spec §6.9).
+     */
+    state: z.enum(["sent", "held", "delivered", "refused"]).optional(),
+    /** With `refused`: the persons whose every copy was rejected or expired. */
+    refused: z.array(PersonId).max(LIMITS.channelPersons).optional(),
+    /** A line this daemon wrote about a channel change or a refusal of one; its text is the daemon's, never a peer's. */
+    notice: z.literal(true).optional(),
+});
+/** The other end of an item or a task: a person's device and, when an agent wrote it, the agent. */
+export const PeerRef = z.object({
+    address: SessionAddress,
+    person: PersonId,
+    agent: SessionName.optional(),
+    device: MachineId,
+    label: MachineLabel,
+});
+export const InboxItem = z.object({
+    id: Ulid.describe("envelope id"),
+    key: SessionKey,
+    from: PeerRef,
+    kind: z.enum(["message", "task"]),
+    messageId: z.string().min(1).max(128),
+    taskId: Ulid.optional(),
+    contextId: z.string().max(128).optional(),
+    replyTo: Ulid.optional(),
+    receivedAt: Millis,
+    stage: z.enum(["delivered", "handed_to_agent", "read"]),
+    bytes: z.number().int().nonnegative(),
+    /** Untrusted peer text, truncated. Clients must frame it as data, never as instructions. */
+    preview: z.string().max(LIMITS.previewChars),
+    wake: z.boolean().describe("sender hint, already filtered by local policy"),
+    /** kind "task" only: the delegation chain this daemon verified (spec §6.7). */
+    chain: DelegationSummary.optional(),
+    /**
+     * How a request from the sender may run here, as this daemon decided it (spec §6.9): `self` (this person's own),
+     * `trusted` (a person this person trusts, under the chain rule) or `guarded` (a peer turn). Never from peer content.
+     * Absent only on items stored before consent.
+     */
+    consent: z.enum(["self", "guarded", "trusted"]).optional(),
+});
+/**
+ * A message this side sent to continue a task it requested (`msg.send` with `kind: "message"`
+ * and the `taskId`), and how far it got, from this daemon's own delivery records (spec §6.3).
+ */
+export const TaskFollowUp = z.object({
+    envelopeId: Ulid,
+    messageId: z.string().min(1).max(128),
+    sentAt: Millis,
+    stage: DeliveryStage,
+    /** When it reached `stage`. */
+    at: Millis,
+});
+export const TaskRecord = z.object({
+    task: Task.extend({ id: Ulid }),
+    role: z.enum(["requester", "executor"]),
+    key: SessionKey.describe("local session that owns this side of the task"),
+    peer: PeerRef,
+    createdAt: Millis,
+    updatedAt: Millis,
+    /** The delegation chain of this task (spec §6.7): as verified on arrival (executor), or as sent (requester). */
+    chain: DelegationSummary.optional(),
+    /**
+     * Requester side, in `task.get` results and `task` events only (not `task.list`): the newest
+     * `LIMITS.taskFollowUps` follow-ups this daemon still has delivery records for, oldest first.
+     * Absent when there are none.
+     */
+    followUps: z.array(TaskFollowUp).min(1).max(LIMITS.taskFollowUps).optional(),
+});
+/**
+ * Where a send went (`msg.send`, spec §8.2): an agent session `person/agent@label`, a person (a line
+ * from an agent to them) or `#<channel>` (a post).
+ */
+export const SendTarget = z.union([SessionAddress, PersonId, z.string().regex(/^#[a-z][a-z0-9-]{0,31}$/, "#<channel>")]);
+export const SendResult = z.object({
+    to: SendTarget,
+    envelopeId: Ulid,
+    messageId: z.string().min(1).max(128),
+    taskId: Ulid.optional(),
+    contextId: z.string().max(128),
+    stage: DeliveryStage,
+    code: ErrorCode.optional(),
+    /** Absent when the stage is `rejected` or `expired`, or when no presence lists the session. */
+    expect: SendExpect.optional(),
+});
+/** A place in a conversation page (`conv.read`): an entry's time and id. */
+export const ConvCursor = z.strictObject({ at: Millis, id: Ulid });
+/**
+ * One entry of a conversation between a local session and one other session (spec §8.2
+ * `conv.read`): mail either way, or a task either way. `text` is untrusted peer text for incoming
+ * mail and for a task the other side asked for; clients frame it as data.
+ */
+export const ConvEntry = z.object({
+    /** The envelope id (mail) or the task id (task). */
+    id: Ulid,
+    kind: z.enum(["mail", "task"]),
+    /** `in`: from the other session (mail it sent, a task it asked this session to run); `out`: the reverse. */
+    direction: z.enum(["in", "out"]),
+    /** The other session, as this machine knows it. */
+    peer: SessionAddress,
+    /** Mail: received (in) or sent (out). Task: created. */
+    at: Millis,
+    /**
+     * Incoming mail: its preview. Task: the start of its request. Absent on outgoing mail: the
+     * daemon keeps no copy of what it sent.
+     */
+    text: z.string().max(LIMITS.previewChars).optional(),
+    /** Mail that continues a task. */
+    taskId: Ulid.optional(),
+    /** Mail: its stage (incoming: this side's inbox stage; outgoing: how far it got). */
+    stage: DeliveryStage.optional(),
+    /** Task: this session's role and the task's state now. */
+    role: z.enum(["requester", "executor"]).optional(),
+    state: TaskState.optional(),
+});

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

@@ -0,0 +1,223 @@
+/**
+ * The local API's surface methods (spec §8.2; design §7.5): what agents reach through their tools
+ * and what people reach through the CLI and the TUI, by conversation.
+ *
+ * - Agent tier (`run/agent.sock`): `contacts.list`, `msg.send`, `item.read`, `conv.read`, `search`.
+ * - Human tier (`run/admin.sock`): `conv.list`, `conv.read`, `conv.markRead`, `conv.subscribe`,
+ *   `person.send`, `people.search`, `people.get`.
+ *
+ * A conversation is named by a `ConversationRef`: `dm:<person>` (this person's DM with another),
+ * `channel:<name>` (a channel this person is in, by its local name) or `agent:<person>/<agent>`
+ * (a local session's mail and tasks with that agent, on any of the person's devices).
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { Message, Part } from "../a2a.js";
+import { Address, DeliveryStage, MachineId, MachineLabel, Millis, PersonId, RoomRef, Ulid, LIMITS } from "../common.js";
+import { DelegationScope } from "../delegation.js";
+import { Email } from "../directory-frames.js";
+import { ErrorCode } from "../errors.js";
+import { PersonReach } from "./consent.js";
+import { DeviceChangeView } from "./device.js";
+import { ChatLine, ChatSeq, ChatText, ConvCursor, ConvEntry, DirectoryEntry, InboxItem, SendResult, SendTarget, SessionKey } from "./shapes.js";
+/**
+ * Max UTF-8 bytes of `msg.send` metadata as JSON. For wire JSON that is its JCS length: JCS only
+ * reorders members.
+ */
+const METADATA_BYTES = 16_384;
+/** A conversation: `dm:<person>`, `channel:<name>` or `agent:<person>/<agent>`. */
+export const ConversationRef = z
+    .string()
+    .regex(/^(?:dm:(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})|channel:[a-z][a-z0-9-]{0,31}|agent:(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})\/[a-z0-9][a-z0-9._-]{0,63})$/, "dm:<person>, channel:<name> or agent:<person>/<agent>");
+/** A place in a conversation: a line's `seq` in a DM or a channel, an entry's `{at, id}` with an agent. */
+export const ConvPlace = z.union([ChatSeq, ConvCursor]);
+/** One conversation this person has (DMs with lines, channels it is in) and this device's read state. */
+export const ConvSummary = z.object({
+    conversation: RoomRef,
+    kind: z.enum(["dm", "channel"]),
+    lastAt: Millis.optional(),
+    /** A channel held under a local name (another channel here already had its name) carries its own name. */
+    name: z.string().max(32).optional(),
+    /** The newest line's seq; absent in a channel with no lines. */
+    lastSeq: ChatSeq.optional(),
+    /** 0 when nothing is marked read. */
+    readUpTo: ChatSeq,
+    /** Lines from others after `readUpTo`. */
+    unread: z.number().int().nonnegative(),
+});
+/** A person of the realm, as verified (a roster realm: a team person). */
+export const PersonSummary = z.object({
+    person: PersonId,
+    /** The display name; a roster realm has only the person name. Untrusted text in a hosted realm. */
+    name: z.string().max(200),
+    /** What a person types to address them. */
+    handle: z.string().max(64),
+    /** `same`: in this device's person's org (a roster realm: the team). */
+    org: z.enum(["same", "other", "none"]),
+    /** The weakest vouch among their current devices. */
+    vouched: z.enum(["jelly", "device", "service", "admin"]),
+});
+export const SURFACE_METHODS = {
+    /**
+     * Agent tier. Who this session can reach: every known agent session (`entries`, as `directory.list`
+     * did in 0.1), and this person's conversations with their read state (`conversations`, as
+     * `conv.list` returns them).
+     */
+    "contacts.list": {
+        params: z.strictObject({ person: PersonId.optional(), includeOffline: z.boolean().optional() }),
+        /**
+         * `reach`: for each other person among `entries` and the DMs, and each person whose card this device holds, what they may
+         * be sent, from their card or the defaults of the relation (spec §6.9, "Contact cards").
+         */
+        result: z.object({ entries: z.array(DirectoryEntry), conversations: z.array(ConvSummary), reach: z.array(PersonReach) }),
+    },
+    /**
+     * Agent tier. One send from the session `key` (spec §8.2): mail or a task to an agent
+     * (`person/agent[@label]`), a line to a person (`<person>`), or a post to a channel (`#<channel>`).
+     * A line or a post is attributed to the session; it takes one text part of at most
+     * `LIMITS.chatChars`, `kind: "message"`, and `replyTo` as the thread (the thread's first line),
+     * and none of the A2A fields. `idempotencyKey` makes any send idempotent.
+     */
+    "msg.send": {
+        params: z.strictObject({
+            key: SessionKey,
+            to: z.union([Address, z.string().regex(/^#[a-z][a-z0-9-]{0,31}$/, "#<channel>")]),
+            kind: z.enum(["message", "task"]),
+            parts: z.array(Part).min(1).max(LIMITS.partsPerMessage),
+            contextId: z.string().max(128).optional(),
+            taskId: Ulid.optional().describe("for kind=message: the task this message continues (INPUT_REQUIRED replies)"),
+            replyTo: Ulid.optional(),
+            idempotencyKey: z.string().min(1).max(200).optional(),
+            /** A2A passthrough. The daemon generates messageId when omitted and always overwrites metadata[URI.provenance]. */
+            messageId: z.string().min(1).max(128).optional(),
+            metadata: z
+                .record(z.string(), z.unknown())
+                .refine((m) => new TextEncoder().encode(JSON.stringify(m)).length <= METADATA_BYTES, { message: `metadata is limited to ${METADATA_BYTES} bytes of JSON` })
+                .optional(),
+            extensions: z.array(z.string().min(1).max(256)).max(16).optional(),
+            referenceTaskIds: z.array(Ulid).max(16).optional(),
+            wake: z.boolean().optional().describe("hint that the recipient may wake an idle session; default true"),
+            /**
+             * Only on a line to the session's own person (`<own person>`, spec §6.9 "Message requests"): the agent asks its
+             * person to send a message request to this exact email. The daemon files it for the person to answer; only the
+             * person sends the request.
+             */
+            request: z.strictObject({ contact: Email }).optional(),
+            /**
+             * kind=task only (spec §6.7): delegate on behalf of a task this session executes. The daemon extends that
+             * task's chain to each recipient, narrowed to `scope` and `maxDepth` when given. Without it, a task starts a new chain.
+             */
+            onBehalfOf: z
+                .strictObject({
+                taskId: Ulid.describe("a task this session executes"),
+                scope: z.array(DelegationScope).max(LIMITS.delegationScopes).optional().describe("narrow the scope; never wider than the task's"),
+                maxDepth: z.number().int().min(1).max(LIMITS.delegationDepth).optional().describe("narrow the depth; never above the task's"),
+            })
+                .optional(),
+        }),
+        result: z.object({ results: z.array(SendResult) }),
+    },
+    /**
+     * Agent tier. One item of the session `key` by id: something it received (`received`: returns the
+     * full message, marks it read and sends a read receipt, as `inbox.read` did in 0.1), or something
+     * it sent to an agent (`sent`: how far it got, as `message.status` did). `not_found` otherwise.
+     */
+    "item.read": {
+        params: z.strictObject({ key: SessionKey, id: Ulid }),
+        result: z.discriminatedUnion("kind", [
+            z.object({ kind: z.literal("received"), item: InboxItem, message: Message }),
+            z.object({
+                kind: z.literal("sent"),
+                envelopeId: Ulid,
+                to: SendTarget,
+                stage: DeliveryStage,
+                history: z.array(z.object({ stage: DeliveryStage, at: Millis, code: ErrorCode.optional(), note: z.string().optional() })),
+            }),
+        ]),
+    },
+    /**
+     * Agent and human tiers. A page of one conversation, oldest first. With no cursor, the latest
+     * `limit` (default 30 with an agent, 50 in a DM or a channel); with `before`, the latest `limit`
+     * before that place; with `after`, the earliest `limit` after it. `more`: entries remain past the
+     * page in the direction read. Changes no stage and sends no receipt.
+     * - `dm:` and `channel:` give `lines`; `thread` narrows to a thread's first line and its replies;
+     *   the cursor is a line's `seq`.
+     * - `agent:<person>/<agent>` needs the session `key` and gives `entries`: mail either way and tasks
+     *   either way between that session and the agent; the cursor is an entry's `{at, id}`.
+     */
+    "conv.read": {
+        params: z
+            .strictObject({
+            key: SessionKey.optional(),
+            conversation: ConversationRef,
+            thread: Ulid.optional(),
+            before: ConvPlace.optional(),
+            after: ConvPlace.optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        })
+            .refine((p) => p.before === undefined || p.after === undefined, { message: "before and after do not combine" }),
+        result: z.discriminatedUnion("kind", [
+            z.object({ kind: z.literal("lines"), lines: z.array(ChatLine), more: z.boolean() }),
+            z.object({ kind: z.literal("agent"), entries: z.array(ConvEntry), more: z.boolean() }),
+        ]),
+    },
+    /** Agent tier. Full-text search over the DM and channel lines `conv.read` can read, newest first. */
+    search: {
+        params: z.strictObject({ query: z.string().min(1).max(200), conversation: RoomRef.optional(), limit: z.number().int().min(1).max(50).optional() }),
+        result: z.object({ hits: z.array(ChatLine.extend({ conversation: RoomRef })) }),
+    },
+    /**
+     * Human tier. The channels this person is in and the DMs with lines, newest first, at most `limit`
+     * (default 100), each with this device's read state.
+     */
+    "conv.list": {
+        params: z.strictObject({ limit: z.number().int().min(1).max(200).optional() }),
+        result: z.object({ conversations: z.array(ConvSummary) }),
+    },
+    /**
+     * Human tier. Marks a DM or a channel read on this device up to `upTo` (a line's `seq`): the cursor
+     * only moves forward, and never past the newest seq here. Returns the cursor and what is still unread.
+     */
+    "conv.markRead": {
+        params: z.strictObject({ conversation: RoomRef, upTo: ChatSeq }),
+        result: z.object({ readUpTo: ChatSeq, unread: z.number().int().nonnegative() }),
+    },
+    /**
+     * Human tier. `conv` events go only to connections that call this (spec §6.8). With `since` (the
+     * `seq` of the last event the client handled), the daemon first replays one event per line changed
+     * after it, oldest first, or sends none and answers `gap: true` when it cannot replay them all; the
+     * client then reloads with `conv.list` and `conv.read`. `seq` is the newest seq at the call.
+     */
+    "conv.subscribe": { params: z.strictObject({ since: ChatSeq.optional() }), result: z.object({ seq: ChatSeq, gap: z.boolean() }) },
+    /**
+     * Human tier. A line from the person (no agent) to a DM or a channel this person is in. `thread` is
+     * the `id` of the thread's first line. `clientId` makes the call idempotent: a repeat with the same
+     * `clientId` and the same conversation, thread and text returns the first line's result and sends nothing.
+     */
+    "person.send": {
+        params: z.strictObject({
+            conversation: RoomRef,
+            text: ChatText.min(1),
+            thread: Ulid.optional(),
+            clientId: z.string().min(1).max(200).optional(),
+        }),
+        result: z.object({ id: Ulid, conversation: RoomRef }),
+    },
+    /** Human tier. The persons of the realm whose handle starts with `query` (all with none), at most `limit` (default 50). */
+    "people.search": {
+        params: z.strictObject({ query: z.string().max(100).optional(), limit: z.number().int().min(1).max(200).optional() }),
+        result: z.object({ people: z.array(PersonSummary) }),
+    },
+    /** Human tier. One person and their current devices, as verified. `not_found` for a person this realm does not know. */
+    "people.get": {
+        params: z.strictObject({ person: PersonId }),
+        /** A device's `away`: its latest presence, still fresh, says no window of the person is visible on it (spec §6.5). */
+        result: PersonSummary.extend({
+            devices: z.array(z.object({ device: MachineId, label: MachineLabel, self: z.boolean(), away: z.literal(true).optional() })),
+            /**
+             * Their devices added, removed or replaced in the last 7 days, newest first, at most 10 (design §2.8: "Bob's
+             * devices changed: added 'bob-vps' (vouched by Jelly ID)"). Absent for this device's own person and when none.
+             */
+            deviceChanges: z.array(DeviceChangeView).max(10).optional(),
+        }),
+    },
+};