@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/lib/core-testing.js

@@ -0,0 +1 @@
+export * from "./modules/core/testing.js";

package/dist/lib/core.js

@@ -0,0 +1 @@
+export * from "./modules/core/index.js";

package/dist/lib/ipc-testing.js

@@ -0,0 +1 @@
+export * from "./modules/ipc/testing.js";

package/dist/lib/ipc.js

@@ -0,0 +1 @@
+export * from "./modules/ipc/index.js";

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

@@ -0,0 +1,42 @@
+import { Address, MachineLabel, PersonId, SessionName } from "./schema/common.js";
+import { MessagingError } from "./schema/errors.js";
+/** Parses the address grammar in `schema/common.ts`. Anything else is `invalid_request`. */
+export function parseAddress(text) {
+    if (!Address.safeParse(text).success)
+        throw invalid();
+    const parts = text.split("/");
+    if (parts.length !== 2)
+        throw invalid();
+    const [person, rest] = parts;
+    if (!PersonId.safeParse(person).success)
+        throw invalid();
+    const at = rest.split("@");
+    if (at.length > 2)
+        throw invalid();
+    const [session, label] = at;
+    if (!SessionName.safeParse(session).success)
+        throw invalid();
+    if (label === undefined)
+        return { kind: "session", person, session };
+    if (!MachineLabel.safeParse(label).success)
+        throw invalid();
+    return { kind: "session", person, session, label };
+}
+export function formatAddress(first, session, label) {
+    const address = typeof first === "string"
+        ? { kind: "session", person: first, session: session, ...(label === undefined ? {} : { label }) }
+        : first;
+    if (address.kind !== "session")
+        throw invalid();
+    if (!SessionName.safeParse(address.session).success)
+        throw invalid();
+    if (address.label !== undefined && !MachineLabel.safeParse(address.label).success)
+        throw invalid();
+    const text = `${address.person}/${address.session}${address.label === undefined ? "" : `@${address.label}`}`;
+    // Re-parsing checks every remaining part (person, length).
+    parseAddress(text);
+    return text;
+}
+function invalid() {
+    return new MessagingError("invalid_request", "invalid address");
+}

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

@@ -0,0 +1,595 @@
+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 { 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";
+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) {
+        this.ctx = ctx;
+    }
+    get framer() {
+        return this.ctx.framer;
+    }
+    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);
+        const [status, { entries, conversations: rooms, reach }] = await Promise.all([
+            s.link.call("daemon.status", {}, signal),
+            s.link.call("contacts.list", { includeOffline: true }, signal),
+        ]);
+        const others = entries.filter((entry) => entry.address !== s.address);
+        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)) ?? []);
+        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]));
+        const reachOf = (person) => {
+            const r = cards.get(person);
+            if (!r)
+                return undefined;
+            return { chat: r.can.chat, agentMail: r.can.agentMail, ask: r.can.ask, source: r.source, ...(r.source === "card" && r.at !== undefined ? { card: isoOf(r.at) } : {}) };
+        };
+        const canAgent = (entry) => {
+            const base = agentCan(entry);
+            const card = reachOf(entry.person);
+            if (!card)
+                return base;
+            return { ...card, chat: false, ask: base.ask === "no" ? "no" : card.ask };
+        };
+        const agent = (entry) => ({
+            ...presentAgent(this.framer, entry),
+            kind: "agent",
+            name: name(entry.agent),
+            org: "same",
+            presence: entry.online ? "online" : "offline",
+            can: canAgent(entry),
+        });
+        const persons = [...byPerson]
+            .sort(([a], [b]) => (a === s.person ? -1 : b === s.person ? 1 : a.localeCompare(b)))
+            .map(([person, list]) => {
+            const can = list.map(canAgent);
+            const self = person === s.person;
+            const card = self ? undefined : reachOf(person);
+            return {
+                match: [person, ...list.map((entry) => entry.agent)],
+                contact: {
+                    address: self ? "me" : person,
+                    kind: "person",
+                    name: name(person),
+                    org: "same",
+                    presence: list.some((entry) => entry.online) ? "online" : "offline",
+                    agents: list.map((entry) => presentAgent(this.framer, entry)),
+                    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))))
+            .map((room) => {
+            const local = room.conversation.slice("channel:".length);
+            return {
+                match: [local, room.name ?? local],
+                contact: {
+                    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 } : {}),
+                },
+            };
+        });
+        const agents = others.map((entry) => ({ match: [entry.person, entry.agent], person: entry.person, contact: agent(entry) }));
+        let list = input.kind === "agent" ? agents : input.kind === "person" ? persons : input.kind === "channel" ? channels : [...persons, ...channels];
+        // A guarded peer turn sees only the teammate who started it.
+        if (s.peer !== undefined)
+            list = list.filter((item) => item.contact.kind !== "channel" && (item.person ?? item.contact.address) === s.peer);
+        const query = input.query?.toLowerCase();
+        if (query !== undefined)
+            list = list.filter((item) => item.match.some((text) => text.toLowerCase().includes(query)));
+        if (input.can === "chat")
+            list = list.filter((item) => item.contact.can.chat);
+        if (input.can === "ask")
+            list = list.filter((item) => item.contact.can.ask !== "no");
+        const limit = input.limit ?? DEFAULT_CONTACTS;
+        const contacts = list.slice(0, limit).map((item) => item.contact);
+        return {
+            me: { address: s.address, person: s.person, agent: s.address.slice(s.person.length + 1).split("@")[0], device: status.identity?.label ?? "", relay: status.relay.connected ? "connected" : "offline" },
+            contacts,
+            more: list.length > limit,
+            ...(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.
+     */
+    async readItem(sessionID, id, assert, 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));
+            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 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() };
+        }
+        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));
+            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() } : {}) };
+    }
+    // ---- tasks ----
+    async tasks(sessionID, input, signal) {
+        const s = await this.ctx.session(sessionID, signal);
+        const role = input.role === "mine" ? "requester" : input.role === "asked" ? "executor" : undefined;
+        const limit = input.limit ?? DEFAULT_TASKS;
+        const present = (record) => {
+            this.ctx.hooks.sawTask(record);
+            return presentTask(this.framer, record, this.consent(record.peer.person, s));
+        };
+        const filtered = input.state === "open" || input.state === "done" || s.peer !== undefined;
+        if (!filtered) {
+            if (input.cursor !== undefined && !input.cursor.startsWith("d"))
+                throw fail("invalid_request", "cursor: not a cursor of this listing");
+            const state = input.state !== undefined ? a2aTaskState(input.state) : undefined;
+            const page = await s.link.call("task.list", compact({ key: s.key, role, state, limit, cursor: input.cursor?.slice(1) }), signal);
+            const tasks = page.tasks.map(present);
+            return { tasks, ...(page.nextCursor !== undefined ? { nextCursor: `d${page.nextCursor}` } : {}), total: page.total, ...(tasks.length > 0 ? { notice: this.framer.notice() } : {}) };
+        }
+        const offset = input.cursor === undefined ? 0 : /^o(\d{1,6})$/.exec(input.cursor)?.[1];
+        if (offset === undefined)
+            throw fail("invalid_request", "cursor: not a cursor of this listing");
+        const all = [];
+        let cursor;
+        for (let page = 0; page < TASK_PAGES; page++) {
+            const listed = await s.link.call("task.list", compact({ key: s.key, role, limit: PAGE, cursor }), signal);
+            all.push(...listed.tasks);
+            cursor = listed.nextCursor;
+            if (cursor === undefined)
+                break;
+        }
+        const done = (record) => DONE_STATES.includes(taskStateName(record.task.status.state));
+        const matching = all.filter((record) => (s.peer === undefined || record.peer.person === s.peer) &&
+            (input.state === undefined || (input.state === "open" ? !done(record) : input.state === "done" ? done(record) : taskStateName(record.task.status.state) === input.state)));
+        const start = Number(offset);
+        const tasks = matching.slice(start, start + limit).map(present);
+        return {
+            tasks,
+            ...(start + limit < matching.length ? { nextCursor: `o${start + limit}` } : {}),
+            total: matching.length,
+            ...(tasks.length > 0 ? { notice: this.framer.notice() } : {}),
+        };
+    }
+    /**
+     * The task an update or a cancel names, checked locally before any permission prompt: this
+     * session holds `role`, and for an update the task is not finished and `next` is legal.
+     */
+    async taskTarget(sessionID, id, role, next, signal) {
+        const s = await this.ctx.session(sessionID, signal);
+        const record = await this.ownTask(s, id, "id", signal);
+        this.ctx.hooks.sawTask(record);
+        if (record.role !== role) {
+            throw fail("invalid_state", role === "executor" ? "id: only the executor updates a task; this session asked for it" : "id: only the requester cancels a task; this session runs it");
+        }
+        const state = record.task.status.state;
+        if (next !== undefined && isTerminal(state))
+            throw fail("invalid_state", `id: the task is already ${taskStateName(state)}`);
+        if (next !== undefined && !canTransition(state, next))
+            throw fail("invalid_state", `state: a task cannot move from ${taskStateName(state)} to ${taskStateName(next)}`);
+        const peer = validatedAddress(record.peer);
+        if (!peer)
+            throw fail("invalid_request", "id: the task's peer has no session address");
+        return { record, to: { kind: "agent", ...peer } };
+    }
+    async updateTask(sessionID, record, input, signal) {
+        const s = await this.ctx.session(sessionID, signal);
+        const files = filesParts(input.files);
+        const updated = await s.link.call("task.update", compact({
+            key: s.key,
+            taskId: record.task.id,
+            state: a2aTaskState(input.state),
+            message: input.text !== undefined ? { parts: [{ text: input.text }] } : undefined,
+            artifact: files.length > 0 ? { artifactId: randomUUID(), parts: files } : undefined,
+        }), signal);
+        this.ctx.hooks.sawTask(updated);
+        return { id: updated.task.id, state: taskStateName(updated.task.status.state), stage: "accepted", to: updated.peer.address };
+    }
+    async cancelTask(sessionID, record, reason, signal) {
+        const s = await this.ctx.session(sessionID, signal);
+        const updated = await s.link.call("task.cancel", compact({ key: s.key, taskId: record.task.id, reason }), signal);
+        this.ctx.hooks.sawTask(updated);
+        return { id: updated.task.id, state: taskStateName(updated.task.status.state), to: updated.peer.address };
+    }
+    /** A task of this session, in its peer scope; `field` names the input for the error. */
+    async ownTask(s, id, field, signal) {
+        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", `${field}: no task with this id belongs to this session`);
+        scoped(s.peer, record.peer.person);
+        return record;
+    }
+}
+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 {
+        return await call;
+    }
+    catch (error) {
+        if (error instanceof MessagingError && error.code === "not_found")
+            return undefined;
+        throw error;
+    }
+}
+/** In a guarded peer turn, only what concerns that peer exists: anything else is `not_found`. */
+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;
+/**
+ * Files as message or artifact parts: a textual file whose bytes are UTF-8 becomes a text part with
+ * its file name and media type; any other file a raw (base64) part.
+ */
+function filesParts(files) {
+    return (files ?? []).map((file) => {
+        const text = TEXTUAL.test(file.mime) ? utf8(file.data) : undefined;
+        return text !== undefined ? { text, filename: file.name, mediaType: file.mime } : { raw: file.data, filename: file.name, mediaType: file.mime };
+    });
+}
+/** Base64 to text, or undefined when the bytes are not UTF-8. */
+function utf8(base64) {
+    try {
+        const binary = atob(base64);
+        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}