@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,244 @@
+import { taskStateName } from "../agent-tools.js";
+import { createFence, PEER_FENCE_TAG, provenanceOf } from "../peer-text.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;
+/** Task history shown by `read`: the most recent messages. */
+const HISTORY_MESSAGES = 20;
+const ARTIFACTS = 20;
+const TITLE_CHARS = 120;
+export const isoOf = (millis) => new Date(millis).toISOString();
+/** A peer-chosen identifier: raw when it is a plain id, fenced otherwise. */
+function idField(framer, value) {
+    return isSafeId(value) ? value : framer.wrap(value);
+}
+/** How a request from `person` runs here (spec §11): your own person, a trusted teammate, or a guarded peer turn. */
+export function consentOf(person, self, trusted) {
+    if (person === self)
+        return "self";
+    return trusted.has(person) ? "trusted" : "guarded";
+}
+function presentChain(framer, chain) {
+    return {
+        path: framer.wrap(chainPath(chain), { source: "delegation" }, 2_048),
+        depth: chain.depth,
+        maxDepth: chain.maxDepth,
+        ...(chain.scope !== undefined ? { scope: framer.wrap(chain.scope.join(" "), { source: "delegation" }, 1_024) } : {}),
+    };
+}
+/**
+ * Text this side wrote, shown without a fence: cleaned like peer text (hidden characters made
+ * visible, fence-like and host-tag openers neutralised), because a model may have copied peer text
+ * into its own status or artifact. Only `neutralize` is used, which draws no nonce.
+ */
+const OWN = createFence({ tag: PEER_FENCE_TAG });
+function shown(framer, author, attributes) {
+    return author === "peer" ? (text, maxChars) => framer.wrap(text, attributes, maxChars) : (text, maxChars) => OWN.neutralize(text, maxChars === undefined ? {} : { maxChars });
+}
+function presentPart(framer, part, author, attributes = {}) {
+    const show = shown(framer, author, attributes);
+    const extras = {
+        ...(part.filename !== undefined ? { filename: show(part.filename) } : {}),
+        ...(part.mediaType !== undefined ? { mediaType: show(part.mediaType) } : {}),
+    };
+    if (part.text !== undefined)
+        return { type: "text", author, content: show(part.text, PART_CHARS), ...extras };
+    if (part.url !== undefined)
+        return { type: "url", author, content: show(part.url, 2_048), ...extras };
+    if (part.raw !== undefined) {
+        const bytes = Math.floor((part.raw.replace(/=+$/, "").length * 3) / 4);
+        return { type: "file", author, content: show(`[file: ${bytes} bytes; contents not shown]`), bytes, ...extras };
+    }
+    return { type: "data", author, content: show(JSON.stringify(part.data) ?? "null", PART_CHARS), ...extras };
+}
+/** The side of a task that `author` wrote for, given this side's role. */
+function sideOf(record, author) {
+    if (author === "ours")
+        return record.role;
+    return record.role === "requester" ? "executor" : "requester";
+}
+/**
+ * Who wrote a message of a task's history. The requester's daemon appends only its own sends; the
+ * executor's only what the requester sent (spec §6.2). So ours only on the requester's side, and only
+ * for a requester's message: an executor never shows history as its own, whatever role the peer set.
+ */
+function historyAuthor(record, message) {
+    return record.role === "requester" && message.role === "ROLE_USER" ? "ours" : "peer";
+}
+/** Who wrote the status and the artifacts: the executor. */
+function executorAuthor(record) {
+    return record.role === "executor" ? "ours" : "peer";
+}
+// ---- contacts ----
+/** A session's state for a contact: live ones idle or busy, kept ones kept, those on an offline machine unknown. */
+function agentState(entry) {
+    if (entry.online)
+        return entry.state;
+    return entry.expect === "offline" ? "unknown" : "kept";
+}
+export function presentAgent(framer, entry) {
+    const from = { from: entry.address };
+    return {
+        address: entry.address,
+        state: agentState(entry),
+        ...(entry.expect !== undefined ? { expect: entry.expect, seen: EXPECT_TEXT[entry.expect] } : {}),
+        ...(entry.repo !== undefined ? { repo: framer.wrap(entry.repo, from, 200) } : {}),
+        ...(entry.branch !== undefined ? { branch: framer.wrap(entry.branch, from, 200) } : {}),
+        ...(entry.doing !== undefined ? { doing: framer.wrap(entry.doing, from, 200) } : {}),
+    };
+}
+/**
+ * What an agent session accepts under today's team policy (spec §8.3): a `cli` session takes mail
+ * but not tasks. Nothing is granted or narrowed per person yet.
+ */
+export function agentCan(entry) {
+    return { chat: false, agentMail: true, ask: entry.client === "cli" ? "no" : "open", source: "default" };
+}
+// ---- inbox ----
+export function presentInboxItem(framer, item, consent) {
+    return {
+        id: item.id,
+        conversation: conversationOfPeer(item.from),
+        from: item.from.address,
+        kind: item.kind === "task" ? "task" : "mail",
+        preview: framer.wrap(item.preview, messageAttributes(item)),
+        at: isoOf(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) {
+    const { item, message } = result;
+    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",
+        from: provenance?.from ?? item.from.address,
+        at: isoOf(item.receivedAt),
+        parts: message.parts.map((part) => presentPart(framer, part, "peer", attributes)),
+        verified: provenance ? "signature" : "none",
+        ...(item.replyTo !== undefined ? { replyTo: item.replyTo } : {}),
+        ...(item.chain !== undefined ? { chain: presentChain(framer, item.chain) } : {}),
+        ...(task !== undefined ? { task } : {}),
+    };
+}
+/** A task as a read item: its request, with the whole task. */
+export function presentTaskItem(framer, record, self, consent) {
+    const request = record.task.history?.[0];
+    const author = request ? historyAuthor(record, request) : "peer";
+    return {
+        id: record.task.id,
+        conversation: conversationOfPeer(record.peer),
+        kind: "task",
+        from: author === "ours" ? self : record.peer.address,
+        at: isoOf(record.createdAt),
+        parts: request ? request.parts.map((part) => presentPart(framer, part, author, peerAttributes(record))) : [],
+        ...(record.chain !== undefined ? { chain: presentChain(framer, record.chain) } : {}),
+        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)
+        return undefined;
+    const text = message.parts.flatMap((part) => (part.text !== undefined ? [part.text] : [])).join("\n");
+    return text.length > 0 ? text : undefined;
+}
+/** The fence attributes of the peer's text in a task. */
+function peerAttributes(record) {
+    return { from: record.peer.address, task: record.task.id };
+}
+export function presentTask(framer, record, consent) {
+    const request = record.task.history?.[0];
+    const title = textOf(request);
+    const status = textOf(record.task.status.message);
+    const titleAuthor = request ? historyAuthor(record, request) : "peer";
+    const statusAuthor = executorAuthor(record);
+    return {
+        id: idField(framer, record.task.id),
+        role: record.role === "requester" ? "mine" : "asked",
+        counterpart: record.peer.address,
+        state: taskStateName(record.task.status.state),
+        ...(title !== undefined ? { title: shown(framer, titleAuthor, peerAttributes(record))(title, TITLE_CHARS), titleAuthor } : {}),
+        ...(status !== undefined ? { status: shown(framer, statusAuthor, peerAttributes(record))(status, PART_CHARS), statusAuthor } : {}),
+        updatedAt: isoOf(record.updatedAt),
+        ...(consent !== undefined && record.role === "executor" ? { consent } : {}),
+        ...(record.chain !== undefined ? { chain: presentChain(framer, record.chain) } : {}),
+    };
+}
+/** A follow-up's stage says the executor read it. */
+export function followUpRead(stage) {
+    return stage === "read" || stage === "replied";
+}
+export function presentTaskView(framer, record, consent) {
+    const attributes = peerAttributes(record);
+    const history = (record.task.history ?? []).slice(-HISTORY_MESSAGES);
+    const artifacts = (record.task.artifacts ?? []).slice(-ARTIFACTS);
+    const executor = executorAuthor(record);
+    return {
+        ...presentTask(framer, record, consent),
+        createdAt: isoOf(record.createdAt),
+        history: history.map((message) => {
+            const author = historyAuthor(record, message);
+            return { from: sideOf(record, author), author, parts: message.parts.map((part) => presentPart(framer, part, author, attributes)) };
+        }),
+        artifacts: artifacts.map((artifact) => ({
+            author: executor,
+            ...(artifact.name !== undefined ? { name: shown(framer, executor, attributes)(artifact.name, 200) } : {}),
+            parts: artifact.parts.map((part) => presentPart(framer, part, executor, attributes)),
+        })),
+        ...(record.followUps !== undefined
+            ? { followUps: record.followUps.map((followUp) => ({ id: followUp.envelopeId, sentAt: isoOf(followUp.sentAt), stage: followUp.stage, read: followUpRead(followUp.stage) })) }
+            : {}),
+    };
+}

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

@@ -0,0 +1,79 @@
+import { cleanPeerText, provenanceOf } from "../peer-text.js";
+import { MachineLabel, PersonId, SessionName } from "../schema/common.js";
+/**
+ * Fixed text and small helpers the agent tools of every client share (spec §11, "Agent tools").
+ * Pure. Peer-derived values here are raw: callers fence or clean them.
+ */
+/**
+ * What a send's `expect` (spec §8.2) means for the agent: fixed text, never peer text. A hint from
+ * the recipient's last presence, not a promise.
+ */
+export const EXPECT_TEXT = {
+    next_turn: "The recipient is busy: it will likely see this after its next tool call or at its next turn.",
+    wake: "The recipient takes wakes: its client may start a turn for this soon.",
+    next_prompt: "The recipient is idle and will not be woken: it sees this when someone next prompts it.",
+    on_read: "The recipient is not pushed messages: it sees this when it next checks its inbox.",
+    kept: "No client holds the recipient session now: this waits until it comes back.",
+    offline: "The recipient's machine is offline: the relay holds this until it connects or the message expires.",
+};
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** True for opaque identifiers that are safe to show outside a fence (ULIDs, UUIDs, slugs). */
+export function isSafeId(value) {
+    return SAFE_ID.test(value);
+}
+/** A peer reference reduced to a validated address, or undefined when any part fails its schema. */
+export function validatedAddress(peer) {
+    if (!peer.agent)
+        return undefined;
+    if (!PersonId.safeParse(peer.person).success)
+        return undefined;
+    if (!SessionName.safeParse(peer.agent).success)
+        return undefined;
+    if (!MachineLabel.safeParse(peer.label).success)
+        return undefined;
+    return { person: peer.person, session: peer.agent, label: peer.label };
+}
+/**
+ * Whether a chain says more than the item's `from` (spec §6.7): a hop before the sender, or a scope. A
+ * direct request from the sender's own session says nothing more.
+ */
+export function delegated(chain) {
+    return chain.depth > 1 || chain.scope !== undefined;
+}
+/** Who asked whom, root first, as raw peer-derived text: callers fence or clean it. */
+export function chainPath(chain) {
+    return chain.addresses.join(" → ");
+}
+/**
+ * The `delegation` field of a task send's permission prompt. It is shown to the user in the
+ * approval UI, not to the model, so the chain is cleaned (hidden characters made visible, one line)
+ * rather than fenced.
+ */
+export function delegationPrompt(chain) {
+    if (chain === undefined)
+        return "new chain: the recipient sees this session as the one who asked";
+    return `on behalf of ${cleanPeerText(chainPath(chain), { singleLine: true, maxChars: 400 })}`;
+}
+/**
+ * Fence attributes for a message: the sender's address, the envelope id, and the verification the
+ * daemon performed. Inbox items exist only after the daemon verified the envelope signature (spec
+ * §5), so an item without a full message is still `verified="signature"`. A message whose
+ * provenance is missing, malformed or for another envelope is shown as `verified="none"`.
+ */
+export function messageAttributes(item, message) {
+    const provenance = message ? provenanceOf(message.metadata, item.id) : undefined;
+    const verified = message === undefined || provenance !== undefined ? "signature" : "none";
+    const chain = item.chain && delegated(item.chain) ? item.chain : undefined;
+    return {
+        from: provenance?.from ?? item.from.address,
+        id: item.id,
+        kind: item.kind,
+        verified,
+        chain: chain && chainPath(chain),
+        scope: chain?.scope?.join(" "),
+    };
+}
+/** Drop undefined members so optional IPC params and output keys stay absent. */
+export function compact(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}