@joe-broadhead/messaging 0.7.1 → 0.8.0

package/dist/lib/modules/core/agent/operations.js

@@ -1,34 +1,15 @@
 import { randomUUID } from "node:crypto";
-import { a2aTaskState, conversationOf, decodeToolCursor, DONE_STATES, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, TOOL_REMEDIES, } from "../agent-tools.js";
-import { LIMITS } from "../schema/common.js";
+import { a2aTaskState, DONE_STATES, taskStateName, } from "../agent-tools.js";
 import { MessagingError } from "../schema/errors.js";
 import { canTransition, isTerminal } from "../task.js";
-import { agentCan, conversationOfPeer, isoOf, presentAgent, presentConvEntry, presentInboxItem, presentLine, presentMail, presentSent, presentTask, presentTaskItem, presentTaskView, } from "./present.js";
-import { compact, delegationPrompt, EXPECT_TEXT, validatedAddress } from "./text.js";
+import { agentCan, isoOf, presentAgent, presentTaskEnvelope, presentTask, presentTaskItem, presentTaskView, } from "./present.js";
+import { compact, validatedAddress } from "./text.js";
 const DEFAULT_CONTACTS = 20;
-const DEFAULT_INBOX = 20;
-const DEFAULT_PAGE = 30;
 const DEFAULT_TASKS = 20;
 /** The daemon's largest `inbox.list` and `task.list` page. */
 const PAGE = 100;
 /** Pages a filtered task listing reads at most. */
 const TASK_PAGES = 10;
-const NOTE = {
-    line: "A line to a person: they see it in their chats, and it wakes no agent. messaging_read {with} shows when it is delivered.",
-    post: "Posted: everyone in the channel sees it, and it wakes no agent.",
-    sent: "Sent. messaging_read {id} shows how far it got.",
-    task: " Follow the task with messaging_read {id: taskId}.",
-    held: "Their person will see a request card first; you will be told when they answer. Follow it with messaging_read {id}.",
-    suggest: "Your person sees your line and your suggestion of that contact; only they can send a message request, and you are not told what they decide.",
-};
-/** `me`, or one's own person by name: the person's own conversation, `dm:<self>` (spec §6.8, design §5.9). */
-function ownPerson(address, self) {
-    return address.kind === "me" || (address.kind === "person" && address.person === self);
-}
-/** `me` as the person it stands for, for the conversation checks and the daemon. */
-function asPerson(address, self) {
-    return address.kind === "me" ? { kind: "person", person: self } : address;
-}
 export class Operations {
     ctx;
     constructor(ctx) {
@@ -40,15 +21,6 @@ export class Operations {
     consent(person, s) {
         return this.ctx.consent(person, s.person);
     }
-    /** Refuses a chat conversation this client may not reach, before any daemon call. */
-    reachable(target, field) {
-        const { access } = this.ctx;
-        if (target.kind === "person" && !access.dms)
-            fail("forbidden", `${field}: conversations with persons are not available to this client`);
-        if (target.kind === "channel" && access.channels !== undefined && !access.channels.has(target.name)) {
-            fail("forbidden", `${field}: this client may reach only the channels its user allowed: ${[...access.channels].map((name) => `#${name}`).join(", ")}`);
-        }
-    }
     // ---- contacts ----
     async contacts(sessionID, input, signal) {
         const s = await this.ctx.session(sessionID, signal);
@@ -60,10 +32,11 @@ export class Operations {
         const byPerson = new Map();
         for (const entry of others)
             byPerson.set(entry.person, [...(byPerson.get(entry.person) ?? []), entry]);
-        const unread = new Map(rooms.map((room) => [room.conversation, room.unread]));
         for (const room of rooms)
-            if (room.kind === "dm")
-                byPerson.set(room.conversation.slice("dm:".length), byPerson.get(room.conversation.slice("dm:".length)) ?? []);
+            if (room.kind === "dm" && room.dmWith) {
+                const person = room.dmWith.split("/")[0];
+                byPerson.set(person, byPerson.get(person) ?? []);
+            }
         const name = (text) => this.framer.wrap(text, {}, 64);
         // What each person's card says (spec §6.9, "Contact cards"), or the defaults; the daemon's, never a peer's text.
         const cards = new Map(reach.map((r) => [r.person, r]));
@@ -106,25 +79,23 @@ export class Operations {
                     can: card
                         ? { ...card, chat: card.chat && this.ctx.access.dms }
                         : { chat: !self && this.ctx.access.dms, agentMail: can.some((c) => c.agentMail), ask: can.some((c) => c.ask === "open") ? "open" : "no", source: "default" },
-                    ...(unread.get(`dm:${person}`) ? { unread: unread.get(`dm:${person}`) } : {}),
                 },
             };
         });
         const allowed = this.ctx.access.channels;
         const channels = rooms
-            .filter((room) => room.kind === "channel" && (allowed === undefined || allowed.has(room.conversation.slice("channel:".length))))
+            .filter((room) => room.kind === "channel" && (allowed === undefined || allowed.has(room.cid)))
             .map((room) => {
-            const local = room.conversation.slice("channel:".length);
+            const local = room.cid;
             return {
                 match: [local, room.name ?? local],
                 contact: {
-                    address: `#${local}`,
+                    address: local,
                     kind: "channel",
                     name: name(room.name ?? local),
                     org: "same",
                     presence: "unknown",
                     can: { chat: true, agentMail: false, ask: "no", source: "default" },
-                    ...(room.unread > 0 ? { unread: room.unread } : {}),
                 },
             };
         });
@@ -149,286 +120,37 @@ export class Operations {
             ...(contacts.length > 0 ? { notice: this.framer.notice() } : {}),
         };
     }
-    // ---- send ----
-    /**
-     * Checks a send without side effects: the address, the peer-turn allowance, what may go to whom,
-     * what `replyTo` and `onBehalfOf` name. Returns what the send will do, for the permission prompt.
-     */
-    async planSend(sessionID, input, signal) {
-        const s = await this.ctx.session(sessionID, signal);
-        const to = parseToolAddress(input.to, s.person, "to");
-        const own = ownPerson(to, s.person);
-        if (s.peer !== undefined && !own && !((to.kind === "person" || to.kind === "agent") && to.person === s.peer)) {
-            throw fail("guarded_turn", "to: this turn was started by a teammate's agent, so it can send only to that teammate or to your person");
-        }
-        const conversation = conversationOf(to, s.person);
-        // Spec §6.9, "Message requests": an agent never sends a request; it asks its own person to.
-        if (input.request !== undefined && !own)
-            throw fail("invalid_request", 'request: only with to: "me"; your person sends the message request');
-        if (to.kind !== "agent") {
-            const target = asPerson(to, s.person);
-            this.reachable(target, "to");
-            if (input.ask && own)
-                throw fail("invalid_request", "ask: a request card to your own person is not in this build; send them a line (without ask)");
-            if (input.ask)
-                throw fail("invalid_request", "ask: a task goes to an agent, <person>/<agent>");
-            if (input.files)
-                throw fail("invalid_request", "files: files go to an agent, never in a chat line");
-            if (input.onBehalfOf)
-                throw fail("invalid_request", "onBehalfOf: only with ask, to an agent");
-            if (input.text.length > LIMITS.chatChars)
-                throw fail("too_large", `text: a chat line is at most ${LIMITS.chatChars} characters`);
-            return {
-                kind: target.kind === "person" ? "line" : "post",
-                to,
-                conversation,
-                target: target.kind === "person" ? target.person : `#${target.name}`,
-                text: input.text,
-                ...(input.replyTo !== undefined ? { thread: input.replyTo } : {}),
-                ...(input.request !== undefined ? { request: input.request } : {}),
-            };
-        }
-        if (input.onBehalfOf !== undefined && !input.ask)
-            throw fail("invalid_request", "onBehalfOf: only with ask: true");
-        const reply = input.replyTo !== undefined ? await this.replyOf(s, to, input.replyTo, input.ask === true, signal) : {};
-        const parent = input.onBehalfOf !== undefined ? await this.delegationParent(s, input.onBehalfOf, signal) : undefined;
-        const parts = [{ text: input.text }, ...filesParts(input.files)];
-        return {
-            kind: input.ask ? "task" : "mail",
-            to,
-            conversation,
-            params: compact({
-                to: formatToolAddress(to),
-                kind: input.ask ? "task" : "message",
-                parts,
-                ...reply,
-                onBehalfOf: input.onBehalfOf !== undefined ? { taskId: input.onBehalfOf } : undefined,
-                wake: true,
-            }),
-            ...(input.ask ? { delegation: delegationPrompt(parent?.chain) } : {}),
-        };
-    }
-    async send(sessionID, plan, idempotencyKey, signal) {
-        const s = await this.ctx.session(sessionID, signal);
-        const to = formatToolAddress(plan.to);
-        if ("target" in plan) {
-            const sent = s.link.call("msg.send", compact({ key: s.key, to: plan.target, kind: "message", parts: [{ text: plan.text }], replyTo: plan.thread, request: plan.request, idempotencyKey }), signal);
-            // With a thread, not_found may be the thread's: it stays not_found.
-            const { results } = await (plan.thread === undefined ? unknownAs(sent, "not_found", "to") : sent);
-            return { id: results[0]?.envelopeId ?? "", conversation: plan.conversation, kind: plan.kind, results: [{ to, stage: "accepted" }], note: plan.request !== undefined ? NOTE.suggest : NOTE[plan.kind] };
-        }
-        const { results } = await unknownAs(s.link.call("msg.send", { ...plan.params, key: s.key, idempotencyKey }, signal), "no_recipients", "to");
-        const first = results[0];
-        const failed = first?.code !== undefined && (first.stage === "rejected" || first.stage === "expired");
-        const held = results.some((result) => result.stage === "held");
-        const note = failed
-            ? `Not delivered (${first.code}). Next: ${TOOL_REMEDIES[first.code]}`
-            : held
-                ? NOTE.held
-                : (first?.expect !== undefined ? EXPECT_TEXT[first.expect] : NOTE.sent) + (plan.kind === "task" ? NOTE.task : "");
-        return {
-            id: first?.envelopeId ?? "",
-            conversation: plan.conversation,
-            kind: plan.kind,
-            ...(first?.taskId !== undefined ? { taskId: first.taskId } : {}),
-            results: results.map((result) => compact({ to: result.to, stage: result.stage, code: result.code, expect: result.stage === "held" ? "on_consent" : result.expect })),
-            note,
-        };
-    }
-    /**
-     * What `replyTo` names, for a send to the agent `to`: a message it sent this session (the reply
-     * joins its conversation), or a task this session asked it to run (the text is input for it).
-     */
-    async replyOf(s, to, id, ask, signal) {
-        const item = await found(s.link.call("inbox.get", { key: s.key, id }, signal));
-        if (item) {
-            const from = item.item.from;
-            if (from.person !== to.person || from.agent !== to.session)
-                throw fail("invalid_request", `replyTo: that message is from ${from.address}; send the reply there`);
-            return compact({ replyTo: item.item.id, contextId: item.item.contextId });
-        }
-        const record = await found(s.link.call("task.get", { key: s.key, taskId: id }, signal));
-        if (!record || record.key !== s.key)
-            throw fail("not_found", "replyTo: no message or task with this id belongs to this session");
-        if (ask)
-            throw fail("invalid_request", "replyTo: a task request answers a message, not a task");
-        if (record.role !== "requester")
-            throw fail("invalid_state", "replyTo: you run this task; report on it with messaging_task_update");
-        if (record.peer.person !== to.person || record.peer.agent !== to.session)
-            throw fail("invalid_state", `replyTo: that task runs at ${record.peer.address}; send the input there`);
-        return { taskId: record.task.id };
-    }
-    /** The task a send `onBehalfOf` delegates for: this session runs it and it is not finished (spec §6.7). */
-    async delegationParent(s, taskId, signal) {
-        const record = await this.ownTask(s, taskId, "onBehalfOf", signal);
-        if (record.role !== "executor")
-            throw fail("invalid_state", "onBehalfOf: name a task this session runs; this session asked for it");
-        if (isTerminal(record.task.status.state))
-            throw fail("invalid_state", `onBehalfOf: the task is already ${taskStateName(record.task.status.state)}`);
-        return record;
-    }
-    // ---- inbox ----
-    /** Lists items; previews put in front of the agent are acknowledged `handed_to_agent` (spec §8.2). */
-    async inbox(sessionID, input, signal) {
-        const s = await this.ctx.session(sessionID, signal);
-        const unreadOnly = input.unread ?? true;
-        const limit = input.limit ?? DEFAULT_INBOX;
-        const from = input.from !== undefined ? parseToolAddress(input.from, s.person, "from") : undefined;
-        if (from?.kind === "channel")
-            throw fail("invalid_request", "from: channels hold no mail; read one with messaging_read {with}");
-        const filtered = from !== undefined || s.peer !== undefined;
-        const listed = await s.link.call("inbox.list", { key: s.key, unreadOnly, limit: filtered ? PAGE : limit }, signal);
-        const keep = (item) => (s.peer === undefined || item.from.person === s.peer) && (from === undefined || fromMatches(item, from, s.person));
-        const items = listed.items.filter(keep).slice(0, limit);
-        const shown = items.filter((item) => item.stage === "delivered");
-        for (const item of shown)
-            this.ctx.hooks.shown(item.id);
-        await Promise.all(shown.map((item) => this.ctx.hooks.ack(s.link, s.key, item.id)));
-        let unread;
-        if (unreadOnly && !filtered && listed.items.length < limit)
-            unread = listed.items.length;
-        else
-            unread = (await s.link.call("inbox.list", { key: s.key, unreadOnly: true, limit: PAGE }, signal)).items.filter((item) => s.peer === undefined || item.from.person === s.peer).length;
-        return {
-            items: items.map((item) => presentInboxItem(this.framer, { ...item, stage: item.stage === "delivered" ? "handed_to_agent" : item.stage }, item.consent ?? this.consent(item.from.person, s))),
-            unread,
-            ...(items.length > 0 ? { notice: this.framer.notice() } : {}),
-        };
-    }
     // ---- read ----
     /**
-     * One item: a message or task request this session received (marks it read and sends a read
-     * receipt), a task this session asked for or runs, or something it sent (how far it got).
-     * `assert` gets the item's conversation before anything changes or is shown.
+      * Read a retained task or one of its received envelopes. The peer check precedes any side effect.
      */
-    async readItem(sessionID, id, assert, signal) {
+    async readItem(sessionID, id, assertPeer, signal) {
         const s = await this.ctx.session(sessionID, signal);
         const got = await found(s.link.call("inbox.get", { key: s.key, id }, signal));
         if (got) {
             scoped(s.peer, got.item.from.person);
-            await assert(conversationOfPeer(got.item.from));
+            if (got.item.cid !== undefined || got.item.taskId === undefined)
+                throw fail("not_found", "id: not a retained task envelope");
+            await assertPeer(got.item.from.person);
             const result = await s.link.call("item.read", { key: s.key, id }, signal);
             if (result.kind !== "received")
                 throw fail("not_found", "id: no message, task or sent item with this id belongs to this session");
             this.ctx.hooks.read(id);
             const consent = result.item.consent ?? this.consent(result.item.from.person, s);
-            const taskId = result.item.kind === "task" ? (result.item.taskId ?? result.message.taskId) : undefined;
+            const taskId = result.item.taskId ?? result.message.taskId;
             const record = taskId !== undefined ? await found(s.link.call("task.get", { key: s.key, taskId }, signal)) : undefined;
             if (record)
                 this.ctx.hooks.sawTask(record);
-            return { item: presentMail(this.framer, result, record ? presentTaskView(this.framer, record, consent) : undefined), notice: this.framer.notice() };
+            return { item: presentTaskEnvelope(this.framer, result, record ? presentTaskView(this.framer, record, consent) : undefined), notice: this.framer.notice() };
         }
         const record = await found(s.link.call("task.get", { key: s.key, taskId: id }, signal));
         if (record && record.key === s.key) {
             scoped(s.peer, record.peer.person);
-            await assert(conversationOfPeer(record.peer));
+            await assertPeer(record.peer.person);
             this.ctx.hooks.sawTask(record);
             return { item: presentTaskItem(this.framer, record, s.address, this.consent(record.peer.person, s)), notice: this.framer.notice() };
         }
-        const item = await found(s.link.call("item.read", { key: s.key, id }, signal));
-        const sent = item?.kind === "sent" ? item : undefined;
-        if (sent) {
-            scoped(s.peer, sent.to.slice(0, sent.to.indexOf("/")));
-            const item = presentSent(sent, s.address);
-            await assert(item.conversation);
-            return { item };
-        }
-        throw fail("not_found", "id: no message, task or sent item with this id belongs to this session");
-    }
-    /**
-     * A page of one conversation, oldest first: the chat lines with a person or in a channel, or the
-     * mail and tasks with an agent. Mail previews shown here count as handed to the agent.
-     */
-    async readConversation(sessionID, input, assert, signal) {
-        const s = await this.ctx.session(sessionID, signal);
-        const named = parseToolAddress(input.with, s.person, "with");
-        const target = asPerson(named, s.person);
-        if (s.peer !== undefined && (target.kind === "channel" || target.person !== s.peer))
-            scoped(s.peer, "");
-        if (input.before !== undefined && input.after !== undefined)
-            throw fail("invalid_request", "before, after: pass one, not both");
-        if (target.kind !== "agent")
-            this.reachable(target, "with");
-        const conversation = conversationOf(target, s.person);
-        const cursor = input.before ?? input.after;
-        const place = cursor !== undefined ? decodeToolCursor(cursor, input.before !== undefined ? "before" : "after") : undefined;
-        const limit = input.limit ?? DEFAULT_PAGE;
-        await assert(conversation);
-        if (target.kind !== "agent") {
-            if (place?.kind === "conv")
-                throw fail("invalid_request", "before, after: that cursor is from another conversation");
-            const room = target.kind === "person" ? `dm:${target.person}` : `channel:${target.name}`;
-            const seq = place?.seq;
-            const page = await unknownAs(s.link.call("conv.read", compact({ conversation: room, limit, before: input.before !== undefined ? seq : undefined, after: input.after !== undefined ? seq : undefined }), signal), "not_found", "with");
-            if (page.kind !== "lines")
-                throw fail("internal", "with: the daemon answered a DM or channel page with agent entries");
-            const { lines: messages, more } = page;
-            return this.page(conversation, messages, (line) => presentLine(this.framer, line, target.kind === "person" ? "line" : "post", conversation), (line) => ({ kind: "seq", seq: line.seq }), more);
-        }
-        if (place?.kind === "seq")
-            throw fail("invalid_request", "before, after: that cursor is from another conversation");
-        const at = place?.kind === "conv" ? { at: place.at, id: place.id } : undefined;
-        const page = await s.link.call("conv.read", compact({ key: s.key, conversation: `agent:${target.person}/${target.session}`, limit, before: input.before !== undefined ? at : undefined, after: input.after !== undefined ? at : undefined }), signal);
-        if (page.kind !== "agent")
-            throw fail("internal", "with: the daemon answered an agent page with lines");
-        const { entries, more } = page;
-        const shown = entries.filter((entry) => entry.kind === "mail" && entry.direction === "in" && entry.stage === "delivered");
-        for (const entry of shown)
-            this.ctx.hooks.shown(entry.id);
-        await Promise.all(shown.map((entry) => this.ctx.hooks.ack(s.link, s.key, entry.id)));
-        return this.page(conversation, entries, (entry) => presentConvEntry(this.framer, entry, s.address), (entry) => ({ kind: "conv", at: entry.at, id: entry.id }), more);
-    }
-    page(conversation, rows, present, place, more) {
-        const first = rows[0];
-        const last = rows.at(-1);
-        return {
-            conversation,
-            entries: rows.map(present),
-            ...(first !== undefined ? { before: encodeToolCursor(place(first)) } : {}),
-            ...(last !== undefined ? { after: encodeToolCursor(place(last)) } : {}),
-            more,
-            ...(rows.length > 0 ? { notice: this.framer.notice() } : {}),
-        };
-    }
-    // ---- search ----
-    /** Chat lines with persons and in channels. Each conversation in the hits is asserted; `allowed` false drops it. */
-    async search(sessionID, input, allowed, signal) {
-        const s = await this.ctx.session(sessionID, signal);
-        let room;
-        if (input.with !== undefined) {
-            const named = parseToolAddress(input.with, s.person, "with");
-            if (named.kind === "agent")
-                throw fail("invalid_request", "with: agent mail is not searched; page it with messaging_read {with}");
-            const target = asPerson(named, s.person);
-            this.reachable(target, "with");
-            room = target.kind === "person" ? `dm:${target.person}` : `channel:${target.name}`;
-        }
-        if (s.peer !== undefined)
-            room = room === undefined || room === `dm:${s.peer}` ? `dm:${s.peer}` : (scoped(s.peer, ""), room);
-        const channels = this.ctx.access.channels;
-        // A client limited to some channels searches each of them: an unscoped search would read the rest.
-        const rooms = room === undefined && channels !== undefined ? [...channels].map((name) => `channel:${name}`) : [room];
-        const limit = input.limit ?? 20;
-        const search = (one) => s.link.call("search", compact({ query: input.query, conversation: one, limit: input.limit }), signal);
-        // A named conversation the daemon does not know is unknown_address; an allowed channel this
-        // person is not in (or no longer) has nothing to find.
-        const pages = await Promise.all(rooms.map((one) => (room !== undefined ? unknownAs(search(one), "not_found", "with") : found(search(one)).then((page) => page ?? { hits: [] }))));
-        const messages = pages
-            .flatMap((page) => page.hits)
-            .filter((line) => (line.conversation.startsWith("dm:") ? this.ctx.access.dms : channels === undefined || channels.has(line.conversation.slice("channel:".length))))
-            .sort((a, b) => b.at - a.at)
-            .slice(0, limit);
-        const verdicts = new Map();
-        for (const conversation of new Set(messages.map((line) => roomConversation(line.conversation))))
-            verdicts.set(conversation, await allowed(conversation));
-        const hits = messages
-            .filter((line) => verdicts.get(roomConversation(line.conversation)))
-            .map((line) => {
-            const conversation = roomConversation(line.conversation);
-            const from = line.agent === undefined ? line.person : `${line.person}/${line.agent}`;
-            return { id: line.id, conversation, from, at: new Date(line.at).toISOString(), snippet: this.framer.wrap(line.body, { from, conversation, id: line.id }, 2_000) };
-        });
-        return { hits, ...(hits.length > 0 ? { notice: this.framer.notice() } : {}) };
+        throw fail("not_found", "id: no task or task envelope with this id belongs to this session");
     }
     // ---- tasks ----
     async tasks(sessionID, input, signal) {
@@ -524,21 +246,6 @@ export class Operations {
 function fail(code, message) {
     throw new MessagingError(code, message);
 }
-/**
- * A daemon call that names an address: the daemon's code for a person, agent or channel it does not
- * know (`not_found` for a person or channel, `no_recipients` for an agent, from `msg.send`) is `unknown_address`
- * to the agent (spec §11), naming the field.
- */
-async function unknownAs(call, code, field) {
-    try {
-        return await call;
-    }
-    catch (error) {
-        if (error instanceof MessagingError && error.code === code)
-            fail("unknown_address", `${field}: no person, agent or channel by that name here`);
-        throw error;
-    }
-}
 /** The result, or undefined for `not_found`. */
 async function found(call) {
     try {
@@ -555,21 +262,6 @@ function scoped(peer, person) {
     if (peer !== undefined && person !== peer)
         throw fail("not_found", "nothing with this id or address concerns the teammate who started this turn");
 }
-function fromMatches(item, from, self) {
-    switch (from.kind) {
-        case "me":
-            return item.from.person === self;
-        case "person":
-            return item.from.person === from.person;
-        case "agent":
-            return item.from.person === from.person && item.from.agent === from.session && (from.label === undefined || item.from.label === from.label);
-        case "channel":
-            return false;
-    }
-}
-function roomConversation(room) {
-    return room.startsWith("dm:") ? `person:${room.slice("dm:".length)}` : room;
-}
 /** Media types sent as text parts: their content stays readable to an A2A client and to the recipient's agent. */
 const TEXTUAL = /^(?:text\/[\w.+-]+|application\/(?:json|xml|yaml|x-yaml|javascript|x-sh|x-diff|x-patch|[\w.-]+\+(?:json|xml)))(?:\s*;.*)?$/i;
 /**

package/dist/lib/modules/core/agent/present.js

@@ -1,8 +1,10 @@
 import { taskStateName } from "../agent-tools.js";
+import { MessagingError } from "../schema/errors.js";
 import { createFence, PEER_FENCE_TAG, provenanceOf } from "../peer-text.js";
+import { LIMITS } from "../schema/common.js";
 import { chainPath, EXPECT_TEXT, isSafeId, messageAttributes } from "./text.js";
 /** Per-part cap in tool outputs; the protocol caps a text part at 65,536 chars. */
-const PART_CHARS = 32_768;
+const PART_CHARS = LIMITS.toolTextChars;
 /** Task history shown by `read`: the most recent messages. */
 const HISTORY_MESSAGES = 20;
 const ARTIFACTS = 20;
@@ -96,32 +98,31 @@ export function agentCan(entry) {
 }
 // ---- inbox ----
 export function presentInboxItem(framer, item, consent) {
+    if (item.cid === undefined && item.taskId === undefined)
+        throw new MessagingError("invalid_request", "inbox item has no conversation or task source");
     return {
         id: item.id,
-        conversation: conversationOfPeer(item.from),
-        from: item.from.address,
-        kind: item.kind === "task" ? "task" : "mail",
+        source: item.cid !== undefined ? { kind: "conv", cid: item.cid, event: item.eventId } : { kind: "task", taskId: item.taskId },
+        from: framer.wrap(item.from.address, { from: "sender" }),
         preview: framer.wrap(item.preview, messageAttributes(item)),
-        at: isoOf(item.receivedAt),
+        at: item.receivedAt,
         stage: item.stage,
         consent,
-        ...(item.taskId !== undefined ? { taskId: item.taskId } : {}),
         ...(item.chain !== undefined ? { chain: presentChain(framer, item.chain) } : {}),
     };
 }
-/** The agent conversation with a peer: `agent:<person>/<agent>`, or `person:<person>` for the person's own. */
-export function conversationOfPeer(peer) {
-    return peer.agent === undefined ? `person:${peer.person}` : `agent:${peer.person}/${peer.agent}`;
-}
 // ---- read ----
-export function presentMail(framer, result, task) {
+export function presentTaskEnvelope(framer, result, task) {
     const { item, message } = result;
+    const taskId = item.taskId ?? message.taskId;
+    if (item.cid !== undefined || taskId === undefined)
+        throw new MessagingError("invalid_request", "envelope does not name a task");
     const attributes = messageAttributes(item, message);
     const provenance = provenanceOf(message.metadata, item.id);
     return {
         id: item.id,
-        conversation: conversationOfPeer(item.from),
-        kind: item.kind === "task" ? "task" : "mail",
+        source: { kind: "task", taskId },
+        kind: item.kind === "task" ? "task" : "continuation",
         from: provenance?.from ?? item.from.address,
         at: isoOf(item.receivedAt),
         parts: message.parts.map((part) => presentPart(framer, part, "peer", attributes)),
@@ -137,7 +138,7 @@ export function presentTaskItem(framer, record, self, consent) {
     const author = request ? historyAuthor(record, request) : "peer";
     return {
         id: record.task.id,
-        conversation: conversationOfPeer(record.peer),
+        source: { kind: "task", taskId: record.task.id },
         kind: "task",
         from: author === "ours" ? self : record.peer.address,
         at: isoOf(record.createdAt),
@@ -146,47 +147,6 @@ export function presentTaskItem(framer, record, self, consent) {
         task: presentTaskView(framer, record, consent),
     };
 }
-/** Something this session sent: no copy is kept, so only how far it got. */
-export function presentSent(result, self) {
-    const [person = "", rest = ""] = result.to.split("/");
-    const session = rest.split("@")[0];
-    return {
-        id: result.envelopeId,
-        conversation: `agent:${person}/${session}`,
-        kind: "sent",
-        from: self,
-        at: isoOf(result.history[0]?.at ?? 0),
-        parts: [],
-        delivery: result.history.map((entry) => ({ to: result.to, stage: entry.stage, at: isoOf(entry.at), ...(entry.code !== undefined ? { code: entry.code } : {}) })),
-    };
-}
-// ---- conversation pages ----
-export function presentLine(framer, line, kind, conversation) {
-    const from = line.agent === undefined ? line.person : `${line.person}/${line.agent}`;
-    return {
-        id: line.id,
-        from,
-        kind: line.notice ? "notice" : kind,
-        at: isoOf(line.at),
-        text: framer.wrap(line.body, { from, conversation, id: line.id }, 8_000),
-        ...(line.thread !== undefined ? { thread: line.thread } : {}),
-        ...(line.state !== undefined ? { stage: line.state } : {}),
-    };
-}
-export function presentConvEntry(framer, entry, self) {
-    const author = entry.direction === "out" ? "ours" : "peer";
-    const from = author === "ours" ? self : entry.peer;
-    return {
-        id: entry.id,
-        from,
-        kind: entry.kind,
-        at: isoOf(entry.at),
-        ...(entry.text !== undefined ? { author, text: shown(framer, author, { from, id: entry.id })(entry.text) } : {}),
-        ...(entry.taskId !== undefined ? { taskId: entry.taskId } : {}),
-        ...(entry.stage !== undefined ? { stage: entry.stage } : {}),
-        ...(entry.state !== undefined ? { state: taskStateName(entry.state) } : {}),
-    };
-}
 // ---- tasks ----
 function textOf(message) {
     if (!message)