@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,451 @@
+/**
+ * Local daemon API. JSON-RPC 2.0, one JSON object per line (NDJSON), over two Unix sockets in
+ * `$MESSAGING_HOME/run/` (spec §8.2, "Two sockets"), each 0600 (the agent socket 0660 to
+ * `ipc.agentGroup` when set):
+ *
+ * - `run/agent.sock` serves only `AGENT_METHODS` (the agent tier): the session, contacts, send,
+ *   inbox, item, conversation, search, task and events methods. The daemon refuses anything else with
+ *   `forbidden`. Agent-facing clients (OpenCode plugin tools, MCP server) connect here.
+ * - `run/admin.sock` serves every method: the agent tier, `HUMAN_METHODS` (acting as the person:
+ *   conversations, the person's own lines, people, channels) and `ADMIN_METHODS` (this device and the
+ *   team). Human clients (the `messaging` CLI and the `/messaging` TUI) connect here; agent-facing
+ *   clients never expose these methods.
+ *
+ * Params are strict: a key a method does not define is refused (-32602), never dropped.
+ *
+ * Errors: standard JSON-RPC codes for transport/schema problems (-32700, -32600, -32601, -32602,
+ * -32603); every Messaging error uses code -32000 with `data: { code: ErrorCode }`.
+ * The daemon pushes notifications `{"jsonrpc":"2.0","method":"event","params":Event}`: `conv` events
+ * to connections that called `conv.subscribe`, every other event to connections that called
+ * `events.subscribe` for its key (or to all of them, for events without a key).
+ */
+import { z } from "../../vendor/zod/index.js";
+import { DEVICE_METHODS, DeviceStatus, LoginPurpose } from "./ipc/device.js";
+import { Artifact, Message, Part, TaskState, TaskStatus } from "./a2a.js";
+import { AgentKind, ChannelName, DeliveryStage, DeliveryTier, EncKey, Hash, MachineId, MachineLabel, MemberRole, Millis, PersonId, PersonName, RelayUrl, RoomRef, SessionAddress, SessionName, SessionState, TeamId, TeamName, Ulid, LIMITS, } from "./common.js";
+import { ErrorCode } from "./errors.js";
+import { ChatSeq, InboxItem, SessionKey, TaskRecord } from "./ipc/shapes.js";
+import { SURFACE_METHODS } from "./ipc/surfaces.js";
+import { Member } from "./roster.js";
+import { CONSENT_METHODS } from "./ipc/consent.js";
+import { JELLY_METHODS, Notice } from "./ipc/jelly.js";
+import { Jws } from "./jelly.js";
+export * from "./ipc/shapes.js";
+export * from "./ipc/surfaces.js";
+export * from "./ipc/jelly.js";
+export const MESSAGING_ERROR_RPC_CODE = -32000;
+/**
+ * Where the daemon can reach a session's host to wake it while no connection holds the session's
+ * key (spec §8.6). Local only: the daemon never publishes it.
+ *
+ * `opencode`: the OpenCode session `sessionID` lives in the location (directory) `location` of the
+ * OpenCode server process `pid`. `location` is absolute: a POSIX path (`/…`), or a Windows drive path
+ * (`C:\…` or `C:/…`) below the drive's root. The daemon may call that server's `messaging.opencode/wake` RPC at
+ * `location`, and nothing else, while OpenCode's service registration names the same `pid`.
+ */
+export const SessionHost = z.strictObject({
+    kind: z.literal("opencode"),
+    location: z
+        .string()
+        .min(2)
+        .max(1024)
+        .refine((path) => (path.startsWith("/") || /^[A-Za-z]:[\\/]./s.test(path)) && !/[\u0000-\u001f\u007f]/.test(path), {
+        message: "an absolute path without control characters",
+    }),
+    sessionID: z.string().min(1).max(200),
+    pid: z.number().int().min(1).max(2_147_483_647),
+});
+/**
+ * The local API's protocol number. A client and a daemon must speak the same one, and be the same
+ * release (`VERSION`): there is no compatibility across versions (spec §8.2).
+ */
+export const IPC_PROTOCOL = 1;
+/**
+ * The daemon's first line on every connection, before any request: a JSON-RPC notification
+ * `{"jsonrpc":"2.0","method":"hello","params":IpcHello}` (spec §8.2). A client reads it before it
+ * sends anything, and refuses a daemon of another `version` or `protocol` with `daemon_mismatch`.
+ * Every release keeps this shape, so any client can say which daemon it found and `messaging daemon
+ * stop` can stop it by `pid`. Unknown fields are ignored.
+ */
+export const IpcHello = z.object({
+    daemon: z.literal("messagingd"),
+    version: z.string().min(1).max(64),
+    protocol: z.number().int().min(1).max(1_000_000),
+    pid: z.number().int().min(1).max(2_147_483_647),
+    /** `jelly`: the daemon runs under a Jelly host (spec §8.11); absent otherwise. */
+    deployment: z.literal("jelly").optional(),
+});
+const Ok = z.object({ ok: z.literal(true) });
+const Empty = z.strictObject({});
+export const DaemonStatus = z.object({
+    version: z.string(),
+    pid: z.number().int(),
+    home: z.string(),
+    identity: z.object({ device: MachineId, person: PersonId, label: MachineLabel }).optional(),
+    team: z
+        .object({ id: TeamId, name: TeamName, role: MemberRole, head: z.object({ seq: z.number().int(), hash: Hash }) })
+        .optional(),
+    relay: z.object({ url: z.string().optional(), connected: z.boolean(), lastError: z.string().max(500).optional() }),
+    sessions: z.number().int().nonnegative(),
+    /**
+     * A signed envelope committed to a roster hash this chain does not have (spec §5, §12). Persists
+     * across restarts while the evidence still proves it. Absent when there is no such alarm.
+     */
+    divergence: z
+        .object({
+        device: MachineId,
+        person: PersonId,
+        seq: z.number().int().nonnegative(),
+        ours: Hash,
+        theirs: Hash,
+        at: Millis,
+        id: Ulid,
+    })
+        .optional(),
+    /**
+     * This machine cannot act as itself (spec §8.9). `restored`: its keys came from an older copy, and the roster
+     * names a newer key this machine signed and does not hold. `keys_missing`: the store names this machine, but its
+     * key files are gone. Either way the daemon publishes no key. Absent when there is no such alarm.
+     */
+    alarm: z.enum(["restored", "keys_missing"]).optional(),
+    /** A directory realm (spec §15.9): this device's binding, the adopted tree head and the realm's alarm. */
+    directory: DeviceStatus.optional(),
+});
+export const InviteSummary = z.object({
+    inviteId: Ulid,
+    person: PersonName,
+    expires: Millis,
+    state: z.enum(["open", "redeemed", "revoked", "expired"]),
+});
+/** Method table: name → params/result schemas. The daemon validates params; clients validate results. */
+export const IPC_METHODS = {
+    ...DEVICE_METHODS,
+    "daemon.status": { params: Empty, result: DaemonStatus },
+    /** Human CLI only: replies, then shuts the daemon down cleanly. */
+    "daemon.stop": { params: Empty, result: Ok },
+    "session.register": {
+        params: z.strictObject({
+            key: SessionKey,
+            agent: AgentKind.describe('client kind, e.g. "opencode", "claude-code"'),
+            name: SessionName.optional().describe("requested name; the daemon may suffix it to keep it unique"),
+            cwd: z.string().max(1024).optional(),
+            repo: z.string().max(200).optional(),
+            branch: z.string().max(200).optional(),
+            tier: DeliveryTier,
+            state: SessionState,
+            doing: z.string().max(200).optional(),
+            host: SessionHost.optional().describe("where the daemon can wake the session while no connection holds its key; kind must equal agent"),
+            /** `deployment: "jelly"` only, and required there: the host's session ticket naming this session (spec §8.11). */
+            ticket: Jws.optional(),
+        }),
+        result: z.object({ session: SessionName, address: SessionAddress }),
+    },
+    "session.update": {
+        params: z.strictObject({
+            key: SessionKey,
+            state: SessionState.optional(),
+            doing: z.string().max(200).optional(),
+            branch: z.string().max(200).optional(),
+            tier: DeliveryTier.optional(),
+        }),
+        result: Ok,
+    },
+    "session.unregister": { params: z.strictObject({ key: SessionKey }), result: Ok },
+    /** Newest first; default limit 50. */
+    "inbox.list": {
+        params: z.strictObject({
+            key: SessionKey,
+            unreadOnly: z.boolean().optional().describe('only items not yet "read" (stage delivered or handed_to_agent)'),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        result: z.object({ items: z.array(InboxItem) }),
+    },
+    /**
+     * Looks up one item without changing its stage or sending a receipt. With `message: true` it
+     * also returns the full message, still with no stage change: a client can show the message first
+     * and ack after (`inbox.ack`), so a crash in between leaves the item unread.
+     */
+    "inbox.get": {
+        params: z.strictObject({ key: SessionKey, id: Ulid, message: z.boolean().optional() }),
+        result: z.object({ item: InboxItem, message: Message.optional() }),
+    },
+    "inbox.ack": {
+        params: z.strictObject({ key: SessionKey, id: Ulid, stage: z.enum(["handed_to_agent", "read"]) }),
+        result: Ok,
+    },
+    "task.list": {
+        params: z.strictObject({
+            key: SessionKey,
+            role: z.enum(["requester", "executor"]).optional(),
+            state: TaskState.optional(),
+            contextId: z.string().max(128).optional(),
+            peer: SessionAddress.optional().describe("only tasks whose peer is this session"),
+            updatedAfter: Millis.optional().describe("only tasks updated at or after this time"),
+            cursor: z.string().min(1).max(200).optional().describe("opaque; from a previous nextCursor"),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        /** Most recently updated first. */
+        result: z.object({
+            tasks: z.array(TaskRecord),
+            nextCursor: z.string().max(200).optional().describe("absent when there are no more pages"),
+            total: z.number().int().nonnegative().describe("matching tasks across all pages"),
+        }),
+    },
+    "task.get": { params: z.strictObject({ key: SessionKey, taskId: Ulid }), result: TaskRecord },
+    "task.update": {
+        params: z.strictObject({
+            key: SessionKey,
+            taskId: Ulid,
+            state: TaskState,
+            message: z.strictObject({ parts: z.array(Part).min(1).max(LIMITS.partsPerMessage) }).optional(),
+            artifact: Artifact.optional(),
+            append: z.boolean().optional(),
+            lastChunk: z.boolean().optional(),
+        }),
+        result: TaskRecord,
+    },
+    "task.cancel": {
+        params: z.strictObject({ key: SessionKey, taskId: Ulid, reason: z.string().max(1000).optional() }),
+        result: TaskRecord,
+    },
+    "events.subscribe": { params: z.strictObject({ keys: z.array(SessionKey).min(1).max(256) }), result: Ok },
+    // ---- human clients only (the CLI and the TUI) ----
+    "team.create": {
+        params: z.strictObject({ name: TeamName, person: PersonName, label: MachineLabel, relay: RelayUrl }),
+        result: z.object({ team: TeamId, name: TeamName, machine: MachineId }),
+    },
+    "team.invite": {
+        params: z.strictObject({ person: PersonName, ttlMs: z.number().int().min(60_000).max(LIMITS.ttlMs).optional() }),
+        result: z.object({ ticket: z.string(), inviteId: Ulid, expires: Millis }),
+    },
+    "team.join": {
+        params: z.strictObject({ ticket: z.string().min(1).max(4096), label: MachineLabel }),
+        result: z.object({ team: TeamId, name: TeamName, machine: MachineId, person: PersonName }),
+    },
+    "team.members": {
+        params: Empty,
+        result: z.object({
+            team: z.object({ id: TeamId, name: TeamName }),
+            members: z.array(Member.extend({ self: z.boolean(), online: z.boolean() })),
+            invites: z.array(InviteSummary),
+        }),
+    },
+    "team.remove": { params: z.strictObject({ machine: MachineId, reason: z.string().max(200).optional() }), result: Ok },
+    "team.role": { params: z.strictObject({ machine: MachineId, role: MemberRole }), result: Ok },
+    "team.revokeInvite": { params: z.strictObject({ inviteId: Ulid }), result: Ok },
+    /**
+     * Rotates this machine's encryption key (spec §4 `member.rekey`, §8.2). Returns the new public key
+     * and when the previous one is dropped. Never a private key.
+     */
+    "identity.rotateEnc": { params: Empty, result: z.object({ enc: EncKey, until: Millis }) },
+    /**
+     * Admin admits a machine by the public keys it showed. No invite seed. The joiner connects only after
+     * this entry is on the roster (spec §4 `member.add`, §8.2).
+     */
+    "team.add": {
+        params: z.strictObject({
+            machine: MachineId,
+            enc: EncKey,
+            person: PersonName,
+            label: MachineLabel,
+        }),
+        result: Ok,
+    },
+    /**
+     * Joiner: generate keys and store them aside from `identity.json`, so the plugin does not treat the
+     * machine as joined. Returns the public admit card. Private keys stay in the daemon.
+     */
+    "team.pair": {
+        params: z.strictObject({ relay: RelayUrl, team: TeamId, person: PersonName, label: MachineLabel }),
+        result: z.object({
+            machine: MachineId,
+            enc: EncKey,
+            person: PersonName,
+            label: MachineLabel,
+            admit: z.string().min(1).max(2048),
+        }),
+    },
+    /**
+     * Joiner: try hello with the paired keys. `waiting` means the admin has not admitted this machine yet.
+     * `joined` means the roster names these exact keys, person and label, and the daemon has adopted them.
+     */
+    "team.claim": {
+        params: z.strictObject({ waitMs: z.number().int().min(0).max(120_000).optional() }),
+        result: z.discriminatedUnion("state", [
+            z.object({ state: z.literal("waiting") }),
+            z.object({
+                state: z.literal("joined"),
+                team: TeamId,
+                name: TeamName,
+                machine: MachineId,
+                person: PersonName,
+                label: MachineLabel,
+            }),
+        ]),
+    },
+    /** Discard pending keys (a pairing or founding keys), including their private keys. */
+    "team.pairCancel": { params: Empty, result: Ok },
+    /**
+     * Founder: generate the keys `team.create` will use and store them aside from `identity.json`, so a
+     * relay operator can list the machine id in `--allow-team-create` first. Returns the same public keys
+     * while they are pending. Private keys stay in the daemon.
+     */
+    "team.prepare": { params: Empty, result: z.object({ machine: MachineId, enc: EncKey }) },
+    /** Creates a channel with this person and `persons` (at most `LIMITS.channelPersons` together). */
+    "channel.create": {
+        params: z.strictObject({ name: ChannelName, persons: z.array(PersonId).max(LIMITS.channelPersons) }),
+        result: z.object({ id: Ulid, name: ChannelName }),
+    },
+    "channel.invite": {
+        params: z.strictObject({ name: ChannelName, persons: z.array(PersonId).min(1).max(LIMITS.channelPersons) }),
+        result: Ok,
+    },
+    "channel.leave": { params: z.strictObject({ name: ChannelName }), result: Ok },
+    /** Removes other persons from a channel; only its creator or a team admin may (spec §6.8). */
+    "channel.remove": {
+        params: z.strictObject({ name: ChannelName, persons: z.array(PersonId).min(1).max(LIMITS.channelPersons) }),
+        result: Ok,
+    },
+    ...CONSENT_METHODS,
+    ...JELLY_METHODS,
+    ...SURFACE_METHODS,
+};
+/**
+ * The agent tier (design §7.5): the methods an agent-facing client may call, and exactly what the
+ * daemon serves on `run/agent.sock` (spec §8.2). Anything else is for human clients, on
+ * `run/admin.sock`: the `messaging` CLI and the `/messaging` TUI.
+ */
+export const AGENT_METHODS = [
+    "daemon.status",
+    "daemon.health",
+    "device.status",
+    "device.bind",
+    "session.register",
+    "session.update",
+    "session.unregister",
+    "events.subscribe",
+    "contacts.list",
+    "msg.send",
+    "inbox.list",
+    "inbox.get",
+    "inbox.ack",
+    "item.read",
+    "conv.read",
+    "search",
+    "task.list",
+    "task.get",
+    "task.update",
+    "task.cancel",
+];
+/**
+ * The human tier (design §7.5): methods that act as the person, on `run/admin.sock` only: their
+ * conversations and own lines, the people of the realm, their grants and held requests (spec §6.9), and channels.
+ * `conv.read` is in both tiers.
+ */
+export const HUMAN_METHODS = [
+    "conv.list",
+    "conv.read",
+    "conv.markRead",
+    "conv.subscribe",
+    "person.send",
+    "people.search",
+    "people.get",
+    "grant.list",
+    "grant.set",
+    "grant.set.preview",
+    "request.list",
+    "request.answer",
+    "request.answer.preview",
+    "contact.request",
+    "contact.request.preview",
+    "card.get",
+    "agents.list",
+    "agents.read",
+    "notice.subscribe",
+    "notice.list",
+    "notice.ack",
+    "device.approve.preview",
+    "device.remove.preview",
+    "identity.replace.preview",
+    "directory.erase.preview",
+    "channel.create",
+    "channel.invite",
+    "channel.leave",
+    "channel.remove",
+];
+/**
+ * The admin tier (design §7.5): this device and the daemon, and in a roster realm the team, on
+ * `run/admin.sock` only.
+ */
+export const ADMIN_METHODS = [
+    "daemon.stop",
+    "daemon.woke",
+    "person.attached",
+    "daemon.snapshot",
+    "wake.arm",
+    "wake.disarm",
+    "device.list",
+    "device.remove",
+    "device.link",
+    "device.login",
+    "device.login.status",
+    "device.login.cancel",
+    "device.approve",
+    "identity.rotateEnc",
+    "identity.replace",
+    "directory.erase",
+    "team.create",
+    "team.invite",
+    "team.join",
+    "team.members",
+    "team.remove",
+    "team.role",
+    "team.revokeInvite",
+    "team.add",
+    "team.pair",
+    "team.claim",
+    "team.pairCancel",
+    "team.prepare",
+];
+/**
+ * What a host-scope action grant (`act: "host"`) allows in `deployment: "jelly"` (spec §8.11), and nothing else: the
+ * notice stream and its counts, `conv.list` with counts only, stopping the daemon, and telling it the host woke
+ * (`daemon.woke`) and whether the person is at it (`person.attached`), a backup of the home (`daemon.snapshot`), and its
+ * wake ticket (`wake.arm`, `wake.disarm`).
+ */
+export const HOST_SCOPE_METHODS = ["notice.subscribe", "notice.list", "conv.list", "daemon.stop", "daemon.woke", "person.attached", "daemon.snapshot", "wake.arm", "wake.disarm"];
+export const IpcEvent = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("inbox"), key: SessionKey, item: InboxItem }),
+    z.object({ type: z.literal("receipt"), key: SessionKey, envelopeId: Ulid, to: SessionAddress, stage: DeliveryStage, code: ErrorCode.optional() }),
+    /** origin "local": caused by this key's own call; "peer": caused by an envelope from the other side or a daemon timeout. */
+    z.object({
+        type: z.literal("task"),
+        key: SessionKey,
+        record: TaskRecord,
+        origin: z.enum(["local", "peer"]),
+        /** The delta that caused this snapshot, when it came from a status or artifact update. */
+        update: z
+            .union([
+            z.object({ status: TaskStatus }),
+            z.object({ artifact: Artifact, append: z.boolean().optional(), lastChunk: z.boolean().optional() }),
+        ])
+            .optional(),
+    }),
+    /** What `contacts.list` returns changed: a presence, a session, the roster. */
+    z.object({ type: z.literal("contacts") }),
+    z.object({ type: z.literal("relay"), connected: z.boolean() }),
+    /**
+     * A line was stored in a DM or a channel, a channel this person is in changed, or the delivery state
+     * of an outgoing line changed. Only for connections that called `conv.subscribe`. The text stays in
+     * the transcript. `seq` rises with every event; a client resumes from the last one it handled
+     * (`conv.subscribe {since}`).
+     */
+    z.object({ type: z.literal("conv"), conversation: RoomRef, id: Ulid, person: PersonId, seq: ChatSeq }),
+    /**
+     * A device's sign-in through the browser changed state (spec §15.9): its state and, when it failed, the code. Never
+     * the code to type, the link or a token; `device.login.status` gives the rest on the admin socket.
+     */
+    z.object({ type: z.literal("login"), state: z.enum(["pending", "done", "failed", "cancelled"]), purpose: LoginPurpose, code: ErrorCode.optional() }),
+    /** A notice (spec §8.2, "Notices"), only for connections that called `notice.subscribe`. */
+    z.object({ type: z.literal("notice"), notice: Notice }),
+]);

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

@@ -0,0 +1,122 @@
+/**
+ * The shapes of Jelly ID that a hosted realm reads (Jelly's resource-token contract v1.1; spec §15.2). Jelly
+ * owns them; these schemas are what Messaging accepts of them. Jelly's versions are additive, so headers,
+ * claims and key-set entries may carry members a later version adds; the members Messaging reads are strict.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Key32 } from "./common.js";
+/** A Jelly account id (contract v1.1 §5 step 6). */
+export const JellySubject = z.string().regex(/^acc_[A-Za-z0-9._:-]{1,123}$/, "Jelly account id");
+/** A Jelly host id (contract v1.1 §5 step 6). */
+export const JellyHost = z.string().regex(/^hst_[A-Za-z0-9._:-]{1,123}$/, "Jelly host id");
+/** A key id: printable ASCII, 1 to 200 characters. */
+export const JellyKid = z.string().regex(/^[\x21-\x7e]{1,200}$/, "key id");
+/** A compact JWS: three base64url segments. The bound is far above a Jelly resource token's size. */
+export const Jws = z
+    .string()
+    .max(8192)
+    .regex(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/, "compact JWS");
+/** The key a token is bound to (RFC 7800 `cnf.jwk`, contract v1.1 §3): exactly these three members. */
+export const CnfJwk = z.strictObject({ kty: z.literal("OKP"), crv: z.literal("Ed25519"), x: Key32 });
+/** The JWS header of a resource token (contract v1.1 §4). */
+export const JellyTokenHeader = z.looseObject({ alg: z.literal("EdDSA"), typ: z.literal("jelly-resource+jwt"), kid: JellyKid });
+const Seconds = z.number().int().nonnegative();
+/**
+ * How a token was minted when it was not by a host (contract v1.2 §12.4): `"device"`, a service's device
+ * that signed in through the browser. Read as a string, so a later value is refused by the verifier, not the schema.
+ */
+export const JELLY_DEVICE_SOURCE = "device";
+/**
+ * The claims of a resource token (contract v1.1 §4; v1.2 §12.4). `aud` is one string; `cnf` is exactly
+ * `{jwk}`. A host's token carries `hst`; a device's carries `src: "device"` and no `hst` (`verifyJellyToken`).
+ */
+export const JellyClaims = z
+    .looseObject({
+    iss: z.string().min(1).max(2048),
+    aud: z.string().min(1).max(2048),
+    sub: JellySubject,
+    email: z.string().min(3).max(320).optional(),
+    email_verified: z.literal(true).optional(),
+    name: z.string().max(256).optional(),
+    hst: JellyHost.optional(),
+    src: z.string().min(1).max(32).optional(),
+    cnf: z.strictObject({ jwk: CnfJwk }).optional(),
+    iat: Seconds,
+    exp: Seconds,
+    jti: z.string().min(1).max(128),
+})
+    .refine((claims) => (claims.email === undefined) === (claims.email_verified === undefined), {
+    message: "email and email_verified come together",
+});
+/** One public Ed25519 key of Jelly ID's key set (contract v1.1 §5). Entries of other key types are skipped. */
+export const JellyJwk = z.looseObject({ kty: z.literal("OKP"), crv: z.literal("Ed25519"), x: Key32, kid: JellyKid });
+/** `<issuer>/.well-known/jwks.json`. Each entry is read with `JellyJwk`; one that does not parse is skipped. */
+export const JellyJwks = z.looseObject({ keys: z.array(z.unknown()).max(64) });
+/** One key of `<issuer>/.well-known/jwks-history.json` (contract v1.1 §11): times are seconds since the epoch. */
+export const JellyHistoryKey = JellyJwk.extend({
+    nbf: Seconds,
+    retired_at: Seconds.nullable(),
+    revoked_at: Seconds.nullable().optional(),
+});
+/** `<issuer>/.well-known/jwks-history.json`, oldest first; it never shrinks. */
+export const JellyKeyHistory = z.looseObject({ keys: z.array(z.unknown()).max(4096) });
+/**
+ * A Jelly key a client has verified, as it persists it (its Jelly key archive, spec §15.2). `nbf`,
+ * `retiredAt` and `revokedAt` are the key history's (seconds) as last seen; `historyAt` is when that was (ms).
+ */
+export const ArchivedJellyKey = z.strictObject({
+    kid: JellyKid,
+    x: Key32,
+    nbf: Seconds.optional(),
+    retiredAt: Seconds.nullable().optional(),
+    revokedAt: Seconds.nullable().optional(),
+    historyAt: z.number().int().nonnegative().optional(),
+});
+// ---- the Jelly host (deployment "jelly", spec §8.11) ----
+/** The audience of every action grant and session ticket a Jelly host mints for Messaging (spec §8.11). */
+export const JELLY_SERVICE_AUDIENCE = "@joe-broadhead/opencode-messaging#service";
+/** A Jelly agent id (`agt`), the engine a session ticket names. */
+export const JellyAgentId = z.string().regex(/^agt_[A-Za-z0-9._:-]{1,123}$/, "Jelly agent id");
+/**
+ * The host's public action key (`--act-key`): exactly a public Ed25519 JWK. `kid`, `alg` and `use` may be present;
+ * any other member, a private `d` above all, is refused, and so is the daemon's start.
+ */
+export const ActKeyJwk = z.strictObject({
+    kty: z.literal("OKP"),
+    crv: z.literal("Ed25519"),
+    x: Key32,
+    kid: JellyKid.optional(),
+    alg: z.enum(["EdDSA", "Ed25519"]).optional(),
+    use: z.literal("sig").optional(),
+});
+/** The JWS header of an action grant (`jelly-act+jwt`). */
+export const JellyActHeader = z.looseObject({ alg: z.literal("EdDSA"), typ: z.literal("jelly-act+jwt"), kid: JellyKid });
+/** The JWS header of a session ticket (`jelly-session+jwt`). */
+export const JellySessionHeader = z.looseObject({ alg: z.literal("EdDSA"), typ: z.literal("jelly-session+jwt"), kid: JellyKid });
+/** base64url of a SHA-256 digest: 43 characters. */
+const Digest = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "base64url SHA-256");
+/**
+ * The claims of an action grant (spec §8.11). `act` is the IPC method it allows, or `host` for a host-scope grant.
+ * `in` (the digest of the call's params) and `cls` (the action class) are required for a method grant. `iss`, `dev`
+ * and `mbr` (the host's member who acted, Jelly D29) are Jelly's; the daemon takes no authority from them.
+ */
+export const JellyActClaims = z.looseObject({
+    aud: z.string().min(1).max(2048),
+    act: z.string().regex(/^[a-z][A-Za-z.]{0,63}$/, "an IPC method or host"),
+    in: Digest.optional(),
+    iat: Seconds,
+    exp: Seconds,
+    jti: z.string().regex(/^[\x21-\x7e]{1,128}$/, "printable jti"),
+    iss: z.string().max(2048).optional(),
+    dev: z.string().max(200).optional(),
+    cls: z.string().max(32).optional(),
+    mbr: z.string().max(200).optional(),
+});
+/** The claims of a session ticket (spec §8.11): the agent and the session name it may register. */
+export const JellySessionClaims = z.looseObject({
+    aud: z.string().min(1).max(2048),
+    agt: JellyAgentId,
+    name: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "lowercase session name"),
+    iat: Seconds,
+    exp: Seconds,
+});

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

@@ -0,0 +1,27 @@
+/**
+ * Realms (spec §5, "Realm and anchor"). A realm is the trust domain one daemon home belongs to: who the
+ * persons and their machines are, and which keys to seal to. A roster realm's id is the team id (§4) and its
+ * authority is the team's roster; a directory realm's id derives from its directory (§15.8) and its authority is
+ * the key directory's epoch log (§15).
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Hash, Key32 } from "./common.js";
+/** A realm's id. For a roster realm, the team id: the hash of the genesis entry; for a directory realm, `directoryRealmId`. */
+export const RealmId = Key32.describe("Realm id; for a roster realm, the team id");
+/** A roster realm's anchor: the sender's roster head (spec §4, §5). */
+export const RosterAnchor = z.object({
+    kind: z.literal("roster"),
+    seq: z.number().int().nonnegative(),
+    hash: Hash,
+});
+/** A directory realm's anchor (spec §5, §15.6): the sender's adopted signed tree head, by its size and root. */
+export const EpochAnchor = z.object({
+    kind: z.literal("epoch"),
+    size: z.number().int().positive(),
+    root: Hash,
+});
+/**
+ * What an envelope commits to of its sender's view of the realm, so a receiver can tell whether the
+ * sender saw more than it has (catch up first) or something else (a divergence).
+ */
+export const Anchor = z.discriminatedUnion("kind", [RosterAnchor, EpochAnchor]);