@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/channels/orgmail/adapter.test.mjs

@@ -1,448 +0,0 @@
-/**
- * orgmail adapter tests — the workspace email channel over org RPC.
- *
- * The hq side is MOCKED the way the other adapter tests mock their provider
- * (telegram injects a fake grammY bot; here we inject a fake fetchImpl that
- * routes /api/v1/email.* to canned res frames) — no network, no timers left
- * running (supervise:false + injected interval fns; ticks driven by hand).
- *
- * Run: node --test lib/channels/orgmail/adapter.test.mjs
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  OrgMailAdapter,
-  createOrgMailChannel,
-  resolvePollMs,
-  htmlToText,
-  DEFAULT_POLL_MS,
-  DEGRADED_POLL_MS,
-  ORGMAIL_CAPABILITIES,
-} from "./adapter.mjs";
-import { getPlatform, isDaemonManagedPlatform } from "../contract.mjs";
-
-const ORG_CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "tok-1" } } };
-
-/**
- * A fake hq: routes the five email.* endpoints. `inboxPages` is a queue of
- * summary arrays (one per poll tick); `messages` maps id → full DTO.
- */
-function hqMock({ inboxPages = [[]], messages = {}, sendBody, markReadFails = false } = {}) {
-  const pages = [...inboxPages];
-  const calls = [];
-  const fn = async (url, init) => {
-    const u = String(url);
-    const body = init && init.body ? JSON.parse(init.body) : {};
-    calls.push({ url: u, body, headers: (init && init.headers) || {} });
-    const respond = (payload, status = 200, ok = true) => ({ ok, status, json: async () => payload, headers: { get: () => undefined } });
-    if (u.endsWith("/api/v1/email.inbox")) {
-      const page = pages.length ? pages.shift() : [];
-      return respond({ ok: true, result: { mailbox: { address: "astra@agents.example", status: "ACTIVE" }, messages: page, nextCursor: null } });
-    }
-    if (u.endsWith("/api/v1/email.message")) {
-      const dto = messages[body.id];
-      return dto ? respond({ ok: true, result: dto }) : respond({ ok: false, error: { code: "NOT_FOUND", message: "no row" } }, 404, false);
-    }
-    if (u.endsWith("/api/v1/email.markRead")) {
-      if (markReadFails) return respond({ ok: false, error: { code: "INTERNAL", message: "boom" } }, 500, false);
-      return respond({ ok: true, result: { updated: 1 } });
-    }
-    if (u.endsWith("/api/v1/email.send")) {
-      return respond(sendBody || { ok: true, result: { status: "queued", messageId: "out-1", threadId: body.threadId } });
-    }
-    return respond({ ok: false, error: { code: "NOT_FOUND", message: `unknown ${u}` } }, 404, false);
-  };
-  fn.calls = calls;
-  fn.callsTo = (suffix) => calls.filter((c) => c.url.endsWith(suffix));
-  return fn;
-}
-
-const DTO = (over = {}) => ({
-  id: "em-1",
-  threadId: "th-1",
-  direction: "INBOUND",
-  status: "RECEIVED",
-  from: "casey@customer.com",
-  to: ["astra@agents.example"],
-  subject: "Quick pricing question",
-  text: "How much for 50 seats?",
-  html: null,
-  receivedAt: "2026-07-21T01:02:03.000Z",
-  createdAt: "2026-07-21T01:02:04.000Z",
-  inReplyTo: null,
-  attachments: [{ id: "att-1", filename: "specs.pdf", contentType: "application/pdf", size: 1234 }],
-  ...over,
-});
-
-function makeAdapter(fetchImpl, over = {}) {
-  const intervals = [];
-  const a = new OrgMailAdapter({
-    agentRoot: "/tmp/orgmail-test",
-    orgConfig: ORG_CFG,
-    config: { orgmail: { enabled: true, poll_seconds: 45, mark_read: true, ...(over.gate || {}) } },
-    fetchImpl,
-    supervise: false,
-    sendGate: over.sendGate ?? false,
-    screenOutbound: over.screenOutbound,
-    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return { unref() {} }; },
-    clearInterval: () => {},
-    log: () => {},
-    ...over.opts,
-  });
-  return { a, intervals };
-}
-
-const settle = () => new Promise((r) => setTimeout(r, 5));
-
-// ── registration ───────────────────────────────────────────────────────────
-
-test("platform self-registration: orgmail gated on config/orgmail.yaml, daemon-managed", () => {
-  const def = getPlatform("orgmail");
-  assert.ok(def, "definePlatform ran at import");
-  assert.equal(def.gateFile, "config/orgmail.yaml");
-  assert.deepEqual(def.capabilities, ORGMAIL_CAPABILITIES);
-  assert.equal(typeof def.factory, "function");
-  assert.equal(isDaemonManagedPlatform("orgmail"), true, "NOT in DEDICATED_PLIST_PLATFORMS");
-  const inst = createOrgMailChannel({ agentRoot: "/tmp", orgConfig: ORG_CFG, supervise: false, log: () => {} });
-  assert.equal(inst.name, "orgmail");
-});
-
-// ── config helpers ─────────────────────────────────────────────────────────
-
-test("resolvePollMs: explicit > env > poll_seconds > 45s default", () => {
-  assert.equal(resolvePollMs(1000, { poll_seconds: 10 }, { MAESTRO_ORGMAIL_POLL_MS: "2000" }), 1000);
-  assert.equal(resolvePollMs(undefined, { poll_seconds: 10 }, { MAESTRO_ORGMAIL_POLL_MS: "2000" }), 2000);
-  assert.equal(resolvePollMs(undefined, { poll_seconds: 10 }, {}), 10_000);
-  assert.equal(resolvePollMs(undefined, {}, {}), DEFAULT_POLL_MS);
-});
-
-test("htmlToText strips markup, decodes entities, preserves paragraph breaks", () => {
-  const text = htmlToText("<div><p>Hello &amp; hi</p><br><script>evil()</script><p>Second&nbsp;line</p></div>");
-  assert.match(text, /Hello & hi/);
-  assert.match(text, /Second line/);
-  assert.ok(!text.includes("evil"), "script bodies stripped");
-});
-
-// ── poll loop ──────────────────────────────────────────────────────────────
-
-test("poll: inbox summaries → per-item email.message → onRaw → markRead on clean handoff", async () => {
-  const fetchImpl = hqMock({
-    inboxPages: [[{ id: "em-2" }, { id: "em-1" }]], // server newest-first
-    messages: { "em-1": DTO({ id: "em-1" }), "em-2": DTO({ id: "em-2", subject: "Follow-up" }) },
-  });
-  const { a } = makeAdapter(fetchImpl);
-  const inbound = [];
-  await a.start({ onInbound: (ev) => inbound.push(ev) });
-  await settle();
-
-  assert.equal(fetchImpl.callsTo("/api/v1/email.inbox").length, 1);
-  assert.deepEqual(fetchImpl.callsTo("/api/v1/email.inbox")[0].body, { unreadOnly: true, limit: 50 });
-  assert.equal(fetchImpl.callsTo("/api/v1/email.message").length, 2, "one body fetch per summary");
-  assert.equal(inbound.length, 2, "both events delivered (pairingMode open)");
-  assert.deepEqual(inbound.map((e) => e.message_id), ["em-1", "em-2"], "newest LAST (chronological)");
-  const marked = fetchImpl.callsTo("/api/v1/email.markRead");
-  assert.deepEqual(marked.map((c) => c.body), [{ messageId: "em-1" }, { messageId: "em-2" }], "markRead per clean handoff — the server-side cursor");
-  await a.stop();
-});
-
-test("poll: a throwing handoff leaves the item UNREAD → re-delivered next tick (at-least-once)", async () => {
-  const fetchImpl = hqMock({
-    inboxPages: [[{ id: "em-1" }], [{ id: "em-1" }]], // still unread on tick 2
-    messages: { "em-1": DTO() },
-  });
-  const { a, intervals } = makeAdapter(fetchImpl);
-  let calls = 0;
-  await a.start({
-    onInbound: () => {
-      calls += 1;
-      if (calls === 1) throw new Error("classifier down");
-    },
-  });
-  await settle();
-  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 0, "no markRead after a throwing handoff");
-  await intervals[0].fn(); // drive tick 2 by hand
-  await settle();
-  assert.equal(calls, 2, "item re-delivered");
-  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 1, "clean second handoff marks read");
-  await a.stop();
-});
-
-test("poll: mark_read:false leaves items unread", async () => {
-  const fetchImpl = hqMock({ inboxPages: [[{ id: "em-1" }]], messages: { "em-1": DTO() } });
-  const { a } = makeAdapter(fetchImpl, { gate: { mark_read: false } });
-  const inbound = [];
-  await a.start({ onInbound: (ev) => inbound.push(ev) });
-  await settle();
-  assert.equal(inbound.length, 1);
-  assert.equal(fetchImpl.callsTo("/api/v1/email.markRead").length, 0);
-  await a.stop();
-});
-
-test("poll: a failed markRead is logged, not thrown (re-delivery next tick)", async () => {
-  const fetchImpl = hqMock({ inboxPages: [[{ id: "em-1" }]], messages: { "em-1": DTO() }, markReadFails: true });
-  const { a } = makeAdapter(fetchImpl);
-  const inbound = [];
-  await a.start({ onInbound: (ev) => inbound.push(ev) });
-  await settle();
-  assert.equal(inbound.length, 1, "delivery still happened");
-  await a.stop();
-});
-
-test("poll: unenrolled org (no token) is dormant — zero network, zero throw", async () => {
-  const fetchImpl = hqMock();
-  const a = new OrgMailAdapter({
-    agentRoot: "/tmp/orgmail-none", orgConfig: { org: {} }, fetchImpl,
-    supervise: false, sendGate: false, log: () => {},
-    setInterval: () => ({ unref() {} }), clearInterval: () => {},
-  });
-  await a.start({ onInbound: () => {} });
-  await settle();
-  assert.equal(fetchImpl.calls.length, 0);
-  await a.stop();
-});
-
-// ── _toEvent ───────────────────────────────────────────────────────────────
-
-test("_toEvent: subject-prefixed text, subject field, ids, source, attachments metadata", () => {
-  const { a } = makeAdapter(hqMock());
-  const ev = a._toEvent(DTO());
-  assert.equal(ev.channel, "orgmail");
-  assert.equal(ev.kind, "message");
-  assert.equal(ev.message_id, "em-1");
-  assert.equal(ev.thread_id, "th-1");
-  assert.equal(ev.text, "Subject: Quick pricing question\n\nHow much for 50 seats?");
-  assert.equal(ev.subject, "Quick pricing question", "item-shape subject carried");
-  assert.equal(ev.from.id, "casey@customer.com");
-  assert.equal(ev.timestamp, "2026-07-21T01:02:03.000Z", "receivedAt preferred");
-  assert.deepEqual(ev.source, {
-    channel: "orgmail", chatId: "th-1", replyToRef: "em-1", userScope: "dm", peerId: "casey@customer.com",
-  });
-  assert.equal(ev.attachments.length, 1);
-  assert.equal(ev.attachments[0].filename, "specs.pdf");
-  assert.equal(ev.raw_ref, "orgmail:th-1:em-1");
-});
-
-test("_toEvent: html-only body converts to text; in_reply_to mapped", () => {
-  const { a } = makeAdapter(hqMock());
-  const ev = a._toEvent(DTO({ text: null, html: "<p>Hello <b>there</b></p>", inReplyTo: "<rfc-1@x>" }));
-  assert.match(ev.text, /Hello there/);
-  assert.equal(ev.in_reply_to, "<rfc-1@x>");
-  assert.equal(ev.is_reply, true);
-});
-
-test("_toEvent: junk frames drop (null)", () => {
-  const { a } = makeAdapter(hqMock());
-  assert.equal(a._toEvent(null), null);
-  assert.equal(a._toEvent({}), null);
-});
-
-// ── _send ──────────────────────────────────────────────────────────────────
-
-test("_send: thread reply rides email.send {threadId, text, idempotencyId} — no to/subject (server reply rule)", async () => {
-  const fetchImpl = hqMock();
-  const { a } = makeAdapter(fetchImpl);
-  const res = await a._send({ text: "On it — reply drafted.", source: { channel: "orgmail", chatId: "th-9" } });
-  assert.equal(res.ok, true);
-  assert.equal(res.message_id, "out-1");
-  const sent = fetchImpl.callsTo("/api/v1/email.send");
-  assert.equal(sent.length, 1);
-  assert.equal(sent[0].body.threadId, "th-9");
-  assert.equal(sent[0].body.text, "On it — reply drafted.");
-  assert.ok(sent[0].body.idempotencyId && sent[0].body.idempotencyId.length >= 8, "business dedup id minted");
-  assert.equal(sent[0].body.to, undefined, "recipients derived server-side");
-  assert.equal(sent[0].body.subject, undefined, "subject inherited from the thread");
-  assert.ok(sent[0].headers["x-idempotency-key"], "fresh dispatcher key per invocation");
-});
-
-test("_send: approval_required maps to {ok:false} pointing at send-orgmail.mjs", async () => {
-  const fetchImpl = hqMock({
-    sendBody: { ok: true, result: { status: "approval_required", approval: { actionClass: "external_comms", payloadHash: "h", intent: {} }, firstContactRecipients: ["new@x.com"] } },
-  });
-  const { a } = makeAdapter(fetchImpl);
-  const res = await a._send({ text: "hi", source: { chatId: "th-9" } });
-  assert.equal(res.ok, false);
-  assert.match(res.error, /send-orgmail\.mjs --request-approval/);
-  assert.equal(res.raw.status, "approval_required");
-});
-
-test("send(): the inherited BaseAdapter perimeter screens outbound content", async () => {
-  const screened = [];
-  const fetchImpl = hqMock();
-  const { a } = makeAdapter(fetchImpl, {
-    sendGate: true,
-    screenOutbound: async (o) => { screened.push(o); return { allow: true }; },
-  });
-  const res = await a.send({ text: "gated reply", source: { channel: "orgmail", chatId: "th-2" } });
-  assert.equal(res.ok, true);
-  assert.equal(screened.length, 1, "screenOutbound ran before _send");
-  // and a veto blocks with a uniform SendResult
-  const { a: blocked } = makeAdapter(hqMock(), { sendGate: true, screenOutbound: async () => ({ allow: false, reason: "policy" }) });
-  const b = await blocked.send({ text: "no", source: { chatId: "th-2" } });
-  assert.deepEqual(b, { ok: false, blocked: true, reason: "policy" });
-});
-
-// ── health ─────────────────────────────────────────────────────────────────
-
-test("healthCheck: one email.inbox {limit:1} probe; surfaces the mailbox address", async () => {
-  const fetchImpl = hqMock();
-  const { a } = makeAdapter(fetchImpl);
-  const h = await a.healthCheck();
-  assert.equal(h.ok, true);
-  assert.match(h.detail, /astra@agents\.example/);
-  assert.deepEqual(fetchImpl.callsTo("/api/v1/email.inbox")[0].body, { limit: 1 });
-});
-
-test("healthCheck: server predating the email family (404 frame) degrades honestly", async () => {
-  const fetchImpl = async (url, init) => ({ ok: false, status: 404, json: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "unknown method email.inbox" } }), headers: { get: () => undefined } });
-  const { a } = makeAdapter(fetchImpl);
-  const h = await a.healthCheck();
-  assert.equal(h.ok, false);
-  assert.match(h.detail, /NOT_FOUND/);
-});
-
-test("healthCheck: missing enrollment is an honest unhealthy, not a throw", async () => {
-  const a = new OrgMailAdapter({ agentRoot: "/tmp/none", orgConfig: { org: {} }, supervise: false, log: () => {}, setInterval: () => ({ unref() {} }), clearInterval: () => {} });
-  const h = await a.healthCheck();
-  assert.equal(h.ok, false);
-  assert.match(h.detail, /enrollment missing/);
-});
-
-// ── standing-fault throttle (the 478-lines-a-day incident) ─────────────────
-//
-// A member with no mailbox made every 45s poll write the same NOT_FOUND line:
-// 478 of them on 2026-08-11, 164 the day before. The lane was dead and the
-// only signal was noise. These tests pin the fix: full detail once, silence in
-// between, a degraded poll while it needs a human, and an explicit recovery.
-
-/** A fake hq whose email.inbox fails with `code` until `heal()` is called. */
-function failingInbox(code, message = "no active mailbox is assigned to this agent") {
-  const state = { healed: false };
-  const fn = async (url) => {
-    const u = String(url);
-    const respond = (payload, status = 200, ok = true) => ({ ok, status, json: async () => payload, headers: { get: () => undefined } });
-    if (u.endsWith("/api/v1/email.inbox")) {
-      if (state.healed) {
-        return respond({ ok: true, result: { mailbox: { address: "astra@agents.example" }, messages: [], nextCursor: null } });
-      }
-      return respond({ ok: false, error: { code, message } }, 404, false);
-    }
-    return respond({ ok: true, result: {} });
-  };
-  fn.heal = () => { state.healed = true; };
-  return fn;
-}
-
-/** Build an adapter that captures its log lines and lets tests drive ticks. */
-function makeLoggingAdapter(fetchImpl, over = {}) {
-  const logs = [];
-  const intervals = [];
-  const a = new OrgMailAdapter({
-    agentRoot: "/tmp/orgmail-test",
-    orgConfig: ORG_CFG,
-    config: { orgmail: { enabled: true, poll_seconds: 45, mark_read: true } },
-    fetchImpl,
-    supervise: false,
-    sendGate: false,
-    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return { unref() {} }; },
-    clearInterval: () => {},
-    log: (level, msg) => logs.push({ level, msg }),
-    ...over,
-  });
-  return { a, logs, intervals };
-}
-
-test("standing NOT_FOUND: the first poll logs it IN FULL with the remedy", async () => {
-  const { a, logs } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const line = logs.find((l) => /email\.inbox NOT_FOUND/.test(l.msg));
-  assert.ok(line, "the first occurrence must be logged");
-  assert.equal(line.level, "error", "a dead lane is not a warning");
-  assert.match(line.msg, /workspace ADMIN/, "an ACTOR");
-  assert.match(line.msg, /Settings → Email → Mailboxes/, "and an ACT");
-  await a.stop();
-});
-
-test("standing NOT_FOUND: 40 further polls add ZERO lines (the incident, prevented)", async () => {
-  const { a, logs, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const afterFirst = logs.length;
-  const tick = intervals[intervals.length - 1].fn;
-  for (let i = 0; i < 40; i += 1) { await tick(); await settle(); }
-  assert.equal(logs.length, afterFirst, `expected no repeats, got ${logs.length - afterFirst}`);
-  await a.stop();
-});
-
-test("standing NOT_FOUND degrades the poll to 10m — no point hammering a human-gated fault", async () => {
-  const { a, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  assert.equal(intervals[intervals.length - 1].ms, DEGRADED_POLL_MS);
-  await a.stop();
-});
-
-test("recovery: the mailbox appearing logs RESOLVED and restores the normal cadence", async () => {
-  const fetchImpl = failingInbox("NOT_FOUND");
-  const { a, logs, intervals } = makeLoggingAdapter(fetchImpl);
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const tick = intervals[intervals.length - 1].fn;
-  for (let i = 0; i < 5; i += 1) { await tick(); await settle(); }
-
-  fetchImpl.heal(); // an admin assigns the mailbox
-  await tick();
-  await settle();
-
-  const resolved = logs.find((l) => /RESOLVED/.test(l.msg));
-  assert.ok(resolved, "recovery must be stated explicitly, not inferred from silence");
-  assert.match(resolved.msg, /6 failed attempt/);
-  assert.match(resolved.msg, /live again/);
-  assert.equal(intervals[intervals.length - 1].ms, 45_000, "normal cadence restored");
-  assert.equal(a.standingFault(), null);
-  await a.stop();
-});
-
-test("a NON-terminal error keeps the normal cadence and stays a warn", async () => {
-  const { a, logs, intervals } = makeLoggingAdapter(failingInbox("INTERNAL", "boom"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const line = logs.find((l) => /email\.inbox INTERNAL/.test(l.msg));
-  assert.equal(line.level, "warn", "a transient server error is not a dead lane");
-  assert.equal(intervals[intervals.length - 1].ms, 45_000);
-  assert.equal(a.standingFault(), null);
-  await a.stop();
-});
-
-test("throttling the LOG never throttles the ANSWER: healthCheck still states the fault + remedy", async () => {
-  const { a, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const tick = intervals[intervals.length - 1].fn;
-  for (let i = 0; i < 20; i += 1) { await tick(); await settle(); }
-  const h = await a.healthCheck();
-  assert.equal(h.ok, false);
-  assert.match(h.detail, /NOT_FOUND/);
-  assert.match(h.detail, /workspace ADMIN/);
-  assert.match(h.detail, /degraded to 10m/);
-  // And the machine-readable form, for doctor / state files.
-  const fault = a.standingFault();
-  assert.equal(fault.code, "NOT_FOUND");
-  assert.match(fault.since, /^\d{4}-/);
-  await a.stop();
-});
-
-test("FORBIDDEN_SCOPE gets the KEY remedy, not the mailbox one", async () => {
-  const { a, logs } = makeLoggingAdapter(failingInbox("FORBIDDEN_SCOPE", "not paired"));
-  await a.start({ onInbound: () => {} });
-  await settle();
-  const line = logs.find((l) => /email\.inbox FORBIDDEN_SCOPE/.test(l.msg));
-  assert.equal(line.level, "error");
-  assert.match(line.msg, /Settings → API keys/);
-  assert.ok(!/Settings → Email → Mailboxes/.test(line.msg), "wrong remedy for this cause");
-  await a.stop();
-});