@joe-broadhead/messaging 0.7.0 → 0.8.0

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

@@ -1,223 +1,40 @@
-/**
- * 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).
- */
+/** Discovery and task-envelope reads. Conversation methods live in conversations.ts. */
 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 { Message } from "../a2a.js";
+import { DeliveryStage, Millis, PersonId, Ulid } from "../common.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(),
+import { ConvId, ConvKind, ParticipantId } from "../conversation.js";
+import { DirectoryEntry, InboxItem, SendTarget, SessionKey } from "./shapes.js";
+/** Verified discovery metadata, without transcript or read-state placeholders. */
+export const ContactConversation = z.strictObject({
+    cid: ConvId, kind: ConvKind, name: z.string().max(200).optional(), dmWith: ParticipantId.optional(),
 });
-/** 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) }),
+        result: z.object({ entries: z.array(DirectoryEntry), conversations: z.array(ContactConversation), 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.
-     */
+    /** A received item, or the delivery records of a sent task envelope. */
     "item.read": {
-        params: z.strictObject({ key: SessionKey, id: Ulid }),
+        params: z.strictObject({ key: SessionKey, id: Ulid, cid: ConvId.optional() }),
         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,
+                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(),
-        }),
-    },
 };

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

@@ -0,0 +1,31 @@
+/** Retained task envelopes, independent of conversation lines. */
+import { z } from "../../../vendor/zod/index.js";
+import { Part } from "../a2a.js";
+import { Address, LIMITS, Ulid } from "../common.js";
+import { DelegationScope } from "../delegation.js";
+import { SendResult, SessionKey } from "./shapes.js";
+const fields = {
+    key: SessionKey,
+    to: Address,
+    parts: z.array(Part).min(1).max(LIMITS.partsPerMessage),
+    contextId: z.string().max(128).optional(),
+    replyTo: Ulid.optional(),
+    idempotencyKey: z.string().min(1).max(200).optional(),
+    messageId: z.string().min(1).max(128).optional(),
+    metadata: z.record(z.string(), z.unknown()).refine((m) => new TextEncoder().encode(JSON.stringify(m)).length <= 16_384, { message: "metadata is limited to 16384 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(),
+};
+const result = z.object({ results: z.array(SendResult) });
+export const TASK_SEND_METHODS = {
+    "task.create": {
+        params: z.strictObject({ ...fields, onBehalfOf: z.strictObject({
+                taskId: Ulid,
+                scope: z.array(DelegationScope).max(LIMITS.delegationScopes).optional(),
+                maxDepth: z.number().int().min(1).max(LIMITS.delegationDepth).optional(),
+            }).optional() }),
+        result,
+    },
+    "task.continue": { params: z.strictObject({ ...fields, taskId: Ulid }), result },
+};

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

@@ -15,21 +15,25 @@
  *
  * 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).
+ * The daemon pushes notifications `{"jsonrpc":"2.0","method":"event","params":Event}` to connections
+ * subscribed to the event's key. Notice subscriptions are human-only. Conversations use `conv.sync`.
  */
 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 { AgentKind, DeliveryStage, DeliveryTier, EncKey, Hash, MachineId, MachineLabel, MemberRole, Millis, PersonId, PersonName, RelayUrl, 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 { 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";
+import { LIVE_CONVERSATION_METHODS, CONVERSATION_TIERS } from "./ipc/conversations.js";
+import { TASK_SEND_METHODS } from "./ipc/tasks.js";
+import { ConvId } from "./conversation.js";
+const conversationTier = (tier) => Object.keys(LIVE_CONVERSATION_METHODS)
+    .filter((m) => CONVERSATION_TIERS[m] === tier);
 export * from "./ipc/shapes.js";
 export * from "./ipc/surfaces.js";
 export * from "./ipc/jelly.js";
@@ -120,6 +124,7 @@ export const InviteSummary = z.object({
 /** Method table: name → params/result schemas. The daemon validates params; clients validate results. */
 export const IPC_METHODS = {
     ...DEVICE_METHODS,
+    ...TASK_SEND_METHODS,
     "daemon.status": { params: Empty, result: DaemonStatus },
     /** Human CLI only: replies, then shuts the daemon down cleanly. */
     "daemon.stop": { params: Empty, result: Ok },
@@ -166,11 +171,11 @@ export const IPC_METHODS = {
      * 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() }),
+        params: z.strictObject({ key: SessionKey, id: Ulid, cid: ConvId.optional(), 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"]) }),
+        params: z.strictObject({ key: SessionKey, id: Ulid, cid: ConvId.optional(), stage: z.enum(["handed_to_agent", "read"]) }),
         result: Ok,
     },
     "task.list": {
@@ -291,24 +296,10 @@ export const IPC_METHODS = {
      * 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,
+    ...LIVE_CONVERSATION_METHODS,
 };
 /**
  * The agent tier (design §7.5): the methods an agent-facing client may call, and exactly what the
@@ -325,13 +316,13 @@ export const AGENT_METHODS = [
     "session.unregister",
     "events.subscribe",
     "contacts.list",
-    "msg.send",
     "inbox.list",
     "inbox.get",
     "inbox.ack",
     "item.read",
-    "conv.read",
-    "search",
+    ...conversationTier("agent"),
+    "task.create",
+    "task.continue",
     "task.list",
     "task.get",
     "task.update",
@@ -343,13 +334,9 @@ export const AGENT_METHODS = [
  * `conv.read` is in both tiers.
  */
 export const HUMAN_METHODS = [
-    "conv.list",
-    "conv.read",
-    "conv.markRead",
-    "conv.subscribe",
-    "person.send",
+    ...conversationTier("human"),
+    ...conversationTier("agent"),
     "people.search",
-    "people.get",
     "grant.list",
     "grant.set",
     "grant.set.preview",
@@ -359,8 +346,6 @@ export const HUMAN_METHODS = [
     "contact.request",
     "contact.request.preview",
     "card.get",
-    "agents.list",
-    "agents.read",
     "notice.subscribe",
     "notice.list",
     "notice.ack",
@@ -368,10 +353,6 @@ export const HUMAN_METHODS = [
     "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
@@ -434,13 +415,6 @@ export const IpcEvent = z.discriminatedUnion("type", [
     /** 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.

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

@@ -7,6 +7,7 @@ export { encodeTicket } from "./roster.js";
 export { grantHash } from "./delegation.js";
 export { signJellyToken } from "./directory/jelly-issuer.js";
 export { jellyHostDouble } from "./jelly-host-double.js";
+export { sealConvMetaWith, sealConvMsgWith, sealConvStateWith, sealKeyShareWith } from "./conversation/seal.js";
 /**
  * Narrows a result whose `kind` tells its shape (`item.read`, `conv.read`) to the expected kind, and
  * throws with both kinds named otherwise: `client.call("item.read", p).then(asKind("received"))`.

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

@@ -3,4 +3,4 @@
  * its IPC hello and a client compares it with its own (spec §8.2). A test keeps it equal to the
  * root package.json.
  */
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.0";

package/dist/lib/modules/ipc/client.js

@@ -1,6 +1,6 @@
 import net from "node:net";
 import { dirname } from "node:path";
-import { ErrorCode, IPC_METHODS, IPC_PROTOCOL, IpcEvent, IpcHello, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, VERSION, parseWire, } from "../core/index.js";
+import { ErrorCode, CONVERSATION_METHODS, IPC_METHODS, IPC_PROTOCOL, IpcEvent, IpcHello, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, VERSION, parseWire, } from "../core/index.js";
 import { encodeLine, LineDecoder } from "./framing.js";
 import { configuredDaemonUid, IS_WINDOWS, messagingHome, socketPath as defaultSocketPath } from "./paths.js";
 import { readPointer } from "./pipes.js";
@@ -153,6 +153,13 @@ export class MessagingClient {
         return this.isClosed;
     }
     call(method, params, options = {}) {
+        return this.callWith(method, params, IPC_METHODS[method].result, options);
+    }
+    /** The staged conversation contract. Use only with a server that opted into it, until cut-over. */
+    callConversation(method, params, options = {}) {
+        return this.callWith(method, params, CONVERSATION_METHODS[method].result, options);
+    }
+    callWith(method, params, result, options) {
         if (this.isClosed)
             return Promise.reject(new MessagingError("daemon_unavailable", "connection to the Messaging daemon is closed"));
         if (options.signal?.aborted)
@@ -168,6 +175,7 @@ export class MessagingClient {
             options.signal?.addEventListener("abort", onAbort, { once: true });
             this.pending.set(id, {
                 method,
+                result,
                 resolve: resolve,
                 reject,
                 cleanup: () => {
@@ -236,7 +244,7 @@ export class MessagingClient {
             this.settle(message.id, undefined, toError(message.error));
             return;
         }
-        const checked = IPC_METHODS[pending.method].result.safeParse(message.result);
+        const checked = pending.result.safeParse(message.result);
         if (!checked.success) {
             this.settle(message.id, undefined, new MessagingError("internal", `daemon returned an invalid result for ${pending.method}`));
             return;

package/dist/lib/modules/ipc/server.js

@@ -2,7 +2,7 @@ import { mkdirSync } from "node:fs";
 import { chmod, chown, rm, stat } from "node:fs/promises";
 import net from "node:net";
 import { dirname } from "node:path";
-import { AGENT_METHODS, IPC_METHODS, IPC_PROTOCOL, IpcEvent, VERSION, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, parseWire, } from "../core/index.js";
+import { AGENT_METHODS, CONVERSATION_METHODS, CONVERSATION_TIERS, IPC_METHODS, IPC_PROTOCOL, IpcEvent, VERSION, LIMITS, MESSAGING_ERROR_RPC_CODE, MessagingError, parseWire, } from "../core/index.js";
 import { encodeLine, LineDecoder, LineTooLongError } from "./framing.js";
 import { IS_WINDOWS, MAX_SOCKET_PATH_BYTES } from "./paths.js";
 import { newPipeName, readPointer, writePointer } from "./pipes.js";
@@ -29,6 +29,13 @@ function agentTierRefusal(method) {
  * `group` is refused there: Node cannot give a pipe to a group.
  */
 export async function createIpcServer(options) {
+    return createServer(options, false);
+}
+/** Used only by the test entry: never changes the real daemon's method table. */
+export async function createConversationIpcServerForTesting(options) {
+    return createServer({ ...options, handlers: options.handlers }, true);
+}
+async function createServer(options, conversations) {
     const path = options.socketPath;
     if (options.tier !== "agent" && options.tier !== "admin")
         throw new MessagingError("invalid_request", "an IPC server needs a tier: agent or admin");
@@ -100,14 +107,16 @@ export async function createIpcServer(options) {
         const { id, method } = request;
         if (id === undefined)
             return; // client notifications are not part of the API
-        const spec = Object.hasOwn(IPC_METHODS, method) ? IPC_METHODS[method] : undefined;
+        const methods = conversations ? CONVERSATION_METHODS : IPC_METHODS;
+        const spec = Object.hasOwn(methods, method) ? methods[method] : undefined;
         const handler = options.handlers[method];
-        if (!spec || (!handler && method !== "events.subscribe")) {
+        if (!spec || (!handler && (conversations || method !== "events.subscribe"))) {
             ctx.send({ jsonrpc: "2.0", id, error: { code: RPC.methodNotFound, message: `method not found: ${method}` } });
             return;
         }
         // The tier is checked before the params are read, so the agent socket tells nothing about the rest.
-        if (options.tier === "agent" && !AGENT_TIER.has(method)) {
+        const agentAllowed = conversations ? CONVERSATION_TIERS[method] === "agent" : AGENT_TIER.has(method);
+        if (options.tier === "agent" && !agentAllowed) {
             ctx.send({ jsonrpc: "2.0", id, error: toRpcError(new MessagingError("forbidden", agentTierRefusal(method))) });
             return;
         }
@@ -130,7 +139,7 @@ export async function createIpcServer(options) {
         try {
             const result = handler ? await handler(parsed.data, ctx, authority) : { ok: true };
             // Subscriptions start only once the handler has accepted the keys.
-            if (method === "events.subscribe")
+            if (!conversations && method === "events.subscribe")
                 for (const key of parsed.data.keys)
                     ctx.subscriptions.add(key);
             const checked = spec.result.safeParse(result);

package/dist/lib/modules/ipc/testing.js

@@ -1,10 +1,10 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { IPC_METHODS, MessagingError } from "../core/index.js";
+import { CONVERSATION_METHODS, IPC_METHODS, MessagingError } from "../core/index.js";
 import { MessagingClient } from "./client.js";
 import { IS_WINDOWS, MAX_SOCKET_PATH_BYTES, socketPath as socketOf } from "./paths.js";
-import { createIpcServer } from "./server.js";
+import { createConversationIpcServerForTesting, createIpcServer } from "./server.js";
 import { newPipeName, readPointer, writePointer } from "./pipes.js";
 import { securePrivate } from "./windows-acl.js";
 /**
@@ -55,36 +55,30 @@ export function rawEndpoint(socketPath) {
 export function ulid(n) {
     return `01JC${String(n).padStart(22, "0")}`;
 }
-/** Polls `predicate` every 10 ms until it holds; throws after `timeoutMs`. */
-export async function until(predicate, timeoutMs = 3_000, what = "condition") {
-    const deadline = Date.now() + timeoutMs;
+/** Polls state with no notification; the enclosing test's timeout is the single bound. Legacy timeout and label are ignored. */
+export async function until(predicate, _timeoutMs, _what = "condition") {
     while (!predicate()) {
-        if (Date.now() > deadline)
-            throw new Error(`timed out waiting for ${what}`);
-        await new Promise((resolve) => setTimeout(resolve, 10));
+        await new Promise((resolve) => setTimeout(resolve, 10).unref());
     }
 }
 export async function recordingDaemon(options = {}) {
+    const conversationMode = "methods" in options && options.methods !== undefined;
+    if (conversationMode && options.methods !== CONVERSATION_METHODS)
+        throw new TypeError("recordingDaemon: unsupported method table");
     const owned = options.at === undefined;
     const dir = options.at?.dir ?? tempSocketPath(options.prefix).dir;
     const socketPath = socketOf(dir, "agent");
     const adminSocketPath = socketOf(dir, "admin");
     const handlers = { ...options.handlers };
     const calls = [];
-    const convSubscribers = new Set();
     const dispatch = {};
-    for (const method of Object.keys(IPC_METHODS)) {
+    for (const method of Object.keys(conversationMode ? CONVERSATION_METHODS : IPC_METHODS)) {
         dispatch[method] = async (params, ctx) => {
             calls.push({ method, params: structuredClone(params) });
             const handler = handlers[method];
             if (!handler)
                 throw new MessagingError("forbidden", `fake daemon: no handler for ${method}`);
-            const result = await handler(params, ctx);
-            if (method === "conv.subscribe") {
-                convSubscribers.add(ctx);
-                ctx.signal.addEventListener("abort", () => convSubscribers.delete(ctx));
-            }
-            return result;
+            return handler(params, ctx);
         };
     }
     let servers;
@@ -92,8 +86,9 @@ export async function recordingDaemon(options = {}) {
         if (servers)
             return;
         const version = options.version === undefined ? {} : { version: options.version };
-        const agent = await createIpcServer({ socketPath, tier: "agent", handlers: dispatch, ...version });
-        const admin = await createIpcServer({ socketPath: adminSocketPath, tier: "admin", handlers: dispatch, ...version }).catch(async (error) => {
+        const serve = conversationMode ? createConversationIpcServerForTesting : createIpcServer;
+        const agent = await serve({ socketPath, tier: "agent", handlers: dispatch, ...version });
+        const admin = await serve({ socketPath: adminSocketPath, tier: "admin", handlers: dispatch, ...version }).catch(async (error) => {
             await agent.close();
             throw error;
         });
@@ -116,17 +111,12 @@ export async function recordingDaemon(options = {}) {
         callsTo,
         last: (method) => callsTo(method).at(-1),
         handle: (method, handler) => {
-            ;
             handlers[method] = handler;
         },
         publish: (event) => {
             for (const server of servers ?? [])
                 server.publish(event);
         },
-        conv: (event) => {
-            for (const ctx of convSubscribers)
-                ctx.notify(event);
-        },
         connect: (tier = "agent") => MessagingClient.connect({ socketPath: tier === "agent" ? socketPath : adminSocketPath, connectTimeoutMs: 500 }),
         connections: () => (servers ?? []).reduce((sum, server) => sum + server.connections(), 0),
         start,