@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/org/inbound/hydrate.mjs

@@ -7,19 +7,31 @@
  * classify and the agent "replies" to a blank message. This module re-joins the
  * content, and it does so through the agent's OWN entitled reads:
  *
- *   | surface        | read                                    | ACL hq applies              |
- *   |----------------|-----------------------------------------|-----------------------------|
- *   | dm / mention   | messaging.history (already in facts)     | assertChannelAccess         |
- *   | thread_reply   | messaging.history (already in facts)     | assertChannelAccess         |
- *   | call           | (payload only — topic + callId)          | —                           |
- *   | task_*         | board.taskComments                       | org-scoped task             |
- *   | file_comment   | file.listComments                        | assertChannelVisible        |
- *   | doc_comment    | files.comments                           | doc ACL (NOT_FOUND if none) |
- *   | decision       | decision.listComments                    | org-scoped                  |
- *   | escalation     | escalation.list (already in facts)        | org-scoped                  |
- *   | approval       | approval.get (already in facts)           | org-scoped                  |
- *   | handoff        | (payload only — intent + itemId)         | —                           |
- *   | email          | email.thread / email.message             | OWN MAILBOX ONLY            |
+ *   | surface        | read                                       | ACL hq applies              |
+ *   |----------------|--------------------------------------------|-----------------------------|
+ *   | dm / mention   | messaging.history (already in facts)        | assertChannelAccess         |
+ *   | thread_reply   | messaging.history (already in facts)        | assertChannelAccess         |
+ *   | call           | calling.getDetails / .getTranscript,        | participation-gated         |
+ *   |                | messaging.history for the room              | assertChannelAccess         |
+ *   | task_*         | board.taskComments                          | org-scoped task             |
+ *   | file_comment   | file.listComments + file.listPinned         | assertChannelVisible        |
+ *   | doc_comment    | files.comments + files.docRead              | doc ACL (NOT_FOUND if none) |
+ *   | decision       | decision.listComments                       | org-scoped                  |
+ *   | escalation     | escalation.list (facts) + board.taskComments| org-scoped                  |
+ *   | approval       | approval.get (facts) + the item's comments  | org-scoped                  |
+ *   | handoff        | board.taskComments on the origin task       | org-scoped task             |
+ *   | calendar       | calendar.list (facts) + the room's history  | lens floor / channel ACL    |
+ *   | email          | email.thread / email.message                | OWN MAILBOX ONLY            |
+ *
+ * ── WHY FIVE SURFACES USED TO HAVE NO HISTORY AT ALL ──
+ * `call`, `approval`, `escalation`, `calendar` and `handoff` rendered the
+ * entity's own fields and stopped (design §3 R5). An approval names an action
+ * class and a requester; an escalation names a severity. Neither says what the
+ * work IS, so the agent answered the row rather than the situation. Each now
+ * reaches for the conversation the entity is anchored to, through the SAME
+ * `io.call` seam and the SAME `renderThread` budget as every other surface, and
+ * each probe is independently fail-open: a probe that fails leaves that one
+ * block absent and the item still hydrates.
  *
  * Because every one of those is the same read the agent could make by hand,
  * hydration can never widen what the agent may see — it only re-joins content
@@ -128,6 +140,220 @@ export function renderThread(comments, { limit = 8, max = 2000 } = {}) {
   return kept.join("\n") || null;
 }
 
+/**
+ * Event kinds whose TRIGGER is the newest row of the comment thread the
+ * hydrator is about to read. hq's own handlers are the source: `board/comment`
+ * appends `board.commented`, `board/addTaskComment` appends `item.commented`,
+ * `file/addComment` appends `file.commented`, `files/commentAdd` appends
+ * `doc.comment`, and both `decision/comment` and `decision/requestAdjustment`
+ * write a `DecisionComment` row before appending theirs.
+ *
+ * Nothing else does. `item.assigned`, `item.moved`, `file.shared` and
+ * `decision.signed` are events ABOUT an entity that happens to have a comment
+ * thread — for those the newest comment is prior context, not the trigger.
+ */
+export const COMMENT_KINDS = Object.freeze([
+  "item.commented",
+  "board.commented",
+  "file.commented",
+  "doc.comment",
+  "decision.comment",
+  "decision.adjustment_requested",
+]);
+
+const COMMENT_KIND_SET = new Set(COMMENT_KINDS);
+
+/** Is this event kind itself a comment? See {@link COMMENT_KINDS}. */
+export function isCommentKind(kind) {
+  return COMMENT_KIND_SET.has(s(kind));
+}
+
+/**
+ * The comments that are CONTEXT for this event, i.e. everything except the one
+ * that triggered it.
+ *
+ * This used to be a flat `comments.slice(0, -1)` on every board, file, doc and
+ * decision hydrator. That is right for a comment event and wrong for every
+ * other kind: an `item.assigned` or a `decision.signed` has no comment of its
+ * own, so slicing the tail threw away the newest — and on a freshly assigned
+ * task with exactly one comment, that comment was the whole of the context and
+ * the agent saw none of it.
+ *
+ * Two guards, in order of precision:
+ *   1. the payload's own `commentId`, when the row is still on the page. Exact,
+ *      and correct even when a newer comment landed between the event being
+ *      appended and this read — the flat slice dropped the WRONG row there.
+ *   2. otherwise the event kind ({@link isCommentKind}).
+ *
+ * @param {object[]} comments the full thread, as read
+ * @param {{kind?:string, commentId?:string}} [ev]
+ * @returns {object[]} a new array — the caller's is never mutated
+ */
+export function priorComments(comments, ev = {}) {
+  const rows = Array.isArray(comments) ? comments.slice() : [];
+  const id = s(ev && ev.commentId);
+  if (id) {
+    const idx = rows.findIndex((c) => s(c && c.id) === id);
+    if (idx !== -1) {
+      rows.splice(idx, 1);
+      return rows;
+    }
+  }
+  if (isCommentKind(ev && ev.kind)) return rows.slice(0, -1);
+  return rows;
+}
+
+/**
+ * How many of a room's most recent messages a non-messaging surface borrows.
+ * A call or a calendar event needs enough of the room to know what is being
+ * talked about; it is not the conversation itself, so it gets less than one.
+ */
+const ROOM_HISTORY_TURNS = 8;
+
+/** Messages fetched when a room has to be paged for one of those surfaces. */
+const ROOM_HISTORY_LIMIT = 25;
+
+/** Transcript lines requested / rendered for a call. */
+const CALL_TRANSCRIPT_LIMIT = 40;
+const CALL_TRANSCRIPT_TURNS = 12;
+
+/** Prior occurrences of a recurring event rendered on a calendar surface. */
+const CALENDAR_SERIES_TURNS = 3;
+
+/** The artifact body budget. Same clamp `clip` already defaults to. */
+const ARTIFACT_BODY_CHARS = 4000;
+
+/** The triggering comment's own budget, alongside an artifact body. */
+const COMMENT_CHARS = 1200;
+
+/**
+ * The doc surface's own ceiling for `hydrated.text`.
+ *
+ * Every other hydrator returns `clip(...)` at {@link clip}'s 4000 default. A doc
+ * carries a body AND the comment being answered, and clipping the two together
+ * at 4000 would spend the whole allowance on the document and cut off the
+ * question. So the ceiling is stated, and it is the sum of the declared parts
+ * plus the heading — not "whatever the parts happen to add up to".
+ */
+const DOC_TEXT_CHARS = 5600;
+
+/**
+ * Pinned-file rows scanned for one comment. `file.listPinned` carries no limit
+ * on the wire, so the bound lives here.
+ */
+const PINNED_FILES_MAX = 200;
+
+/**
+ * The most doc HTML that is ever CONVERTED.
+ *
+ * `files.docRead` returns the whole document; the wire has no limit to ask for
+ * and inventing a parameter hq does not document would be a silent no-op. So
+ * the raw string is clamped the instant it lands, BEFORE `htmlToText` runs and
+ * before the per-pull cache holds it. Measured before this clamp: 8 MB of HTML
+ * converted to 7,435,349 characters to retain 4,000. Generous against
+ * {@link ARTIFACT_BODY_CHARS} because markup is most of the bytes — the body of
+ * a long doc still reaches its full text budget.
+ */
+export const DOC_HTML_MAX_CHARS = 200_000;
+
+/**
+ * The doc HTML this pull is willing to hold and convert. Exported so the bound
+ * is testable on its own — the clamp is invisible in the hydrated output (the
+ * 4000-char text clip hides it), which is exactly how it went missing.
+ */
+export function clampDocHtml(html) {
+  const t = s(html);
+  return t.length > DOC_HTML_MAX_CHARS ? t.slice(0, DOC_HTML_MAX_CHARS) : t;
+}
+
+/**
+ * The room's recent conversation, for a surface anchored to a channel.
+ *
+ * THE ONE RULE `facts.mjs` enforces holds here too: a channel outside the
+ * visible roster is NEVER touched. `messaging.channels` returns a private room
+ * only to its members, so refusing to page anything outside that set means this
+ * cannot become the aperture the directedness probe declined to open. When the
+ * roster is unknown (`visibleChannelIds === null`) we also decline — unknown is
+ * not permission, and this is the one gate in the file that is NOT fail-open.
+ * `facts.mjs:314-321` already enforces exactly that (`if (!visible) { … return; }`);
+ * writing the guard as `visible instanceof Set && !visible.has(id)` let the null
+ * case through, so an unreadable roster plus a channel id supplied by the event
+ * payload paged a room this seat may never have been in. hq's
+ * `assertChannelAccess` still refused it, but the local gate the docstring
+ * claims has to exist or the claim is the thing that is wrong.
+ *
+ * Free when the facts pass already paged the channel; one capped
+ * `messaging.history` otherwise, memoised for the pull.
+ *
+ * @returns {Promise<string|null>} a rendered thread block, or null
+ */
+async function roomHistory(channelId, facts, io, cache) {
+  const id = s(channelId);
+  if (!id || !io) return null;
+  const visible = facts && facts.visibleChannelIds;
+  if (!(visible instanceof Set) || !visible.has(id)) return null;
+
+  const page = facts && facts.channelPages instanceof Map ? facts.channelPages.get(id) : null;
+  const messages = page && Array.isArray(page.messages) && page.messages.length
+    ? page.messages
+    : await cached(cache, `roomHistory:${id}`, async () => {
+        const frame = await io.call("messaging.history", { channelId: id, limit: ROOM_HISTORY_LIMIT });
+        return frame && frame.ok === true ? arrayOf(resultOf(frame), "messages") : [];
+      });
+
+  return renderThread(
+    (Array.isArray(messages) ? messages : []).map((m) => ({
+      authorName: speakerFor(m, facts),
+      body: m.body ?? m.text,
+      createdAt: m.createdAt,
+    })),
+    { limit: ROOM_HISTORY_TURNS },
+  );
+}
+
+/**
+ * A board item's comment thread. Shared by the board, escalation, approval and
+ * handoff hydrators, which all anchor on a task id. Fail-open: an unreadable
+ * thread is an absent block, never a failed hydration.
+ */
+async function taskComments(taskId, io, cache) {
+  const id = s(taskId);
+  if (!id || !io) return [];
+  return cached(cache, `taskComments:${id}`, async () => {
+    const frame = await io.call("board.taskComments", { taskId: id });
+    return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
+  });
+}
+
+/** Join the context blocks a surface gathered, dropping the ones that are empty. */
+function joinContext(blocks) {
+  const kept = (Array.isArray(blocks) ? blocks : []).map((b) => s(b).trim()).filter(Boolean);
+  return kept.length ? kept.join("\n") : null;
+}
+
+/**
+ * HTML → the text a reader would see. `files.docRead` returns the doc's HEAD
+ * html; handing raw markup to the model spends the budget on tags and teaches
+ * it to answer in markup. Deliberately small: block tags become newlines, the
+ * five XML entities are decoded, everything else goes.
+ */
+export function htmlToText(html) {
+  return s(html)
+    .replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ")
+    .replace(/<\/(p|div|li|h[1-6]|tr|blockquote)>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/&amp;/gi, "&")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
 /**
  * @typedef {Object} Hydrated
  * @property {boolean} ok
@@ -164,7 +390,7 @@ export async function hydrate(o = {}) {
       case "messaging":
         return hydrateMessage(c, facts);
       case "calling":
-        return hydrateCall(c, facts);
+        return await hydrateCall(c, facts, io, cache);
       case "board":
         return await hydrateTask(c, verdict, facts, io, cache);
       case "file":
@@ -174,13 +400,13 @@ export async function hydrate(o = {}) {
       case "decision":
         return await hydrateDecision(c, facts, io, cache);
       case "escalation":
-        return hydrateEscalation(c, facts);
+        return await hydrateEscalation(c, facts, io, cache);
       case "approval":
-        return hydrateApproval(c, facts);
+        return await hydrateApproval(c, facts, io, cache);
       case "handoff":
-        return hydrateHandoff(c, facts);
+        return await hydrateHandoff(c, facts, io, cache);
       case "calendar":
-        return hydrateCalendar(c, facts);
+        return await hydrateCalendar(c, facts, io, cache);
       case "email":
         return await hydrateEmail(c, facts, io, cache);
       default:
@@ -242,15 +468,73 @@ function hydrateMessage(c, facts) {
   };
 }
 
-/** Calls: the invite topic is the whole content; there is no body to fetch. */
-function hydrateCall(c, facts) {
+/**
+ * A call. The invite topic used to be the whole of it — an agent pulled into a
+ * huddle knew the room and the word "standup" and nothing else.
+ *
+ * Three reads, each independently fail-open:
+ *   - `calling.getDetails` for the roster (who is actually in the room). It is
+ *     participation-gated, so an invite not yet accepted can come back
+ *     FORBIDDEN; that is a missing line, not a failed hydration.
+ *   - `calling.getTranscript` for what has already been said, when the call is
+ *     under way (an invite to a fresh call simply has no lines).
+ *   - the room's recent messages, which is where the call was almost always
+ *     agreed before it was started.
+ */
+async function hydrateCall(c, facts, io, cache) {
   const chan = facts.channels instanceof Map ? facts.channels.get(s(c.ids.channelId)) : null;
   const topic = s(c.ids.topic);
+  const callId = s(c.ids.callId);
+
+  const details = callId && io
+    ? await cached(cache, `callDetails:${callId}`, async () => {
+        const frame = await io.call("calling.getDetails", { callId });
+        return frame && frame.ok === true ? resultOf(frame) : null;
+      })
+    : null;
+
+  // `limit` is asked for, and then enforced locally anyway: `ui-parity.mjs`
+  // documents the wire contract for `calling.getTranscript` as `{ callId }`
+  // alone, so a server that ignores the extra key would hand back every line of
+  // an hour-long call. The tail is the part that matters, so the tail is kept.
+  const transcript = callId && io
+    ? await cached(cache, `callTranscript:${callId}`, async () => {
+        const frame = await io.call("calling.getTranscript", { callId, limit: CALL_TRANSCRIPT_LIMIT });
+        const lines = frame && frame.ok === true ? arrayOf(resultOf(frame), "lines") : [];
+        return lines.length > CALL_TRANSCRIPT_LIMIT ? lines.slice(-CALL_TRANSCRIPT_LIMIT) : lines;
+      })
+    : [];
+
+  const lines = [topic ? `Call invite: ${topic}` : "Call invite"];
+  if (details) {
+    const roster = arrayOf(details, "participants")
+      .filter((p) => p && (p.inCall || p.joinedAt))
+      .map((p) => s(p.memberId || p.contactId))
+      .filter(Boolean);
+    if (roster.length) lines.push(`In the call: ${roster.join(", ")}`);
+    else if (Number.isFinite(Number(details.participantCount))) {
+      lines.push(`Participants: ${Number(details.participantCount)}`);
+    }
+    if (details.live === false) lines.push("This call has ended.");
+  }
+
+  const transcriptBlock = renderThread(
+    transcript.map((l) => ({
+      authorName: s(l && (l.memberName || l.memberId)) || "someone",
+      body: l && l.text,
+      createdAt: l && l.at,
+    })),
+    { limit: CALL_TRANSCRIPT_TURNS },
+  );
+  const room = await roomHistory(c.ids.channelId, facts, io, cache);
+
   return {
     ok: true,
-    text: topic ? `Call invite: ${topic}` : "Call invite",
+    text: clip(lines.join("\n")),
     subjectDetail: topic,
-    threadId: s(c.ids.callId),
+    threadId: callId,
+    threadContext: joinContext([room, transcriptBlock ? `Call transcript so far:\n${transcriptBlock}` : null]),
+    isReply: Boolean(transcriptBlock),
     from: { id: s(c.actor), name: s(c.actor) },
     channelId: s(c.ids.channelId),
     channelLabel: s((chan && (chan.name || chan.slug)) || c.ids.channelId || "cohort"),
@@ -261,12 +545,10 @@ function hydrateCall(c, facts) {
 async function hydrateTask(c, verdict, facts, io, cache) {
   const taskId = s(c.ids.taskId);
   const task = facts.tasks instanceof Map ? facts.tasks.get(taskId) : null;
-  const comments = await cached(cache, `taskComments:${taskId}`, async () => {
-    const frame = await io.call("board.taskComments", { taskId });
-    return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
-  });
+  const comments = await taskComments(taskId, io, cache);
 
   const title = s(task && task.title) || taskId;
+  const prior = priorComments(comments, { kind: c.kind, commentId: c.ids.commentId });
   const latest = comments.length ? comments[comments.length - 1] : null;
   const verb = describeBoardKind(c.kind);
   const lines = [`${verb} — "${title}"`];
@@ -282,15 +564,29 @@ async function hydrateTask(c, verdict, facts, io, cache) {
     text: clip(lines.join("\n")),
     subjectDetail: title,
     threadId: taskId,
-    threadContext: renderThread(comments.slice(0, -1)),
-    isReply: comments.length > 1,
+    threadContext: renderThread(prior),
+    isReply: prior.length > 0,
     from: { id: s(c.actor), name: s((latest && latest.authorName) || c.actor) },
     channelId: s(c.ids.channelId || (task && task.channelId) || ""),
     channelLabel: `task/${title}`,
   };
 }
 
-/** A chat-attached file's comment thread (`file.listComments`). */
+/**
+ * A chat-attached file: its comment thread AND the file itself.
+ *
+ * FileComment had ZERO agent activity in 14 days (design §2), and this is one
+ * half of why: the hydrator read the comments and never the artifact, so the
+ * agent was asked to respond to "is this right?" about a thing it had not seen.
+ *
+ * What "the artifact" means here is bounded by the protocol, deliberately.
+ * `file.listPinned` is explicit that "the dataUrl bytes are NOT projected —
+ * only ids + metadata", so a chat attachment's BYTES are not on the wire at
+ * all and this cannot invent a read that would serve them. What it can join is
+ * the file's record (name, type, size) and the message that shared it, which
+ * together are what a human sees in the room before opening it. Both are
+ * fail-open: no record and no room simply means no extra lines.
+ */
 async function hydrateChatFile(c, facts, io, cache) {
   const fileKey = s(c.ids.fileKey);
   const channelId = s(c.ids.channelId);
@@ -304,21 +600,87 @@ async function hydrateChatFile(c, facts, io, cache) {
   const latest = comments.length ? comments[comments.length - 1] : null;
   if (!latest) return { ok: false, reason: "file_comment_unreadable", text: "" };
 
+  const record = await pinnedFileRecord(fileKey, channelId, facts, io, cache);
+  const prior = priorComments(comments, { kind: c.kind, commentId: c.ids.commentId });
   const chan = facts.channels instanceof Map ? facts.channels.get(channelId) : null;
+  const name = s(record && record.name) || fileKey;
+
+  const lines = [`Comment on file ${name}`];
+  if (record) lines.push(`File: ${describeFileRecord(record)}`);
+  lines.push(`${s(latest.authorName || latest.authorId)}: ${s(latest.body)}`);
+
   return {
     ok: true,
-    text: clip(`Comment on file ${fileKey}\n${s(latest.authorName || latest.authorId)}: ${s(latest.body)}`),
-    subjectDetail: fileKey,
+    text: clip(lines.join("\n")),
+    subjectDetail: name,
     threadId: fileKey,
-    threadContext: renderThread(comments.slice(0, -1)),
-    isReply: comments.length > 1,
+    threadContext: renderThread(prior),
+    isReply: prior.length > 0,
     from: { id: s(latest.authorId || c.actor), name: s(latest.authorName || latest.authorId || c.actor) },
     channelId,
     channelLabel: s((chan && (chan.name || chan.slug)) || `file/${fileKey}`),
   };
 }
 
-/** A workspace doc's comment thread (`files.comments`). */
+/**
+ * The pinned-file record for an opaque chat `fileKey`, or null.
+ *
+ * ONE `file.listPinned` per CHANNEL per pull — the read is channel-scoped, so
+ * two comments on two files in the same room share it. Gated on channel
+ * visibility exactly as {@link roomHistory} is, unknown roster included: an
+ * absent roster declines rather than proceeding.
+ *
+ * `file.listPinned` takes no limit, so the row list is clamped here — a room
+ * with hundreds of pinned files must not turn one comment into an unbounded
+ * scan. The rows carry names and sizes, not bodies, so the clamp is generous.
+ */
+async function pinnedFileRecord(fileKey, channelId, facts, io, cache) {
+  const key = s(fileKey);
+  const cid = s(channelId);
+  if (!key || !cid || !io) return null;
+  const visible = facts && facts.visibleChannelIds;
+  if (!(visible instanceof Set) || !visible.has(cid)) return null;
+
+  const rows = await cached(cache, `pinnedFiles:${cid}`, async () => {
+    const frame = await io.call("file.listPinned", { channelId: cid });
+    return frame && frame.ok === true
+      ? arrayOf(resultOf(frame), "files").slice(0, PINNED_FILES_MAX)
+      : [];
+  });
+  return rows.find((r) => r && (s(r.fileKey) === key || s(r.id) === key)) || null;
+}
+
+/** `quarterly.pdf · application/pdf · 1.2 MB` — what the room shows about a file. */
+function describeFileRecord(record) {
+  const parts = [s(record.name) || "file"];
+  if (record.mimeType) parts.push(s(record.mimeType));
+  const bytes = Number(record.sizeBytes);
+  if (Number.isFinite(bytes) && bytes > 0) parts.push(formatBytes(bytes));
+  return parts.join(" · ");
+}
+
+/** Bytes as a person reads them. */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * A workspace doc: its comment thread AND the document.
+ *
+ * `files.docRead` returns the doc's HEAD html through the SAME `files.read`
+ * scope `files.get` already used in the facts pass — it is the read the agent
+ * could make by hand, so joining it here widens nothing. The body is converted
+ * to text and clipped to {@link ARTIFACT_BODY_CHARS}: a 40-page doc must not
+ * spend the whole prompt, and the comment being answered is nearly always about
+ * the top of it.
+ *
+ * Only DOC-kind files are read. A sheet or a deck answers `BAD_REQUEST` from
+ * `files.docRead`, so when the facts pass already knows the kind we skip the
+ * call rather than spend a round trip on a refusal; when it does not, the
+ * refusal is fail-open like every other probe here.
+ */
 async function hydrateDoc(c, facts, io, cache) {
   const fileId = s(c.ids.fileId);
   const comments = await cached(cache, `docComments:${fileId}`, async () => {
@@ -327,25 +689,49 @@ async function hydrateDoc(c, facts, io, cache) {
   });
   const acl = facts.fileAcl instanceof Map ? facts.fileAcl.get(fileId) : null;
   const name = s(c.ids.name || (acl && acl.name) || fileId);
+  const prior = priorComments(comments, { kind: c.kind, commentId: c.ids.commentId });
   const latest = comments.length ? comments[comments.length - 1] : null;
-  const head = describeFilesKind(c.kind, name);
-  const text = latest
-    ? `${head}\n${s(latest.authorName || latest.authorId)}: ${s(latest.body)}`
-    : head;
+  const body = await docBody(fileId, acl, io, cache);
+
+  const lines = [describeFilesKind(c.kind, name)];
+  if (body) lines.push(`Document:\n${body}`);
+  // The comment is clipped on its own, not with the body: one `clip` over the
+  // join would spend the whole 4000 on the document and drop the very sentence
+  // being answered. The join is then clipped AGAIN at the shared ceiling, which
+  // every other hydrator applies — dropping it here made this the one surface
+  // that could exceed `clip`'s default, silently, by about a third.
+  if (latest) lines.push(`${s(latest.authorName || latest.authorId)}: ${clip(s(latest.body), COMMENT_CHARS)}`);
 
   return {
     ok: true,
-    text: clip(text),
+    text: clip(lines.join("\n"), DOC_TEXT_CHARS),
     subjectDetail: name,
     threadId: fileId,
-    threadContext: renderThread(comments.slice(0, -1)),
-    isReply: comments.length > 1,
+    threadContext: renderThread(prior),
+    isReply: prior.length > 0,
     from: { id: s((latest && latest.authorId) || c.actor), name: s((latest && latest.authorName) || c.actor) },
     channelId: "",
     channelLabel: `doc/${name}`,
   };
 }
 
+/** The doc's text, bounded, or null. Fail-open on every path. */
+async function docBody(fileId, acl, io, cache) {
+  const id = s(fileId);
+  if (!id || !io) return null;
+  const kind = s(acl && acl.kind).toUpperCase();
+  if (kind && kind !== "DOC") return null;
+  const html = await cached(cache, `docBody:${id}`, async () => {
+    const frame = await io.call("files.docRead", { fileId: id });
+    const res = frame && frame.ok === true ? resultOf(frame) : null;
+    // Clamped HERE, not after conversion: this is what the cache holds and what
+    // htmlToText walks. See DOC_HTML_MAX_CHARS.
+    return res ? clampDocHtml(res.html) : "";
+  });
+  const text = htmlToText(html);
+  return text ? clip(text, ARTIFACT_BODY_CHARS) : null;
+}
+
 /** A decision, its rationale, and its comment thread. */
 async function hydrateDecision(c, facts, io, cache) {
   const decisionId = s(c.ids.decisionId);
@@ -355,6 +741,7 @@ async function hydrateDecision(c, facts, io, cache) {
     return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
   });
   const title = s((d && d.title) || c.ids.title || decisionId);
+  const prior = priorComments(comments, { kind: c.kind, commentId: c.ids.commentId });
   const latest = comments.length ? comments[comments.length - 1] : null;
 
   const lines = [`${describeDecisionKind(c.kind)} — "${title}"`];
@@ -369,41 +756,67 @@ async function hydrateDecision(c, facts, io, cache) {
     text: clip(lines.join("\n")),
     subjectDetail: title,
     threadId: decisionId,
-    threadContext: renderThread(comments.slice(0, -1)),
-    isReply: comments.length > 1,
+    threadContext: renderThread(prior),
+    isReply: prior.length > 0,
     from: { id: s(c.ids.authorId || c.actor), name: s((latest && latest.authorName) || c.actor) },
     channelId: "",
     channelLabel: `decision/${title}`,
   };
 }
 
-/** An escalation — already fully read back by the facts pass. */
-function hydrateEscalation(c, facts) {
+/**
+ * An escalation, plus the work it escalated.
+ *
+ * The row says a severity and a sentence of detail. What it never said is what
+ * the task is or what has already been tried on it — which is the whole of what
+ * an escalation is asking about. The escalated task's board row (free, already
+ * in `facts.tasks`) and its comment thread supply that.
+ */
+async function hydrateEscalation(c, facts, io, cache) {
   const id = s(c.ids.escalationId);
   const e = facts.escalations instanceof Map ? facts.escalations.get(id) : null;
   const title = s((e && e.title) || id);
+  const taskId = s(c.ids.taskId || (e && e.taskId));
+  const task = taskId && facts.tasks instanceof Map ? facts.tasks.get(taskId) : null;
+
   const lines = [`${c.kind === "escalation.resolved" ? "Escalation resolved" : "Escalation raised"} — "${title}"`];
   if (e && e.severity) lines.push(`Severity: ${s(e.severity)}`);
   if (e && e.detail) lines.push(clip(e.detail, 1200));
   if (e && e.waitingOn) lines.push(`Waiting on: ${s(e.waitingOn)}`);
   if (e && e.resolution) lines.push(`Resolution: ${clip(e.resolution, 600)}`);
+  if (task) lines.push(describeTaskRow(task, taskId));
+
+  const comments = taskId ? await taskComments(taskId, io, cache) : [];
+
   return {
     ok: true,
     text: clip(lines.join("\n")),
     subjectDetail: title,
     threadId: id,
+    threadContext: renderThread(comments),
+    isReply: comments.length > 0,
     from: { id: s(c.actor), name: s(c.actor) },
     channelId: s(c.ids.channelId || (e && e.channelId) || ""),
     channelLabel: `escalation/${title}`,
   };
 }
 
+/** One line of board row: `Board item "Ship it" — doing · priority 1 · due …`. */
+function describeTaskRow(task, taskId) {
+  const bits = [];
+  if (task.col) bits.push(s(task.col));
+  if (task.priority != null) bits.push(`priority ${s(task.priority)}`);
+  if (task.dueAt) bits.push(`due ${s(task.dueAt)}`);
+  const head = `Board item "${s(task.title) || s(taskId)}"`;
+  return bits.length ? `${head} — ${bits.join(" · ")}` : head;
+}
+
 /**
  * A calendar event. The body came back on the ACL'd `calendar.list` read in the
  * facts pass — that read IS the probe, so there is no second request here and
  * nothing is rendered that hq did not already hand this seat.
  */
-function hydrateCalendar(c, facts) {
+async function hydrateCalendar(c, facts, io, cache) {
   const id = s(c.ids.eventId);
   const e = facts.myEvents instanceof Map ? facts.myEvents.get(id) : null;
   const title = s((e && e.title) || c.ids.title || id);
@@ -413,17 +826,56 @@ function hydrateCalendar(c, facts) {
   if (c.kind === "event.rsvp" && c.ids.rsvp) lines.push(`RSVP: ${s(c.ids.rsvp)}`);
   if (e && e.location) lines.push(`Location: ${s(e.location)}`);
   if (e && e.description) lines.push(clip(e.description, 1200));
+
+  const channelId = s(c.ids.channelId || (e && e.channelId) || "");
+  const room = await roomHistory(channelId, facts, io, cache);
+  const series = priorOccurrences(e || { id, title, startsAt }, facts);
+
   return {
     ok: true,
     text: clip(lines.join("\n")),
     subjectDetail: title,
     threadId: id,
+    threadContext: joinContext([room, series]),
+    isReply: Boolean(room || series),
     from: { id: s(c.actor), name: s(c.actor) },
-    channelId: s(c.ids.channelId || (e && e.channelId) || ""),
+    channelId,
     channelLabel: `calendar/${title}`,
   };
 }
 
+/**
+ * Earlier occurrences of the same recurring meeting, rendered as one block.
+ *
+ * hq's Meeting DTO carries no series id — recurrence is not modelled on the
+ * wire — so the series is identified the way a person identifies it: same
+ * title, earlier start. That is a HEURISTIC and is deliberately kept cheap and
+ * local: it reads only `facts.myEvents`, which the ACL'd `calendar.list` in the
+ * facts pass already produced, so it costs no request and cannot see an event
+ * the lens floor withheld. A same-titled one-off is at worst one extra line of
+ * true context; it is never a read the agent was not entitled to.
+ */
+function priorOccurrences(event, facts) {
+  const all = facts && facts.myEvents instanceof Map ? Array.from(facts.myEvents.values()) : [];
+  if (all.length < 2) return null;
+  const title = s(event && event.title);
+  if (!title) return null;
+  const at = Date.parse(s(event && event.startsAt));
+
+  const earlier = all
+    .filter((m) => m && s(m.id) !== s(event && event.id) && s(m.title) === title)
+    .filter((m) => {
+      const t = Date.parse(s(m.startsAt));
+      return Number.isFinite(t) && (!Number.isFinite(at) || t < at);
+    })
+    .sort((a, b) => Date.parse(s(a.startsAt)) - Date.parse(s(b.startsAt)))
+    .slice(-CALENDAR_SERIES_TURNS);
+
+  if (earlier.length === 0) return null;
+  const rows = earlier.map((m) => `${s(m.startsAt)}${m.location ? ` · ${s(m.location)}` : ""}`);
+  return `Earlier in this series:\n${rows.join("\n")}`;
+}
+
 /** Human phrasing for a `calendar.*` event kind. */
 export function describeCalendarKind(kind) {
   switch (kind) {
@@ -436,11 +888,23 @@ export function describeCalendarKind(kind) {
   }
 }
 
-/** An approval — already read back by the facts pass (that IS the probe). */
-function hydrateApproval(c, facts) {
+/**
+ * An approval, plus the thread of whatever it is an approval OF.
+ *
+ * An action class and a requester is not enough to decide anything: the
+ * approver needs the discussion that produced the request. hq's Approval row
+ * carries `itemId`, which is a board item most of the time and a decision the
+ * rest, and the row does not say which — so the board thread is tried first and
+ * the decision thread only when that read REFUSES (an empty board thread is an
+ * answer, and must not cost a second probe).
+ */
+async function hydrateApproval(c, facts, io, cache) {
   const id = s(c.ids.approvalId);
   const a = facts.approvals instanceof Map ? facts.approvals.get(id) : null;
   const actionClass = s((a && a.actionClass) || c.ids.actionClass);
+  const itemId = s((a && a.itemId) || c.ids.taskId);
+  const task = itemId && facts.tasks instanceof Map ? facts.tasks.get(itemId) : null;
+
   const lines = [`${describeApprovalKind(c.kind)} — ${actionClass || id}`];
   if (a) {
     lines.push(`Status: ${s(a.status)} · requester ${s(a.requester)}${a.approver ? ` · approver ${s(a.approver)}` : ""}`);
@@ -451,31 +915,68 @@ function hydrateApproval(c, facts) {
       lines.push(`Subject: ${clip(typeof a.subject === "string" ? a.subject : JSON.stringify(a.subject), 600)}`);
     }
   }
+  if (task) lines.push(describeTaskRow(task, itemId));
+
+  const comments = itemId ? await anchoredItemComments(itemId, io, cache) : [];
+
   return {
     ok: true,
     text: clip(lines.join("\n")),
     subjectDetail: actionClass || id,
     threadId: id,
+    threadContext: renderThread(comments),
+    isReply: comments.length > 0,
     from: { id: s((a && a.requester) || c.actor), name: s((a && a.requester) || c.actor) },
     channelId: "",
     channelLabel: `approval/${actionClass || id}`,
   };
 }
 
-/** A handoff — the payload already carries intent + both ends. */
-function hydrateHandoff(c, facts) {
+/**
+ * The comment thread of an item that is EITHER a board task or a decision.
+ * Board first; the decision read happens only when the board read refuses, so
+ * the common case costs exactly one probe.
+ */
+async function anchoredItemComments(itemId, io, cache) {
+  const id = s(itemId);
+  if (!id || !io) return [];
+  return cached(cache, `anchoredComments:${id}`, async () => {
+    const board = await io.call("board.taskComments", { taskId: id });
+    if (board && board.ok === true) return arrayOf(resultOf(board), "comments");
+    const decision = await io.call("decision.listComments", { decisionId: id });
+    if (decision && decision.ok === true) return arrayOf(resultOf(decision), "comments");
+    return [];
+  });
+}
+
+/**
+ * A handoff, plus the originating task's thread.
+ *
+ * The payload names both ends and an intent sentence, which tells the receiving
+ * agent what it is being asked to take but nothing about the state of the work.
+ * The originating task's comments are that state — and they are also where the
+ * handoff CHAIN is legible, because hq exposes no handoff-history read: every
+ * offer, accept and decline that mattered was narrated onto the item.
+ */
+async function hydrateHandoff(c, facts, io, cache) {
   const taskId = s(c.ids.taskId);
   const task = facts.tasks instanceof Map ? facts.tasks.get(taskId) : null;
   const title = s((task && task.title) || taskId);
   const lines = [`${describeHandoffKind(c.kind)}${title ? ` — "${title}"` : ""}`];
   if (c.ids.intent) lines.push(`Intent: ${clip(c.ids.intent, 800)}`);
   lines.push(`From ${s(c.ids.from)} → to ${s(c.ids.to)}`);
+  if (task) lines.push(describeTaskRow(task, taskId));
   if (task && task.detail) lines.push(`Detail: ${clip(task.detail, 600)}`);
+
+  const comments = taskId ? await taskComments(taskId, io, cache) : [];
+
   return {
     ok: true,
     text: clip(lines.join("\n")),
     subjectDetail: title || s(c.ids.handoffId),
     threadId: s(c.ids.runId || c.ids.handoffId),
+    threadContext: renderThread(comments),
+    isReply: comments.length > 0,
     from: { id: s(c.ids.from || c.actor), name: s(c.ids.from || c.actor) },
     channelId: "",
     channelLabel: `handoff/${title || s(c.ids.handoffId)}`,
@@ -659,6 +1160,9 @@ export default {
   hydrate,
   clip,
   renderThread,
+  priorComments,
+  isCommentKind,
+  htmlToText,
   describeBoardKind,
   describeDecisionKind,
   describeApprovalKind,