@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/execution/intake.test.mjs

@@ -0,0 +1,343 @@
+/**
+ * lib/execution/intake.test.mjs — every inbound shape, every surface, both signs.
+ *
+ * The negatives matter more than the positives here. `intake` is the only place
+ * that decides a Slack channel message nobody addressed is NOT this agent's
+ * problem, and the only place an `info` alert is stopped from becoming work. A
+ * regression in a positive case is a missed reply; a regression in a negative
+ * case is an agent that interrupts every conversation in the workspace.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  intake,
+  fromInboxItem,
+  fromChannelEvent,
+  fromAlert,
+  fromRawEvent,
+  fromMessageEvent,
+  parseRawRef,
+  isKnownSurface,
+  KIND_SURFACE,
+  SURFACE_FAMILY,
+  SURFACE_TOPIC,
+  RECONSTRUCTED_REASON,
+} from "./intake.mjs";
+import { SURFACE_POLICY, EXTENDED_SURFACE_NAMES } from "./surface-policy.mjs";
+import { SURFACE_NAMES } from "../org/inbound/surfaces.mjs";
+import { decide } from "./disposition.mjs";
+import { dedupeKey, threadKey } from "./journal.mjs";
+
+const ME = "mem_self";
+const NOW = "2026-08-11T09:00:00.000Z";
+
+/** A cohort inbox item as it exists on disk (post-`eventToInboxItem` flattening). */
+function orgItem(over = {}) {
+  return {
+    id: "cohort-mention-4821",
+    service: "cohort",
+    channel: "eng-space",
+    channel_id: "chan_1",
+    sender: "peer-one",
+    sender_id: "mem_peer",
+    timestamp: NOW,
+    subject: "Cohort @mention: eng-space",
+    content: "can you take a look at this",
+    thread_id: "msg_77",
+    is_reply: false,
+    priority_signals: { from_ceo: false, tagged_urgent: false, contains_deadline: false, mentions_agent: true },
+    raw_ref: "cohort:mention:msg_99:4821",
+    source: "cohort",
+    kind: "mention",
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// raw_ref
+// ---------------------------------------------------------------------------
+
+test("parseRawRef reads the projection's cohort ref, including ids containing colons", () => {
+  assert.deepEqual(parseRawRef("cohort:mention:msg_99:4821"), {
+    surface: "mention",
+    entityId: "msg_99",
+    seq: "4821",
+  });
+  assert.deepEqual(parseRawRef("cohort:task_comment:task:abc:def:12"), {
+    surface: "task_comment",
+    entityId: "task:abc:def",
+    seq: "12",
+  });
+});
+
+test("parseRawRef refuses a channel adapter's legacy ref and an unknown surface", () => {
+  assert.equal(parseRawRef("slack:C123:1699.1"), null, "legacy channel ref must not parse as cohort");
+  assert.equal(parseRawRef("cohort:teleport:x:1"), null, "unknown surface must not parse");
+  assert.equal(parseRawRef(""), null);
+  assert.equal(parseRawRef(null), null);
+});
+
+// ---------------------------------------------------------------------------
+// coverage: every surface is reachable and decidable
+// ---------------------------------------------------------------------------
+
+test("every policy surface has a family, a topic and a reconstructable reason", () => {
+  for (const name of Object.keys(SURFACE_POLICY)) {
+    assert.ok(SURFACE_FAMILY[name], `${name} has no family`);
+    assert.ok(SURFACE_TOPIC[name], `${name} has no topic`);
+    assert.ok(RECONSTRUCTED_REASON[name], `${name} has no reconstructable reason`);
+    assert.ok(isKnownSurface(name), `${name} is not a known surface`);
+  }
+});
+
+test("every org surface can be reconstructed from an on-disk item and decided", () => {
+  for (const surface of SURFACE_NAMES) {
+    const item = orgItem({
+      raw_ref: `cohort:${surface}:ent_1:900`,
+      kind: surface === "dm" ? "message" : surface,
+      id: `cohort-${surface}-900`,
+    });
+    const norm = fromInboxItem(item, { me: ME, now: NOW });
+    assert.equal(norm.verdict.surface, surface, `${surface} did not round-trip`);
+    assert.equal(norm.verdict.directed, true, `${surface} lost its directedness`);
+    assert.equal(norm.candidate.family, SURFACE_FAMILY[surface]);
+
+    const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
+    assert.ok(d.disposition, `${surface} produced no disposition`);
+    assert.notEqual(d.policySurface, "default", `${surface} fell back to DEFAULT_POLICY`);
+  }
+});
+
+test("the three extended surfaces decide without falling back to the default row", () => {
+  for (const surface of EXTENDED_SURFACE_NAMES) {
+    const norm = fromInboxItem(orgItem({ raw_ref: `cohort:${surface}:ent_9:12`, kind: surface }), { me: ME });
+    assert.equal(norm.verdict.surface, surface);
+    const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
+    assert.equal(d.policySurface, surface, `${surface} has no policy row`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// org inbox items
+// ---------------------------------------------------------------------------
+
+test("an org inbox item reconstructs directed:true and SAYS it reconstructed it", () => {
+  const norm = fromInboxItem(orgItem(), { me: ME });
+  assert.equal(norm.origin, "inbox_item");
+  assert.equal(norm.verdict.directed, true);
+  assert.equal(norm.verdict.surface, "mention");
+  assert.ok(
+    norm.degraded.some((d) => d.startsWith("verdict_reconstructed:")),
+    "a reconstructed verdict must be labelled as such, never presented as a resolved one",
+  );
+});
+
+test("mentions_agent upgrades a lane-tier reason to a structural one", () => {
+  const named = fromInboxItem(orgItem({ raw_ref: "cohort:thread_reply:msg_5:7", kind: "thread_reply" }), { me: ME });
+  assert.equal(named.verdict.reason, "named", "mentions_agent:true must read as T0");
+
+  const quiet = fromInboxItem(
+    orgItem({
+      raw_ref: "cohort:thread_reply:msg_5:7",
+      kind: "thread_reply",
+      priority_signals: { mentions_agent: false },
+    }),
+    { me: ME },
+  );
+  assert.equal(quiet.verdict.reason, "thread", "no mention must stay lane tier");
+});
+
+test("a lost raw_ref falls back to kind, and is_dm:false stops a channel item being read as a DM", () => {
+  const norm = fromInboxItem(orgItem({ raw_ref: "", kind: "message", is_dm: false }), { me: ME });
+  assert.equal(norm.verdict.surface, "mention");
+  assert.ok(norm.degraded.includes("surface_inferred_from_kind"));
+});
+
+test("an org item whose surface cannot be established is refused, not guessed", () => {
+  const norm = fromInboxItem(orgItem({ raw_ref: "", kind: "reaction" }), { me: ME });
+  assert.equal(norm.candidate, null);
+  assert.equal(norm.verdict.directed, false);
+  assert.equal(norm.verdict.reason, "unknown_surface");
+});
+
+test("two comments on the same task get different dedupe keys but share a thread", () => {
+  const a = fromInboxItem(orgItem({ raw_ref: "cohort:task_comment:task_7:101", kind: "task_comment" }), { me: ME });
+  const b = fromInboxItem(orgItem({ raw_ref: "cohort:task_comment:task_7:102", kind: "task_comment" }), { me: ME });
+  assert.notEqual(dedupeKey(a.candidate), dedupeKey(b.candidate), "distinct events must not collapse");
+  assert.equal(threadKey(a.candidate), threadKey(b.candidate), "one task is one conversation");
+});
+
+// ---------------------------------------------------------------------------
+// channel adapters — the negatives
+// ---------------------------------------------------------------------------
+
+function slackItem(over = {}) {
+  return {
+    id: "1699000000.0001",
+    service: "slack",
+    channel: "general",
+    channel_id: "C123",
+    sender: "someone",
+    sender_id: "U9",
+    timestamp: NOW,
+    content: "shipping the thing today",
+    thread_id: "",
+    is_reply: false,
+    priority_signals: { mentions_agent: false },
+    raw_ref: "slack:C123:1699000000.0001",
+    source: "slack",
+    ...over,
+  };
+}
+
+test("NEGATIVE: an ambient Slack channel message is NOT directed", () => {
+  const norm = fromChannelEvent(slackItem(), { me: ME });
+  assert.equal(norm.verdict.directed, false);
+  assert.equal(norm.verdict.reason, "ambient_channel");
+  assert.ok(norm.why.join(" ").includes("not directed"));
+});
+
+test("NEGATIVE: an ambient channel message is parked, not dropped, because it could have been a mention", () => {
+  const norm = fromChannelEvent(slackItem(), { me: ME });
+  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
+  assert.equal(d.disposition, "ignore");
+  assert.equal(d.ambient, true, "a message that might have been a mention deserves the ambient sweep");
+});
+
+test("a Slack DM is directed by construction", () => {
+  const norm = fromChannelEvent(slackItem({ is_dm: true, channel_type: "im" }), { me: ME });
+  assert.equal(norm.verdict.directed, true);
+  assert.equal(norm.verdict.surface, "dm");
+});
+
+test("a Slack channel message that names the agent is a mention", () => {
+  const norm = fromChannelEvent(slackItem({ priority_signals: { mentions_agent: true } }), { me: ME });
+  assert.equal(norm.verdict.surface, "mention");
+  assert.equal(norm.verdict.reason, "mention");
+});
+
+test("a thread reply on a channel is lane tier, and says membership is unverified", () => {
+  const norm = fromChannelEvent(slackItem({ is_reply: true, thread_id: "1699.0" }), { me: ME });
+  assert.equal(norm.verdict.surface, "thread_reply");
+  assert.ok(norm.degraded.includes("thread_membership_unverified"));
+});
+
+test("an org-mail item is email, directed, and keeps its service as the key space", () => {
+  const norm = fromChannelEvent(slackItem({ service: "orgmail", content: "quote attached" }), { me: ME });
+  assert.equal(norm.verdict.surface, "email");
+  assert.equal(norm.verdict.directed, true);
+  assert.equal(norm.candidate.family, "orgmail");
+});
+
+test("channel and org key spaces never collide", () => {
+  const org = fromInboxItem(orgItem({ raw_ref: "cohort:dm:m1:5" }), { me: ME });
+  const chan = fromChannelEvent(slackItem({ id: "m1", is_dm: true }), { me: ME });
+  assert.notEqual(dedupeKey(org.candidate), dedupeKey(chan.candidate));
+  assert.notEqual(threadKey(org.candidate), threadKey(chan.candidate));
+});
+
+// ---------------------------------------------------------------------------
+// alerts
+// ---------------------------------------------------------------------------
+
+test("a critical alert is directed and decides to queued work", () => {
+  const norm = fromAlert({ id: "daemon_down", severity: "critical", detail: "no beat in 40m" }, { me: ME, now: NOW });
+  assert.equal(norm.verdict.directed, true);
+  assert.equal(norm.verdict.surface, "alert");
+  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
+  assert.equal(d.disposition, "schedule", "an alert is work, not conversation");
+});
+
+test("NEGATIVE: an info alert never becomes work", () => {
+  const norm = fromAlert({ id: "cache_warm", severity: "info", detail: "warmed" }, { me: ME });
+  assert.equal(norm.verdict.directed, false);
+  assert.equal(norm.verdict.reason, "alert_below_threshold");
+  const d = decide({ candidate: norm.candidate, verdict: norm.verdict, me: ME, history: null });
+  assert.equal(d.disposition, "ignore");
+});
+
+test("repeated firings of one alert collapse onto one thread", () => {
+  const a = fromAlert({ id: "disk_low", severity: "warning" }, { me: ME, now: NOW });
+  const b = fromAlert({ id: "disk_low", severity: "warning" }, { me: ME, now: "2026-08-11T10:00:00.000Z" });
+  assert.equal(threadKey(a.candidate), threadKey(b.candidate), "a flapping check must not become a task storm");
+});
+
+// ---------------------------------------------------------------------------
+// raw chain events
+// ---------------------------------------------------------------------------
+
+test("a raw chain row is classified and joined through the inbound layer, not a second copy of it", () => {
+  const norm = fromRawEvent(
+    { seq: 12, family: "escalation", kind: "raised", entity_id: "esc_1", payload: { actor: "mem_peer", waitingOnMemberId: ME } },
+    { me: ME },
+  );
+  assert.equal(norm.origin, "raw_event");
+  assert.ok(norm.candidate, "the classifier should have produced a candidate");
+  assert.ok(norm.degraded.includes("joined_without_facts"), "a factless join must be labelled");
+});
+
+test("NEGATIVE: a family an agent is not woken for produces no candidate and no throw", () => {
+  const norm = fromRawEvent({ seq: 1, family: "presence", kind: "beat", payload: {} }, { me: ME });
+  assert.equal(norm.candidate, null);
+  assert.equal(norm.verdict.directed, false);
+  assert.equal(norm.verdict.reason, "not_classified");
+});
+
+// ---------------------------------------------------------------------------
+// projected MessageEvents
+// ---------------------------------------------------------------------------
+
+test("a projected MessageEvent is lossless — no reconstruction, no degradation", () => {
+  const norm = fromMessageEvent(
+    {
+      message_id: "msg_3",
+      channel_id: "chan_2",
+      thread_id: "msg_1",
+      from: { id: "mem_peer", name: "peer" },
+      timestamp: NOW,
+      kind: "mention",
+      cohort: { surface: "mention", topic: "message", reason: "mention", family: "messaging", event_kind: "send", entity_id: "msg_3", seq: 55, me: ME },
+    },
+    { me: ME },
+  );
+  assert.deepEqual(norm.degraded, [], "a full-provenance event needs no guessing");
+  assert.equal(norm.verdict.reason, "mention");
+  assert.equal(norm.candidate.seq, 55);
+});
+
+// ---------------------------------------------------------------------------
+// intake() dispatch + totality
+// ---------------------------------------------------------------------------
+
+test("intake routes each shape to the right reader", () => {
+  assert.equal(intake({ candidate: { family: "x" }, verdict: { directed: true, surface: "dm" } }).origin, "pair");
+  assert.equal(intake({ cohort: { surface: "dm" }, from: {} }).origin, "message_event");
+  assert.equal(intake({ id: "a", severity: "critical" }).origin, "alert");
+  assert.equal(intake({ family: "board", kind: "assigned", payload: {} }).origin, "raw_event");
+  assert.equal(intake(orgItem()).origin, "inbox_item");
+  assert.equal(intake(slackItem()).origin, "channel_event");
+});
+
+test("intake is TOTAL: no input throws, returns undefined, or silently vanishes", () => {
+  for (const bad of [null, undefined, 7, "a string", [], {}, { kind: 5 }, { raw_ref: {} }]) {
+    const r = intake(bad, { me: ME });
+    assert.ok(r && typeof r === "object", `intake(${JSON.stringify(bad)}) returned nothing`);
+    assert.ok(r.verdict, "every result carries a verdict");
+    assert.ok(Array.isArray(r.why) && r.why.length > 0, "every result explains itself");
+  }
+});
+
+test("an unrecognised object is refused with a reason rather than guessed at", () => {
+  const r = intake({ some: "thing" }, { me: ME });
+  assert.equal(r.verdict.directed, false);
+  assert.equal(r.verdict.reason, "unrecognised_shape");
+  assert.ok(r.degraded.includes("unrecognised_shape"));
+});
+
+test("KIND_SURFACE covers every event kind the channel contract ships", async () => {
+  const { EVENT_KINDS } = await import("../channels/contract.mjs");
+  const missing = EVENT_KINDS.filter((k) => !["reaction", "channel_cc"].includes(k) && !KIND_SURFACE[k]);
+  assert.deepEqual(missing, [], "a shipped event kind with no surface would fall through to the default policy");
+});