@cohortapp/agent-sdk 2.3.2 → 2.4.0

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

@@ -0,0 +1,375 @@
+/**
+ * facts.test.mjs — the agent-side half of the directedness join.
+ *
+ * Everything here runs against an injected fake IO that RECORDS every call, so
+ * the tests can assert not just what was resolved but what was *spent* — and,
+ * critically, what was NEVER asked for. The headline assertion is the negative
+ * one: a private room outside the agent's roster must never produce a
+ * `messaging.history` call. A leak here would be invisible in a "did it deliver"
+ * test, so it is asserted by call log.
+ *
+ * Run: node --test lib/org/inbound/facts.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { resolveFacts, collectTasks } from "./facts.mjs";
+import { classifyEvent } from "./directedness.mjs";
+
+const ME = "M-me";
+const THEM = "M-them";
+
+/**
+ * A fake IO seam. `routes` maps `method` or `read:<path>` to a handler; anything
+ * unrouted returns an error frame (which the real seam would have logged).
+ */
+function fakeIo(routes = {}) {
+  const calls = [];
+  const logs = [];
+  return {
+    calls,
+    logs,
+    stats: { calls: 0, reads: 0, failures: 0, methods: [] },
+    log: (level, message, meta) => logs.push({ level, message, meta }),
+    async call(method, params) {
+      calls.push({ kind: "call", method, params });
+      this.stats.calls += 1;
+      const h = routes[method];
+      if (!h) return { ok: false, error: { code: "NOT_FOUND", message: `no route ${method}` } };
+      const out = typeof h === "function" ? await h(params) : h;
+      return out === undefined ? { ok: true, result: null } : out;
+    },
+    async read(path) {
+      const base = String(path).split("?")[0];
+      calls.push({ kind: "read", path, base });
+      this.stats.reads += 1;
+      const h = routes[`read:${base}`];
+      if (!h) return { ok: false, error: { code: "NOT_FOUND", message: `no route ${base}` }, status: 404 };
+      const out = typeof h === "function" ? await h(path) : h;
+      return out === undefined ? { ok: true, payload: null } : out;
+    },
+  };
+}
+
+const okFrame = (result) => ({ ok: true, result });
+const okRead = (payload) => ({ ok: true, payload, status: 200 });
+
+function ev(over) {
+  return { seq: over.seq ?? 1, at: "2026-08-11T00:00:00.000Z", actor: THEM, ...over };
+}
+
+function msgEvent(channelId, channelKind, messageId, extra = {}) {
+  return classifyEvent(
+    ev({
+      family: "messaging",
+      kind: "send",
+      entity_id: messageId,
+      payload: { actor: THEM, channelId, channelKind, mentionCount: 1, threaded: false, ...extra },
+    }),
+  );
+}
+
+const ROSTER = {
+  "messaging.channels": okFrame({
+    channels: [
+      { id: "C-dm", kind: "DM", slug: "dm-them", name: "them" },
+      { id: "C-pub", kind: "PUBLIC", slug: "general", name: "General" },
+      { id: "C-priv", kind: "PRIVATE", slug: "leads", name: "Leads" },
+    ],
+  }),
+};
+
+// ---------------------------------------------------------------------------
+// THE negative: never touch a room outside my roster
+// ---------------------------------------------------------------------------
+
+test("NEVER probes a channel outside my roster (asserted by call log)", async () => {
+  const io = fakeIo({
+    ...ROSTER,
+    "messaging.history": ({ channelId }) => okFrame({ channelId, messages: [] }),
+  });
+  const candidates = [
+    msgEvent("C-theirs", "DM", "m1"), // someone else's DM — invisible to me
+    msgEvent("C-secret", "PRIVATE", "m2"), // a private space I am not in
+  ];
+  await resolveFacts({ candidates, me: ME, io });
+
+  const histories = io.calls.filter((c) => c.method === "messaging.history");
+  assert.equal(histories.length, 0, "no history may be fetched for a room outside my roster");
+  assert.equal(io.calls.filter((c) => c.method === "messaging.channels").length, 1);
+  assert.ok(
+    io.logs.some((l) => /outside my roster/.test(l.message)),
+    "the skip must be LOGGED, never silent",
+  );
+});
+
+test("roster unreadable → nothing is paged at all, and it says so", async () => {
+  const io = fakeIo({ "messaging.history": () => okFrame({ messages: [] }) });
+  const facts = await resolveFacts({ candidates: [msgEvent("C-dm", "DM", "m1")], me: ME, io });
+
+  assert.equal(facts.visibleChannelIds, null);
+  assert.equal(facts.memberChannelIds, null);
+  assert.deepEqual(facts.degraded, ["channels"]);
+  assert.equal(io.calls.filter((c) => c.method === "messaging.history").length, 0);
+  assert.ok(io.logs.some((l) => /roster/.test(l.message)));
+});
+
+// ---------------------------------------------------------------------------
+// roster → visible vs member
+// ---------------------------------------------------------------------------
+
+test("a PUBLIC channel is visible but NOT proof of membership", async () => {
+  const io = fakeIo({ ...ROSTER, "messaging.history": () => okFrame({ messages: [] }) });
+  const facts = await resolveFacts({ candidates: [msgEvent("C-pub", "PUBLIC", "m1")], me: ME, io });
+
+  assert.deepEqual([...facts.visibleChannelIds].sort(), ["C-dm", "C-priv", "C-pub"]);
+  assert.deepEqual([...facts.memberChannelIds].sort(), ["C-dm", "C-priv"]);
+});
+
+// ---------------------------------------------------------------------------
+// cost: the redacted counts avoid pages entirely
+// ---------------------------------------------------------------------------
+
+test("a space message with mentionCount=0 and threaded=false costs ZERO history calls", async () => {
+  const io = fakeIo({ ...ROSTER, "messaging.history": () => okFrame({ messages: [] }) });
+  const cand = classifyEvent(
+    ev({
+      family: "messaging",
+      kind: "send",
+      entity_id: "m1",
+      payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: false },
+    }),
+  );
+  await resolveFacts({ candidates: [cand], me: ME, io });
+  assert.equal(io.calls.filter((c) => c.method === "messaging.history").length, 0);
+  assert.ok(io.logs.some((l) => /mentionCount=0/.test(l.message)));
+});
+
+test("one history page per affected channel, not per message", async () => {
+  let pages = 0;
+  const io = fakeIo({
+    ...ROSTER,
+    "messaging.history": ({ channelId }) => {
+      pages += 1;
+      return okFrame({ channelId, messages: [{ id: "m1", authorId: THEM, body: "a", mentions: [ME] }] });
+    },
+  });
+  await resolveFacts({
+    candidates: [msgEvent("C-pub", "PUBLIC", "m1"), msgEvent("C-pub", "PUBLIC", "m2"), msgEvent("C-pub", "PUBLIC", "m3")],
+    me: ME,
+    io,
+  });
+  assert.equal(pages, 1);
+});
+
+test("the channel-page cap bites and is logged", async () => {
+  const channels = Array.from({ length: 5 }, (_, i) => ({ id: `C-${i}`, kind: "PUBLIC", slug: `c${i}` }));
+  const io = fakeIo({
+    "messaging.channels": okFrame({ channels }),
+    "messaging.history": ({ channelId }) => okFrame({ channelId, messages: [] }),
+  });
+  await resolveFacts({
+    candidates: channels.map((c, i) => msgEvent(c.id, "PUBLIC", `m${i}`)),
+    me: ME,
+    io,
+    limits: { maxChannelPages: 2 },
+  });
+  assert.equal(io.calls.filter((c) => c.method === "messaging.history").length, 2);
+  assert.ok(io.logs.some((l) => /capping at 2/.test(l.message)));
+});
+
+// ---------------------------------------------------------------------------
+// thread roots
+// ---------------------------------------------------------------------------
+
+test("myThreadRootIds records threads I authored in and threads that named me", async () => {
+  const io = fakeIo({
+    ...ROSTER,
+    "messaging.history": () =>
+      okFrame({
+        messages: [
+          { id: "r1", authorId: ME, body: "kick off", mentions: [] },
+          { id: "m2", authorId: THEM, body: "reply", threadRootId: "r1", mentions: [] },
+          { id: "m3", authorId: THEM, body: "hi", threadRootId: "r2", mentions: [ME] },
+          { id: "m4", authorId: THEM, body: "nothing to do with me", threadRootId: "r3", mentions: [] },
+        ],
+      }),
+  });
+  const facts = await resolveFacts({ candidates: [msgEvent("C-pub", "PUBLIC", "m2")], me: ME, io });
+  assert.deepEqual([...facts.myThreadRootIds].sort(), ["r1", "r2"]);
+});
+
+// ---------------------------------------------------------------------------
+// board
+// ---------------------------------------------------------------------------
+
+test("board.context resolves assignee/reviewer roles out of the swimlane projection", async () => {
+  const io = fakeIo({
+    "read:board.context": okRead({
+      lanes: [
+        {
+          workstreamId: "W-1",
+          columns: {
+            doing: [{ id: "T-1", title: "mine", col: "doing", assigneeId: ME, reviewerId: null }],
+            review: [{ id: "T-2", title: "review", col: "review", assigneeId: THEM, reviewerId: ME }],
+            done: [{ id: "T-3", title: "theirs", col: "done", assigneeId: THEM, reviewerId: THEM }],
+          },
+        },
+      ],
+    }),
+    "board.taskComments": okFrame({ comments: [] }),
+  });
+  const cand = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  const facts = await resolveFacts({ candidates: [cand], me: ME, io });
+
+  assert.equal(facts.taskRole.get("T-1"), "assignee");
+  assert.equal(facts.taskRole.get("T-2"), "reviewer");
+  assert.equal(facts.taskRole.has("T-3"), false);
+  assert.equal(facts.tasks.get("T-1").title, "mine");
+});
+
+test("board.context unreadable → taskRole empty-but-present + degraded + logged", async () => {
+  const io = fakeIo({});
+  const cand = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  const facts = await resolveFacts({ candidates: [cand], me: ME, io });
+  assert.equal(facts.taskRole, null);
+  assert.deepEqual(facts.degraded, ["board"]);
+  assert.ok(facts.degraded.length && io.logs.some((l) => /board\.context/.test(l.message)));
+});
+
+test("collectTasks is defensive about shape changes", () => {
+  assert.deepEqual(collectTasks(null), []);
+  assert.deepEqual(collectTasks({ nope: 1 }), []);
+  assert.equal(collectTasks([{ id: "T-1", col: "doing" }]).length, 1);
+  // No infinite recursion on a deep/odd payload.
+  assert.doesNotThrow(() => collectTasks({ a: { b: { c: { d: { e: { f: { g: 1 } } } } } } }));
+});
+
+// ---------------------------------------------------------------------------
+// decision / escalation / approval / files probes
+// ---------------------------------------------------------------------------
+
+test("decision facts: list read + one listComments probe, skipped when I proposed it", async () => {
+  const io = fakeIo({
+    "read:decision.list": okRead({
+      decisions: [
+        { id: "D-mine", title: "mine", proposedBy: ME },
+        { id: "D-theirs", title: "theirs", proposedBy: THEM },
+      ],
+    }),
+    "decision.listComments": ({ decisionId }) =>
+      okFrame({ decisionId, comments: [{ id: "c1", authorId: ME, body: "+1" }] }),
+  });
+  const cands = [
+    classifyEvent(ev({ family: "decision", kind: "decision.comment", entity_id: "D-mine", payload: { authorId: THEM } })),
+    classifyEvent(ev({ family: "decision", kind: "decision.comment", entity_id: "D-theirs", payload: { authorId: THEM } })),
+  ];
+  const facts = await resolveFacts({ candidates: cands, me: ME, io });
+
+  const probes = io.calls.filter((c) => c.method === "decision.listComments");
+  assert.deepEqual(probes.map((p) => p.params.decisionId), ["D-theirs"], "no probe needed for one I proposed");
+  assert.ok(facts.decisionVoices.get("D-theirs").has(ME));
+});
+
+test("escalation facts come from one list read", async () => {
+  const io = fakeIo({
+    "messaging.channels": okFrame({ channels: [] }),
+    "read:board.context": okRead({ lanes: [] }),
+    "escalation.list": okFrame({ escalations: [{ id: "E-1", title: "prod", waitingOn: ME }] }),
+  });
+  const cand = classifyEvent(ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-1", payload: { actor: THEM } }));
+  const facts = await resolveFacts({ candidates: [cand], me: ME, io });
+  assert.equal(facts.escalations.get("E-1").waitingOn, ME);
+  assert.equal(io.calls.filter((c) => c.method === "escalation.list").length, 1);
+});
+
+test("approval facts: the approver seat is READ BACK, because the payload never names it", async () => {
+  const io = fakeIo({
+    "approval.get": ({ id }) => okFrame({ id, requester: THEM, approver: ME, status: "pending", actionClass: "spend" }),
+  });
+  const cand = classifyEvent(
+    ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM, actionClass: "spend" } }),
+  );
+  const facts = await resolveFacts({ candidates: [cand], me: ME, io });
+  assert.equal(facts.approvals.get("A-1").approver, ME);
+  assert.deepEqual(io.calls.filter((c) => c.method === "approval.get").map((c) => c.params.id), ["A-1"]);
+});
+
+test("approval probes are de-duplicated and capped", async () => {
+  const io = fakeIo({ "approval.get": ({ id }) => okFrame({ id, requester: THEM, approver: ME }) });
+  const cands = [
+    classifyEvent(ev({ seq: 1, family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM } })),
+    classifyEvent(ev({ seq: 2, family: "approval", kind: "approval.approved", entity_id: "A-1", payload: { requester: THEM } })),
+    classifyEvent(ev({ seq: 3, family: "approval", kind: "approval.requested", entity_id: "A-2", payload: { requester: THEM } })),
+  ];
+  await resolveFacts({ candidates: cands, me: ME, io, limits: { maxApprovalProbes: 1 } });
+  assert.equal(io.calls.filter((c) => c.method === "approval.get").length, 1);
+});
+
+test("doc facts: files.get IS the ACL — an invisible doc simply never appears", async () => {
+  const io = fakeIo({
+    "files.get": ({ fileId }) => {
+      if (fileId === "F-mine") return okFrame({ file: { id: "F-mine", name: "spec", ownerId: ME }, permission: "owner" });
+      if (fileId === "F-shared") return okFrame({ file: { id: "F-shared", name: "plan", ownerId: THEM }, permission: "comment" });
+      return { ok: false, error: { code: "NOT_FOUND", message: "no such file" } };
+    },
+  });
+  const mk = (id) => classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: id, payload: { name: "x" } }));
+  const facts = await resolveFacts({ candidates: [mk("F-mine"), mk("F-shared"), mk("F-hidden")], me: ME, io });
+
+  assert.equal(facts.fileAcl.get("F-mine").ownerId, ME);
+  assert.equal(facts.fileAcl.get("F-shared").shared, true);
+  assert.equal(facts.fileAcl.has("F-hidden"), false, "a doc I cannot read must not get an ACL entry");
+});
+
+test("doc facts: a prose-name probe runs only when myNames is configured", async () => {
+  const routes = {
+    "files.get": ({ fileId }) => okFrame({ file: { id: fileId, name: "spec", ownerId: THEM }, permission: "none" }),
+    "files.comments": () => okFrame({ comments: [{ id: "c1", authorId: THEM, body: "Isla should look at this" }] }),
+  };
+  const mk = () => classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-1", payload: {} }));
+
+  const without = fakeIo(routes);
+  await resolveFacts({ candidates: [mk()], me: ME, io: without });
+  assert.equal(without.calls.filter((c) => c.method === "files.comments").length, 0);
+
+  const with_ = fakeIo(routes);
+  const facts = await resolveFacts({ candidates: [mk()], me: ME, io: with_, myNames: ["Isla"] });
+  assert.equal(with_.calls.filter((c) => c.method === "files.comments").length, 1);
+  assert.equal(facts.fileAcl.get("F-1").mentionsMe, true);
+});
+
+// ---------------------------------------------------------------------------
+// no work → no spend
+// ---------------------------------------------------------------------------
+
+test("a family absent from the batch costs nothing", async () => {
+  const io = fakeIo({ ...ROSTER, "messaging.history": () => okFrame({ messages: [] }) });
+  await resolveFacts({ candidates: [msgEvent("C-dm", "DM", "m1")], me: ME, io });
+  const methods = io.calls.map((c) => c.method || c.base);
+  assert.equal(methods.includes("board.context"), false);
+  assert.equal(methods.includes("escalation.list"), false);
+  assert.equal(methods.includes("approval.get"), false);
+  assert.equal(methods.includes("files.get"), false);
+});
+
+test("an empty batch, or no io, resolves to an inert fact set", async () => {
+  const a = await resolveFacts({ candidates: [], me: ME, io: fakeIo({}) });
+  assert.equal(a.channelPages.size, 0);
+  const b = await resolveFacts({ candidates: [msgEvent("C-dm", "DM", "m1")], me: ME, io: null });
+  assert.equal(b.visibleChannelIds, null);
+});
+
+test("a disabled surface is never probed for", async () => {
+  const io = fakeIo({ ...ROSTER, "messaging.history": () => okFrame({ messages: [] }) });
+  await resolveFacts({
+    candidates: [msgEvent("C-pub", "PUBLIC", "m1")],
+    me: ME,
+    io,
+    enabled: { dm: true, mention: false, thread_reply: false },
+  });
+  assert.equal(io.calls.filter((c) => c.method === "messaging.history").length, 0);
+});