@cohortapp/agent-sdk 2.3.2 → 2.4.0

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

@@ -0,0 +1,326 @@
+/**
+ * hydrate.test.mjs — per-family body/context hydration.
+ *
+ * Two things are being asserted throughout:
+ *   1. every surface produces a body a classifier can actually act on, and
+ *   2. hydration only ever uses the agent's OWN entitled reads — the call log is
+ *      checked so a hydrator cannot quietly acquire a wider aperture than the
+ *      directedness probe that let the item through.
+ *
+ * Run: node --test lib/org/inbound/hydrate.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { hydrate, clip, renderThread, describeBoardKind, describeApprovalKind } from "./hydrate.mjs";
+import { classifyEvent } from "./directedness.mjs";
+
+const ME = "M-me";
+const THEM = "M-them";
+const okFrame = (result) => ({ ok: true, result });
+
+function fakeIo(routes = {}) {
+  const calls = [];
+  const logs = [];
+  return {
+    calls,
+    logs,
+    log: (level, message, meta) => logs.push({ level, message, meta }),
+    async call(method, params) {
+      calls.push({ method, params });
+      const h = routes[method];
+      if (!h) return { ok: false, error: { code: "NOT_FOUND", message: method } };
+      return typeof h === "function" ? await h(params) : h;
+    },
+    async read() {
+      return { ok: false, error: { code: "NOT_FOUND", message: "read" }, status: 404 };
+    },
+  };
+}
+
+function facts(over = {}) {
+  return {
+    me: ME,
+    myNames: [],
+    channels: new Map(),
+    channelPages: new Map(),
+    myThreadRootIds: new Set(),
+    tasks: null,
+    decisions: null,
+    escalations: null,
+    approvals: null,
+    fileAcl: null,
+    degraded: [],
+    ...over,
+  };
+}
+
+function ev(over) {
+  return { seq: 7, at: "2026-08-11T00:00:00.000Z", actor: THEM, ...over };
+}
+
+// ---------------------------------------------------------------------------
+// messaging
+// ---------------------------------------------------------------------------
+
+test("messaging hydrates from the ACL'd history page — no extra RPC", async () => {
+  const f = facts();
+  f.channels.set("C-pub", { id: "C-pub", kind: "PUBLIC", name: "General", slug: "general" });
+  f.channelPages.set("C-pub", {
+    byId: new Map([
+      ["m1", { id: "m1", authorId: THEM, authorName: "Casey", body: "@Isla take a look", mentions: [ME] }],
+    ]),
+    messages: [{ id: "m1", authorId: THEM, authorName: "Casey", body: "@Isla take a look", mentions: [ME] }],
+  });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 1 } }));
+  const io = fakeIo({});
+  const h = await hydrate({ candidate: c, verdict: { surface: "mention", reason: "mention" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.equal(h.text, "@Isla take a look");
+  assert.deepEqual(h.from, { id: THEM, name: "Casey" });
+  assert.equal(h.channelLabel, "General");
+  assert.equal(io.calls.length, 0, "the body was already on the page");
+});
+
+test("a message that never hydrated is DROPPED, not delivered blank", async () => {
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m404", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "mention" }, facts: facts(), io: fakeIo({}) });
+  assert.equal(h.ok, false);
+  assert.equal(h.reason, "message_not_in_page");
+});
+
+test("an empty body is dropped (a blank inbound produces a nonsense reply)", async () => {
+  const f = facts();
+  f.channelPages.set("C", { byId: new Map([["m1", { id: "m1", authorId: THEM, body: "   " }]]), messages: [] });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm" }, facts: f, io: fakeIo({}) });
+  assert.equal(h.ok, false);
+  assert.equal(h.reason, "empty_body");
+});
+
+test("a threaded message carries prior-thread context", async () => {
+  const msgs = [
+    { id: "r1", authorId: ME, authorName: "Isla", body: "kick off", threadRootId: null },
+    { id: "m2", authorId: THEM, authorName: "Casey", body: "one more thing", threadRootId: "r1" },
+  ];
+  const f = facts();
+  f.channelPages.set("C-pub", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", threaded: true } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "thread_reply", reason: "thread" }, facts: f, io: fakeIo({}) });
+
+  assert.equal(h.isReply, true);
+  assert.equal(h.threadId, "r1");
+  assert.match(h.threadContext, /Isla: kick off/);
+  assert.doesNotMatch(h.threadContext, /one more thing/, "the trigger itself is not its own context");
+});
+
+// ---------------------------------------------------------------------------
+// board
+// ---------------------------------------------------------------------------
+
+test("board hydrates the task card + its comment thread", async () => {
+  const f = facts({ tasks: new Map([["T-1", { id: "T-1", title: "Ship the thing", col: "doing", priority: 1, detail: "make it fast", channelId: "C-eng" }]]) });
+  const io = fakeIo({
+    "board.taskComments": ({ taskId }) =>
+      okFrame({
+        taskId,
+        comments: [
+          { id: "c1", authorId: ME, authorName: "Isla", body: "on it" },
+          { id: "c2", authorId: THEM, authorName: "Casey", body: "any update?" },
+        ],
+      }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM, kind: "human" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /New comment on your board item — "Ship the thing"/);
+  assert.match(h.text, /Column: doing/);
+  assert.match(h.text, /any update\?/);
+  assert.match(h.threadContext, /Isla: on it/);
+  assert.equal(h.threadId, "T-1");
+  assert.deepEqual(io.calls.map((x) => x.method), ["board.taskComments"]);
+});
+
+test("a reviewer is TOLD they are the reviewer", async () => {
+  const f = facts({ tasks: new Map([["T-2", { id: "T-2", title: "Review me", col: "review" }]]) });
+  const io = fakeIo({ "board.taskComments": okFrame({ comments: [] }) });
+  const c = classifyEvent(ev({ family: "board", kind: "item.moved", entity_id: "T-2", payload: { actor: THEM, to: "review" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "reviewer" }, facts: f, io });
+  assert.match(h.text, /You are the REVIEWER/);
+});
+
+test("two candidates on one task share a single taskComments read", async () => {
+  let n = 0;
+  const io = fakeIo({ "board.taskComments": () => { n += 1; return okFrame({ comments: [] }); } });
+  const f = facts({ tasks: new Map([["T-3", { id: "T-3", title: "x" }]]) });
+  const cache = new Map();
+  const mk = (seq, kind) => classifyEvent(ev({ seq, family: "board", kind, entity_id: "T-3", payload: { actor: THEM } }));
+  await hydrate({ candidate: mk(1, "item.commented"), verdict: { surface: "task_comment" }, facts: f, io, cache });
+  await hydrate({ candidate: mk(2, "item.moved"), verdict: { surface: "task_comment" }, facts: f, io, cache });
+  assert.equal(n, 1);
+});
+
+// ---------------------------------------------------------------------------
+// file / doc
+// ---------------------------------------------------------------------------
+
+test("a chat-file comment hydrates through file.listComments, scoped by channel", async () => {
+  const f = facts();
+  f.channels.set("C-team", { id: "C-team", kind: "PRIVATE", name: "Leads" });
+  const io = fakeIo({
+    "file.listComments": okFrame({ comments: [{ id: "fc1", authorId: THEM, authorName: "Casey", body: "typo on slide 3" }] }),
+  });
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { fileKey: "message-attachment:abc", channelId: "C-team", authorId: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "channel" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /typo on slide 3/);
+  // The channel is forwarded so hq can run its own visibility gate.
+  assert.equal(io.calls[0].params.channelId, "C-team");
+});
+
+test("an unreadable file thread is dropped rather than delivered empty", async () => {
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc2", payload: { fileKey: "message-attachment:z", channelId: "C-team" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "file_comment" }, facts: facts(), io: fakeIo({}) });
+  assert.equal(h.ok, false);
+  assert.equal(h.reason, "file_comment_unreadable");
+});
+
+test("a workspace doc comment hydrates through files.comments", async () => {
+  const f = facts({ fileAcl: new Map([["F-1", { ownerId: ME, shared: false, name: "Spec" }]]) });
+  const io = fakeIo({
+    "files.comments": okFrame({ comments: [{ id: "dc1", authorId: THEM, authorName: "Casey", body: "can we cut section 4?" }] }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-1", payload: { name: "Spec", commentId: "dc1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /New comment on "Spec"/);
+  assert.match(h.text, /cut section 4/);
+});
+
+// ---------------------------------------------------------------------------
+// decision / escalation / approval / handoff
+// ---------------------------------------------------------------------------
+
+test("a decision carries status, body, rationale and the latest comment", async () => {
+  const f = facts({
+    decisions: new Map([["D-1", { id: "D-1", title: "Adopt X", status: "proposed", scope: "eng", body: "we adopt X", rationale: "cheaper" }]]),
+  });
+  const io = fakeIo({
+    "decision.listComments": okFrame({ comments: [{ id: "c1", authorId: THEM, authorName: "Casey", body: "what about Y?" }] }),
+  });
+  const c = classifyEvent(ev({ family: "decision", kind: "decision.adjustment_requested", entity_id: "D-1", payload: { commentId: "c1", authorId: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "decision", reason: "proposer" }, facts: f, io });
+
+  assert.match(h.text, /An adjustment was requested on a decision — "Adopt X"/);
+  assert.match(h.text, /Status: proposed/);
+  assert.match(h.text, /Rationale: cheaper/);
+  assert.match(h.text, /what about Y\?/);
+  assert.match(h.text, /needs a response/);
+});
+
+test("an escalation needs no extra read — the facts pass already had it", async () => {
+  const f = facts({ escalations: new Map([["E-1", { id: "E-1", title: "prod down", severity: "high", detail: "500s on /v1", waitingOn: ME }]]) });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-1", payload: { actor: THEM, severity: "high" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "escalation", reason: "waiting_on" }, facts: f, io });
+
+  assert.match(h.text, /Escalation raised — "prod down"/);
+  assert.match(h.text, /Severity: high/);
+  assert.match(h.text, /Waiting on: M-me/);
+  assert.equal(io.calls.length, 0);
+});
+
+test("an approval renders the whole decision packet", async () => {
+  const f = facts({
+    approvals: new Map([["A-1", { id: "A-1", requester: THEM, approver: ME, status: "pending", actionClass: "spend.over_1k", reason: "vendor renewal", itemId: "T-9", expiresAt: "2026-08-12T00:00:00.000Z" }]]),
+  });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM, actionClass: "spend.over_1k" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.text, /An approval is waiting on you — spend\.over_1k/);
+  assert.match(h.text, /Status: pending/);
+  assert.match(h.text, /vendor renewal/);
+  assert.match(h.text, /Board item: T-9/);
+});
+
+test("a handoff renders intent and both ends from the payload alone", async () => {
+  const f = facts({ tasks: new Map([["T-1", { id: "T-1", title: "Migrate DB", detail: "zero downtime" }]]) });
+  const c = classifyEvent(ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { itemId: "T-1", from: THEM, to: ME, intent: "please take this over" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "handoff", reason: "direct" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.text, /A handoff was offered to you — "Migrate DB"/);
+  assert.match(h.text, /Intent: please take this over/);
+  assert.match(h.text, /From M-them → to M-me/);
+});
+
+// ---------------------------------------------------------------------------
+// email
+// ---------------------------------------------------------------------------
+
+test("email hydrates through email.thread, which hq scopes to MY mailbox", async () => {
+  const io = fakeIo({
+    "email.thread": ({ threadId }) =>
+      okFrame({
+        thread: { id: threadId, subject: "Contract renewal" },
+        messages: [
+          { id: "EM-0", subject: "Contract renewal", text: "here is the draft", from: { name: "Dana", address: "dana@acme.com" } },
+          { id: "EM-1", subject: "Re: Contract renewal", text: "any thoughts?", from: { name: "Dana", address: "dana@acme.com" } },
+        ],
+      }),
+  });
+  const c = classifyEvent(ev({ family: "email", kind: "received", actor: "system", entity_id: "EM-1", payload: { emailMessageId: "EM-1", threadId: "ET-1", mailboxId: "MB-1", memberId: ME } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "email", reason: "direct" }, facts: facts(), io });
+
+  assert.equal(h.ok, true);
+  assert.equal(h.text, "any thoughts?");
+  assert.equal(h.subjectDetail, "Re: Contract renewal");
+  assert.equal(h.from.name, "Dana");
+  assert.match(h.threadContext, /here is the draft/);
+  assert.deepEqual(io.calls.map((x) => x.method), ["email.thread"]);
+});
+
+test("unreadable mail is dropped (not another seat's mail leaking through)", async () => {
+  const c = classifyEvent(ev({ family: "email", kind: "received", entity_id: "EM-9", payload: { emailMessageId: "EM-9", threadId: "ET-9", memberId: ME } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "email" }, facts: facts(), io: fakeIo({}) });
+  assert.equal(h.ok, false);
+  assert.equal(h.reason, "email_unreadable");
+});
+
+// ---------------------------------------------------------------------------
+// robustness
+// ---------------------------------------------------------------------------
+
+test("a hydrator that throws fails open, loudly, and never takes the pull down", async () => {
+  const io = fakeIo({
+    "board.taskComments": () => {
+      throw new Error("boom");
+    },
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment" }, facts: facts(), io });
+  assert.equal(h.ok, false);
+  assert.equal(h.reason, "hydrate_threw");
+  assert.ok(io.logs.some((l) => l.level === "warn" && /hydrate board threw/.test(l.message)));
+});
+
+test("clip and renderThread are bounded", () => {
+  assert.equal(clip("abc", 10), "abc");
+  assert.ok(clip("x".repeat(100), 10).length <= 11);
+  assert.equal(renderThread([]), null);
+  assert.equal(renderThread(null), null);
+  assert.match(renderThread([{ authorName: "A", body: "hi" }]), /A: hi/);
+});
+
+test("event-kind phrasing is stable and total", () => {
+  assert.match(describeBoardKind("item.assigned"), /assigned to you/);
+  assert.match(describeBoardKind("who.knows"), /Update on your board item/);
+  assert.match(describeApprovalKind("approval.requested"), /waiting on you/);
+  assert.match(describeApprovalKind("approval.rejected"), /REJECTED/);
+});

package/lib/org/inbound/index.mjs

@@ -0,0 +1,233 @@
+/**
+ * lib/org/inbound/index.mjs — WIDE inbound: give an SDK agent the same inbound
+ * coverage hq's own responder has.
+ *
+ * ── THE PROBLEM ──
+ * `lib/org/messaging.pullInbound` tails two families (`messaging`, `calling`)
+ * and recognises two things: a message in a private room I belong to, and a call
+ * in one of my rooms. hq's in-process responder (`src/server/llm-responder/`)
+ * reacts to eleven triggers — channel @mentions, thread replies, reactions,
+ * polls, decision comments, board comments, file comments, genUI actions,
+ * inbound email, call utterances, ambient. And since hq commit `4d762d30` it
+ * STANDS DOWN for any member whose daemon beat inside 100 s
+ * (`llm-responder/sdk-driven.ts`). So for a live SDK agent the net effect of an
+ * @mention in a space today is: **nobody answers**. hq is quiet by design and the
+ * SDK is deaf by omission.
+ *
+ * ── THE SHAPE OF THE FIX ──
+ * Four pure-ish stages over one injectable IO seam:
+ *
+ *   events  ──classifyEvent──▶  candidates        (pure, directedness.mjs)
+ *                                   │
+ *              resolveFacts ◀───────┘              (agent's OWN entitled reads,
+ *                   │                               facts.mjs — batched + capped)
+ *                   ▼
+ *           resolveDirected                        (pure verdict + typed reason)
+ *                   │  directed only
+ *                   ▼
+ *              hydrate                             (bodies, ACL'd, hydrate.mjs)
+ *                   │
+ *                   ▼
+ *           toMessageEvent                         (existing contract, project.mjs)
+ *
+ * Nothing downstream changes: the output is the same `MessageEvent` array
+ * `pullInbound` already returns, so `guardMessagingInbound` keeps calling
+ * `eventToInboxItem` + `writeInboxItem` verbatim. The only new information the
+ * daemon sees is `kind`, which carries the surface so the classifier can route.
+ *
+ * ── SAFETY ──
+ * The org feed is org-wide and redacted. The hard rule, enforced in
+ * `directedness.mjs` and again in `facts.mjs`, is: **a channel outside my
+ * `messaging.channels` roster is never probed, never hydrated, and never
+ * directed.** hq returns a non-PUBLIC channel only to its members, so a private
+ * room I am not in cannot appear — and a negative test asserts that no
+ * `messaging.history` call is ever made for one.
+ *
+ * ── FAIL-OPEN, NEVER SILENT ──
+ * Every read that fails degrades the verdict to "unknown" (which closes private
+ * surfaces rather than opening them) and logs through `io.log`. `pullWideInbound`
+ * never throws into its caller, and returns `stats` so the cadence handler can
+ * log what it spent and what it dropped.
+ *
+ * @module lib/org/inbound
+ */
+
+"use strict";
+
+import { read as clientRead } from "../client.mjs";
+import { classifyEvent, resolveDirected } from "./directedness.mjs";
+import { resolveFacts, DEFAULT_LIMITS } from "./facts.mjs";
+import { hydrate } from "./hydrate.mjs";
+import { toMessageEvent } from "./project.mjs";
+import { makeIo, resolveOrg } from "./io.mjs";
+import { resolveEnabledSurfaces, parseSurfaceEnv, SURFACES } from "./surfaces.mjs";
+
+export { SURFACES, parseSurfaceEnv, resolveEnabledSurfaces } from "./surfaces.mjs";
+export { classifyEvent, resolveDirected } from "./directedness.mjs";
+export { resolveFacts } from "./facts.mjs";
+export { hydrate } from "./hydrate.mjs";
+export { toMessageEvent } from "./project.mjs";
+export { makeIo } from "./io.mjs";
+
+/** Default page size for the `/v1/events` read. */
+const DEFAULT_EVENT_LIMIT = 200;
+
+/**
+ * Pull every DIRECTED org event since `cursor` and project it onto MessageEvent.
+ *
+ * Drop-in for `lib/org/messaging.pullInbound`: same `{cfg, agentId, cursor,
+ * limit, fetchImpl}` in, same `{events, nextCursor}` out — plus `stats`.
+ *
+ * @param {Object} o
+ * @param {object} o.cfg                       the agent config (org.cohort.*)
+ * @param {string} [o.agentId]                 the seat's member id (REQUIRED in
+ *   practice — without it own-echo suppression is off and every direct surface
+ *   misses, so we refuse to run and say so)
+ * @param {number|string} [o.cursor]
+ * @param {number} [o.limit]
+ * @param {Function} [o.fetchImpl]
+ * @param {string[]} [o.myNames]               display names for prose-mention matching
+ * @param {string[]|Record<string,boolean>} [o.surfaces] surface enable override
+ * @param {object} [o.limits]                  overrides for {@link DEFAULT_LIMITS}
+ * @param {Function} [o.log]                   (level, message, meta?) — daemon logger
+ * @param {import("./io.mjs").InboundIo} [o.io] injected IO (tests)
+ * @param {Function} [o.readImpl]              injected `/v1` GET (tests)
+ * @returns {Promise<{events:object[], nextCursor:(number|string|null), stats:object}>}
+ */
+export async function pullWideInbound(o = {}) {
+  const log = typeof o.log === "function" ? o.log : () => {};
+  const cursor = o.cursor ?? 0;
+  const stats = {
+    scanned: 0,
+    classified: 0,
+    directed: 0,
+    delivered: 0,
+    bySurface: {},
+    dropped: {},
+    degraded: [],
+    calls: 0,
+    reads: 0,
+  };
+  const empty = { events: [], nextCursor: cursor, stats };
+
+  const org = resolveOrg(o.cfg);
+  if (!org) {
+    log("info", "[inbound] org messaging not configured — wide inbound inert");
+    return empty;
+  }
+
+  const me = o.agentId ? String(o.agentId) : "";
+  if (!me) {
+    // NEVER SILENT. Without the seat id we cannot suppress the agent's own
+    // echoes and every payload-named surface (email/approval/handoff) misses.
+    // Running anyway would produce an agent talking to itself.
+    log("error", "[inbound] no agentId — refusing to pull (set COHORT_AGENT_ID)");
+    return empty;
+  }
+
+  const { enabled, unknown } = resolveEnabledSurfaces(
+    o.surfaces !== undefined ? o.surfaces : parseSurfaceEnv(process.env.COHORT_INBOUND_SURFACES),
+  );
+  if (unknown.length) {
+    log("warn", `[inbound] ignoring unknown surface name(s): ${unknown.join(", ")}`);
+  }
+
+  const io =
+    o.io ||
+    makeIo({ cfg: o.cfg, fetchImpl: o.fetchImpl, log, timeoutMs: o.timeoutMs });
+  if (!io) return empty;
+
+  // ── 1. Read the ledger window. hq IGNORES `family=` on this read
+  //      (`src/server/rpc/reads.ts` looks at `cursor` + `limit` only), so the
+  //      filter is ours to apply — which is exactly why widening the aperture
+  //      costs no extra bandwidth: the rows were always arriving.
+  const limit = Number.isFinite(o.limit) ? o.limit : DEFAULT_EVENT_LIMIT;
+  const readImpl = o.readImpl || (io.read ? (p) => io.read(p) : clientRead);
+  const r = await readImpl(
+    `events?cursor=${encodeURIComponent(cursor)}&limit=${encodeURIComponent(limit)}`,
+  );
+  if (!r || r.ok !== true || !r.payload) {
+    log("warn", "[inbound] events read failed — cursor held, will retry next tick");
+    return empty;
+  }
+
+  const raw = Array.isArray(r.payload)
+    ? r.payload
+    : Array.isArray(r.payload.events)
+      ? r.payload.events
+      : [];
+  stats.scanned = raw.length;
+
+  let maxSeq = cursor;
+  const candidates = [];
+  for (const ev of raw) {
+    const seq = Number(ev && ev.seq);
+    if (Number.isFinite(seq)) maxSeq = Math.max(Number(maxSeq) || 0, seq);
+    const cand = classifyEvent(ev);
+    if (cand) candidates.push(cand);
+  }
+  stats.classified = candidates.length;
+  const nextCursor = raw.length ? maxSeq : cursor;
+
+  if (candidates.length === 0) return { events: [], nextCursor, stats };
+
+  // ── 2. The agent's own half of the join.
+  const facts = await resolveFacts({
+    candidates,
+    me,
+    io,
+    myNames: o.myNames,
+    enabled,
+    limits: { ...DEFAULT_LIMITS, ...(o.limits || {}) },
+  });
+  stats.degraded = facts.degraded.slice();
+
+  // ── 3. Verdicts.
+  const directed = [];
+  for (const cand of candidates) {
+    const verdict = resolveDirected(cand, me, facts, { enabled });
+    if (!verdict.directed) {
+      stats.dropped[verdict.reason] = (stats.dropped[verdict.reason] || 0) + 1;
+      continue;
+    }
+    directed.push({ cand, verdict });
+  }
+  stats.directed = directed.length;
+
+  // ── 4. Hydrate + project. Body reads happen ONLY for what is already mine.
+  const cache = new Map();
+  const events = [];
+  for (const { cand, verdict } of directed) {
+    const hydrated = await hydrate({ candidate: cand, verdict, facts, io, cache });
+    if (!hydrated || hydrated.ok !== true) {
+      const why = (hydrated && hydrated.reason) || "hydration_failed";
+      stats.dropped[why] = (stats.dropped[why] || 0) + 1;
+      // A blank inbound produces a nonsense reply in a real room. Drop it, loudly.
+      log("warn", `[inbound] dropping ${verdict.surface} ${cand.entityId || cand.seq}: ${why}`);
+      continue;
+    }
+    const projected = toMessageEvent({ candidate: cand, verdict, hydrated, me, facts });
+    if (!projected) {
+      stats.dropped.projection_refused = (stats.dropped.projection_refused || 0) + 1;
+      continue;
+    }
+    events.push(projected);
+    stats.bySurface[verdict.surface] = (stats.bySurface[verdict.surface] || 0) + 1;
+  }
+  stats.delivered = events.length;
+  if (io.stats) {
+    stats.calls = io.stats.calls;
+    stats.reads = io.stats.reads;
+  }
+
+  if (events.length) {
+    const summary = Object.entries(stats.bySurface)
+      .map(([k, v]) => `${k}×${v}`)
+      .join(", ");
+    log("info", `[inbound] ${events.length} directed item(s): ${summary}`);
+  }
+
+  return { events, nextCursor, stats };
+}
+
+export default { pullWideInbound };