@cotal-ai/connector-core 0.58.0 → 0.59.0

package/dist/tool-specs.js

@@ -11,6 +11,8 @@ import { execFileSync } from "node:child_process";
 import { z } from "zod";
 import { isConcreteChannel, channelInAllow, AmbiguousPeerError, assertLifecycleToken, isPermissionDenied, renderLifecycleBlocked, LANG_PROBLEM_DETAIL_KIND } from "@cotal-ai/core";
 import { afterRecallMark } from "./agent.js";
+// The neutralization and the per-item rendering live in `framing.ts`, one convention shared with
+// the auto-injected block, and are used here rather than restated. See that file for the rule.
 import { attributionSafe, fmtBody, fmtItem, fmtFrom } from "./framing.js";
 import { FEEDBACK_URL, PUBLIC_FEEDBACK_URL, isAuthed } from "./config.js";
 import { buildOrientation, renderOrientation } from "./orientation.js";
@@ -81,6 +83,9 @@ export function parseToolArgs(spec, args) {
         .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
         .join("; ")}`);
 }
+/** The closed EMPTY input, for an adapter that republishes a tool with no arguments of its own.
+ *  A host given this refuses extras itself; a host given no `inputSchema` at all forwards them. */
+export const NO_TOOL_ARGS = z.strictObject({});
 /**
  * Refuse ANY caller-supplied argument to a tool an adapter publishes with none — returning the
  * refusal text, or `undefined` when the call is clean.
@@ -91,13 +96,21 @@ export function parseToolArgs(spec, args) {
  * tool while every sibling refuses it. The wording matches {@link parseToolArgs} so a caller cannot
  * tell which mechanism turned it away, and this stays dependency-free for hosts that bundle.
  */
-/** The closed EMPTY input, for an adapter that republishes a tool with no arguments of its own.
- *  A host given this refuses extras itself; a host given no `inputSchema` at all forwards them. */
-export const NO_TOOL_ARGS = z.strictObject({});
 export function refuseAnyArgs(name, args) {
     const keys = args && typeof args === "object" ? Object.keys(args) : [];
     return keys.length ? `${name}: unknown argument(s): ${keys.join(", ")} — this tool takes no arguments` : undefined;
 }
+/** Compact age: `12s`, `47m`, `3h`, `2d`. */
+function ageText(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    if (s < 86_400)
+        return `${Math.floor(s / 3600)}h`;
+    return `${Math.floor(s / 86_400)}d`;
+}
 function statusGlyph(s) {
     return s === "working" ? "●" : s === "waiting" ? "◐" : s === "idle" ? "○" : "·";
 }
@@ -108,8 +121,6 @@ const ATTENTION_DESC = {
     dnd: "dnd — channel chatter no longer wakes you (it still arrives in your next turn); DMs, anycast, and @mentions still wake you",
     focus: "focus — only DMs and anycast reach your context; an @mention wakes you to pull; untagged channel chatter is held on the channel — read it with cotal_inbox",
 };
-/** The neutralization and the per-item rendering live in `framing.ts`, one convention shared with
- *  the auto-injected block, and are used here rather than restated. See that file for the rule. */
 /**
  * HOW MUCH OF THE INBOX ONE RESPONSE MAY CARRY, in characters.
  *
@@ -157,9 +168,12 @@ export function renderInbox(opts) {
     //
     // Stuck means "no response could carry this", so it is measured against the friendliest response
     // there is: this item alone, its head, and any rider, with no held-note at all.
+    // Every set in this walk is keyed by receive key. An id-less item's wire id is the empty string,
+    // so a set of wire ids makes every id-less item the same item: a held giant vanished from the
+    // note when a small id-less item went out, and recall moved its mark past an unread one (#613).
     const stuck = new Set(ordered
         .filter((i) => opts.head([i]).length + 1 + itemCost(i) + (warning ? warning.length + 2 : 0) > budget)
-        .map((i) => i.id));
+        .map((i) => i.recvKey));
     const assemble = (shown, held, tier) => {
         const note = heldNote(held, peek, stuck, tier);
         const parts = [];
@@ -194,14 +208,14 @@ export function renderInbox(opts) {
     let used = 0;
     let strictGap = false; // the in-order lane stops at its first gap; the free lane steps over its own
     for (const i of ordered) {
-        const strict = strictIds.has(i.id);
+        const strict = strictIds.has(i.recvKey);
         if (strict && strictGap)
             continue;
         const cost = itemCost(i);
         if (used + cost > budget) {
-            // A message nothing could ever carry is not a gap: it will never become deliverable, so the
-            // walk steps over it and the note says so. Anything else IS a gap, and the ordered lane waits.
-            if (strict && !stuck.has(i.id))
+            // In the ordered lane even a message no response could carry whole is a gap: the mark would
+            // pass it if the walk stepped over it, so the lane waits for it to go out in parts (#613).
+            if (strict)
                 strictGap = true;
             continue;
         }
@@ -209,8 +223,8 @@ export function renderInbox(opts) {
         used += cost;
     }
     const heldOf = () => {
-        const ids = new Set(shown.map((i) => i.id));
-        return ordered.filter((i) => !ids.has(i.id));
+        const keys = new Set(shown.map((i) => i.recvKey));
+        return ordered.filter((i) => !keys.has(i.recvKey));
     };
     let held = heldOf();
     let text = assemble(shown, held, "full");
@@ -241,9 +255,9 @@ function itemCost(i) {
  * The tail that keeps a windowed response honest: what is still there, and that it was not lost.
  *
  * TWO KINDS OF HELD, because they are not the same promise. Most held mail is waiting its turn and
- * a later call delivers it. A message larger than one whole response is not waiting for anything:
- * calling again will never produce it, and saying "call again for the next batch" over it would be
- * a queue that looks like it is moving when it is not.
+ * a later call delivers it whole. A message larger than one whole response never arrives whole: it
+ * goes out in parts through {@link renderPart}, after the smaller mail, so the note says that rather
+ * than promising it in the next batch.
  *
  * THE NOTE IS BOUNDED. It names at most {@link NAMED_STUCK} of the stuck messages and counts the
  * rest, and it truncates a sender's name, because a steady stream of oversized mail would otherwise
@@ -252,7 +266,7 @@ function itemCost(i) {
 function heldNote(held, peek = false, stuckIds = new Set(), tier = "full") {
     if (!held.length || tier === "none")
         return "";
-    const stuck = held.filter((i) => stuckIds.has(i.id));
+    const stuck = held.filter((i) => stuckIds.has(i.recvKey));
     const waiting = held.length - stuck.length;
     if (tier === "compact") {
         const bits = [];
@@ -269,7 +283,7 @@ function heldNote(held, peek = false, stuckIds = new Set(), tier = "full") {
     }
     const parts = [];
     if (waiting) {
-        const dms = held.filter((i) => i.kind !== "channel" && !stuckIds.has(i.id)).length;
+        const dms = held.filter((i) => i.kind !== "channel" && !stuckIds.has(i.recvKey)).length;
         // Under peek nothing is cleared, so the next call returns THIS window again. Telling a peeking
         // caller to call again for the next batch is a promise the read cannot keep, and an obedient
         // caller loops on it forever.
@@ -284,10 +298,115 @@ function heldNote(held, peek = false, stuckIds = new Set(), tier = "full") {
             .map((i) => `${fmtFrom(i).slice(0, 40)} (${itemCost(i).toLocaleString("en-US")} chars)`)
             .join(", ");
         const rest = stuck.length - Math.min(NAMED_STUCK, stuck.length);
-        parts.push(`${stuck.length} message${stuck.length === 1 ? " is" : "s are"} larger than one response can carry and cannot be delivered by this tool at all: ${named}${rest ? `, and ${rest} more` : ""}. ${stuck.length === 1 ? "It stays" : "They stay"} buffered and uncleared, and calling again will not produce ${stuck.length === 1 ? "it" : "them"}.`);
+        parts.push(`${stuck.length} message${stuck.length === 1 ? " is" : "s are"} larger than one response can carry: ${named}${rest ? `, and ${rest} more` : ""}. ${stuck.length === 1 ? "It stays" : "They stay"} buffered and uncleared, and once no smaller mail is waiting, each call delivers the next part of one of them; a message is cleared only after its last part goes out.`);
     }
     return `\n\n… ${parts.join(" ")}`;
 }
+/**
+ * How far each oversized message has been read, by receive key, per agent (#613).
+ *
+ * It lives beside the agent rather than in the reply, so a reconnect, which keeps the agent and its
+ * buffer, resumes where the last part ended. A process restart loses it, and the redelivered message
+ * starts again from its first part: repeated, never skipped. An entry goes when its message is no
+ * longer offered, whether by its last part or by anything else that consumed it.
+ */
+const partOffsets = new WeakMap();
+/**
+ * One `cotal_inbox` read at a time per agent (#613). A read decides what to hide, render and clear from
+ * state it took before awaiting recall, so a second read that overlapped it decided from a snapshot the
+ * first had already moved past: it hid a recalled message the first had just read in part, and moved
+ * the recall mark past the rest of it. A read waits for the one before it to finish, failed or not.
+ */
+const inboxReads = new WeakMap();
+function oneReadAtATime(read) {
+    return (agent, config, args) => {
+        const turn = (inboxReads.get(agent) ?? Promise.resolve()).then(() => read(agent, config, args));
+        inboxReads.set(agent, turn.catch(() => undefined));
+        return turn;
+    };
+}
+/** The read position for an oversized message, after dropping positions of messages no longer offered. */
+function partCursor(agent, offered) {
+    let m = partOffsets.get(agent);
+    if (!m)
+        partOffsets.set(agent, (m = new Map()));
+    const live = new Set(offered.map((i) => i.recvKey));
+    for (const k of m.keys())
+        if (!live.has(k))
+            m.delete(k);
+    return m;
+}
+/**
+ * One part of a message no single response can carry: the next slice of its rendered form, with a
+ * line saying which characters these are and whether more follow (#613).
+ *
+ * The slice is of the RENDERED item, so its indented continuations come with it, and it starts on
+ * its own indented line, so a cut that lands mid-line cannot put peer text at column zero. Its size
+ * is what the window has left once the line above it, the note and any rider are in, and the
+ * finished text is measured like {@link renderInbox}'s. `end` is where the next part starts; the
+ * caller clears the message only when `done`, and advances nothing on a peek.
+ */
+function renderPart(opts) {
+    const budget = opts.budget ?? INBOX_WINDOW_CHARS;
+    const full = fmtItem(opts.item);
+    const total = full.length;
+    const fmt = (n) => n.toLocaleString("en-US");
+    const assemble = (end, tier) => {
+        const done = end >= total;
+        const next = opts.peek
+            ? "A peek advances nothing, so read without peek to take this part."
+            : done
+                ? "This was its last part, so it is now cleared."
+                : "It stays buffered and uncleared until its last part goes out; call cotal_inbox again for the next part.";
+        const head = `Part of a message larger than one response, from ${fmtFrom(opts.item).slice(0, 40)}: characters ${fmt(opts.offset + 1)}-${fmt(end)} of ${fmt(total)}${opts.peek ? " (peek: nothing cleared)" : ""}. ${next}`;
+        const body = `${head}\n  ${full.slice(opts.offset, end)}${heldNote(opts.others, opts.peek, opts.stuck, tier)}`;
+        return opts.warning ? `${body}\n\n${opts.warning}` : body;
+    };
+    for (const tier of NOTE_TIERS) {
+        // Measure everything but the slice with the widest numbers the header can carry, then fill.
+        const room = budget - assemble(opts.offset, tier).length - 2 * fmt(total).length;
+        if (room <= 0)
+            continue;
+        let end = Math.min(total, opts.offset + room);
+        // Never split a surrogate pair across two parts.
+        if (end < total && /[\uD800-\uDBFF]/.test(full[end - 1]))
+            end--;
+        const text = assemble(end, tier);
+        if (text.length <= budget && end > opts.offset)
+            return { text, end, done: end >= total };
+    }
+    throw new Error(`cotal_inbox: no room for a part of a ${fmt(total)}-character message in a ${fmt(budget)}-character window`);
+}
+/**
+ * The reply for a call that could carry no whole message: the next part of `item`, a message too
+ * large for any response, or `undefined` when there is none. The read position moves only when the
+ * part went out, and `last` records the message as handed over only with its last part, so nothing
+ * is cleared before it was handed over (#603). `last` is a buffered message's ack, or for focus
+ * recall the mark or the ahead record that a whole recalled item would have moved.
+ */
+function partReply(opts) {
+    const { agent, item, peek } = opts;
+    if (!item)
+        return undefined;
+    const cursor = partCursor(agent, opts.offered);
+    const part = renderPart({
+        item,
+        offset: cursor.get(item.recvKey) ?? 0,
+        peek,
+        others: opts.offered.filter((i) => i !== item),
+        stuck: opts.stuck,
+        warning: opts.warning,
+    });
+    if (!peek) {
+        if (part.done) {
+            opts.last(item);
+            cursor.delete(item.recvKey);
+        }
+        else
+            cursor.set(item.recvKey, part.end);
+    }
+    return part.text;
+}
 /**
  * The recall warning, bounded and budgeted like every other part of a response.
  *
@@ -589,7 +708,12 @@ export function cotalToolSpecs(config, source = "connector") {
                             .map(([c]) => `#${c}`)
                         : [];
                     const mutedHint = muted.length ? ` (locally muted ${muted.join(", ")}; DM to reach)` : "";
-                    const condition = p.condition ? ` (${p.condition.code})` : "";
+                    // The condition with how long it has held, and the age of the last harness-reported work
+                    // event (#618): a turn that died or stopped advancing 40m ago no longer reads like a live one.
+                    const now = Date.now();
+                    const since = p.condition?.since;
+                    const active = p.activeAt === undefined ? "" : ` · active ${ageText(now - p.activeAt)} ago`;
+                    const condition = (p.condition ? ` (${p.condition.code}${since === undefined ? "" : ` for ${ageText(now - since)}`})` : "") + active;
                     const progress = p.status === "working" ? `working${condition} · progress unknown` : `${p.status}${condition}`;
                     return `${statusGlyph(p.status)} ${who} — ${progress}${p.activity ? `: ${p.activity}` : ""}${attn}${me}${mutedHint}${id}`;
                 });
@@ -603,11 +727,11 @@ export function cotalToolSpecs(config, source = "connector") {
         {
             name: "cotal_inbox",
             title: "Cotal: read incoming messages",
-            description: "Read messages other agents have sent you since you last checked: channel broadcasts, direct messages, and role requests. It clears ONLY what it actually returns to you (nothing at all when peek is true), and one call carries at most a receivable window: direct messages and role requests first, then channel traffic, with replayed history last. Anything that does not fit stays buffered and is named in the reply, so call again for the next batch. A single message larger than one whole response is never consumed either: it is named with its sender and size and stays buffered, since delivering it is impossible and clearing it would lose it. In focus mode it also pulls back the channel chatter held since you entered focus.",
+            description: "Read messages other agents have sent you since you last checked: channel broadcasts, direct messages, and role requests. It clears ONLY what it actually returns to you (nothing at all when peek is true), and one call carries at most a receivable window: direct messages and role requests first, then channel traffic, with replayed history last. Anything that does not fit stays buffered and is named in the reply, so call again for the next batch. A single message larger than one whole response is delivered in parts: once no smaller mail is waiting, each call carries the next part of it, a peek shows the current part without moving on, and the message is cleared only after its last part goes out. In focus mode it also pulls back the channel chatter held since you entered focus.",
             schema: {
                 peek: z.boolean().optional().describe("If true, show messages without clearing them."),
             },
-            async run(agent, _config, { peek, scope }) {
+            run: oneReadAtATime(async (agent, _config, { peek, scope }) => {
                 const inboxScope = scope ?? "all";
                 // SELECT, RENDER, THEN CLEAR EXACTLY WHAT WENT OUT (#603). The old order drained the whole
                 // scope up front, so a payload too large for the host to deliver had already been marked
@@ -616,10 +740,10 @@ export function cotalToolSpecs(config, source = "connector") {
                 // It is not the only acker: the inbox's own overflow valve acks what it evicts, so an item
                 // that arrives while this call is awaiting recall can still be evicted and lost. That is the
                 // buffer's documented bounded local loss (see MeshAgent.buffer), unchanged by this path.
-                const buffered = agent.peekInbox(inboxScope);
                 const automaticPending = scope ? agent.inboxCount("automatic") : 0;
                 if (agent.attention !== "focus") {
-                    const { text, shown, held } = renderInbox({
+                    const buffered = agent.peekInbox(inboxScope);
+                    const { text, shown, held, stuck } = renderInbox({
                         items: buffered,
                         peek,
                         head: (s) => scope
@@ -630,6 +754,18 @@ export function cotalToolSpecs(config, source = "connector") {
                         return ok(scope
                             ? `No pull-only messages.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued.` : ""}`
                             : "Inbox empty, no new messages.");
+                    if (!shown.length) {
+                        const part = partReply({
+                            agent,
+                            item: buffered.find((i) => stuck.has(i.recvKey)),
+                            offered: buffered,
+                            stuck,
+                            peek: peek ?? false,
+                            last: (i) => agent.drainInboxDeliveries([i.recvKey]),
+                        });
+                        if (part)
+                            return ok(part);
+                    }
                     // The response exists before anything is acked: an ack is a claim that these messages were
                     // handed over, so nothing may be cleared while the handing-over is still hypothetical. And
                     // it is the ASSEMBLED response that decides, so what is acked is what a caller was handed.
@@ -640,8 +776,14 @@ export function cotalToolSpecs(config, source = "connector") {
                 }
                 // Focus: the live buffer holds only DMs/anycast; the channel ambient + @mentions were
                 // acked-and-dropped at ingest, so pull them back from the channel stream here (replay-gated,
-                // "since you entered focus"). Recall is read-only, so peek only affects the live buffer.
-                const recall = await agent.recallAmbient();
+                // "since you entered focus"). Recall acks nothing, so peek only affects the live buffer.
+                // A recalled message already part read stays offered until its last part goes out (#613).
+                const before = new Set(agent.peekInbox("all").map((i) => i.recvKey));
+                const underway = new Set([...(partOffsets.get(agent)?.keys() ?? [])].filter((k) => !before.has(k)));
+                const recall = await agent.recallAmbient(underway);
+                // Read after recall, which can hand an id-less message back into the buffer (#662).
+                const buffered = agent.peekInbox(inboxScope);
+                const bufferedIds = new Set(buffered.map((i) => i.recvKey));
                 // RECALL HAS TO ADVANCE, or windowing it starves it. Recall is re-derived from an unchanged
                 // frontier on every call, so showing its first window and stopping there returned the same
                 // prefix forever while the reply promised a next batch: measured as three identical replies
@@ -690,12 +832,11 @@ export function cotalToolSpecs(config, source = "connector") {
                 const warning = [droppedNote(recall.droppedChannels), aheadNote(aheadWithheld)]
                     .filter(Boolean)
                     .join(" ");
-                const bufferedIds = new Set(buffered.map((i) => i.recvKey));
                 const { text, shown: all, stuck } = renderInbox({
                     items: [...buffered, ...fresh],
                     peek,
                     warning,
-                    strictIds: new Set(clocked.map((i) => i.id)),
+                    strictIds: new Set(clocked.map((i) => i.recvKey)),
                     head: (s) => scope
                         ? `${s.length} message${s.length === 1 ? "" : "s"}. Buffered pull-only items were cleared; normal focus channel items are read-only recall:`
                         : `${s.length} message${s.length === 1 ? "" : "s"}${peek ? " (peek: live buffer not cleared)" : ""} in focus mode; channel items are recall since you focused:`,
@@ -704,6 +845,32 @@ export function cotalToolSpecs(config, source = "connector") {
                     return ok(scope
                         ? `No pull-only messages and no normal focus recall.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued.` : ""}`
                         : "Inbox empty, no new messages, and no channel chatter since you entered focus.");
+                if (!all.length) {
+                    // A recalled message goes out in parts too, and its last part moves what a whole one would
+                    // have: the mark for the ordered lane, whose first item is the only one it may take, or the
+                    // ahead record, so the mark never passes a message that has not been handed over.
+                    const first = clocked[0];
+                    const item = buffered.find((i) => stuck.has(i.recvKey)) ??
+                        (first && stuck.has(first.recvKey) ? first : aheadFresh.find((i) => stuck.has(i.recvKey)));
+                    const part = partReply({
+                        agent,
+                        item,
+                        offered: [...buffered, ...fresh],
+                        stuck,
+                        peek: peek ?? false,
+                        warning,
+                        last: (i) => {
+                            if (bufferedIds.has(i.recvKey))
+                                agent.drainInboxDeliveries([i.recvKey]);
+                            else if (aheadIds.has(i.recvKey))
+                                agent.noteRecalledAhead(i.recvKey);
+                            else
+                                agent.noteRecalled({ ts: i.ts, id: i.recvKey });
+                        },
+                    });
+                    if (part)
+                        return ok(part);
+                }
                 // Render first, ack second, and only ever ids from the buffered lane: acking a recall id
                 // would mark it handled, so a later live copy of that channel message would be dropped.
                 if (!peek) {
@@ -723,14 +890,14 @@ export function cotalToolSpecs(config, source = "connector") {
                     for (const i of shownRecall)
                         if (aheadIds.has(i.recvKey))
                             agent.noteRecalledAhead(i.recvKey);
-                    const shownClocked = shownRecall.filter((i) => !aheadIds.has(i.id));
+                    const shownClocked = shownRecall.filter((i) => !aheadIds.has(i.recvKey));
                     const last = shownClocked[shownClocked.length - 1];
                     if (last)
                         agent.noteRecalled({ ts: last.ts, id: last.recvKey });
                     void stuck;
                 }
                 return ok(text);
-            },
+            }),
         },
         {
             name: "cotal_send",
@@ -767,10 +934,14 @@ export function cotalToolSpecs(config, source = "connector") {
             schema: {
                 to: z.string().describe("The peer's name (or instance id)."),
                 text: z.string().describe("The message."),
+                replyTo: z
+                    .string()
+                    .optional()
+                    .describe("The id of the peer's message this DM answers. Omit it to answer the peer's oldest unanswered message; when that peer's waiting messages belong to more than one conversation, the DM is refused with their ids."),
             },
-            async run(agent, _config, { to, text: msg }) {
+            async run(agent, _config, { to, text: msg, replyTo }) {
                 try {
-                    const { peer, ack, recipientStatusAtSend } = await agent.dm(to, msg);
+                    const { peer, ack, recipientStatusAtSend } = await agent.dm(to, msg, { replyTo });
                     const dup = ack.duplicate ? " duplicate publication." : "";
                     return ok(`DM stored as seq ${ack.seq} for ${peer.card.name} (recipient was ${recipientStatusAtSend} at send; delivery not confirmed).${dup}`);
                 }