@cohortapp/agent-sdk 2.5.0 → 2.5.1

package/lib/org/inbound/hydrate.mjs

@@ -51,16 +51,81 @@ export function clip(text, max = 4000) {
   return `${sp > max * 0.8 ? cut.slice(0, sp) : cut}…`;
 }
 
-/** Render a comment list into a compact prior-thread context block. */
+/**
+ * How many of the most recent turns must survive a binding character budget.
+ * Without a per-turn cap one long message spends the whole allowance and the
+ * turns around it vanish.
+ */
+const MIN_TURNS_VISIBLE = 4;
+
+/**
+ * Who said it. hq denormalises `authorName` onto history rows, and when it is
+ * there it wins. When it is NOT — an older server, or any surface that never
+ * denormalised one — the fallback is a bare cuid, and a transcript of
+ * "cmqh0t9…: fix this / cmqh0tc…: which one?" loses the single distinction that
+ * matters most: which turns are MINE. An agent that cannot tell its own words
+ * from the sender's re-answers itself and misattributes its own statements back
+ * to them. `facts.me` is always known, so that distinction never has to be lost.
+ */
+export function speakerFor(m, facts) {
+  const name = s(m && m.authorName);
+  if (name) return name;
+  const id = s(m && (m.authorId || m.author));
+  if (facts && facts.me && id === s(facts.me)) {
+    return (Array.isArray(facts.myNames) && facts.myNames[0]) || "me";
+  }
+  return id || "someone";
+}
+
+/**
+ * Render a comment list into a compact prior-thread context block, oldest first.
+ *
+ * ORDER IS NOT A DETAIL HERE. The sources disagree: every comment read
+ * (`board.taskComments`, `file.listComments`, `files.comments`,
+ * `decision.listComments`) returns ASCENDING, but `messaging.history` returns
+ * DESCENDING — hq orders `createdAt desc` unless the caller pages forward with
+ * an `after` cursor, and the inbound pull never does. So the bare `slice(-limit)`
+ * this used to do took the OLDEST rows off a message page and then printed them
+ * backwards: the wrong window, in the wrong direction, silently.
+ *
+ * Sorting on the timestamp makes the tail mean "the most recent turns" for every
+ * source. The sort is stable and the comparator declines to order rows with no
+ * parseable timestamp, so a source that carries none keeps its arrival order.
+ */
 export function renderThread(comments, { limit = 8, max = 2000 } = {}) {
-  const rows = (Array.isArray(comments) ? comments : []).slice(-limit);
+  const all = (Array.isArray(comments) ? comments : []).slice();
+  all.sort((a, b) => {
+    const ta = Date.parse(s(a && (a.createdAt || a.at)));
+    const tb = Date.parse(s(b && (b.createdAt || b.at)));
+    if (!Number.isFinite(ta) || !Number.isFinite(tb)) return 0;
+    return ta - tb;
+  });
+  const rows = all.slice(-limit);
   if (rows.length === 0) return null;
+
+  // Spend the budget from the NEWEST turn backwards. Clipping the joined string
+  // — which is what this did — keeps the oldest turns and drops the newest, the
+  // exact inverse of what context is for: the turns nearest the message being
+  // answered are the ones that explain it. Caught on the live CEO DM, where one
+  // long reply of mine filled the 2000 chars and displaced the four newer turns,
+  // including the question under discussion. The per-turn cap is the other half:
+  // without it a single long message starves every turn around it.
+  const perTurn = Math.max(200, Math.floor(max / Math.min(rows.length, MIN_TURNS_VISIBLE)));
   const lines = rows.map((c) => {
     const who = s(c.authorName || c.authorId || c.author || "someone");
-    const body = s(c.body || c.text).replace(/\s+/g, " ").trim();
+    const body = clip(s(c.body || c.text).replace(/\s+/g, " ").trim(), perTurn);
     return `${who}: ${body}`;
   });
-  return clip(lines.join("\n"), max) || null;
+
+  const kept = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const cost = lines[i].length + (kept.length ? 1 : 0); // +1 for the joining newline
+    if (kept.length > 0 && used + cost > max) break;
+    kept.unshift(lines[i]);
+    used += cost;
+  }
+  return kept.join("\n") || null;
 }
 
 /**
@@ -146,17 +211,24 @@ function hydrateMessage(c, facts) {
 
   const chan = facts.channels instanceof Map ? facts.channels.get(s(c.ids.channelId)) : null;
   const root = s(msg.threadRootId || msg.thread_root_id);
-  let threadContext = null;
-  if (root && page) {
-    const siblings = page.messages.filter(
-      (m) => s(m.threadRootId || m.thread_root_id) === root || s(m.id) === root,
-    );
-    threadContext = renderThread(
-      siblings
-        .filter((m) => s(m.id) !== s(c.ids.messageId))
-        .map((m) => ({ authorName: m.authorName || m.authorId, body: m.body ?? m.text })),
-    );
-  }
+
+  // THE CONVERSATION SO FAR. For a thread reply that is the thread; for a
+  // TOP-LEVEL message it is the channel itself — which is the whole of a DM.
+  // This used to be gated on `root`, so a DM (no thread root, by definition)
+  // arrived with no context at all and the agent answered "fix this" without
+  // ever seeing what "this" referred to. The page is already in hand from the
+  // ACL'd `messaging.history` read `pageChannels` made, so re-joining it here
+  // costs no RPC and widens nothing: it is the same read, same aperture.
+  const scope = root
+    ? page.messages.filter((m) => s(m.threadRootId || m.thread_root_id) === root || s(m.id) === root)
+    : page.messages;
+  const threadContext = renderThread(
+    priorTo(scope, msg, c.ids.messageId).map((m) => ({
+      authorName: speakerFor(m, facts),
+      body: m.body ?? m.text,
+      createdAt: m.createdAt,
+    })),
+  );
 
   return {
     ok: true,
@@ -467,6 +539,26 @@ async function hydrateEmail(c, facts, io, cache) {
 // Small helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The messages that came BEFORE the trigger — never the ones after it.
+ *
+ * A history page is a window, not a prefix: when the pull is running behind, or
+ * replaying after a crash, the page can hold turns that were said AFTER the
+ * message being hydrated. Handing those to the agent as "prior context" would
+ * have it answer a question using an answer it has not given yet. When a row
+ * carries no parseable timestamp we keep it rather than guess — dropping real
+ * conversation is the failure mode being fixed here.
+ */
+function priorTo(messages, trigger, triggerId) {
+  const at = Date.parse(s(trigger && trigger.createdAt));
+  return (Array.isArray(messages) ? messages : []).filter((m) => {
+    if (s(m.id) === s(triggerId)) return false;
+    if (!Number.isFinite(at)) return true;
+    const t = Date.parse(s(m.createdAt));
+    return !Number.isFinite(t) || t <= at;
+  });
+}
+
 /** Memoise an async read for the lifetime of one pull. */
 async function cached(cache, key, fn) {
   if (cache.has(key)) return cache.get(key);

package/lib/org/inbound/hydrate.test.mjs

@@ -118,6 +118,64 @@ test("a threaded message carries prior-thread context", async () => {
   assert.doesNotMatch(h.threadContext, /one more thing/, "the trigger itself is not its own context");
 });
 
+// A DM has no thread root — the CHANNEL is the conversation. Before this, the
+// `if (root)` guard meant a top-level message carried no context at all, so the
+// agent answered "fix this" with no idea what "this" referred to. The page is
+// already in hand from the ACL'd `messaging.history` read, so this costs no RPC.
+test("a top-level DM carries the preceding conversation as context", async () => {
+  // Newest-first, exactly as hq's messaging.history returns it.
+  const msgs = [
+    { id: "m3", authorId: THEM, authorName: "Casey", body: "fix this then", createdAt: "2026-08-11T15:33:54.000Z" },
+    { id: "m2", authorId: ME, authorName: "Alex", body: "16 min pickup on the morning batch", createdAt: "2026-08-11T15:32:00.000Z" },
+    { id: "m1", authorId: THEM, authorName: "Casey", body: "what is the reply latency here", createdAt: "2026-08-11T15:31:00.000Z" },
+  ];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM", name: "dm-h001-a016" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m3", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const io = fakeIo({});
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.equal(io.calls.length, 0, "the page was already in hand — context must cost no extra RPC");
+  assert.ok(h.threadContext, "a DM with prior turns must carry them");
+  assert.match(h.threadContext, /Casey: what is the reply latency here/);
+  assert.match(h.threadContext, /Alex: 16 min pickup/);
+  assert.doesNotMatch(h.threadContext, /fix this then/, "the trigger itself is not its own context");
+  assert.ok(
+    h.threadContext.indexOf("what is the reply latency") < h.threadContext.indexOf("16 min pickup"),
+    "oldest first — the conversation must read forwards",
+  );
+});
+
+test("a first-ever message in a channel has no context, not an empty block", async () => {
+  const msgs = [{ id: "m1", authorId: THEM, authorName: "Casey", body: "hello", createdAt: "2026-08-11T15:31:00.000Z" }];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+});
+
+test("messages AFTER the trigger are never passed off as prior context", async () => {
+  const msgs = [
+    { id: "m3", authorId: THEM, authorName: "Casey", body: "later message", createdAt: "2026-08-11T16:00:00.000Z" },
+    { id: "m2", authorId: THEM, authorName: "Casey", body: "the trigger", createdAt: "2026-08-11T15:00:00.000Z" },
+    { id: "m1", authorId: ME, authorName: "Alex", body: "earlier message", createdAt: "2026-08-11T14:00:00.000Z" },
+  ];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.threadContext, /earlier message/);
+  assert.doesNotMatch(h.threadContext, /later message/);
+});
+
 // ---------------------------------------------------------------------------
 // board
 // ---------------------------------------------------------------------------
@@ -318,6 +376,75 @@ test("clip and renderThread are bounded", () => {
   assert.match(renderThread([{ authorName: "A", body: "hi" }]), /A: hi/);
 });
 
+// `messaging.history` returns DESCENDING; every comment source returns ASCENDING.
+// A bare slice(-limit) therefore took the OLDEST rows off a message page and
+// printed them backwards — the wrong window, in the wrong order.
+test("renderThread reads forwards and keeps the most RECENT turns", () => {
+  const rows = [];
+  for (let i = 12; i >= 1; i -= 1) {
+    rows.push({ authorName: "A", body: `turn ${i}`, createdAt: `2026-08-11T00:${String(i).padStart(2, "0")}:00.000Z` });
+  }
+  const out = renderThread(rows); // limit 8
+
+  assert.match(out, /turn 12/, "the newest turn is the one that matters most");
+  assert.doesNotMatch(out, /turn 1\b/, "the oldest turns fall off the window, not the newest");
+  assert.ok(out.indexOf("turn 5") < out.indexOf("turn 12"), "oldest first");
+});
+
+test("renderThread leaves undated rows in the order they arrived", () => {
+  const out = renderThread([
+    { authorName: "A", body: "first" },
+    { authorName: "B", body: "second" },
+  ]);
+  assert.ok(out.indexOf("first") < out.indexOf("second"));
+});
+
+// The `limit` window and the `max` CHARACTER budget are two different windows,
+// and only the first was covered: twelve short turns never reach 2000 chars, so
+// the clip never fired and the direction it clips in was never asserted. On the
+// real DM it fired immediately — one long reply filled the budget and the four
+// newest turns, including the question being answered, were the ones discarded.
+test("renderThread keeps the NEWEST turns when the CHARACTER budget binds", () => {
+  const out = renderThread(
+    [
+      { authorName: "A", body: "x".repeat(1500), createdAt: "2026-08-11T00:01:00.000Z" },
+      { authorName: "B", body: "the thing I actually asked", createdAt: "2026-08-11T00:02:00.000Z" },
+    ],
+    { max: 300 },
+  );
+  assert.match(out, /the thing I actually asked/, "the latest turn must survive the budget");
+});
+
+test("renderThread does not let one huge turn starve the turns around it", () => {
+  const out = renderThread(
+    [
+      { authorName: "A", body: "y".repeat(5000), createdAt: "2026-08-11T00:01:00.000Z" },
+      { authorName: "B", body: "second", createdAt: "2026-08-11T00:02:00.000Z" },
+      { authorName: "C", body: "third", createdAt: "2026-08-11T00:03:00.000Z" },
+    ],
+    { max: 2000 },
+  );
+  assert.match(out, /B: second/);
+  assert.match(out, /C: third/);
+  assert.ok(out.length <= 2100, `bounded, got ${out.length}`);
+});
+
+// Until hq's `authorName` denormalisation is deployed every row carries a bare
+// cuid, and the agent must still be able to see which turns are its own.
+test("a transcript labels my own turns even when the server sends no names", async () => {
+  const msgs = [
+    { id: "m1", authorId: ME, body: "already answered that", createdAt: "2026-08-11T14:00:00.000Z" },
+    { id: "m2", authorId: THEM, body: "and the other thing?", createdAt: "2026-08-11T15:00:00.000Z" },
+  ];
+  const f = facts({ myNames: ["Isla"] });
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.threadContext, /Isla: already answered that/, "my own turn is mine, not a cuid");
+});
+
 test("event-kind phrasing is stable and total", () => {
   assert.match(describeBoardKind("item.assigned"), /assigned to you/);
   assert.match(describeBoardKind("who.knows"), /Update on your board item/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {