@cohortapp/agent-sdk 2.3.0

package/lib/org/messaging.mjs

@@ -0,0 +1,503 @@
+/**
+ * lib/org/messaging.mjs — the maestro seam for posting / @mentioning / calling
+ * ON Cohort (SP10).
+ *
+ * Why this exists
+ * ---------------
+ * The org protocol froze a `messaging.*` / `calling.*` surface (protocol.mjs)
+ * so a fleet of agents can participate in the org's OWN human messaging app —
+ * post a message, @mention a teammate, react, read channel history, and join /
+ * start a call — exactly as they already do on Slack/Telegram/WhatsApp. This
+ * module is the agent-side helper layer over that surface. It is to messaging
+ * what cost-sync.mjs is to cost.report: a thin, fail-open wrapper over
+ * lib/org/client.call/read that adds the cross-cutting policy + telemetry the
+ * raw RPC must not skip.
+ *
+ * Three invariants this layer enforces (and the raw client.call cannot):
+ *
+ *   1. EVERY outbound message runs lib/comms/send-gate.screenOutbound BEFORE the
+ *      messaging.send RPC. A blocked message (banned phrase / AI-disclosure /
+ *      information barrier / off-allowlist) is NOT sent — sendMessage returns a
+ *      blocked frame and never touches the wire. This closes the same gap the
+ *      send-gate closes for the channel adapters: the org messaging path is just
+ *      another real send path, so it must run the one shared chokepoint.
+ *
+ *   2. After a successful send we emit `afterSend` on the typed hook bus
+ *      (lib/hooks/bus.getHookBus) so audit/delivery-receipt subscribers observe
+ *      the org messaging path like every other send. afterSend is observe-only
+ *      (never cancellable) — the cancellable gate already ran in step 1.
+ *
+ *   3. We attribute the send to the cost ledger with `source: "messaging"` so the
+ *      org rollup can see how much messaging the agent does. A plain message send
+ *      is a ZERO-token, zero-LLM action, so the attributed row carries 0 spend —
+ *      it is a COUNT/attribution row, not an LLM-spend row (the G16 honesty line
+ *      stays intact: messaging is not an LLM-in-the-loop cost).
+ *
+ * Wire shape (frozen in protocol.mjs):
+ *   messaging.send / .react / .edit  — POST /v1/messaging.* (Bearer + x-org-protocol,
+ *                                      x-idempotency-key on send — idempotent on the
+ *                                      client-supplied message id).
+ *   messaging.history / .channels    — POST /v1/messaging.* (read scope, non-mutating).
+ *   calling.start / .join / .invite / .end — POST /v1/calling.* (calling.write scope).
+ *
+ * Fail-open by design: a disabled/unreachable org server yields an error frame,
+ * never a throw — so the messaging path can never take down the agent. The
+ * send-gate, hook bus, and ledger are all injectable for deterministic tests.
+ *
+ * Node builtins + the existing maestro libs only. ESM.
+ *
+ * @module lib/org/messaging
+ */
+
+"use strict";
+
+import { isEnabled, configFromAgent, call, read } from "./client.mjs";
+import { errFrame } from "./protocol.mjs";
+import { screenOutbound } from "../comms/send-gate.mjs";
+import { getHookBus } from "../hooks/bus.mjs";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the {base, token} the RPC needs from an agent cfg, or null when the
+ * org integration is disabled / unconfigured (so the caller fails open).
+ * @param {object} cfg
+ * @returns {{base:string, token:string}|null}
+ */
+function resolveOrg(cfg) {
+  if (!isEnabled(cfg)) return null;
+  const c = configFromAgent(cfg);
+  if (!c.base) return null;
+  return { base: c.base, token: c.token };
+}
+
+/** A best-effort agent id for ledger attribution (never throws). */
+function agentIdOf(cfg) {
+  const n = (cfg && cfg.org && cfg.org.cohort) || {};
+  return n.agentId || n.id || (cfg && cfg.identity && cfg.identity.id) || (cfg && cfg.agentId) || null;
+}
+
+/**
+ * Attribute a messaging action to the cost ledger with source="messaging".
+ * A message send is zero-token / zero-LLM, so the attributed row carries 0
+ * spend — it's a COUNT row, not an LLM-spend row. Fail-open and fully optional:
+ * the write is best-effort (writeLedgerRow never throws) and entirely skipped
+ * when an injected `ledger:null` opts out (tests / read-only callers).
+ *
+ * @param {object} o - { cfg, agentRoot, action, channel }
+ * @param {object} deps - { ledgerImpl?, catalog? } injectable for tests
+ */
+async function attributeMessaging(o, deps = {}) {
+  // Opt-out: an explicit `ledgerImpl: null` (or false) disables attribution.
+  if (Object.prototype.hasOwnProperty.call(deps, "ledgerImpl") && !deps.ledgerImpl) return;
+  try {
+    const writeLedgerRow =
+      deps.ledgerImpl || (await import("../model-router/ledger.mjs")).writeLedgerRow;
+    // No model is involved in a plain message send, so the catalog is empty and
+    // the row prices to $0 (estimated_usd:0). The attribution is the `source`.
+    writeLedgerRow(
+      deps.catalog || {},
+      {
+        agent: agentIdOf(o.cfg),
+        source: "messaging",
+        task_class: o.action || "messaging.send",
+        lane: o.channel || null,
+        inputTokens: 0,
+        outputTokens: 0,
+        exitReason: "ok",
+      },
+      { agentRoot: o.agentRoot, now: deps.now }
+    );
+  } catch {
+    /* fail-open: attribution must never block or break a send */
+  }
+}
+
+/** Emit afterSend on the hook bus (observe-only; never throws). */
+async function emitAfterSend(ctx, deps = {}) {
+  try {
+    const bus = deps.hookBus || getHookBus();
+    await bus.emit("afterSend", ctx);
+  } catch {
+    /* fail-open: a broken subscriber must never break the send */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Messaging — send / react / history / channels
+// ---------------------------------------------------------------------------
+
+/**
+ * Post a message to an org channel ON Cohort (messaging.send). THE outbound
+ * primitive — it runs the shared send-gate BEFORE the wire, emits afterSend on
+ * success, and attributes a source="messaging" ledger row.
+ *
+ * Flow:
+ *   1. resolve org enrollment (disabled ⇒ fail-open error frame, no send).
+ *   2. screenOutbound({channel, recipient:channel, text:body}) — a BLOCK returns
+ *      a frame `{ok:false, error:{code:"FORBIDDEN_SCOPE"|"BAD_REQUEST", message}}`
+ *      and the message is NEVER sent (no client.call).
+ *   3. messaging.send RPC (Bearer + x-org-protocol + x-idempotency-key from the
+ *      client-supplied message id, so a retried send dedupes server-side).
+ *   4. on ok: emit afterSend + attribute the ledger row.
+ *
+ * @param {object} params
+ * @param {string} params.channel       org channel id to post into
+ * @param {string} params.body          the message text
+ * @param {string[]} [params.mentions]  agent/user ids to @mention
+ * @param {string} [params.idempotencyId] stable client message id (idempotency key)
+ * @param {string} [params.threadId]    reply within a thread
+ * @param {object} o - {
+ *   cfg, agentRoot?, fetchImpl?,
+ *   jurisdiction?, firstContact?, internalDomains?, allowlist?,  // → send-gate
+ *   gateImpl?, hookBus?, ledgerImpl?, catalog?, now?             // → test seams
+ * }
+ * @returns {Promise<object>} res frame {ok:true,result}|{ok:false,error,blocked?}
+ */
+export async function sendMessage(params = {}, o = {}) {
+  const channel = params.channel != null ? String(params.channel) : "";
+  const body = params.body != null ? String(params.body) : "";
+  if (!channel) return errFrame("BAD_REQUEST", "missing channel");
+  if (!body) return errFrame("BAD_REQUEST", "missing body");
+
+  // (2) The one shared outbound chokepoint — runs BEFORE the wire.
+  const gate = o.gateImpl || screenOutbound;
+  let screened;
+  try {
+    screened = await gate({
+      channel: "cohort",
+      recipient: channel,
+      text: body,
+      agentRoot: o.agentRoot || process.cwd(),
+      jurisdiction: o.jurisdiction,
+      firstContact: o.firstContact !== undefined ? o.firstContact : false,
+      internalDomains: o.internalDomains || [],
+      allowlist: o.allowlist,
+    });
+  } catch (err) {
+    // A gate fault is fail-CLOSED for an outbound message: never send when we
+    // could not screen it (mirrors the send-gate's own external posture).
+    return { ...errFrame("INTERNAL", `send-gate error: ${err && err.message ? err.message : String(err)}`), blocked: true };
+  }
+  if (!screened || !screened.allow) {
+    // A blocked message is NOT sent. Surface the policy reason; mark blocked so
+    // the caller can distinguish a policy refusal from a transport failure.
+    return { ...errFrame("FORBIDDEN_SCOPE", screened && screened.reason ? screened.reason : "blocked by send-gate"), blocked: true };
+  }
+  const text = screened.redactedText != null ? screened.redactedText : body;
+
+  // (1) org resolution AFTER the gate so a policy violation is caught even when
+  // the org is disabled (defence: the gate is the one chokepoint).
+  const org = resolveOrg(o.cfg);
+  if (!org) return errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+
+  // (3) the wire — idempotent on the client message id.
+  const idempotencyId = params.idempotencyId != null ? String(params.idempotencyId) : "";
+  const wire = {
+    channel,
+    body: text,
+    ...(Array.isArray(params.mentions) && params.mentions.length ? { mentions: params.mentions.map(String) } : {}),
+    ...(params.threadId != null ? { threadId: String(params.threadId) } : {}),
+    ...(idempotencyId ? { id: idempotencyId } : {}),
+  };
+  const frame = await call("messaging.send", wire, {
+    base: org.base,
+    token: org.token,
+    idempotencyKey: idempotencyId || undefined,
+    fetchImpl: o.fetchImpl,
+  });
+
+  // (4) on success: observe-only afterSend + source="messaging" attribution.
+  if (frame && frame.ok) {
+    await emitAfterSend(
+      { channel: "cohort", recipient: channel, text, mentions: wire.mentions || [], result: frame.result, source: "messaging" },
+      o
+    );
+    await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: "messaging.send", channel }, o);
+  }
+  return frame;
+}
+
+/**
+ * React to a message ON Cohort (messaging.react). A reaction is not a content
+ * send, so it does NOT run the banned-phrase send-gate (there is no prose to
+ * screen) — but it is still attributed (source="messaging") and fail-open.
+ * @param {object} params - { channel, messageId, emoji }
+ * @param {object} o - { cfg, agentRoot?, fetchImpl?, ... test seams }
+ * @returns {Promise<object>} res frame
+ */
+export async function reactMessage(params = {}, o = {}) {
+  const channel = params.channel != null ? String(params.channel) : "";
+  const messageId = params.messageId != null ? String(params.messageId) : "";
+  const emoji = params.emoji != null ? String(params.emoji) : "";
+  if (!channel || !messageId || !emoji) return errFrame("BAD_REQUEST", "missing channel, messageId, or emoji");
+
+  const org = resolveOrg(o.cfg);
+  if (!org) return errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+
+  const frame = await call("messaging.react", { channel, messageId, emoji }, {
+    base: org.base,
+    token: org.token,
+    idempotencyKey: o.idempotencyKey,
+    fetchImpl: o.fetchImpl,
+  });
+  if (frame && frame.ok) {
+    await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: "messaging.react", channel }, o);
+  }
+  return frame;
+}
+
+/**
+ * Fetch recent channel history ON Cohort (messaging.history). Read-scope,
+ * non-mutating. Returns the messages array, or [] on any failure (fail-open).
+ * @param {object} params - { channel, since?, cursor?, limit? }
+ * @param {object} o - { cfg, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function fetchHistory(params = {}, o = {}) {
+  const channel = params.channel != null ? String(params.channel) : "";
+  if (!channel) return [];
+  const org = resolveOrg(o.cfg);
+  if (!org) return [];
+
+  const frame = await call(
+    "messaging.history",
+    {
+      channel,
+      ...(params.since != null ? { since: params.since } : {}),
+      ...(params.cursor != null ? { cursor: params.cursor } : {}),
+      ...(Number.isFinite(params.limit) ? { limit: params.limit } : {}),
+    },
+    { base: org.base, token: org.token, fetchImpl: o.fetchImpl }
+  );
+  if (!frame || !frame.ok || !frame.result) return [];
+  const r = frame.result;
+  if (Array.isArray(r)) return r;
+  if (Array.isArray(r.messages)) return r.messages;
+  if (Array.isArray(r.items)) return r.items;
+  return [];
+}
+
+/**
+ * List the org channels visible to this agent (messaging.channels). Read-scope.
+ * Returns the channels array, or [] on any failure (fail-open).
+ * @param {object} o - { cfg, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function listChannels(o = {}) {
+  const org = resolveOrg(o.cfg);
+  if (!org) return [];
+  const frame = await call("messaging.channels", {}, { base: org.base, token: org.token, fetchImpl: o.fetchImpl });
+  if (!frame || !frame.ok || !frame.result) return [];
+  const r = frame.result;
+  if (Array.isArray(r)) return r;
+  if (Array.isArray(r.channels)) return r.channels;
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Calling — start / join
+// ---------------------------------------------------------------------------
+
+/**
+ * Start a call ON Cohort (calling.start). calling.write scope. Attributed
+ * (source="messaging") and fail-open. There is no prose to screen, so the
+ * banned-phrase send-gate does not run — but an `invitees` list is passed
+ * through so the server can ring participants.
+ * @param {object} params - { channel?, invitees?, topic?, idempotencyId? }
+ * @param {object} o - { cfg, agentRoot?, fetchImpl?, ... test seams }
+ * @returns {Promise<object>} res frame {ok:true,result:{callId,...}}|{ok:false,error}
+ */
+export async function initiateCall(params = {}, o = {}) {
+  const org = resolveOrg(o.cfg);
+  if (!org) return errFrame("BAD_REQUEST", "org calling disabled or unconfigured");
+  const idempotencyId = params.idempotencyId != null ? String(params.idempotencyId) : "";
+  const wire = {
+    ...(params.channel != null ? { channel: String(params.channel) } : {}),
+    ...(Array.isArray(params.invitees) && params.invitees.length ? { invitees: params.invitees.map(String) } : {}),
+    ...(params.topic != null ? { topic: String(params.topic) } : {}),
+    ...(idempotencyId ? { id: idempotencyId } : {}),
+  };
+  const frame = await call("calling.start", wire, {
+    base: org.base,
+    token: org.token,
+    idempotencyKey: idempotencyId || undefined,
+    fetchImpl: o.fetchImpl,
+  });
+  if (frame && frame.ok) {
+    await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: "calling.start", channel: wire.channel || null }, o);
+  }
+  return frame;
+}
+
+/**
+ * Join an existing call ON Cohort (calling.join). calling.write scope.
+ * Attributed (source="messaging") and fail-open.
+ * @param {object} params - { callId }
+ * @param {object} o - { cfg, agentRoot?, fetchImpl?, ... test seams }
+ * @returns {Promise<object>} res frame
+ */
+export async function joinCall(params = {}, o = {}) {
+  const callId = params.callId != null ? String(params.callId) : "";
+  if (!callId) return errFrame("BAD_REQUEST", "missing callId");
+  const org = resolveOrg(o.cfg);
+  if (!org) return errFrame("BAD_REQUEST", "org calling disabled or unconfigured");
+  const frame = await call("calling.join", { callId }, {
+    base: org.base,
+    token: org.token,
+    idempotencyKey: o.idempotencyKey,
+    fetchImpl: o.fetchImpl,
+  });
+  if (frame && frame.ok) {
+    await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: "calling.join", channel: callId }, o);
+  }
+  return frame;
+}
+
+// ---------------------------------------------------------------------------
+// Inbound — pull new messages / @mentions / call-invites for THIS agent
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull org events newer than `cursor` that are DIRECTED AT this agent — new
+ * messages in a channel it is in, @mentions, and call-invites — and project them
+ * onto the unified MessageEvent contract so the existing daemon inbox pipeline
+ * (classifier → dispatcher → responder) reacts to them like any other channel.
+ *
+ * This is the read leg the inbound cadence handler drives. It is pure over the
+ * injected fetch: the handler decides whether to escalate and where to write the
+ * resulting items. The cursor advance is the caller's responsibility (returned
+ * here as `nextCursor`) so a crash never loses or double-delivers events.
+ *
+ * Mention detection: an event whose `mentions[]` (or `mentioned_agents[]`)
+ * includes this agent's id, OR a DM-kind event addressed to it, counts as
+ * directed. We do NOT include the agent's own outbound echoes (`from` == self).
+ *
+ * @param {object} o - { cfg, agentId?, cursor?, limit?, fetchImpl? }
+ * @returns {Promise<{events:object[], nextCursor:(number|string|null)}>}
+ */
+export async function pullInbound(o = {}) {
+  const org = resolveOrg(o.cfg);
+  if (!org) return { events: [], nextCursor: o.cursor ?? null };
+  const me = o.agentId || agentIdOf(o.cfg);
+
+  const cursor = o.cursor ?? 0;
+  const limit = Number.isFinite(o.limit) ? o.limit : 200;
+  const path = `events?cursor=${encodeURIComponent(cursor)}&limit=${encodeURIComponent(limit)}&family=messaging,calling`;
+  const r = await read(path, { base: org.base, token: org.token, fetchImpl: o.fetchImpl });
+  if (!r.ok || !r.payload) return { events: [], nextCursor: cursor };
+
+  const raw = Array.isArray(r.payload) ? r.payload : (Array.isArray(r.payload.events) ? r.payload.events : []);
+  let maxSeq = cursor;
+  const events = [];
+  for (const ev of raw) {
+    if (ev && (ev.seq != null) && Number.isFinite(Number(ev.seq))) {
+      maxSeq = Math.max(Number(maxSeq) || 0, Number(ev.seq));
+    }
+    const directed = isDirectedAtAgent(ev, me);
+    if (!directed) continue;
+    events.push(toMessageEvent(ev, me));
+  }
+  return { events, nextCursor: raw.length ? maxSeq : cursor };
+}
+
+/**
+ * Decide whether an org event is directed at this agent (an inbound it should
+ * react to) vs ambient chatter / its own echo. Pure.
+ * @param {object} ev @param {string} me agent id
+ * @returns {boolean}
+ */
+export function isDirectedAtAgent(ev, me) {
+  if (!ev || typeof ev !== "object") return false;
+  const family = ev.family || (ev.kind ? String(ev.kind).split(".")[0] : "");
+  if (family && family !== "messaging" && family !== "calling") return false;
+  const p = ev.payload || ev;
+  const from = String(p.from || p.author || p.sender || (ev.actor || "")).trim();
+  if (me && from && from === String(me)) return false; // ignore own echoes
+
+  const mentions = []
+    .concat(Array.isArray(p.mentions) ? p.mentions : [])
+    .concat(Array.isArray(p.mentioned_agents) ? p.mentioned_agents : [])
+    .map((m) => String(m));
+  if (me && mentions.includes(String(me))) return true;
+
+  // A DM / direct call-invite addressed to this agent is directed even with no
+  // explicit @mention.
+  const to = []
+    .concat(Array.isArray(p.to) ? p.to : (p.to != null ? [p.to] : []))
+    .concat(Array.isArray(p.invitees) ? p.invitees : [])
+    .map((t) => String(t));
+  if (me && to.includes(String(me))) return true;
+
+  const kind = String(p.kind || ev.kind || "").toLowerCase();
+  if (kind.includes("dm") || kind.includes("invite") || family === "calling") {
+    return !me || to.includes(String(me)) || mentions.includes(String(me)) || to.length === 0;
+  }
+  return false;
+}
+
+/**
+ * Project an org messaging/calling event onto the unified MessageEvent contract
+ * (lib/channels/contract.MessageEvent) so eventToInboxItem can serialise it into
+ * the legacy inbox pipeline unchanged. Pure.
+ * @param {object} ev @param {string} me
+ * @returns {object} MessageEvent
+ */
+export function toMessageEvent(ev, me) {
+  const p = (ev && ev.payload) || ev || {};
+  const family = ev.family || (ev.kind ? String(ev.kind).split(".")[0] : "messaging");
+  const isCall = family === "calling";
+  const channelId = String(p.channel || p.channelId || p.callId || "");
+  const messageId = String(p.id || p.messageId || ev.entity_id || ev.seq || "");
+  const fromId = String(p.from || p.author || p.sender || ev.actor || "");
+  const text = isCall
+    ? (p.topic ? `Call invite: ${p.topic}` : "Call invite")
+    : (p.body != null ? String(p.body) : (p.text != null ? String(p.text) : ""));
+
+  return {
+    channel: "cohort",
+    message_id: messageId,
+    id: messageId ? `cohort-${messageId}` : undefined,
+    thread_id: p.threadId != null ? String(p.threadId) : "",
+    from: { id: fromId, name: String(p.fromName || p.authorName || fromId) },
+    text,
+    timestamp: ev.at || p.at || new Date().toISOString(),
+    kind: isCall ? "call" : "message",
+    subject: isCall ? "Cohort call invite" : "Cohort message",
+    channel_id: channelId,
+    channel_label: String(p.channelName || channelId || "cohort"),
+    sender: String(p.fromName || fromId),
+    priority_signals: {
+      from_ceo: false,
+      tagged_urgent: false,
+      contains_deadline: false,
+      mentions_agent: !!(me && []
+        .concat(Array.isArray(p.mentions) ? p.mentions : [])
+        .concat(Array.isArray(p.mentioned_agents) ? p.mentioned_agents : [])
+        .map(String)
+        .includes(String(me))),
+    },
+    raw_ref: `cohort:${channelId}:${messageId}`,
+    ingest_source: "cohort",
+    source: {
+      channel: "cohort",
+      chatId: channelId,
+      threadRef: p.threadId != null ? String(p.threadId) : undefined,
+      userScope: isCall ? "channel" : (channelId ? "channel" : "dm"),
+    },
+  };
+}
+
+export default {
+  sendMessage,
+  reactMessage,
+  fetchHistory,
+  listChannels,
+  initiateCall,
+  joinCall,
+  pullInbound,
+  isDirectedAtAgent,
+  toMessageEvent,
+};