@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/inbound/facts.mjs

@@ -0,0 +1,501 @@
+/**
+ * lib/org/inbound/facts.mjs — the agent's OWN half of "is this for me?".
+ *
+ * The org event feed is org-wide and redacted (see `directedness.mjs` for the
+ * long version), so directedness is a JOIN: the event names ids, the agent knows
+ * which of those ids are its own. This module resolves that second half — and
+ * ONLY over the agent's own entitled reads, so the aperture can never be wider
+ * than what hq would already hand this API key:
+ *
+ *   | fact                       | read                    | hq ACL                          |
+ *   |----------------------------|-------------------------|---------------------------------|
+ *   | visible / member channels  | messaging.channels      | PUBLIC floor + own memberships  |
+ *   | message bodies + mentions  | messaging.history       | assertChannelAccess             |
+ *   | my tasks (assignee/review) | GET board.context       | org-scoped board read           |
+ *   | decisions + their voices   | GET decision.list,      | org-scoped                      |
+ *   |                            | decision.listComments   |                                 |
+ *   | open escalations           | escalation.list         | org-scoped                      |
+ *   | approvals (approver seat)  | approval.get            | org-scoped, NOT_FOUND otherwise |
+ *   | doc ownership / shares     | files.get               | NOT_FOUND when not visible      |
+ *
+ * ── THE ONE RULE THIS FILE ENFORCES ──
+ * A channel that is not in the visible roster is NEVER paged. `messaging.channels`
+ * returns a private room only to its members (hq `methods/messaging/channels.ts`),
+ * so refusing to page anything outside that set means a private room the agent is
+ * not in is never even TOUCHED — no history request, no body, no verdict. The
+ * negative test in `facts.test.mjs` asserts exactly that, by call log.
+ *
+ * ── COST ──
+ * Everything is BATCHED and CAPPED. One roster read per pull; one board/decision/
+ * escalation read per pull *only when that family appears in the batch*; one
+ * history page per affected channel (not per message); a bounded number of
+ * targeted thread pages. Every cap is in {@link DEFAULT_LIMITS} and every time a
+ * cap bites it is logged, never silently dropped.
+ *
+ * Fail-open everywhere, NEVER silent: a fact that cannot be read degrades the
+ * verdict to "unknown" (→ not directed for private surfaces, which is the safe
+ * direction) and logs the failure through `io.log`.
+ *
+ * @module lib/org/inbound/facts
+ */
+
+"use strict";
+
+import { arrayOf, resultOf } from "./io.mjs";
+import { needsSpaceProbe, matchesMyName, PRIVATE_ROOM_KINDS } from "./directedness.mjs";
+
+/** Bounds on how much one pull may spend resolving facts. */
+export const DEFAULT_LIMITS = Object.freeze({
+  /** `messaging.history` pages per pull (one per affected channel). */
+  maxChannelPages: 25,
+  /** messages per history page. */
+  historyLimit: 50,
+  /** targeted `messaging.history {threadRootId}` fetches per pull. */
+  maxThreadPages: 10,
+  /** `approval.get` probes per pull. */
+  maxApprovalProbes: 20,
+  /** `files.get` (+ optional `files.comments`) probes per pull. */
+  maxFileProbes: 20,
+  /** `decision.listComments` probes per pull. */
+  maxDecisionProbes: 20,
+});
+
+/**
+ * @typedef {Object} Facts
+ * @property {string} me
+ * @property {string[]} myNames               display names for prose-mention matching
+ * @property {Map<string,object>} channels    visible channel roster, by id
+ * @property {Set<string>|null} visibleChannelIds  null == roster unreadable
+ * @property {Set<string>|null} memberChannelIds   non-PUBLIC visible == proven member
+ * @property {Map<string,object>} channelPages     channelId → {messages, byId}
+ * @property {Set<string>} myThreadRootIds
+ * @property {Map<string,string>|null} taskRole    taskId → "assignee"|"reviewer"
+ * @property {Map<string,object>|null} tasks       taskId → task card
+ * @property {Map<string,object>|null} decisions
+ * @property {Map<string,Set<string>>} decisionVoices
+ * @property {Map<string,object>|null} escalations
+ * @property {Map<string,object>|null} approvals
+ * @property {Map<string,object>|null} fileAcl     fileId → {ownerId, shared, mentionsMe}
+ * @property {string[]} degraded               names of facts that could not be read
+ */
+
+/** Which families are present in this batch of candidates? */
+function familiesIn(candidates) {
+  const s = new Set();
+  for (const c of candidates) if (c && c.family) s.add(c.family);
+  return s;
+}
+
+/**
+ * Resolve every fact the batch needs. One pass, batched by family, capped, and
+ * fail-open with a log line per degradation.
+ *
+ * @param {Object} o
+ * @param {import("./directedness.mjs").Candidate[]} o.candidates
+ * @param {string} o.me                       the agent's member id
+ * @param {import("./io.mjs").InboundIo} o.io
+ * @param {string[]} [o.myNames]              display names for prose-mention matching
+ * @param {Record<string,boolean>} [o.enabled] the surface enable map
+ * @param {object} [o.limits]                 overrides for {@link DEFAULT_LIMITS}
+ * @returns {Promise<Facts>}
+ */
+export async function resolveFacts(o = {}) {
+  const candidates = Array.isArray(o.candidates) ? o.candidates.filter(Boolean) : [];
+  const me = o.me ? String(o.me) : "";
+  const io = o.io;
+  const log = (io && io.log) || (() => {});
+  const limits = { ...DEFAULT_LIMITS, ...(o.limits || {}) };
+  const enabled = o.enabled || null;
+  const on = (s) => (enabled ? !!enabled[s] : true);
+  const families = familiesIn(candidates);
+  const degraded = [];
+
+  /** @type {Facts} */
+  const facts = {
+    me,
+    myNames: Array.isArray(o.myNames) ? o.myNames.filter((n) => typeof n === "string" && n.trim()) : [],
+    channels: new Map(),
+    visibleChannelIds: null,
+    memberChannelIds: null,
+    channelPages: new Map(),
+    myThreadRootIds: new Set(),
+    taskRole: null,
+    tasks: null,
+    decisions: null,
+    decisionVoices: new Map(),
+    escalations: null,
+    approvals: null,
+    fileAcl: null,
+    degraded,
+  };
+  if (!io || candidates.length === 0) return facts;
+
+  // ── 1. The channel roster. Needed by messaging, calling, file and escalation.
+  const needsRoster =
+    families.has("messaging") || families.has("calling") || families.has("file") || families.has("escalation");
+  if (needsRoster) {
+    const frame = await io.call("messaging.channels", {});
+    const rows = arrayOf(resultOf(frame), "channels");
+    if (frame && frame.ok === true) {
+      const visible = new Set();
+      const members = new Set();
+      for (const c of rows) {
+        const id = String((c && (c.id || c.channelId)) || "");
+        if (!id) continue;
+        const kind = String((c && c.kind) || "").toUpperCase();
+        facts.channels.set(id, { id, kind, name: c.name || c.slug || "", slug: c.slug || "" });
+        visible.add(id);
+        // `messaging.channels` returns a NON-PUBLIC channel only to its members,
+        // so appearing here with a non-PUBLIC kind IS the membership proof. For
+        // a PUBLIC channel the roster proves visibility, never membership — and
+        // we never upgrade one to the other.
+        if (kind && kind !== "PUBLIC") members.add(id);
+      }
+      facts.visibleChannelIds = visible;
+      facts.memberChannelIds = members;
+    } else {
+      degraded.push("channels");
+      log("warn", "[inbound] channel roster unreadable — private surfaces stay closed this tick");
+    }
+  }
+
+  // ── 2. Message pages: one per affected, VISIBLE channel. Public-space traffic
+  //      that the redacted counts already prove uninteresting is skipped.
+  if (families.has("messaging")) {
+    await pageChannels({ candidates, facts, io, limits, log, on });
+  }
+
+  // ── 3. Board: my tasks (assignee OR reviewer) from the board context read.
+  if (families.has("board") || families.has("escalation") || families.has("file")) {
+    await resolveBoardFacts({ facts, io, log, degraded });
+  }
+
+  // ── 4. Decisions I proposed / decided, plus the voices in each thread.
+  if (families.has("decision") && (on("decision") || !enabled)) {
+    await resolveDecisionFacts({ candidates, facts, io, limits, log, degraded });
+  }
+
+  // ── 5. Escalations (one list read; the payload's taskId/channelId do the rest).
+  if (families.has("escalation") && (on("escalation") || !enabled)) {
+    const frame = await io.call("escalation.list", {});
+    if (frame && frame.ok === true) {
+      const map = new Map();
+      for (const e of arrayOf(resultOf(frame), "escalations")) {
+        if (e && e.id) map.set(String(e.id), e);
+      }
+      facts.escalations = map;
+    } else {
+      degraded.push("escalations");
+    }
+  }
+
+  // ── 6. Approvals: the approver seat is on the ROW, never in the payload
+  //      (hq `methods/approval/request.ts` emits only `requester`), so an
+  //      approver only learns a request landed by reading it back. `approval.get`
+  //      is org-scoped and NOT_FOUND for another tenant, so this cannot widen.
+  if (families.has("approval") && (on("approval") || !enabled)) {
+    await resolveApprovalFacts({ candidates, facts, io, limits, log, degraded });
+  }
+
+  // ── 7. Workspace docs: ownership + effective permission via `files.get`,
+  //      which is itself ACL'd (a doc I cannot see is NOT_FOUND, not a leak).
+  if (families.has("files") && (on("doc_comment") || !enabled)) {
+    await resolveFileFacts({ candidates, facts, io, limits, log, degraded });
+  }
+
+  return facts;
+}
+
+// ---------------------------------------------------------------------------
+// Step implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch one `messaging.history` page per affected channel and fold it into
+ * `facts.channelPages` + `facts.myThreadRootIds`.
+ *
+ * THE GATE: a channel id absent from `facts.visibleChannelIds` is skipped
+ * outright. When the roster is unreadable (`visibleChannelIds === null`) NOTHING
+ * is paged — we would not be able to tell a private room from a public one, and
+ * guessing is how an agent ends up reading someone else's DM.
+ */
+async function pageChannels({ candidates, facts, io, limits, log, on }) {
+  const visible = facts.visibleChannelIds;
+  const members = facts.memberChannelIds;
+  if (!visible) {
+    log("warn", "[inbound] skipping all history pages — channel roster unknown");
+    return;
+  }
+
+  /** channelId → candidates needing it */
+  const wanted = new Map();
+  let skippedInvisible = 0;
+  let skippedByCounts = 0;
+
+  for (const cand of candidates) {
+    if (cand.family !== "messaging") continue;
+    const channelId = String(cand.ids.channelId || "");
+    if (!channelId) continue;
+    if (!visible.has(channelId)) {
+      skippedInvisible += 1;
+      continue; // ← the hard gate. Never probe a room outside my roster.
+    }
+    const chan = facts.channels.get(channelId);
+    const kind = String(cand.ids.channelKind || (chan && chan.kind) || "").toUpperCase();
+    const isPrivateRoom = PRIVATE_ROOM_KINDS.includes(kind);
+
+    if (isPrivateRoom) {
+      // A private room I am in: paged for the BODY (the verdict is already
+      // decided by membership). If I am somehow not a member, do not page.
+      if (!members || !members.has(channelId)) continue;
+      if (!on("dm")) continue;
+    } else {
+      // A space: paged only if it could be a mention or a thread reply.
+      if (!on("mention") && !on("thread_reply")) continue;
+      if (needsSpaceProbe(cand, facts) === false) {
+        skippedByCounts += 1;
+        continue;
+      }
+      // A PRIVATE space I am not a member of is not readable — do not try.
+      if (kind === "PRIVATE" && (!members || !members.has(channelId))) continue;
+    }
+    if (!wanted.has(channelId)) wanted.set(channelId, []);
+    wanted.get(channelId).push(cand);
+  }
+
+  if (skippedInvisible) {
+    log("info", `[inbound] ${skippedInvisible} messaging event(s) in channels outside my roster — not probed`);
+  }
+  if (skippedByCounts) {
+    log("info", `[inbound] ${skippedByCounts} space message(s) dropped on mentionCount=0/threaded=false (no RPC spent)`);
+  }
+
+  const channelIds = Array.from(wanted.keys());
+  if (channelIds.length > limits.maxChannelPages) {
+    log("warn", `[inbound] ${channelIds.length} channels need a history page; capping at ${limits.maxChannelPages}`);
+  }
+
+  for (const channelId of channelIds.slice(0, limits.maxChannelPages)) {
+    const frame = await io.call("messaging.history", { channelId, limit: limits.historyLimit });
+    if (!frame || frame.ok !== true) continue; // io.call already logged it
+    const messages = arrayOf(resultOf(frame), "messages");
+    foldPage(facts, channelId, messages);
+  }
+
+  // Targeted thread pages: a reply whose root fell outside the 50-message page.
+  const missing = [];
+  for (const [channelId, cands] of wanted) {
+    const page = facts.channelPages.get(channelId);
+    if (!page) continue;
+    for (const cand of cands) {
+      const msg = page.byId.get(String(cand.ids.messageId || ""));
+      const root = msg && (msg.threadRootId || msg.thread_root_id);
+      if (!root) continue;
+      if (facts.myThreadRootIds.has(String(root))) continue;
+      const key = `${channelId}:${root}`;
+      if (!missing.some((m) => m.key === key)) missing.push({ key, channelId, root: String(root) });
+    }
+  }
+  if (missing.length > limits.maxThreadPages) {
+    log("warn", `[inbound] ${missing.length} thread pages wanted; capping at ${limits.maxThreadPages}`);
+  }
+  for (const { channelId, root } of missing.slice(0, limits.maxThreadPages)) {
+    const frame = await io.call("messaging.history", {
+      channelId,
+      threadRootId: root,
+      limit: limits.historyLimit,
+    });
+    if (!frame || frame.ok !== true) continue;
+    foldPage(facts, channelId, arrayOf(resultOf(frame), "messages"));
+  }
+}
+
+/**
+ * Fold a history page into the fact set: index the messages by id and record
+ * every thread root I have a stake in (authored under, or was named in).
+ */
+function foldPage(facts, channelId, messages) {
+  const existing = facts.channelPages.get(String(channelId));
+  const byId = existing ? existing.byId : new Map();
+  const all = existing ? existing.messages.slice() : [];
+  for (const m of messages) {
+    const id = String((m && (m.id || m.messageId)) || "");
+    if (!id) continue;
+    if (!byId.has(id)) all.push(m);
+    byId.set(id, m);
+    const root = String(m.threadRootId || m.thread_root_id || "") || id;
+    const mine =
+      (facts.me && String(m.authorId || m.author || "") === facts.me) ||
+      (facts.me && Array.isArray(m.mentions) && m.mentions.map(String).includes(facts.me));
+    if (mine) facts.myThreadRootIds.add(root);
+  }
+  facts.channelPages.set(String(channelId), { byId, messages: all });
+}
+
+/** `GET board.context` → taskRole (assignee|reviewer) + the task cards. */
+async function resolveBoardFacts({ facts, io, log, degraded }) {
+  if (facts.taskRole) return;
+  const r = await io.read("board.context");
+  if (!r || r.ok !== true || !r.payload) {
+    degraded.push("board");
+    log("warn", "[inbound] board.context unreadable — task surfaces stay closed this tick");
+    return;
+  }
+  const role = new Map();
+  const tasks = new Map();
+  for (const task of collectTasks(r.payload)) {
+    const id = String((task && task.id) || "");
+    if (!id) continue;
+    tasks.set(id, task);
+    const assignee = String(task.assigneeId || task.assignee || "");
+    const reviewer = String(task.reviewerId || task.reviewer || "");
+    if (facts.me && assignee === facts.me) role.set(id, "assignee");
+    else if (facts.me && reviewer === facts.me) role.set(id, "reviewer");
+  }
+  facts.taskRole = role;
+  facts.tasks = tasks;
+}
+
+/**
+ * `board.context` is a swimlane projection (`{lanes:[{columns:{col:[card]}}]}`),
+ * and older/alternate shapes exist. Walk defensively and collect anything that
+ * looks like a task card — a shape change upstream must degrade to "fewer
+ * tasks", never to a throw.
+ */
+export function collectTasks(payload) {
+  const out = [];
+  const seen = new Set();
+  const visit = (node, depth) => {
+    if (!node || depth > 6) return;
+    if (Array.isArray(node)) {
+      for (const n of node) visit(n, depth + 1);
+      return;
+    }
+    if (typeof node !== "object") return;
+    if (typeof node.id === "string" && ("assigneeId" in node || "reviewerId" in node || "col" in node)) {
+      if (!seen.has(node.id)) {
+        seen.add(node.id);
+        out.push(node);
+      }
+      return;
+    }
+    for (const v of Object.values(node)) visit(v, depth + 1);
+  };
+  visit(payload, 0);
+  return out;
+}
+
+/** `GET decision.list` + one `decision.listComments` per decision in the batch. */
+async function resolveDecisionFacts({ candidates, facts, io, limits, log, degraded }) {
+  const r = await io.read("decision.list");
+  if (r && r.ok === true && r.payload) {
+    const map = new Map();
+    for (const d of arrayOf(r.payload, "decisions")) {
+      if (d && d.id) map.set(String(d.id), d);
+    }
+    facts.decisions = map;
+  } else {
+    degraded.push("decisions");
+  }
+
+  const ids = [];
+  for (const c of candidates) {
+    if (c.family !== "decision") continue;
+    const id = String(c.ids.decisionId || "");
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  if (ids.length > limits.maxDecisionProbes) {
+    log("warn", `[inbound] ${ids.length} decision threads wanted; capping at ${limits.maxDecisionProbes}`);
+  }
+  for (const decisionId of ids.slice(0, limits.maxDecisionProbes)) {
+    // Skip the probe when the list read already proved it mine.
+    const d = facts.decisions && facts.decisions.get(decisionId);
+    if (d && facts.me && (String(d.proposedBy || "") === facts.me || String(d.decidedBy || "") === facts.me)) {
+      continue;
+    }
+    const frame = await io.call("decision.listComments", { decisionId });
+    if (!frame || frame.ok !== true) continue;
+    const voices = new Set();
+    for (const c of arrayOf(resultOf(frame), "comments")) {
+      const author = String((c && (c.authorId || c.author)) || "");
+      if (author) voices.add(author);
+    }
+    facts.decisionVoices.set(decisionId, voices);
+  }
+}
+
+/** One `approval.get` per distinct approval id in the batch. */
+async function resolveApprovalFacts({ candidates, facts, io, limits, log, degraded }) {
+  const ids = [];
+  for (const c of candidates) {
+    if (c.family !== "approval") continue;
+    const id = String(c.ids.approvalId || "");
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  if (ids.length === 0) return;
+  if (ids.length > limits.maxApprovalProbes) {
+    log("warn", `[inbound] ${ids.length} approvals wanted; capping at ${limits.maxApprovalProbes}`);
+  }
+  const map = new Map();
+  let anyOk = false;
+  for (const id of ids.slice(0, limits.maxApprovalProbes)) {
+    const frame = await io.call("approval.get", { id });
+    if (!frame || frame.ok !== true) continue;
+    anyOk = true;
+    const a = resultOf(frame);
+    if (a && (a.id || id)) map.set(String(a.id || id), a);
+  }
+  if (!anyOk) degraded.push("approvals");
+  facts.approvals = map;
+}
+
+/**
+ * One `files.get` per distinct doc in the batch → `{ownerId, shared}`.
+ *
+ * `files.get` is the ACL: a doc this key cannot see is NOT_FOUND, so an absent
+ * entry means "not mine" and the resolver refuses it. When the doc IS visible
+ * but neither owned nor shared, and the caller supplied display names, we spend
+ * ONE `files.comments` read to see whether the thread names me by name.
+ */
+async function resolveFileFacts({ candidates, facts, io, limits, log, degraded }) {
+  const ids = [];
+  for (const c of candidates) {
+    if (c.family !== "files") continue;
+    const id = String(c.ids.fileId || "");
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  if (ids.length === 0) return;
+  if (ids.length > limits.maxFileProbes) {
+    log("warn", `[inbound] ${ids.length} docs wanted; capping at ${limits.maxFileProbes}`);
+  }
+  const map = new Map();
+  let anyOk = false;
+  for (const fileId of ids.slice(0, limits.maxFileProbes)) {
+    const frame = await io.call("files.get", { fileId });
+    if (!frame || frame.ok !== true) continue;
+    anyOk = true;
+    const res = resultOf(frame) || {};
+    const file = res.file || res;
+    const permission = String(res.permission || "").toLowerCase();
+    const ownerId = String(file.ownerId || file.owner || "") || null;
+    const shared = Boolean(permission && permission !== "none");
+    const entry = { ownerId, shared, permission, mentionsMe: false, name: file.name || "" };
+
+    if (!shared && !(ownerId && ownerId === facts.me) && facts.myNames.length > 0) {
+      const cf = await io.call("files.comments", { fileId, limit: 20 });
+      if (cf && cf.ok === true) {
+        for (const c of arrayOf(resultOf(cf), "comments")) {
+          if (matchesMyName(facts, c && c.body)) {
+            entry.mentionsMe = true;
+            break;
+          }
+        }
+      }
+    }
+    map.set(fileId, entry);
+  }
+  if (!anyOk) degraded.push("files");
+  facts.fileAcl = map;
+}
+
+export default { resolveFacts, collectTasks, DEFAULT_LIMITS };