@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/org/inbound/directedness.mjs

@@ -54,6 +54,12 @@
 "use strict";
 
 import { SURFACES } from "./surfaces.mjs";
+import { isBroadcast, BROADCAST_KIND, BROADCAST_REASON } from "./broadcast.mjs";
+
+// The collective-address vocabulary lives in ONE place (`broadcast.mjs`, with an
+// hq twin at `src/server/llm-responder/broadcast.ts`); re-exported here so the
+// daemon and the tests keep a single import for "is this mine, and why".
+export { isBroadcast, BROADCAST_PATTERNS, BROADCAST_CORPUS } from "./broadcast.mjs";
 
 /** Channel kinds where every message is addressed to the room. */
 export const PRIVATE_ROOM_KINDS = Object.freeze(["DM", "GROUP_DM", "HUDDLE"]);
@@ -68,9 +74,12 @@ export const MEMBERSHIP_REQUIRED_KINDS = Object.freeze([
  * The typed reasons a verdict can carry. A daemon switches on `reason` for
  * triage; it is a closed set so a new value is a deliberate, reviewable change.
  *
- * @typedef {"dm"|"mention"|"thread"|"channel"|"participant"|"assignee"
- *          |"reviewer"|"direct"|"requester"|"approver"|"proposer"|"commenter"
- *          |"owner"|"shared"|"waiting_on"|"task"|"named"} Reason
+ * @typedef {"dm"|"mention"|"collective"|"thread"|"channel"|"participant"
+ *          |"assignee"|"reviewer"|"direct"|"requester"|"approver"|"proposer"
+ *          |"commenter"|"owner"|"shared"|"waiting_on"|"task"|"named"} Reason
+ *
+ * `collective` — a HUMAN addressed the whole room I am in ("everyone",
+ * "@here", "roll call"); surface `broadcast`. See broadcast.mjs.
  */
 
 /** Narrow an unknown payload to a readable record (never throws). */
@@ -168,7 +177,7 @@ export function classifyEvent(ev) {
     return {
       ...base,
       topic: "message",
-      surfaces: ["dm", "mention", "thread_reply"],
+      surfaces: ["dm", "mention", "broadcast", "thread_reply"],
       ids: {
         channelId,
         channelKind: String(p.channelKind || p.channel_kind || "").toUpperCase() || undefined,
@@ -179,6 +188,9 @@ export function classifyEvent(ev) {
       // mention or a thread reply, so it can be dropped WITHOUT paging the
       // channel at all. That single test is what keeps mention-detection from
       // costing one `messaging.history` per busy public channel per pull.
+      // The ONE exception is a HUMAN-authored space post, which may still be a
+      // broadcast ("everyone …") — see `needsSpaceProbe`, which lets exactly
+      // those through for hydration and still drops agent-authored ones.
       hints: {
         mentionCount: Number.isFinite(Number(p.mentionCount)) ? Number(p.mentionCount) : undefined,
         threaded: typeof p.threaded === "boolean" ? p.threaded : undefined,
@@ -522,6 +534,11 @@ function resolveCalendar(cand, me, facts, on) {
  *   2. private room + I am a member         → `dm`
  *   3. private room + I am NOT a member     → NOT directed (hard stop)
  *   4. private SPACE + I am not a member    → NOT directed (hard stop)
+ *   4b. a HUMAN's un-threaded, un-mentioning post to the WHOLE ROOM
+ *       ("everyone", "@here", "roll call" …) in a space I am a member of
+ *                                           → `broadcast` (reason `collective`)
+ *       — decided BEFORE the structural count drop, because the drop is
+ *       exactly what silenced thirteen seats on 2026-09-21.
  *   5. mentions[] (from history) names me   → `mention`
  *   6. thread root I have spoken in / been named in → `thread_reply`
  *   7. otherwise                            → ambient chatter, not directed
@@ -557,12 +574,26 @@ function resolveMessaging(cand, me, facts, on) {
   // membership-required — the conservative branch.
   if (!channelKind && !has(members, channelId)) return no("channel_kind_unknown");
 
+  const msg = lookupMessage(facts, channelId, cand.ids.messageId);
+
+  // (4b) BROADCAST — a human addressed the whole room. This sits ABOVE the
+  //      structural drop on purpose: the drop reasons from `mentionCount: 0`,
+  //      and a roll-call has, by construction, zero mentions. It is gated on
+  //      every condition the vocabulary module documents — human author, a
+  //      space I am a MEMBER of (a public room I merely see does not address
+  //      me), not threaded, and no structured mention of anyone (a message that
+  //      @-names specific people chose them; "everyone" inside it is prose).
+  //      A DM never reaches this line: (2) returned `dm` above.
+  if (msg && isBroadcastFor(cand, msg, channelId, members, facts)) {
+    return on(BROADCAST_KIND) ? yes(BROADCAST_KIND, BROADCAST_REASON) : no("surface_disabled");
+  }
+
   // Cheap structural drop from the redacted counts, BEFORE any hydration: a
-  // space message that mentions nobody and is not threaded cannot be mine.
+  // space message that mentions nobody and is not threaded cannot be mine —
+  // unless a human wrote it, in which case `needsSpaceProbe` answered `null`
+  // (page it) and we reach here with the body in hand to say so either way.
   if (needsSpaceProbe(cand, facts) === false) return no("no_mentions_not_threaded");
 
-  const msg = lookupMessage(facts, channelId, cand.ids.messageId);
-
   // (5) An explicit @mention of my member id. The mention list is NOT in the
   //     chain payload; it comes from `messaging.history`, which hq ACLs to rooms
   //     I may read.
@@ -764,8 +795,16 @@ function resolveApproval(cand, me, facts, on) {
  * Prose-name matching, when the caller enabled it, always needs the body — so a
  * caller with `myNames` gets `null` rather than `false`.
  *
+ * A HUMAN-authored post with zero mentions and no thread is the shape of a
+ * broadcast ("everyone, status?"), and only the body can tell. So when
+ * `facts.memberKinds` PROVES the actor is a human the answer is `null` — page
+ * it — while an agent-authored one, or one whose author kind is unknown (the
+ * `member.list` read failed, or the surface is off so it was never made),
+ * keeps today's `false`. That is the cheapest correct thing: the extra history
+ * page is spent only on posts a person wrote, never on agent chatter.
+ *
  * @param {Candidate} cand
- * @param {{myNames?: string[]}} [facts]
+ * @param {{myNames?: string[], memberKinds?: Map<string,string>|null}} [facts]
  * @returns {boolean|null}
  */
 export function needsSpaceProbe(cand, facts = {}) {
@@ -774,9 +813,55 @@ export function needsSpaceProbe(cand, facts = {}) {
   if (h.mentionCount === undefined || h.threaded === undefined) return null;
   if (h.mentionCount > 0) return true;
   if (h.threaded) return true;
+  if (authorKindOf(facts, cand && cand.actor) === "HUMAN") return null;
   return false;
 }
 
+/**
+ * The org-directory kind ("HUMAN" | "AI_AGENT" | …) of a member id or slug, from
+ * the ONE `member.list` read `facts.mjs` makes per pull. `""` when unknown —
+ * and unknown is never treated as human.
+ *
+ * @param {{memberKinds?: Map<string,string>|null}} facts
+ * @param {unknown} id
+ * @returns {string}
+ */
+export function authorKindOf(facts, id) {
+  const kinds = facts && facts.memberKinds instanceof Map ? facts.memberKinds : null;
+  const key = id == null ? "" : String(id).trim();
+  if (!kinds || !key) return "";
+  return String(kinds.get(key) || kinds.get(key.toLowerCase()) || "").toUpperCase();
+}
+
+/**
+ * Conditions 1–3 of the broadcast rule (see broadcast.mjs), joined with the
+ * body test. `msg` is the hydrated history row — the body never enters the
+ * chain, so this can only ever be asked after paging.
+ *
+ * @param {Candidate} cand
+ * @param {object} msg the hydrated message row
+ * @param {string} channelId
+ * @param {Set<string>|null} members proven memberships (null == unknown)
+ * @param {import("./facts.mjs").Facts} facts
+ * @returns {boolean}
+ */
+export function isBroadcastFor(cand, msg, channelId, members, facts) {
+  if (!msg || !cand) return false;
+  // (2) a space I am a MEMBER of. `members` for a PUBLIC room is populated only
+  //     from hq's own `joined` flag, so visibility alone never qualifies.
+  if (!has(members, channelId)) return false;
+  // (3) not threaded — a thread reply keeps the thread rule.
+  if (msg.threadRootId || msg.thread_root_id) return false;
+  if (cand.hints && cand.hints.threaded === true) return false;
+  // A message that structurally @-names people is addressed to THEM.
+  if (Array.isArray(msg.mentions) && msg.mentions.length > 0) return false;
+  // (1) the author is a HUMAN — proven by the directory, never assumed.
+  const author = msg.authorId || msg.author || cand.actor;
+  if (authorKindOf(facts, author) !== "HUMAN") return false;
+  // (4) the body names the whole room.
+  return isBroadcast(msg.body ?? msg.text);
+}
+
 /** Find a hydrated message row in `facts.channelPages`. */
 export function lookupMessage(facts, channelId, messageId) {
   if (!(facts.channelPages instanceof Map) || !channelId || !messageId) return null;
@@ -847,6 +932,9 @@ export default {
   coordsOf,
   asSet,
   needsSpaceProbe,
+  authorKindOf,
+  isBroadcastFor,
+  isBroadcast,
   lookupMessage,
   matchesMyName,
   taskIdFromFileKey,

package/lib/org/inbound/facts.mjs

@@ -76,9 +76,11 @@ export const DEFAULT_LIMITS = Object.freeze({
  * @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 {Map<string,object>|null} fileAcl     fileId → {ownerId, shared, mentionsMe, kind}
  * @property {Set<string>|null} myEventIds        calendar events I own or attend (null == unreadable)
  * @property {Map<string,object>|null} myEvents   eventId → the calendar event DTO
+ * @property {Map<string,string>|null} memberKinds member id AND slug → "HUMAN"|"AI_AGENT" (null == not read / unreadable)
+ * @property {number|null} aiMemberCount          how many AI_AGENT members the org has (the roll-call respondent bound)
  * @property {string[]} degraded               names of facts that could not be read
  */
 
@@ -131,6 +133,8 @@ export async function resolveFacts(o = {}) {
     fileAcl: null,
     myEventIds: null,
     myEvents: null,
+    memberKinds: null,
+    aiMemberCount: null,
     degraded,
   };
   if (!io || candidates.length === 0) return facts;
@@ -185,6 +189,16 @@ export async function resolveFacts(o = {}) {
     }
   }
 
+  // ── 1b. Who is a HUMAN. A broadcast is only ever a human's ("everyone,
+  //      status?" from a peer agent is ambient), and the chain payload carries
+  //      no author kind — so the directory is the only proof. ONE `member.list`
+  //      per pull, and only when this pull holds a space post that the counts
+  //      alone cannot rule out. Unreadable ⇒ `memberKinds` stays null ⇒ nobody
+  //      is proven human ⇒ today's structural drop stands (logged, not silent).
+  if (families.has("messaging") && on("broadcast") && wantsMemberKinds(candidates, facts, me)) {
+    await resolveMemberKinds({ facts, io, log, degraded });
+  }
+
   // ── 2. Message pages: one per affected, VISIBLE channel. Public-space traffic
   //      that the redacted counts already prove uninteresting is skipped.
   if (families.has("messaging")) {
@@ -307,6 +321,67 @@ async function resolveCalendarFacts({ candidates, facts, io, log, degraded }) {
 // Step implementations
 // ---------------------------------------------------------------------------
 
+/**
+ * Does this batch hold a space post whose author kind could change the verdict?
+ * That is: a non-private-room message, in a space I am a MEMBER of, by someone
+ * other than me, with counts that would otherwise drop it (0 mentions, not
+ * threaded) or counts absent. Anything else never asks the directory.
+ *
+ * @param {import("./directedness.mjs").Candidate[]} candidates
+ * @param {Facts} facts
+ * @param {string} me
+ * @returns {boolean}
+ */
+export function wantsMemberKinds(candidates, facts, me) {
+  const members = facts.memberChannelIds;
+  if (!members) return false;
+  for (const cand of candidates) {
+    if (!cand || cand.family !== "messaging") continue;
+    const channelId = String((cand.ids && cand.ids.channelId) || "");
+    if (!channelId || !members.has(channelId)) continue;
+    const chan = facts.channels.get(channelId);
+    const kind = String((cand.ids && cand.ids.channelKind) || (chan && chan.kind) || "").toUpperCase();
+    if (PRIVATE_ROOM_KINDS.includes(kind)) continue;
+    if (me && String(cand.actor || "") === me) continue;
+    const h = cand.hints || {};
+    if (h.mentionCount > 0 || h.threaded === true) continue; // paged anyway; no kind needed
+    return true;
+  }
+  return false;
+}
+
+/**
+ * `member.list` → `facts.memberKinds` keyed by BOTH member id and slug (the
+ * chain's `actor` is documented as "member slug or api-key id" while history's
+ * `authorId` is the cuid; one map answers either) + `facts.aiMemberCount`.
+ * Org-scoped, read-only, the same directory every seat may already list.
+ */
+async function resolveMemberKinds({ facts, io, log, degraded }) {
+  const frame = await io.call("member.list", {});
+  if (!frame || frame.ok !== true) {
+    degraded.push("members");
+    log("warn", "[inbound] member.list unreadable — no author can be proven human this tick, so a human's roll-call in a space WILL be dropped as no_mentions_not_threaded");
+    return;
+  }
+  const kinds = new Map();
+  let ai = 0;
+  for (const m of arrayOf(resultOf(frame), "members")) {
+    if (!m) continue;
+    const kind = String(m.kind || "").toUpperCase();
+    if (!kind) continue;
+    const id = String(m.id || "");
+    const slug = String(m.slug || "");
+    if (id) kinds.set(id, kind);
+    if (slug) {
+      kinds.set(slug, kind);
+      kinds.set(slug.toLowerCase(), kind);
+    }
+    if (kind === "AI_AGENT") ai += 1;
+  }
+  facts.memberKinds = kinds;
+  facts.aiMemberCount = ai;
+}
+
 /**
  * Fetch one `messaging.history` page per affected channel and fold it into
  * `facts.channelPages` + `facts.myThreadRootIds`.
@@ -347,8 +422,9 @@ async function pageChannels({ candidates, facts, io, limits, log, on }) {
       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;
+      // A space: paged only if it could be a mention, a thread reply or a
+      // human's broadcast to the room.
+      if (!on("mention") && !on("thread_reply") && !on("broadcast")) continue;
       if (needsSpaceProbe(cand, facts) === false) {
         skippedByCounts += 1;
         continue;
@@ -602,7 +678,9 @@ async function resolveFileFacts({ candidates, facts, io, limits, log, degraded }
     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 || "" };
+    // `kind` (DOC | SHEET | DECK | …) rides along so the doc hydrator can skip a
+    // `files.docRead` that hq would answer BAD_REQUEST for. One field, no read.
+    const entry = { ownerId, shared, permission, mentionsMe: false, name: file.name || "", kind: String(file.kind || "") };
 
     if (!shared && !(ownerId && ownerId === facts.me) && facts.myNames.length > 0) {
       const cf = await io.call("files.comments", { fileId, limit: 20 });