@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/inbound/hydrate.mjs

@@ -0,0 +1,535 @@
+/**
+ * lib/org/inbound/hydrate.mjs — per-family body + context hydration.
+ *
+ * The chain is an AUDIT log, not a content feed: hq redacts every payload down
+ * to ids, counts and flags, so a projected event arrives with `text: ""`. An
+ * empty inbound is WORSE than no inbound — the classifier sees nothing to
+ * 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            |
+ *
+ * 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
+ * it was always entitled to. And it runs ONLY for candidates already ruled
+ * directed, so an event that is not mine costs zero body reads.
+ *
+ * Fail-open, never silent: a hydration that fails returns `{ok:false, reason}`
+ * and the caller drops the item rather than delivering it blank; `io.log`
+ * carries the failure.
+ *
+ * @module lib/org/inbound/hydrate
+ */
+
+"use strict";
+
+import { arrayOf, resultOf } from "./io.mjs";
+
+/** A blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/** Trim to a sane inbox size without cutting mid-word where avoidable. */
+export function clip(text, max = 4000) {
+  const t = s(text);
+  if (t.length <= max) return t;
+  const cut = t.slice(0, max);
+  const sp = cut.lastIndexOf(" ");
+  return `${sp > max * 0.8 ? cut.slice(0, sp) : cut}…`;
+}
+
+/** Render a comment list into a compact prior-thread context block. */
+export function renderThread(comments, { limit = 8, max = 2000 } = {}) {
+  const rows = (Array.isArray(comments) ? comments : []).slice(-limit);
+  if (rows.length === 0) return null;
+  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();
+    return `${who}: ${body}`;
+  });
+  return clip(lines.join("\n"), max) || null;
+}
+
+/**
+ * @typedef {Object} Hydrated
+ * @property {boolean} ok
+ * @property {string} [reason]        why hydration failed (drop reason)
+ * @property {string} text            the body the classifier/responder reads
+ * @property {string} [subjectDetail] appended to the surface's subject
+ * @property {string} [threadId]
+ * @property {string|null} [threadContext]
+ * @property {{id:string,name:string}} [from]
+ * @property {string} [channelLabel]
+ * @property {string} [channelId]
+ * @property {boolean} [isReply]
+ */
+
+/**
+ * Hydrate ONE directed candidate. `cache` is a per-pull Map so two candidates on
+ * the same task/decision/doc share a single read.
+ *
+ * @param {Object} o
+ * @param {import("./directedness.mjs").Candidate} o.candidate
+ * @param {{surface:string, reason:string}} o.verdict
+ * @param {import("./facts.mjs").Facts} o.facts
+ * @param {import("./io.mjs").InboundIo} o.io
+ * @param {Map<string,any>} [o.cache]
+ * @returns {Promise<Hydrated>}
+ */
+export async function hydrate(o = {}) {
+  const { candidate: c, verdict, facts, io } = o;
+  const cache = o.cache instanceof Map ? o.cache : new Map();
+  if (!c) return { ok: false, reason: "no_candidate", text: "" };
+
+  try {
+    switch (c.family) {
+      case "messaging":
+        return hydrateMessage(c, facts);
+      case "calling":
+        return hydrateCall(c, facts);
+      case "board":
+        return await hydrateTask(c, verdict, facts, io, cache);
+      case "file":
+        return await hydrateChatFile(c, facts, io, cache);
+      case "files":
+        return await hydrateDoc(c, facts, io, cache);
+      case "decision":
+        return await hydrateDecision(c, facts, io, cache);
+      case "escalation":
+        return hydrateEscalation(c, facts);
+      case "approval":
+        return hydrateApproval(c, facts);
+      case "handoff":
+        return hydrateHandoff(c, facts);
+      case "email":
+        return await hydrateEmail(c, facts, io, cache);
+      default:
+        return { ok: false, reason: "no_hydrator", text: "" };
+    }
+  } catch (err) {
+    // Fail-open but NEVER silent: one bad row must not take the pull down.
+    if (io && io.log) {
+      io.log("warn", `[inbound] hydrate ${c.family} threw`, {
+        error: err && err.message ? err.message : String(err),
+      });
+    }
+    return { ok: false, reason: "hydrate_threw", text: "" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-family hydrators
+// ---------------------------------------------------------------------------
+
+/** Messaging: the body already came back on the ACL'd history page. */
+function hydrateMessage(c, facts) {
+  const page = facts.channelPages instanceof Map ? facts.channelPages.get(s(c.ids.channelId)) : null;
+  const msg = page && page.byId ? page.byId.get(s(c.ids.messageId)) : null;
+  if (!msg) return { ok: false, reason: "message_not_in_page", text: "" };
+  const body = s(msg.body ?? msg.text).trim();
+  if (!body) return { ok: false, reason: "empty_body", text: "" };
+
+  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 })),
+    );
+  }
+
+  return {
+    ok: true,
+    text: clip(body),
+    threadId: root,
+    threadContext,
+    isReply: Boolean(root),
+    from: { id: s(msg.authorId || c.actor), name: s(msg.authorName || msg.authorId || c.actor) },
+    channelId: s(c.ids.channelId),
+    channelLabel: s((chan && (chan.name || chan.slug)) || c.ids.channelId),
+  };
+}
+
+/** Calls: the invite topic is the whole content; there is no body to fetch. */
+function hydrateCall(c, facts) {
+  const chan = facts.channels instanceof Map ? facts.channels.get(s(c.ids.channelId)) : null;
+  const topic = s(c.ids.topic);
+  return {
+    ok: true,
+    text: topic ? `Call invite: ${topic}` : "Call invite",
+    subjectDetail: topic,
+    threadId: s(c.ids.callId),
+    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"),
+  };
+}
+
+/** Board: the task card from `board.context` plus its comment thread. */
+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 title = s(task && task.title) || taskId;
+  const latest = comments.length ? comments[comments.length - 1] : null;
+  const verb = describeBoardKind(c.kind);
+  const lines = [`${verb} — "${title}"`];
+  if (task && task.col) lines.push(`Column: ${task.col}${task.priority ? ` · priority ${task.priority}` : ""}`);
+  if (task && task.detail) lines.push(`Detail: ${clip(task.detail, 600)}`);
+  if (task && task.dueAt) lines.push(`Due: ${s(task.dueAt)}`);
+  if (latest) lines.push(`Latest comment (${s(latest.authorName || latest.authorId)}): ${clip(latest.body, 800)}`);
+  if (c.payload && c.payload.reason) lines.push(`Reason: ${clip(c.payload.reason, 400)}`);
+  if (verdict && verdict.reason === "reviewer") lines.push("You are the REVIEWER on this item.");
+
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title,
+    threadId: taskId,
+    threadContext: renderThread(comments.slice(0, -1)),
+    isReply: comments.length > 1,
+    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`). */
+async function hydrateChatFile(c, facts, io, cache) {
+  const fileKey = s(c.ids.fileKey);
+  const channelId = s(c.ids.channelId);
+  const comments = await cached(cache, `fileComments:${fileKey}`, async () => {
+    const frame = await io.call("file.listComments", {
+      fileKey,
+      ...(channelId ? { channelId } : {}),
+    });
+    return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
+  });
+  const latest = comments.length ? comments[comments.length - 1] : null;
+  if (!latest) return { ok: false, reason: "file_comment_unreadable", text: "" };
+
+  const chan = facts.channels instanceof Map ? facts.channels.get(channelId) : null;
+  return {
+    ok: true,
+    text: clip(`Comment on file ${fileKey}\n${s(latest.authorName || latest.authorId)}: ${s(latest.body)}`),
+    subjectDetail: fileKey,
+    threadId: fileKey,
+    threadContext: renderThread(comments.slice(0, -1)),
+    isReply: comments.length > 1,
+    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`). */
+async function hydrateDoc(c, facts, io, cache) {
+  const fileId = s(c.ids.fileId);
+  const comments = await cached(cache, `docComments:${fileId}`, async () => {
+    const frame = await io.call("files.comments", { fileId, limit: 50 });
+    return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
+  });
+  const acl = facts.fileAcl instanceof Map ? facts.fileAcl.get(fileId) : null;
+  const name = s(c.ids.name || (acl && acl.name) || fileId);
+  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;
+
+  return {
+    ok: true,
+    text: clip(text),
+    subjectDetail: name,
+    threadId: fileId,
+    threadContext: renderThread(comments.slice(0, -1)),
+    isReply: comments.length > 1,
+    from: { id: s((latest && latest.authorId) || c.actor), name: s((latest && latest.authorName) || c.actor) },
+    channelId: "",
+    channelLabel: `doc/${name}`,
+  };
+}
+
+/** A decision, its rationale, and its comment thread. */
+async function hydrateDecision(c, facts, io, cache) {
+  const decisionId = s(c.ids.decisionId);
+  const d = facts.decisions instanceof Map ? facts.decisions.get(decisionId) : null;
+  const comments = await cached(cache, `decisionComments:${decisionId}`, async () => {
+    const frame = await io.call("decision.listComments", { decisionId });
+    return frame && frame.ok === true ? arrayOf(resultOf(frame), "comments") : [];
+  });
+  const title = s((d && d.title) || c.ids.title || decisionId);
+  const latest = comments.length ? comments[comments.length - 1] : null;
+
+  const lines = [`${describeDecisionKind(c.kind)} — "${title}"`];
+  if (d && d.status) lines.push(`Status: ${s(d.status)}${d.scope ? ` · scope ${s(d.scope)}` : ""}`);
+  if (d && d.body) lines.push(`Body: ${clip(d.body, 800)}`);
+  if (d && d.rationale) lines.push(`Rationale: ${clip(typeof d.rationale === "string" ? d.rationale : JSON.stringify(d.rationale), 600)}`);
+  if (latest) lines.push(`Latest comment (${s(latest.authorName || latest.authorId)}): ${clip(latest.body, 800)}`);
+  if (c.kind === "decision.adjustment_requested") lines.push("An ADJUSTMENT was requested — this needs a response.");
+
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title,
+    threadId: decisionId,
+    threadContext: renderThread(comments.slice(0, -1)),
+    isReply: comments.length > 1,
+    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) {
+  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 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)}`);
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title,
+    threadId: id,
+    from: { id: s(c.actor), name: s(c.actor) },
+    channelId: s(c.ids.channelId || (e && e.channelId) || ""),
+    channelLabel: `escalation/${title}`,
+  };
+}
+
+/** An approval — already read back by the facts pass (that IS the probe). */
+function hydrateApproval(c, facts) {
+  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 lines = [`${describeApprovalKind(c.kind)} — ${actionClass || id}`];
+  if (a) {
+    lines.push(`Status: ${s(a.status)} · requester ${s(a.requester)}${a.approver ? ` · approver ${s(a.approver)}` : ""}`);
+    if (a.reason) lines.push(`Reason: ${clip(a.reason, 600)}`);
+    if (a.itemId) lines.push(`Board item: ${s(a.itemId)}`);
+    if (a.expiresAt) lines.push(`Expires: ${s(a.expiresAt)}`);
+    if (a.subject) {
+      lines.push(`Subject: ${clip(typeof a.subject === "string" ? a.subject : JSON.stringify(a.subject), 600)}`);
+    }
+  }
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: actionClass || id,
+    threadId: id,
+    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) {
+  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 && task.detail) lines.push(`Detail: ${clip(task.detail, 600)}`);
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title || s(c.ids.handoffId),
+    threadId: s(c.ids.runId || c.ids.handoffId),
+    from: { id: s(c.ids.from || c.actor), name: s(c.ids.from || c.actor) },
+    channelId: "",
+    channelLabel: `handoff/${title || s(c.ids.handoffId)}`,
+  };
+}
+
+/**
+ * Inbound email. `email.thread` is OWN-MAILBOX ONLY (hq
+ * `methods/email/thread.ts` pins `mailboxId: actingMailbox(ctx).id`), so this
+ * read is the ACL — another seat's mail is simply not returned.
+ */
+async function hydrateEmail(c, facts, io, cache) {
+  const threadId = s(c.ids.threadId);
+  const messageId = s(c.ids.emailMessageId);
+
+  const thread = threadId
+    ? await cached(cache, `emailThread:${threadId}`, async () => {
+        const frame = await io.call("email.thread", { threadId });
+        return frame && frame.ok === true ? resultOf(frame) : null;
+      })
+    : null;
+
+  let message = null;
+  const messages = arrayOf(thread, "messages");
+  if (messageId) message = messages.find((m) => s(m.id) === messageId) || null;
+  if (!message && messages.length) message = messages[messages.length - 1];
+  if (!message && messageId) {
+    const frame = await io.call("email.message", { id: messageId });
+    message = frame && frame.ok === true ? resultOf(frame) : null;
+  }
+  if (!message) return { ok: false, reason: "email_unreadable", text: "" };
+
+  const subject = s(message.subject || (thread && thread.thread && thread.thread.subject));
+  const body = clip(s(message.text || message.bodyText || message.snippet || message.html));
+  if (!body) return { ok: false, reason: "empty_body", text: "" };
+  const fromAddr = s(
+    (message.from && (message.from.address || message.from.email || message.from.name)) || message.fromAddress,
+  );
+
+  return {
+    ok: true,
+    text: body,
+    subjectDetail: subject,
+    threadId,
+    threadContext: renderThread(
+      messages
+        .filter((m) => s(m.id) !== s(message.id))
+        .map((m) => ({
+          authorName: s((m.from && (m.from.name || m.from.address)) || m.fromAddress),
+          body: m.text || m.snippet,
+        })),
+    ),
+    isReply: messages.length > 1,
+    from: { id: fromAddr, name: s((message.from && message.from.name) || fromAddr) },
+    channelId: s(c.ids.mailboxId),
+    channelLabel: "email",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+
+/** Memoise an async read for the lifetime of one pull. */
+async function cached(cache, key, fn) {
+  if (cache.has(key)) return cache.get(key);
+  const v = await fn();
+  cache.set(key, v);
+  return v;
+}
+
+/** Human phrasing for a board event kind. */
+export function describeBoardKind(kind) {
+  switch (kind) {
+    case "item.assigned":
+      return "A board item was assigned to you";
+    case "item.claimed":
+      return "A board item was claimed";
+    case "item.commented":
+    case "board.commented":
+      return "New comment on your board item";
+    case "board.blocked":
+      return "Your board item was BLOCKED";
+    case "item.moved":
+      return "Your board item moved column";
+    case "item.completed":
+      return "Your board item was completed";
+    case "item.attached":
+      return "A file was attached to your board item";
+    default:
+      return "Update on your board item";
+  }
+}
+
+/** Human phrasing for a decision event kind. */
+export function describeDecisionKind(kind) {
+  switch (kind) {
+    case "decision.proposed":
+      return "A decision was proposed";
+    case "decision.comment":
+      return "New comment on a decision";
+    case "decision.adjustment_requested":
+      return "An adjustment was requested on a decision";
+    case "decision.signed":
+      return "A decision was signed";
+    case "decision.adopted":
+      return "A decision was adopted";
+    case "decision.superseded":
+      return "A decision was superseded";
+    case "decision.reversed":
+      return "A decision was reversed";
+    default:
+      return "Decision update";
+  }
+}
+
+/** Human phrasing for an approval event kind. */
+export function describeApprovalKind(kind) {
+  if (kind === "approval.requested") return "An approval is waiting on you";
+  if (kind === "approval.approved") return "Your approval request was APPROVED";
+  if (kind === "approval.rejected") return "Your approval request was REJECTED";
+  if (kind === "approval.expired") return "An approval request EXPIRED";
+  return "Approval update";
+}
+
+/** Human phrasing for a handoff event kind. */
+export function describeHandoffKind(kind) {
+  switch (kind) {
+    case "handoff.offered":
+      return "A handoff was offered to you";
+    case "handoff.accepted":
+      return "Your handoff was accepted";
+    case "handoff.declined":
+      return "Your handoff was declined";
+    case "handoff.cancelled":
+      return "A handoff was cancelled";
+    default:
+      return "Handoff update";
+  }
+}
+
+/** Human phrasing for a workspace-doc event kind. */
+export function describeFilesKind(kind, name) {
+  switch (kind) {
+    case "doc.comment":
+      return `New comment on "${name}"`;
+    case "doc.suggested":
+      return `A suggestion was made on "${name}"`;
+    case "doc.suggestion_accepted":
+      return `A suggestion on "${name}" was accepted`;
+    case "doc.suggestion_rejected":
+      return `A suggestion on "${name}" was rejected`;
+    case "file.shared":
+      return `"${name}" was shared with you`;
+    default:
+      return `Update on "${name}"`;
+  }
+}
+
+export default {
+  hydrate,
+  clip,
+  renderThread,
+  describeBoardKind,
+  describeDecisionKind,
+  describeApprovalKind,
+  describeHandoffKind,
+  describeFilesKind,
+};