@joe-broadhead/messaging 0.7.1 → 0.9.0

package/dist/types/core/schema/ipc/surfaces.d.ts

@@ -1,40 +1,18 @@
-/**
- * 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 "zod";
-/** A conversation: `dm:<person>`, `channel:<name>` or `agent:<person>/<agent>`. */
-export declare const ConversationRef: z.ZodString;
-export type ConversationRef = z.infer<typeof ConversationRef>;
-/** A place in a conversation: a line's `seq` in a DM or a channel, an entry's `{at, id}` with an agent. */
-export declare const ConvPlace: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
-    at: z.ZodNumber;
-    id: z.ZodString;
-}, z.core.$strict>]>;
-export type ConvPlace = z.infer<typeof ConvPlace>;
-/** One conversation this person has (DMs with lines, channels it is in) and this device's read state. */
-export declare const ConvSummary: z.ZodObject<{
-    conversation: z.ZodString;
+/** Verified discovery metadata, without transcript or read-state placeholders. */
+export declare const ContactConversation: z.ZodObject<{
+    cid: z.ZodString;
     kind: z.ZodEnum<{
+        self: "self";
         channel: "channel";
+        group: "group";
         dm: "dm";
     }>;
-    lastAt: z.ZodOptional<z.ZodNumber>;
     name: z.ZodOptional<z.ZodString>;
-    lastSeq: z.ZodOptional<z.ZodNumber>;
-    readUpTo: z.ZodNumber;
-    unread: z.ZodNumber;
-}, z.core.$strip>;
-export type ConvSummary = z.infer<typeof ConvSummary>;
-/** A person of the realm, as verified (a roster realm: a team person). */
+    dmWith: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ContactConversation = z.infer<typeof ContactConversation>;
 export declare const PersonSummary: z.ZodObject<{
     person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
     name: z.ZodString;
@@ -53,20 +31,11 @@ export declare const PersonSummary: z.ZodObject<{
 }, z.core.$strip>;
 export type PersonSummary = z.infer<typeof PersonSummary>;
 export declare 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).
-     */
     readonly "contacts.list": {
         readonly params: z.ZodObject<{
             person: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
             includeOffline: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>;
-        /**
-         * `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").
-         */
         readonly result: z.ZodObject<{
             entries: z.ZodArray<z.ZodObject<{
                 address: z.ZodString;
@@ -91,33 +60,32 @@ export declare const SURFACE_METHODS: {
                 self: z.ZodBoolean;
                 expect: z.ZodOptional<z.ZodEnum<{
                     kept: "kept";
-                    next_turn: "next_turn";
                     wake: "wake";
+                    next_turn: "next_turn";
                     next_prompt: "next_prompt";
                     on_read: "on_read";
                     offline: "offline";
                 }>>;
             }, z.core.$strip>>;
             conversations: z.ZodArray<z.ZodObject<{
-                conversation: z.ZodString;
+                cid: z.ZodString;
                 kind: z.ZodEnum<{
+                    self: "self";
                     channel: "channel";
+                    group: "group";
                     dm: "dm";
                 }>;
-                lastAt: z.ZodOptional<z.ZodNumber>;
                 name: z.ZodOptional<z.ZodString>;
-                lastSeq: z.ZodOptional<z.ZodNumber>;
-                readUpTo: z.ZodNumber;
-                unread: z.ZodNumber;
-            }, z.core.$strip>>;
+                dmWith: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             reach: z.ZodArray<z.ZodObject<{
                 person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
                 can: z.ZodObject<{
                     chat: z.ZodBoolean;
                     agentMail: z.ZodBoolean;
                     ask: z.ZodEnum<{
-                        open: "open";
                         request: "request";
+                        open: "open";
                         no: "no";
                     }>;
                     trustedUntil: z.ZodOptional<z.ZodNumber>;
@@ -131,133 +99,12 @@ export declare const SURFACE_METHODS: {
             }, z.core.$strip>>;
         }, z.core.$strip>;
     };
-    /**
-     * 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.
-     */
-    readonly "msg.send": {
-        readonly params: z.ZodObject<{
-            key: z.ZodString;
-            to: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-            kind: z.ZodEnum<{
-                message: "message";
-                task: "task";
-            }>;
-            parts: z.ZodArray<z.ZodObject<{
-                text: z.ZodOptional<z.ZodString>;
-                raw: z.ZodOptional<z.ZodString>;
-                url: z.ZodOptional<z.ZodString>;
-                data: z.ZodOptional<z.ZodUnknown>;
-                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-                filename: z.ZodOptional<z.ZodString>;
-                mediaType: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>>;
-            contextId: z.ZodOptional<z.ZodString>;
-            taskId: z.ZodOptional<z.ZodString>;
-            replyTo: z.ZodOptional<z.ZodString>;
-            idempotencyKey: z.ZodOptional<z.ZodString>;
-            messageId: z.ZodOptional<z.ZodString>;
-            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            wake: z.ZodOptional<z.ZodBoolean>;
-            request: z.ZodOptional<z.ZodObject<{
-                contact: z.ZodString;
-            }, z.core.$strict>>;
-            onBehalfOf: z.ZodOptional<z.ZodObject<{
-                taskId: z.ZodString;
-                scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                maxDepth: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            results: z.ZodArray<z.ZodObject<{
-                to: z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodString]>;
-                envelopeId: z.ZodString;
-                messageId: z.ZodString;
-                taskId: z.ZodOptional<z.ZodString>;
-                contextId: z.ZodString;
-                stage: z.ZodEnum<{
-                    accepted: "accepted";
-                    relayed: "relayed";
-                    delivered: "delivered";
-                    held: "held";
-                    handed_to_agent: "handed_to_agent";
-                    read: "read";
-                    replied: "replied";
-                    rejected: "rejected";
-                    expired: "expired";
-                }>;
-                code: z.ZodOptional<z.ZodEnum<{
-                    expired: "expired";
-                    invalid_request: "invalid_request";
-                    not_member: "not_member";
-                    bad_signature: "bad_signature";
-                    unknown_session: "unknown_session";
-                    ambiguous_address: "ambiguous_address";
-                    no_recipients: "no_recipients";
-                    unknown_address: "unknown_address";
-                    refused: "refused";
-                    declined: "declined";
-                    request_required: "request_required";
-                    rate_limited: "rate_limited";
-                    loop_guard: "loop_guard";
-                    too_large: "too_large";
-                    secret_refused: "secret_refused";
-                    duplicate: "duplicate";
-                    relay_unavailable: "relay_unavailable";
-                    not_found: "not_found";
-                    invalid_state: "invalid_state";
-                    forbidden: "forbidden";
-                    guarded_turn: "guarded_turn";
-                    roster_conflict: "roster_conflict";
-                    invite_invalid: "invite_invalid";
-                    no_identity: "no_identity";
-                    binding_invalid: "binding_invalid";
-                    jelly_unavailable: "jelly_unavailable";
-                    log_conflict: "log_conflict";
-                    conv_conflict: "conv_conflict";
-                    stale_epoch: "stale_epoch";
-                    device_limit: "device_limit";
-                    admission_required: "admission_required";
-                    admission_invalid: "admission_invalid";
-                    directory_inconsistent: "directory_inconsistent";
-                    unknown_device: "unknown_device";
-                    directory_unavailable: "directory_unavailable";
-                    login_unsupported: "login_unsupported";
-                    login_denied: "login_denied";
-                    grant_required: "grant_required";
-                    grant_invalid: "grant_invalid";
-                    ticket_required: "ticket_required";
-                    ticket_invalid: "ticket_invalid";
-                    daemon_unavailable: "daemon_unavailable";
-                    daemon_mismatch: "daemon_mismatch";
-                    store_refused: "store_refused";
-                    internal: "internal";
-                }>>;
-                expect: z.ZodOptional<z.ZodEnum<{
-                    kept: "kept";
-                    next_turn: "next_turn";
-                    wake: "wake";
-                    next_prompt: "next_prompt";
-                    on_read: "on_read";
-                    offline: "offline";
-                }>>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>;
-    };
-    /**
-     * 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. */
     readonly "item.read": {
         readonly params: z.ZodObject<{
             key: z.ZodString;
             id: z.ZodString;
+            cid: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         readonly result: z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"received">;
@@ -265,12 +112,14 @@ export declare const SURFACE_METHODS: {
                 id: z.ZodString;
                 key: z.ZodString;
                 from: z.ZodObject<{
-                    address: z.ZodString;
                     person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
                     agent: z.ZodOptional<z.ZodString>;
-                    device: z.ZodString;
-                    label: z.ZodString;
+                    address: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+                    device: z.ZodOptional<z.ZodString>;
+                    label: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
+                cid: z.ZodOptional<z.ZodString>;
+                eventId: z.ZodOptional<z.ZodString>;
                 kind: z.ZodEnum<{
                     message: "message";
                     task: "task";
@@ -325,7 +174,7 @@ export declare const SURFACE_METHODS: {
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"sent">;
             envelopeId: z.ZodString;
-            to: z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodString]>;
+            to: z.ZodString;
             stage: z.ZodEnum<{
                 accepted: "accepted";
                 relayed: "relayed";
@@ -362,6 +211,7 @@ export declare const SURFACE_METHODS: {
                     refused: "refused";
                     declined: "declined";
                     request_required: "request_required";
+                    peer_outdated: "peer_outdated";
                     rate_limited: "rate_limited";
                     loop_guard: "loop_guard";
                     too_large: "too_large";
@@ -379,6 +229,7 @@ export declare const SURFACE_METHODS: {
                     jelly_unavailable: "jelly_unavailable";
                     log_conflict: "log_conflict";
                     conv_conflict: "conv_conflict";
+                    conflict: "conflict";
                     stale_epoch: "stale_epoch";
                     device_limit: "device_limit";
                     admission_required: "admission_required";
@@ -401,202 +252,6 @@ export declare const SURFACE_METHODS: {
             }, z.core.$strip>>;
         }, z.core.$strip>], "kind">;
     };
-    /**
-     * 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}`.
-     */
-    readonly "conv.read": {
-        readonly params: z.ZodObject<{
-            key: z.ZodOptional<z.ZodString>;
-            conversation: z.ZodString;
-            thread: z.ZodOptional<z.ZodString>;
-            before: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
-                at: z.ZodNumber;
-                id: z.ZodString;
-            }, z.core.$strict>]>>;
-            after: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
-                at: z.ZodNumber;
-                id: z.ZodString;
-            }, z.core.$strict>]>>;
-            limit: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>;
-        readonly result: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"lines">;
-            lines: z.ZodArray<z.ZodObject<{
-                id: z.ZodString;
-                seq: z.ZodNumber;
-                at: z.ZodNumber;
-                person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-                agent: z.ZodOptional<z.ZodString>;
-                direction: z.ZodEnum<{
-                    out: "out";
-                    in: "in";
-                }>;
-                body: z.ZodString;
-                thread: z.ZodOptional<z.ZodString>;
-                state: z.ZodOptional<z.ZodEnum<{
-                    delivered: "delivered";
-                    held: "held";
-                    refused: "refused";
-                    sent: "sent";
-                }>>;
-                refused: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>>;
-                notice: z.ZodOptional<z.ZodLiteral<true>>;
-            }, z.core.$strip>>;
-            more: z.ZodBoolean;
-        }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"agent">;
-            entries: z.ZodArray<z.ZodObject<{
-                id: z.ZodString;
-                kind: z.ZodEnum<{
-                    task: "task";
-                    mail: "mail";
-                }>;
-                direction: z.ZodEnum<{
-                    out: "out";
-                    in: "in";
-                }>;
-                peer: z.ZodString;
-                at: z.ZodNumber;
-                text: z.ZodOptional<z.ZodString>;
-                taskId: z.ZodOptional<z.ZodString>;
-                stage: z.ZodOptional<z.ZodEnum<{
-                    accepted: "accepted";
-                    relayed: "relayed";
-                    delivered: "delivered";
-                    held: "held";
-                    handed_to_agent: "handed_to_agent";
-                    read: "read";
-                    replied: "replied";
-                    rejected: "rejected";
-                    expired: "expired";
-                }>>;
-                role: z.ZodOptional<z.ZodEnum<{
-                    requester: "requester";
-                    executor: "executor";
-                }>>;
-                state: z.ZodOptional<z.ZodEnum<{
-                    TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
-                    TASK_STATE_WORKING: "TASK_STATE_WORKING";
-                    TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
-                    TASK_STATE_FAILED: "TASK_STATE_FAILED";
-                    TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
-                    TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
-                    TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
-                    TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
-                }>>;
-            }, z.core.$strip>>;
-            more: z.ZodBoolean;
-        }, z.core.$strip>], "kind">;
-    };
-    /** Agent tier. Full-text search over the DM and channel lines `conv.read` can read, newest first. */
-    readonly search: {
-        readonly params: z.ZodObject<{
-            query: z.ZodString;
-            conversation: z.ZodOptional<z.ZodString>;
-            limit: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            hits: z.ZodArray<z.ZodObject<{
-                id: z.ZodString;
-                seq: z.ZodNumber;
-                at: z.ZodNumber;
-                person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-                agent: z.ZodOptional<z.ZodString>;
-                direction: z.ZodEnum<{
-                    out: "out";
-                    in: "in";
-                }>;
-                body: z.ZodString;
-                thread: z.ZodOptional<z.ZodString>;
-                state: z.ZodOptional<z.ZodEnum<{
-                    delivered: "delivered";
-                    held: "held";
-                    refused: "refused";
-                    sent: "sent";
-                }>>;
-                refused: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>>;
-                notice: z.ZodOptional<z.ZodLiteral<true>>;
-                conversation: z.ZodString;
-            }, z.core.$strip>>;
-        }, z.core.$strip>;
-    };
-    /**
-     * 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.
-     */
-    readonly "conv.list": {
-        readonly params: z.ZodObject<{
-            limit: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            conversations: z.ZodArray<z.ZodObject<{
-                conversation: z.ZodString;
-                kind: z.ZodEnum<{
-                    channel: "channel";
-                    dm: "dm";
-                }>;
-                lastAt: z.ZodOptional<z.ZodNumber>;
-                name: z.ZodOptional<z.ZodString>;
-                lastSeq: z.ZodOptional<z.ZodNumber>;
-                readUpTo: z.ZodNumber;
-                unread: z.ZodNumber;
-            }, z.core.$strip>>;
-        }, z.core.$strip>;
-    };
-    /**
-     * 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.
-     */
-    readonly "conv.markRead": {
-        readonly params: z.ZodObject<{
-            conversation: z.ZodString;
-            upTo: z.ZodNumber;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            readUpTo: z.ZodNumber;
-            unread: z.ZodNumber;
-        }, z.core.$strip>;
-    };
-    /**
-     * 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.
-     */
-    readonly "conv.subscribe": {
-        readonly params: z.ZodObject<{
-            since: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            seq: z.ZodNumber;
-            gap: z.ZodBoolean;
-        }, z.core.$strip>;
-    };
-    /**
-     * 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.
-     */
-    readonly "person.send": {
-        readonly params: z.ZodObject<{
-            conversation: z.ZodString;
-            text: z.ZodString;
-            thread: z.ZodOptional<z.ZodString>;
-            clientId: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>;
-        readonly result: z.ZodObject<{
-            id: z.ZodString;
-            conversation: z.ZodString;
-        }, z.core.$strip>;
-    };
-    /** Human tier. The persons of the realm whose handle starts with `query` (all with none), at most `limit` (default 50). */
     readonly "people.search": {
         readonly params: z.ZodObject<{
             query: z.ZodOptional<z.ZodString>;
@@ -621,60 +276,4 @@ export declare const SURFACE_METHODS: {
             }, z.core.$strip>>;
         }, z.core.$strip>;
     };
-    /** Human tier. One person and their current devices, as verified. `not_found` for a person this realm does not know. */
-    readonly "people.get": {
-        readonly params: z.ZodObject<{
-            person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-        }, z.core.$strict>;
-        /** A device's `away`: its latest presence, still fresh, says no window of the person is visible on it (spec §6.5). */
-        readonly result: z.ZodObject<{
-            person: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-            name: z.ZodString;
-            handle: z.ZodString;
-            org: z.ZodEnum<{
-                other: "other";
-                none: "none";
-                same: "same";
-            }>;
-            vouched: z.ZodEnum<{
-                admin: "admin";
-                device: "device";
-                jelly: "jelly";
-                service: "service";
-            }>;
-            devices: z.ZodArray<z.ZodObject<{
-                device: z.ZodString;
-                label: z.ZodString;
-                self: z.ZodBoolean;
-                away: z.ZodOptional<z.ZodLiteral<true>>;
-            }, z.core.$strip>>;
-            deviceChanges: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                change: z.ZodEnum<{
-                    removed: "removed";
-                    replaced: "replaced";
-                    added: "added";
-                    vouched: "vouched";
-                }>;
-                device: z.ZodString;
-                label: z.ZodString;
-                kind: z.ZodOptional<z.ZodEnum<{
-                    "jelly-host": "jelly-host";
-                    laptop: "laptop";
-                    server: "server";
-                    other: "other";
-                }>>;
-                vouch: z.ZodEnum<{
-                    admin: "admin";
-                    device: "device";
-                    jelly: "jelly";
-                }>;
-                via: z.ZodOptional<z.ZodEnum<{
-                    host: "host";
-                    browser: "browser";
-                }>>;
-                approver: z.ZodOptional<z.ZodString>;
-                at: z.ZodNumber;
-            }, z.core.$strip>>>;
-        }, z.core.$strip>;
-    };
 };