@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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(),
+        }),
+    },
+};