@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/execution/intake.mjs

@@ -0,0 +1,581 @@
+/**
+ * lib/execution/intake.mjs — normalise ANY inbound artefact into `{candidate, verdict}`.
+ *
+ * `disposition.decide` needs two structured inputs: a Candidate (what happened,
+ * in chain coordinates) and a directedness verdict (is it mine, and on which
+ * surface). `lib/org/inbound/` produces exactly that pair — but only for org
+ * chain events, and only in memory. Four other things reach an agent every day
+ * and none of them arrives as that pair:
+ *
+ *   1. **An inbox item on disk.** `eventToInboxItem` flattens a MessageEvent for
+ *      the YAML writer and DROPS unknown keys, which is where the projection's
+ *      `ev.cohort` provenance block dies. Everything the daemon reads back off
+ *      `state/inbox/**` has therefore already lost its surface and its reason.
+ *      They are recoverable — `raw_ref` is `cohort:<surface>:<entityId>:<seq>`
+ *      and survives the flattening — but somebody has to do the recovering.
+ *
+ *   2. **A channel-adapter event.** Slack, Telegram, SMS, WhatsApp, voice and the
+ *      org-mail adapter write inbox items directly. They never touch
+ *      `directedness.resolveDirected`, so nothing has ever asked whether a
+ *      message in a busy Slack channel was actually addressed to this agent.
+ *      That is the "responds to everything" failure mode, on the surfaces where
+ *      the volume actually is.
+ *
+ *   3. **A local alert.** `lib/diagnostics/alerts.mjs` and `lib/telemetry/alerts.mjs`
+ *      derive `{id, severity, detail}` records. `emitAlerts` hands them to a sink
+ *      and that is the end of them — an alert has never been able to become work.
+ *
+ *   4. **A raw chain event** with no join done yet (an SSE frame, a replay).
+ *
+ * This module is the one door. Every path returns the SAME shape, is TOTAL (no
+ * input throws, no input returns undefined), and reports what it had to guess in
+ * `degraded[]` — because a reconstructed verdict is a weaker fact than a
+ * resolved one and the journal must be able to tell them apart.
+ *
+ * PURE. No disk, no network, no clock beyond an injectable `now`. The one import
+ * with behaviour is `directedness.mjs`, reused rather than re-implemented — that
+ * module is the org join and this module must never grow a second copy of it.
+ *
+ * @module lib/execution/intake
+ */
+
+"use strict";
+
+import { classifyEvent, resolveDirected } from "../org/inbound/directedness.mjs";
+import { SURFACES } from "../org/inbound/surfaces.mjs";
+import { EXTENDED_SURFACE_POLICY } from "./surface-policy.mjs";
+
+/** Where a normalised pair came from. Stamped on the result for the journal. */
+export const INTAKE_ORIGINS = Object.freeze([
+  "pair",
+  "message_event",
+  "inbox_item",
+  "channel_event",
+  "alert",
+  "raw_event",
+]);
+
+/**
+ * surface → hq chain family. `dedupeKey` and `threadKey` are built from
+ * `family`, so a surface with the wrong family silently shares a key space with
+ * another one. Extended surfaces use their own protocol family name where one
+ * exists (`calendar`) and their surface name where it does not (`alert`).
+ */
+export const SURFACE_FAMILY = Object.freeze({
+  dm: "messaging",
+  mention: "messaging",
+  thread_reply: "messaging",
+  call: "calling",
+  task_assigned: "board",
+  task_comment: "board",
+  file_comment: "file",
+  doc_comment: "files",
+  approval: "approval",
+  decision: "decision",
+  escalation: "escalation",
+  handoff: "handoff",
+  email: "email",
+  calendar: "calendar",
+  alert: "alert",
+  mandate: "mandate",
+});
+
+/** surface → coarse topic, taken from the inbound table where it defines one. */
+export const SURFACE_TOPIC = Object.freeze({
+  ...Object.fromEntries(Object.entries(SURFACES).map(([name, def]) => [name, def.topic])),
+  calendar: "calendar",
+  alert: "alert",
+  mandate: "mandate",
+});
+
+/**
+ * MessageEvent `kind` → surface, for items whose `raw_ref` is missing or
+ * unparseable. Lossy in one place and knowingly so: the projection maps BOTH
+ * `file_comment` and `doc_comment` onto kind `file_comment`, so a kind-only
+ * reconstruction lands on `file_comment`. Their policy rows are identical, so
+ * the disposition is the same either way; only the label in the journal differs,
+ * and `degraded[]` records that it was inferred.
+ */
+export const KIND_SURFACE = Object.freeze({
+  message: "dm",
+  mention: "mention",
+  thread_reply: "thread_reply",
+  call: "call",
+  voice_note: "dm",
+  task_assigned: "task_assigned",
+  task_comment: "task_comment",
+  file_comment: "file_comment",
+  approval: "approval",
+  decision: "decision",
+  escalation: "escalation",
+  handoff: "handoff",
+  email: "email",
+  calendar: "calendar",
+  mandate: "mandate",
+  alert: "alert",
+});
+
+/**
+ * The directedness reason to reconstruct per surface when the real one was lost.
+ *
+ * This is only ever applied to an item that ALREADY passed the join — an org
+ * inbox item exists because `pullWideInbound` decided it was directed and wrote
+ * it. So reconstructing `directed:true` is sound; what is genuinely unknown is
+ * WHICH rule fired, and the reason only feeds the T0/T1 tier. The values below
+ * are the reason that surface is normally delivered for. `.mentions_agent` on
+ * the item overrides with `named` where it is set, which is the one signal the
+ * flattening does preserve.
+ */
+export const RECONSTRUCTED_REASON = Object.freeze({
+  dm: "dm",
+  mention: "mention",
+  thread_reply: "thread",
+  call: "invited",
+  task_assigned: "assignee",
+  task_comment: "owner",
+  file_comment: "shared",
+  doc_comment: "shared",
+  approval: "approver",
+  decision: "proposer",
+  escalation: "waiting_on",
+  handoff: "direct",
+  email: "direct",
+  calendar: "attendee",
+  mandate: "direct",
+  alert: "direct",
+});
+
+/** Alert severities that are worth waking an agent for. Anything else is noise. */
+export const ACTIONABLE_SEVERITIES = Object.freeze(["critical", "warning", "warn", "error"]);
+
+/** Services whose inbound is mail, not chat. */
+const MAIL_SERVICES = Object.freeze(["orgmail", "gmail", "email", "imap", "smtp"]);
+
+/** Blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/** True for a plain object. */
+function isObj(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** A surface name this layer has a policy for (org table or extended table). */
+export function isKnownSurface(name) {
+  const k = s(name);
+  return (
+    Object.prototype.hasOwnProperty.call(SURFACES, k) ||
+    Object.prototype.hasOwnProperty.call(EXTENDED_SURFACE_POLICY, k)
+  );
+}
+
+/**
+ * Parse the projection's `raw_ref`: `cohort:<surface>:<entityId>:<seq>`.
+ *
+ * Tolerant of an entity id containing colons (it splits from BOTH ends), and
+ * returns null for the legacy `<channel>:<chatId>:<messageId>` form a channel
+ * adapter writes — that one is handled by `fromChannelEvent`.
+ *
+ * @param {string} raw
+ * @returns {{surface:string, entityId:string, seq:string|null}|null}
+ */
+export function parseRawRef(raw) {
+  const str = s(raw);
+  if (!str.startsWith("cohort:")) return null;
+  const rest = str.slice("cohort:".length);
+  const firstColon = rest.indexOf(":");
+  if (firstColon < 0) return null;
+  const surface = rest.slice(0, firstColon);
+  if (!isKnownSurface(surface)) return null;
+  const tail = rest.slice(firstColon + 1);
+  const lastColon = tail.lastIndexOf(":");
+  if (lastColon < 0) return { surface, entityId: tail, seq: null };
+  return {
+    surface,
+    entityId: tail.slice(0, lastColon),
+    seq: tail.slice(lastColon + 1) || null,
+  };
+}
+
+/** Assemble a normalised intake result. Internal; every path funnels through it. */
+function out(origin, candidate, verdict, degraded, why) {
+  return {
+    origin,
+    candidate: candidate || null,
+    verdict: verdict || null,
+    degraded: degraded.slice(),
+    why: why.slice(),
+  };
+}
+
+/** A verdict that says "not mine", with the surfaces it might plausibly have been. */
+function undirected(reason) {
+  return { directed: false, reason: s(reason) || "not_directed", surface: null };
+}
+
+/**
+ * Build a Candidate from flat inbox-item fields. Shared by the org and channel
+ * paths so the two cannot drift into producing different key spaces for the same
+ * conversation.
+ */
+function candidateFrom(o) {
+  return {
+    seq: o.seq ?? null,
+    family: s(o.family) || "?",
+    kind: s(o.kind) || "?",
+    entityId: o.entityId == null ? null : s(o.entityId),
+    actor: s(o.actor),
+    at: s(o.at),
+    topic: s(o.topic),
+    surfaces: Array.isArray(o.surfaces) ? o.surfaces.slice() : [],
+    ids: isObj(o.ids) ? { ...o.ids } : {},
+    directTo: Array.isArray(o.directTo) ? o.directTo.map(String) : [],
+    payload: isObj(o.payload) ? o.payload : {},
+  };
+}
+
+/**
+ * Pass through a pair the inbound layer already produced. The only path with no
+ * reconstruction at all, and therefore the one to prefer everywhere it is
+ * available (i.e. in-process, at pull time).
+ */
+export function fromPair(input) {
+  const why = ["pair supplied by the inbound layer — no reconstruction needed"];
+  return out("pair", input.candidate, input.verdict, [], why);
+}
+
+/**
+ * Rebuild the pair from a projected MessageEvent — the shape
+ * `lib/org/inbound/project.toMessageEvent` returns, BEFORE `eventToInboxItem`
+ * flattens it. Its `ev.cohort` block carries surface, reason, family, kind, seq
+ * and entity id verbatim, so this path is lossless too.
+ */
+export function fromMessageEvent(ev, o = {}) {
+  const why = [];
+  const c = isObj(ev.cohort) ? ev.cohort : {};
+  const surface = s(c.surface);
+  if (!isKnownSurface(surface)) {
+    why.push(`projected event names surface "${surface || "(none)"}" which has no policy row`);
+    return out("message_event", null, undirected("unknown_surface"), ["unknown_surface"], why);
+  }
+  const ids = {};
+  if (ev.channel_id) ids.channelId = s(ev.channel_id);
+  if (ev.thread_id) ids.threadId = s(ev.thread_id);
+  if (ev.message_id) ids.messageId = s(ev.message_id);
+  if (c.entity_id) ids.entityId = s(c.entity_id);
+
+  why.push(`projected MessageEvent carries full provenance: ${surface} via ${s(c.reason)}`);
+  const candidate = candidateFrom({
+    seq: c.seq ?? null,
+    family: s(c.family) || SURFACE_FAMILY[surface],
+    kind: s(c.event_kind) || s(ev.kind),
+    entityId: c.entity_id ?? ev.message_id ?? null,
+    actor: s(ev.from && ev.from.id) || s(ev.sender),
+    at: s(ev.timestamp) || s(o.now),
+    topic: s(c.topic) || SURFACE_TOPIC[surface],
+    surfaces: [surface],
+    ids,
+    directTo: s(c.me) ? [s(c.me)] : [],
+    payload: {},
+  });
+  return out("message_event", candidate, { directed: true, surface, reason: s(c.reason) || RECONSTRUCTED_REASON[surface] }, [], why);
+}
+
+/**
+ * Rebuild the pair from an ORG inbox item read back off disk.
+ *
+ * The item exists BECAUSE the join already said it was directed — `pullWideInbound`
+ * drops everything else before projection. So this path reconstructs
+ * `directed:true` and says so in `degraded[]`; what it cannot recover is which
+ * rule fired, and the tier that implies.
+ */
+export function fromInboxItem(item, o = {}) {
+  const why = [];
+  const degraded = [];
+  const ref = parseRawRef(item.raw_ref);
+  let surface = ref ? ref.surface : null;
+
+  if (surface) {
+    why.push(`raw_ref names surface ${surface}`);
+  } else {
+    const kind = s(item.kind) || "message";
+    surface = KIND_SURFACE[kind] || null;
+    if (surface === "dm" && item.is_dm === false) {
+      // kind "message" is the DM projection, but a channel item that lost its
+      // raw_ref would land here too. `is_dm:false` is a positive assertion that
+      // it was not a DM, so honour it rather than forging one.
+      surface = "mention";
+      why.push(`kind "${kind}" with is_dm:false → treating as a space mention, not a DM`);
+    } else {
+      why.push(`no parseable raw_ref — inferring surface ${surface || "(none)"} from kind "${kind}"`);
+    }
+    degraded.push("surface_inferred_from_kind");
+  }
+
+  if (!isKnownSurface(surface)) {
+    why.push("could not establish a surface for this item");
+    return out("inbox_item", null, undirected("unknown_surface"), degraded.concat("unknown_surface"), why);
+  }
+
+  const mentions = !!(item.priority_signals && item.priority_signals.mentions_agent);
+  let reason = RECONSTRUCTED_REASON[surface] || "direct";
+  if (mentions && (reason === "thread" || reason === "shared" || reason === "owner")) {
+    // The one signal the flattening preserves, and it upgrades a lane-tier
+    // reason to a structural one — being named IS the strongest reason there is.
+    reason = "named";
+    why.push("priority_signals.mentions_agent → the item names me outright (T0)");
+  }
+  degraded.push(`verdict_reconstructed:${surface}`);
+  why.push(`org inbox item: reconstructing directed:true (it was written because the join said so), reason ${reason}`);
+
+  const ids = {};
+  if (item.channel_id) ids.channelId = s(item.channel_id);
+  if (item.thread_id) ids.threadId = s(item.thread_id);
+  if (ref && ref.entityId) ids.entityId = ref.entityId;
+  if (item.id) ids.messageId = s(item.id);
+
+  const candidate = candidateFrom({
+    seq: ref ? ref.seq : null,
+    family: SURFACE_FAMILY[surface],
+    kind: s(item.kind) || surface,
+    entityId: ref ? ref.entityId : s(item.id) || null,
+    actor: s(item.sender_id) || s(item.sender),
+    at: s(item.timestamp) || s(o.now),
+    topic: SURFACE_TOPIC[surface],
+    surfaces: [surface],
+    ids,
+    directTo: o.me ? [s(o.me)] : [],
+    payload: {},
+  });
+  return out("inbox_item", candidate, { directed: true, surface, reason }, degraded, why);
+}
+
+/**
+ * Establish directedness for a NON-org channel item (Slack, Telegram, SMS,
+ * WhatsApp, voice, org-mail).
+ *
+ * This is the path with no join behind it at all, so it is the one that has to
+ * be honest about the negative case. A message in a shared channel that neither
+ * names the agent nor sits in a thread it is part of is NOT directed — it gets
+ * an undirected verdict and the ladder parks or drops it. That is the entire
+ * difference between an agent that participates and one that interrupts.
+ */
+export function fromChannelEvent(item, o = {}) {
+  const why = [];
+  const degraded = [];
+  const service = s(item.service) || s(item.channel) || s(item.source) || "channel";
+  const kind = s(item.kind) || "message";
+  const mentions = !!(item.priority_signals && item.priority_signals.mentions_agent);
+  const isDm = item.is_dm === true || (item.is_private === true && s(item.channel_type) === "im");
+  const mail = MAIL_SERVICES.includes(service.toLowerCase());
+
+  let surface = null;
+  let reason = null;
+
+  if (mail) {
+    // Mail is addressed by construction: it arrived in this agent's mailbox.
+    surface = "email";
+    reason = "direct";
+    why.push(`${service} is a mailbox service — an item in it is addressed to me`);
+  } else if (kind === "call" || kind === "voice_note") {
+    surface = kind === "call" ? "call" : "dm";
+    reason = "invited";
+    why.push(`${service} ${kind} → ${surface}`);
+  } else if (isDm) {
+    surface = "dm";
+    reason = "dm";
+    why.push(`${service} private room → a DM is addressed to me by construction`);
+  } else if (mentions || kind === "mention") {
+    surface = "mention";
+    reason = "mention";
+    why.push(`${service} channel item names me`);
+  } else if (kind === "thread_reply" || (item.is_reply === true && s(item.thread_id))) {
+    // A reply in a thread. Whether the agent is IN that thread is a fact only
+    // the adapter has; without it this is a lane-tier claim at best.
+    surface = "thread_reply";
+    reason = "thread";
+    degraded.push("thread_membership_unverified");
+    why.push(`${service} thread reply — membership unverified, treating as lane tier`);
+  } else {
+    // THE ignore case, and by volume the common one on a chat platform.
+    why.push(
+      `${service} channel item does not name me, is not a DM and is not a reply in my thread → not directed`,
+    );
+    const candidate = channelCandidate(item, service, kind, ["mention", "thread_reply"], o);
+    return out("channel_event", candidate, undirected("ambient_channel"), degraded, why);
+  }
+
+  const candidate = channelCandidate(item, service, kind, [surface], o);
+  return out("channel_event", candidate, { directed: true, surface, reason }, degraded, why);
+}
+
+/** Candidate for a channel item. Family is the SERVICE, so key spaces stay separate. */
+function channelCandidate(item, service, kind, surfaces, o) {
+  const ids = {};
+  if (item.channel_id) ids.channelId = s(item.channel_id);
+  if (item.thread_id) ids.threadId = s(item.thread_id);
+  if (item.id) ids.messageId = s(item.id);
+  return candidateFrom({
+    seq: null,
+    family: service,
+    kind,
+    entityId: s(item.id) || null,
+    actor: s(item.sender_id) || s(item.sender),
+    at: s(item.timestamp) || s(o.now),
+    topic: SURFACE_TOPIC[surfaces[0]] || "message",
+    surfaces,
+    ids,
+    directTo: [],
+    payload: {},
+  });
+}
+
+/**
+ * Turn a derived alert (`{id, severity, detail}`) into a decidable event.
+ *
+ * Directed by construction — an alert about this agent is addressed to this
+ * agent — EXCEPT below the actionable severity floor. An `info` alert that woke
+ * a session would be the "responds to everything" failure in its purest form.
+ */
+export function fromAlert(alert, o = {}) {
+  const why = [];
+  const id = s(alert.id) || s(alert.code) || "alert";
+  const severity = s(alert.severity).toLowerCase();
+  const candidate = candidateFrom({
+    seq: null,
+    family: "alert",
+    kind: id,
+    entityId: id,
+    actor: "system",
+    at: s(alert.at) || s(o.now),
+    topic: "alert",
+    surfaces: ["alert"],
+    // The alert id is the thread: repeated firings of the SAME alert must
+    // collapse onto one chain, or a flapping check becomes a task storm.
+    ids: { alertId: id },
+    directTo: o.me ? [s(o.me)] : [],
+    payload: { severity, detail: s(alert.detail) },
+  });
+
+  if (!ACTIONABLE_SEVERITIES.includes(severity)) {
+    why.push(`alert ${id} is severity "${severity || "(none)"}" — below the actionable floor, record and move on`);
+    return out("alert", candidate, undirected("alert_below_threshold"), [], why);
+  }
+  why.push(`alert ${id} is ${severity} and is about this agent → directed`);
+  return out("alert", candidate, { directed: true, surface: "alert", reason: "direct" }, [], why);
+}
+
+/**
+ * Classify and join a RAW chain event. Reuses `directedness.mjs` rather than
+ * re-implementing it; the caller supplies whatever `facts` it has resolved.
+ *
+ * With no facts, only payload-named directedness can resolve — which is honest
+ * and is recorded, not hidden: a raw event joined without facts under-reports
+ * membership-based surfaces, and `degraded[]` says so.
+ */
+export function fromRawEvent(ev, o = {}) {
+  const why = [];
+  const degraded = [];
+  let candidate = null;
+  try {
+    candidate = classifyEvent(ev);
+  } catch (err) {
+    why.push(`classifier threw on this row: ${err && err.message ? err.message : String(err)}`);
+    return out("raw_event", null, undirected("classifier_error"), ["classifier_error"], why);
+  }
+  if (!candidate) {
+    why.push("raw event is not one of the families an agent is woken for");
+    return out("raw_event", null, undirected("not_classified"), [], why);
+  }
+  if (!isObj(o.facts)) {
+    degraded.push("joined_without_facts");
+    why.push("no facts supplied — only payload-named directedness can resolve on this event");
+  }
+  let verdict;
+  try {
+    verdict = resolveDirected(candidate, s(o.me), isObj(o.facts) ? o.facts : {}, o.opts || {});
+  } catch (err) {
+    why.push(`directedness join threw: ${err && err.message ? err.message : String(err)}`);
+    return out("raw_event", candidate, undirected("join_error"), degraded.concat("join_error"), why);
+  }
+  why.push(
+    verdict && verdict.directed
+      ? `join: directed on ${verdict.surface} via ${verdict.reason}`
+      : `join: not directed (${(verdict && verdict.reason) || "unknown"})`,
+  );
+  return out("raw_event", candidate, verdict, degraded, why);
+}
+
+/**
+ * Detect what `input` is and normalise it. TOTAL: every input, including null,
+ * a string, and a shape from a future version of some other module, produces a
+ * result object — never a throw and never `undefined`.
+ *
+ * Detection order is by decreasing certainty, so a richer shape is never
+ * demoted to a poorer reading of itself.
+ *
+ * @param {object} input
+ * @param {object} [o] { me, now, facts, opts }
+ * @returns {{origin:string, candidate:object|null, verdict:object|null, degraded:string[], why:string[]}}
+ */
+export function intake(input, o = {}) {
+  if (!isObj(input)) {
+    return out("raw_event", null, undirected("not_an_object"), ["not_an_object"], [
+      `intake received ${input === null ? "null" : typeof input} — nothing to decide`,
+    ]);
+  }
+  try {
+    // 1. Already joined.
+    if (isObj(input.candidate) && isObj(input.verdict)) return fromPair(input);
+    // 2. A projected MessageEvent (pre-flattening) — carries `cohort` provenance.
+    if (isObj(input.cohort) && input.cohort.surface) return fromMessageEvent(input, o);
+    // 3. A derived alert: `{id|code, severity}` and none of the item fields.
+    if ((input.id || input.code) && input.severity && input.content === undefined && input.text === undefined) {
+      return fromAlert(input, o);
+    }
+    // 4. A raw chain row: family/kind coordinates and no inbox-item shape.
+    if ((input.family || (typeof input.kind === "string" && input.kind.includes("."))) && input.content === undefined) {
+      return fromRawEvent(input, o);
+    }
+    // 5. An inbox item. Cohort-sourced ones keep their raw_ref provenance;
+    //    everything else is a channel adapter's and needs a real join.
+    const cohortSourced =
+      s(input.raw_ref).startsWith("cohort:") ||
+      s(input.service).toLowerCase() === "cohort" ||
+      s(input.source).toLowerCase() === "cohort" ||
+      s(input.ingest_source).toLowerCase() === "cohort";
+    if (cohortSourced) return fromInboxItem(input, o);
+    if (input.content !== undefined || input.text !== undefined || input.service || input.channel) {
+      return fromChannelEvent(input, o);
+    }
+    return out("raw_event", null, undirected("unrecognised_shape"), ["unrecognised_shape"], [
+      "intake could not recognise this object as an event, an item or an alert",
+    ]);
+  } catch (err) {
+    // NEVER SILENT, and never fatal: an intake bug must degrade one event, not
+    // take the sweep down. The reason string names the throw so it is greppable.
+    const msg = err && err.message ? err.message : String(err);
+    return out("raw_event", null, undirected("intake_error"), [`intake_error:${msg}`], [
+      `intake threw while normalising this input: ${msg}`,
+    ]);
+  }
+}
+
+export default {
+  intake,
+  fromPair,
+  fromMessageEvent,
+  fromInboxItem,
+  fromChannelEvent,
+  fromAlert,
+  fromRawEvent,
+  parseRawRef,
+  isKnownSurface,
+  INTAKE_ORIGINS,
+  SURFACE_FAMILY,
+  SURFACE_TOPIC,
+  KIND_SURFACE,
+  RECONSTRUCTED_REASON,
+  ACTIONABLE_SEVERITIES,
+};