@cohortapp/agent-sdk 2.16.0 → 2.17.0

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

@@ -15,7 +15,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 
-import { hydrate, clip, renderThread, describeBoardKind, describeApprovalKind } from "./hydrate.mjs";
+import {
+  hydrate,
+  clip,
+  renderThread,
+  priorComments,
+  isCommentKind,
+  htmlToText,
+  clampDocHtml,
+  DOC_HTML_MAX_CHARS,
+  describeBoardKind,
+  describeApprovalKind,
+} from "./hydrate.mjs";
 import { classifyEvent } from "./directedness.mjs";
 
 const ME = "M-me";
@@ -46,7 +57,9 @@ function facts(over = {}) {
     me: ME,
     myNames: [],
     channels: new Map(),
+    visibleChannelIds: null,
     channelPages: new Map(),
+    myEvents: null,
     myThreadRootIds: new Set(),
     tasks: null,
     decisions: null,
@@ -451,3 +464,445 @@ test("event-kind phrasing is stable and total", () => {
   assert.match(describeApprovalKind("approval.requested"), /waiting on you/);
   assert.match(describeApprovalKind("approval.rejected"), /REJECTED/);
 });
+
+// ---------------------------------------------------------------------------
+// the slice(0,-1) guard — four surfaces used to lose their newest comment
+//
+// `renderThread(comments.slice(0,-1))` assumed the event was always a comment.
+// It is not: item.assigned, item.moved, file.shared and decision.signed are
+// events ABOUT an entity that HAS a thread, and for those the newest comment is
+// context, not the trigger. On a freshly assigned task with one comment, that
+// comment was the whole of the context and the agent saw none of it.
+// ---------------------------------------------------------------------------
+
+test("item.assigned KEEPS its newest comment — it is context, not the trigger", async () => {
+  const f = facts({ tasks: new Map([["T-1", { id: "T-1", title: "Ship the thing", col: "todo" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "the client needs this by Friday" }] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.assigned", entity_id: "T-1", payload: { actor: THEM, assignee: ME } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_assigned", reason: "assignee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.threadContext, /Casey: the client needs this by Friday/);
+  assert.equal(h.isReply, true);
+});
+
+test("item.moved keeps its newest comment", async () => {
+  const f = facts({ tasks: new Map([["T-2", { id: "T-2", title: "Rework", col: "blocked" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c9", authorName: "Casey", body: "moving this back, the numbers are wrong" }] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.moved", entity_id: "T-2", payload: { actor: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /the numbers are wrong/);
+});
+
+test("file.shared keeps its newest comment", async () => {
+  const f = facts({ fileAcl: new Map([["F-1", { ownerId: ME, shared: true, name: "Q3 plan", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "read section two first" }] }),
+    "files.docRead": () => okFrame({ html: "<p>Q3 plan</p>" }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "file.shared", entity_id: "F-1", payload: { actor: THEM, name: "Q3 plan" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "shared" }, facts: f, io });
+  assert.match(h.threadContext, /Casey: read section two first/);
+});
+
+test("decision.signed keeps its newest comment", async () => {
+  const f = facts({ decisions: new Map([["D-1", { id: "D-1", title: "Pick a vendor", status: "signed" }]]) });
+  const io = fakeIo({
+    "decision.listComments": () => okFrame({ comments: [{ id: "d1", authorName: "Casey", body: "signing on the understanding we revisit in Q4" }] }),
+  });
+  const c = classifyEvent(ev({ family: "decision", kind: "decision.signed", entity_id: "D-1", payload: { actor: THEM, signedBy: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "decision", reason: "voice" }, facts: f, io });
+  assert.match(h.threadContext, /revisit in Q4/);
+});
+
+test("a comment event still drops its OWN comment from the context", async () => {
+  const f = facts({ tasks: new Map([["T-3", { id: "T-3", title: "Ship it" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Isla", body: "first pass is up" },
+      { id: "c2", authorName: "Casey", body: "any update?" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-3", payload: { actor: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /first pass is up/);
+  assert.doesNotMatch(h.threadContext, /any update\?/, "the trigger is not its own context");
+});
+
+test("the payload's commentId drops the RIGHT comment when a newer one raced in", async () => {
+  const f = facts({ tasks: new Map([["T-4", { id: "T-4", title: "Ship it" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Isla", body: "first pass is up" },
+      { id: "c2", authorName: "Casey", body: "the trigger comment" },
+      { id: "c3", authorName: "Dana", body: "landed while we were reading" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-4", payload: { actor: THEM, commentId: "c2" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /first pass is up/);
+  assert.match(h.threadContext, /landed while we were reading/);
+  assert.doesNotMatch(h.threadContext, /the trigger comment/);
+});
+
+// ---------------------------------------------------------------------------
+// pure guards
+// ---------------------------------------------------------------------------
+
+test("priorComments never mutates the caller's array", () => {
+  const rows = [{ id: "a" }, { id: "b" }];
+  const out = priorComments(rows, { kind: "item.commented" });
+  assert.equal(rows.length, 2);
+  assert.equal(out.length, 1);
+});
+
+test("isCommentKind knows the six kinds that ARE comments", () => {
+  for (const k of ["item.commented", "board.commented", "file.commented", "doc.comment", "decision.comment", "decision.adjustment_requested"]) {
+    assert.equal(isCommentKind(k), true, k);
+  }
+  for (const k of ["item.assigned", "item.moved", "file.shared", "decision.signed", "", null]) {
+    assert.equal(isCommentKind(k), false, String(k));
+  }
+});
+
+test("htmlToText keeps the prose and drops the markup", () => {
+  assert.equal(htmlToText("<h1>Title</h1><p>One &amp; two</p><p>Three</p>"), "Title\nOne & two\nThree");
+  assert.equal(htmlToText("<script>bad()</script><p>ok</p>"), "ok");
+  assert.equal(htmlToText(null), "");
+});
+
+// ---------------------------------------------------------------------------
+// call — participants, the room, and the transcript
+// ---------------------------------------------------------------------------
+
+test("a call carries the roster, the room's recent messages and the transcript", async () => {
+  const msgs = [
+    { id: "m1", authorId: THEM, authorName: "Casey", body: "can we talk through the pricing", createdAt: "2026-08-11T09:00:00.000Z" },
+    { id: "m2", authorId: ME, authorName: "Isla", body: "yes — starting a huddle", createdAt: "2026-08-11T09:01:00.000Z" },
+  ];
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  f.channelPages.set("C-eng", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const io = fakeIo({
+    "calling.getDetails": () => okFrame({ callId: "CALL-1", live: true, participantCount: 2, participants: [
+      { kind: "MEMBER", memberId: THEM, inCall: true },
+      { kind: "GUEST", contactId: "contact-9", inCall: true },
+    ] }),
+    "calling.getTranscript": () => okFrame({ lines: [
+      { id: "l1", memberName: "Casey", text: "the list price is wrong on tier two", at: "2026-08-11T09:02:00.000Z" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-1", payload: { actor: THEM, channelId: "C-eng", topic: "pricing" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Call invite: pricing/);
+  assert.match(h.text, new RegExp(`In the call: ${THEM}, contact-9`));
+  assert.match(h.threadContext, /Casey: can we talk through the pricing/);
+  assert.match(h.threadContext, /Call transcript so far:/);
+  assert.match(h.threadContext, /the list price is wrong on tier two/);
+  assert.equal(io.calls.filter((k) => k.method === "messaging.history").length, 0, "the page was already in hand");
+});
+
+test("a call whose probes all fail still hydrates — fail-open, never blank", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  const io = fakeIo({}); // every method NOT_FOUND
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-2", payload: { actor: THEM, channelId: "C-eng", topic: "standup" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Call invite: standup/);
+  assert.equal(h.threadContext, null);
+});
+
+test("a call in a room outside my roster is never paged for history", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-mine"]) });
+  const io = fakeIo({ "calling.getDetails": () => okFrame({ participants: [] }) });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-3", payload: { actor: THEM, channelId: "C-not-mine", topic: "x" } }));
+  await hydrate({ candidate: c, verdict: { surface: "call", reason: "invited" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "messaging.history"), false, "a room outside the roster must never be touched");
+});
+
+test("an UNREADABLE roster is not permission — no room is paged when visibleChannelIds is null", async () => {
+  // The guard read `visible instanceof Set && !visible.has(id)`, so the null
+  // case — the roster call failed, or has not run — fell straight through into
+  // `messaging.history` on a channel id that arrived on the EVENT PAYLOAD.
+  // facts.mjs enforces the opposite (`if (!visible) … return`) and this file's
+  // own docstring claimed it; now the code does too.
+  const f = facts({ visibleChannelIds: null });
+  const io = fakeIo({ "calling.getDetails": () => okFrame({ participants: [] }) });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-4", payload: { actor: THEM, channelId: "C-PRIVATE-NOT-MINE", topic: "x" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "invited" }, facts: f, io });
+  assert.equal(h.ok, true, "declining a read is not a failed hydration");
+  assert.equal(
+    io.calls.some((k) => k.method === "messaging.history"),
+    false,
+    "an unknown roster must decline, not page an arbitrary payload-supplied channel",
+  );
+});
+
+test("an UNREADABLE roster is not permission — pinned files are not listed either", async () => {
+  const f = facts({ visibleChannelIds: null });
+  f.channels.set("C-PRIVATE-NOT-MINE", { id: "C-PRIVATE-NOT-MINE", kind: "PRIVATE", name: "board" });
+  const io = fakeIo({ "file.listComments": () => okFrame({ comments: [
+    { id: "fc1", authorId: THEM, authorName: "Casey", body: "@Isla thoughts?" },
+  ] }) });
+  const c = classifyEvent(ev({
+    family: "file", kind: "comment", entity_id: "FK-1",
+    payload: { actor: THEM, channelId: "C-PRIVATE-NOT-MINE", fileKey: "FK-1", body: "@Isla thoughts?", mentions: [ME] },
+  }));
+  await hydrate({ candidate: c, verdict: { surface: "chatFile", reason: "mention" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "file.listPinned"), false);
+});
+
+// ---------------------------------------------------------------------------
+// approval / escalation / handoff / calendar
+// ---------------------------------------------------------------------------
+
+test("an approval carries the thread of the item it is an approval OF", async () => {
+  const f = facts({
+    approvals: new Map([["A-1", { id: "A-1", status: "pending", requester: THEM, actionClass: "financial", itemId: "T-9" }]]),
+    tasks: new Map([["T-9", { id: "T-9", title: "Wire the retainer", col: "doing", priority: 1 }]]),
+  });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Casey", body: "legal cleared this on Tuesday" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { actor: THEM, requester: THEM, itemId: "T-9", actionClass: "financial" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Board item "Wire the retainer" — doing · priority 1/);
+  assert.match(h.threadContext, /legal cleared this on Tuesday/);
+});
+
+test("an approval on a DECISION falls back to the decision thread, and only then", async () => {
+  const f = facts({ approvals: new Map([["A-2", { id: "A-2", status: "pending", requester: THEM, itemId: "D-7" }]]) });
+  const io = fakeIo({
+    "decision.listComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "we ruled out the cheaper vendor" }] }),
+  });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-2", payload: { actor: THEM, requester: THEM, itemId: "D-7" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.match(h.threadContext, /we ruled out the cheaper vendor/);
+  assert.equal(io.calls.filter((k) => k.method === "board.taskComments").length, 1, "board is tried first, once");
+});
+
+test("an approval whose board thread is EMPTY does not pay for a second probe", async () => {
+  const f = facts({ approvals: new Map([["A-3", { id: "A-3", status: "pending", requester: THEM, itemId: "T-8" }]]) });
+  const io = fakeIo({ "board.taskComments": () => okFrame({ comments: [] }) });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-3", payload: { actor: THEM, requester: THEM, itemId: "T-8" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.equal(h.threadContext, null);
+  assert.equal(io.calls.some((k) => k.method === "decision.listComments"), false, "an empty thread is an answer, not a refusal");
+});
+
+test("an escalation carries the escalated task's row and its comments", async () => {
+  const f = facts({
+    escalations: new Map([["E-1", { id: "E-1", title: "Blocked on credentials", severity: "high", taskId: "T-5" }]]),
+    tasks: new Map([["T-5", { id: "T-5", title: "Migrate the vault", col: "blocked", priority: 0 }]]),
+  });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "the rotation script needs an admin key" }] }),
+  });
+  const c = classifyEvent(ev({ family: "escalation", kind: "escalation.created", entity_id: "E-1", payload: { actor: THEM, taskId: "T-5", severity: "high" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "escalation", reason: "assignee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Board item "Migrate the vault" — blocked · priority 0/);
+  assert.match(h.threadContext, /needs an admin key/);
+});
+
+test("an escalation whose task thread is unreadable still hydrates", async () => {
+  const f = facts({ escalations: new Map([["E-2", { id: "E-2", title: "Stuck", severity: "low", taskId: "T-6" }]]) });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "escalation", kind: "escalation.created", entity_id: "E-2", payload: { actor: THEM, taskId: "T-6" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "escalation", reason: "assignee" }, facts: f, io });
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+});
+
+test("a handoff carries the originating task's thread", async () => {
+  const f = facts({ tasks: new Map([["T-7", { id: "T-7", title: "Draft the board pack", col: "doing", detail: "for Thursday" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Casey", body: "sections 1-3 are done, 4 needs the latest numbers" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { actor: THEM, to: ME, from: THEM, itemId: "T-7", intent: "take over section 4" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "handoff", reason: "named" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Intent: take over section 4/);
+  assert.match(h.text, /Board item "Draft the board pack" — doing/);
+  assert.match(h.threadContext, /4 needs the latest numbers/);
+});
+
+test("a calendar event carries the room it was agreed in and earlier occurrences", async () => {
+  const msgs = [{ id: "m1", authorId: THEM, authorName: "Casey", body: "let's move the weekly to Thursdays", createdAt: "2026-08-10T09:00:00.000Z" }];
+  const f = facts({
+    visibleChannelIds: new Set(["C-ops"]),
+    myEvents: new Map([
+      ["E-now", { id: "E-now", title: "Ops weekly", startsAt: "2026-08-13T09:00:00.000Z", channelId: "C-ops" }],
+      ["E-old", { id: "E-old", title: "Ops weekly", startsAt: "2026-08-06T09:00:00.000Z", location: "Room 2" }],
+      ["E-other", { id: "E-other", title: "Board review", startsAt: "2026-08-05T09:00:00.000Z" }],
+    ]),
+  });
+  f.channels.set("C-ops", { id: "C-ops", kind: "PUBLIC", name: "ops" });
+  f.channelPages.set("C-ops", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "calendar", kind: "event.rescheduled", entity_id: "E-now", payload: { actor: THEM, channelId: "C-ops", title: "Ops weekly" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "calendar", reason: "attendee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.threadContext, /move the weekly to Thursdays/);
+  assert.match(h.threadContext, /Earlier in this series:/);
+  assert.match(h.threadContext, /2026-08-06T09:00:00.000Z · Room 2/);
+  assert.doesNotMatch(h.threadContext, /Board review/, "a different meeting is not this series");
+});
+
+test("a calendar event with no room and no series carries no invented context", async () => {
+  const f = facts({ myEvents: new Map([["E-1", { id: "E-1", title: "1:1", startsAt: "2026-08-13T09:00:00.000Z" }]]) });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "calendar", kind: "event.created", entity_id: "E-1", payload: { actor: THEM, calendarMemberId: ME, title: "1:1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "calendar", reason: "owner" }, facts: f, io });
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+  assert.equal(io.calls.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// artifact bodies — the agent must have READ the thing it is commenting on
+// ---------------------------------------------------------------------------
+
+test("a doc comment carries the document body, bounded", async () => {
+  const f = facts({ fileAcl: new Map([["F-2", { ownerId: ME, shared: true, name: "Pricing memo", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "is the tier-two number right?" }] }),
+    "files.docRead": () => okFrame({ html: `<h1>Pricing memo</h1><p>Tier two is ${"$"}4,800 per seat.</p>` }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-2", payload: { actor: THEM, name: "Pricing memo", commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Document:/);
+  assert.match(h.text, /Tier two is \$4,800 per seat\./);
+  assert.match(h.text, /is the tier-two number right\?/);
+  assert.doesNotMatch(h.text, /<p>/, "markup must not reach the model");
+});
+
+test("a doc body that is too long is clipped, and the comment still survives", async () => {
+  const f = facts({ fileAcl: new Map([["F-3", { ownerId: ME, shared: true, name: "Long", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "THE QUESTION" }] }),
+    "files.docRead": () => okFrame({ html: `<p>${"w".repeat(20000)}</p>` }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-3", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.ok(h.text.length < 6000, `doc body was not bounded (${h.text.length} chars)`);
+  assert.match(h.text, /THE QUESTION/, "the comment being answered must survive the doc body");
+});
+
+test("clampDocHtml bounds what a pull holds and converts", () => {
+  // files.docRead has no `limit` on the wire (ui-parity documents `{ fileId }`),
+  // so the only place this can be bounded is the instant it lands — before
+  // htmlToText walks it and before the per-pull cache keeps it. Measured before
+  // the clamp: 8 MB of HTML → 7,435,349 characters converted to retain 4,000.
+  assert.equal(clampDocHtml("<p>short</p>"), "<p>short</p>");
+  assert.equal(clampDocHtml("x".repeat(DOC_HTML_MAX_CHARS + 10)).length, DOC_HTML_MAX_CHARS);
+  assert.equal(clampDocHtml(null), "");
+  assert.ok(DOC_HTML_MAX_CHARS > 4000, "the clamp must leave room for a full text budget after markup");
+});
+
+test("a HUGE doc is clamped before it is converted, and never exceeds the shared ceiling", async () => {
+  // Two separate bounds, and the second one used to be missing entirely.
+  //   1. the raw HTML is sliced the instant it lands, so an 8 MB document does
+  //      not walk 7.4 M characters through htmlToText to retain 4,000;
+  //   2. the JOINED text is clipped like every other surface's — hydrateDoc had
+  //      dropped its outer clip(), making it the one hydrator that could hand
+  //      `item.content` more than the shared clamp allows.
+  // The name is unbounded on the wire (it rides `c.ids.name` / the ACL row), so
+  // it is the part that proves the OUTER clip is doing work rather than sitting
+  // above a ceiling the parts can never reach.
+  const f = facts({ fileAcl: new Map([["F-BIG", { ownerId: ME, shared: true, name: "N".repeat(50_000), kind: "DOC" }]]) });
+  const huge = `<p>${"w".repeat(2_000_000)}</p>`;
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "z".repeat(9000) }] }),
+    "files.docRead": () => okFrame({ html: huge }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-BIG", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.ok(h.text.length <= 5601, `hydrateDoc must honour its declared ceiling (${h.text.length} chars)`);
+});
+
+test("a SHEET is never asked for a doc body — hq would only refuse", async () => {
+  const f = facts({ fileAcl: new Map([["F-4", { ownerId: ME, shared: true, name: "Model", kind: "SHEET" }]]) });
+  const io = fakeIo({ "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "row 12?" }] }) });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-4", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.equal(io.calls.some((k) => k.method === "files.docRead"), false);
+});
+
+test("an unreadable doc body leaves the comment thread intact", async () => {
+  const f = facts({ fileAcl: new Map([["F-5", { ownerId: ME, shared: true, name: "Memo", kind: "DOC" }]]) });
+  const io = fakeIo({ "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "thoughts?" }] }) });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-5", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /thoughts\?/);
+  assert.doesNotMatch(h.text, /Document:/);
+});
+
+test("a file comment names the file — type and size, not just an opaque key", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  const io = fakeIo({
+    "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "page 3 is stale" }] }),
+    "file.listPinned": () => okFrame({ files: [
+      { id: "pf1", fileKey: "fk-1", name: "q3-forecast.pdf", mimeType: "application/pdf", sizeBytes: 1258291 },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { actor: THEM, fileKey: "fk-1", channelId: "C-eng" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Comment on file q3-forecast\.pdf/);
+  assert.match(h.text, /File: q3-forecast\.pdf · application\/pdf · 1\.2 MB/);
+  assert.match(h.text, /page 3 is stale/);
+  assert.equal(h.subjectDetail, "q3-forecast.pdf");
+});
+
+test("a file in a room outside my roster is never asked about", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-mine"]) });
+  const io = fakeIo({ "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "x" }] }) });
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { actor: THEM, fileKey: "fk-2", channelId: "C-not-mine" } }));
+  await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "file.listPinned"), false);
+});
+
+test("two comments on files in ONE room share a single listPinned read", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  const io = fakeIo({
+    "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "x" }] }),
+    "file.listPinned": () => okFrame({ files: [] }),
+  });
+  const cache = new Map();
+  for (const key of ["fk-a", "fk-b"]) {
+    const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: `c-${key}`, payload: { actor: THEM, fileKey: key, channelId: "C-eng" } }));
+    await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io, cache });
+  }
+  assert.equal(io.calls.filter((k) => k.method === "file.listPinned").length, 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
     "./singleton": "./lib/singleton.js",
     "./cadence-bus": "./lib/cadence-bus.mjs",
     "./fs-atomic": "./lib/fs-atomic.mjs",
+    "./context/budget": "./lib/context/budget.mjs",
+    "./context/history-scope": "./lib/context/history-scope.mjs",
     "./org/protocol": "./lib/org/protocol.mjs",
     "./org/client": "./lib/org/client.mjs",
     "./org/ui-parity": "./lib/org/ui-parity.mjs",

package/scripts/daemon/context-compiler.mjs

@@ -15,6 +15,8 @@ import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { isEnabled as orgEnabled, loadOrgConfig } from "../../lib/org/client.mjs";
 import { recall as orgRecall } from "../../lib/org/knowledge.mjs";
+import { isPrivateConversation, historyDirNames } from "../../lib/context/history-scope.mjs";
+import { fitSections } from "../../lib/context/budget.mjs";
 
 const AGENT_REPO_DIR = process.env.__TEST_AGENT_DIR || process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 const SESSION_DIR = process.env.__TEST_SESSION_DIR || join(AGENT_REPO_DIR, "state", "sessions");
@@ -56,6 +58,8 @@ const HISTORY_SHARE = 0.6;
  */
 function extractChannelId(item) {
   if (!item) return null;
+  // Every non-Slack service sets this outright; Slack is the one that has to be
+  // dug out of `raw_ref`.
   if (item.channel_id) return item.channel_id;
   if (item.raw_ref) {
     const match = item.raw_ref.match(/slack:([DC][A-Z0-9]+):/);
@@ -234,14 +238,32 @@ function loadDisclosureBoundaries(senderSlug, budgetTokens) {
 
 /**
  * Load conversation history from interaction logs, filtered by disclosure boundaries.
+ *
+ * READS THE ITEM'S OWN SERVICE. `responder.mjs#logInteraction` files every
+ * exchange under `memory/interactions/<service>/…`; this read was pinned to
+ * `…/slack/…`, so a Cohort, Telegram or WhatsApp exchange was written down and
+ * then never found (design §3 R12) — which is how "why can't you see the
+ * context of our ongoing conversation?" happened in a thread whose whole
+ * history was on disk the whole time.
+ *
+ * Slack keeps its legacy bare `<sender-slug>` directory alongside the `dm-`
+ * one, so historical logs do not go dark on this change.
+ *
+ * AND IT READS ONLY WHAT THIS ROOM MAY SEE. `logInteraction` files every
+ * exchange under BOTH the room and `dm-<sender-slug>`, so merging the candidate
+ * directories put one person's private DM sentence into the prompt built for a
+ * public channel the moment this read stopped being Slack-only. The gate lives
+ * in `lib/context/history-scope.mjs`, shared with the legacy prompt path and
+ * with the writer (design §5.5, resource scope).
  */
-function loadConversationHistory(senderSlug, channelId, budgetTokens, forbiddenDomains) {
-  const candidateDirs = [];
-  if (channelId) candidateDirs.push(join(AGENT_REPO_DIR, "memory", "interactions", "slack", channelId));
-  if (senderSlug) {
-    candidateDirs.push(join(AGENT_REPO_DIR, "memory", "interactions", "slack", `dm-${senderSlug}`));
-    candidateDirs.push(join(AGENT_REPO_DIR, "memory", "interactions", "slack", senderSlug));
-  }
+function loadConversationHistory(senderSlug, channelId, budgetTokens, forbiddenDomains, service = "slack", isPrivate = false) {
+  const svc = String(service || "slack");
+  const candidateDirs = historyDirNames({
+    channelId,
+    senderSlug,
+    isPrivate: isPrivate === true,
+    service: svc,
+  }).map((name) => join(AGENT_REPO_DIR, "memory", "interactions", svc, name));
 
   const entries = [];
   const seenKeys = new Set();
@@ -292,25 +314,27 @@ function loadConversationHistory(senderSlug, channelId, budgetTokens, forbiddenD
 
   if (filtered.length === 0) return null;
 
-  // Truncate to character budget — most recent messages prioritised (iterate from end)
-  const charBudget = budgetTokens * CHARS_PER_TOKEN;
-  const outputLines = [];
-  let totalChars = 0;
-
-  for (let i = filtered.length - 1; i >= 0; i--) {
-    const entry = filtered[i];
+  // Spend the budget from the NEWEST turn backwards, and SAY what fell off.
+  // This used to `break` out of the loop and return the survivors, so a prompt
+  // that had quietly lost thirty turns of a conversation looked exactly like a
+  // conversation thirty turns shorter — design §5.4: "dropping is visible in
+  // the prompt, never silent". `lib/context/budget.mjs` owns the arithmetic and
+  // the wording; this function only supplies the turns.
+  const turns = filtered.map((entry) => {
     const from = entry.from || entry.sender || entry.user_name || "unknown";
     const text = entry.content || entry.text || "(no text)";
     const ts = entry.received_at || entry.timestamp || entry.processed_at || entry.ts || "";
     const responded = entry.response_sent ? " [Responded]" : "";
-    const line = `[${ts}] ${from}: ${text.substring(0, 500)}${responded}`;
+    return `[${ts}] ${from}: ${text.substring(0, 500)}${responded}`;
+  });
 
-    if (totalChars + line.length > charBudget) break;
-    outputLines.unshift(line);
-    totalChars += line.length;
-  }
+  const fitted = fitSections({
+    sections: [{ name: "thread", turns }],
+    budgetTokens: Math.max(1, Number(budgetTokens) || 0),
+    charsPerToken: CHARS_PER_TOKEN,
+  });
 
-  return outputLines.length > 0 ? outputLines.join("\n") : null;
+  return fitted.text ? fitted.text : null;
 }
 
 // ── Active sessions ────────────────────────────────────────────────
@@ -522,7 +546,14 @@ export async function compileContext(item, classResult, options = {}) {
     const fixedTokens = ALLOC.profile + ALLOC.boundaries + ALLOC.active_sessions + ALLOC.sent_registry + ALLOC.org_memory;
     const remainingTokens = tokenBudget - fixedTokens;
     const historyBudget = Math.floor(remainingTokens * HISTORY_SHARE);
-    const historyText = loadConversationHistory(senderSlug, channelId, historyBudget, forbiddenDomains);
+    const historyText = loadConversationHistory(
+      senderSlug,
+      channelId,
+      historyBudget,
+      forbiddenDomains,
+      item?.service,
+      isPrivateConversation(item),
+    );
 
     // Step 5 — Active sessions
     const sessionsText = loadActiveSessions(ALLOC.active_sessions);