@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/channels/channels.test.mjs

@@ -1,371 +0,0 @@
-/**
- * channels.test.mjs — node:test coverage for the channel bus.
- *
- * Tests focus on the pure pieces: validateChannel, conversation
- * resolver, registry semantics. Adapter wrappers around external
- * scripts are exercised by mocking the script presence on a tmp dir;
- * we don't shell out to Twilio/Slack from the test suite.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
-import { promises as fsp } from "fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  validateChannel,
-  CHANNEL_CAPABILITIES,
-} from "./channel.mjs";
-
-import {
-  resolveConversation,
-  sameConversation,
-  sessionLockKey,
-} from "./conversation-resolver.mjs";
-
-import {
-  registerChannel,
-  getChannel,
-  listChannels,
-  findChannelsWithCapability,
-  clearChannels,
-  startAllChannels,
-} from "./registry.mjs";
-
-import { createChannel } from "./index.mjs";
-
-async function makeAgentRoot() {
-  const path = join(tmpdir(), `channels-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-  await fsp.mkdir(path, { recursive: true });
-  return path;
-}
-async function rmRoot(path) { try { await fsp.rm(path, { recursive: true, force: true }); } catch {} }
-
-function fakeChannel(name, capabilities = ["send"]) {
-  const out = {
-    name,
-    capabilities,
-    started: false,
-    sentMessages: [],
-    stopped: false,
-    async start({ onInbound }) {
-      this.started = true;
-      this.onInbound = onInbound;
-    },
-    async send(msg) {
-      this.sentMessages.push(msg);
-      return { message_id: `${name}-${this.sentMessages.length}` };
-    },
-    async healthCheck() { return { ok: true }; },
-    async stop() { this.stopped = true; },
-  };
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// validateChannel
-// ---------------------------------------------------------------------------
-
-test("validateChannel accepts a minimal valid channel", () => {
-  const ch = fakeChannel("test");
-  assert.equal(validateChannel(ch), ch);
-});
-
-test("validateChannel rejects missing members", () => {
-  assert.throws(() => validateChannel(null), /must be an object/);
-  assert.throws(() => validateChannel({ name: "x" }), /required member "start"/);
-  assert.throws(() => validateChannel({ name: "x", start: "no", send: () => {}, stop: () => {} }), /start must be a function/);
-  assert.throws(() => validateChannel({ name: "x", start: () => {}, send: () => {}, stop: () => {}, capabilities: "not-array" }), /capabilities must be an array/);
-});
-
-// ---------------------------------------------------------------------------
-// CHANNEL_CAPABILITIES
-// ---------------------------------------------------------------------------
-
-test("CHANNEL_CAPABILITIES surface is frozen and complete", () => {
-  assert.ok(Object.isFrozen(CHANNEL_CAPABILITIES));
-  for (const k of ["SEND", "REACT", "THREAD", "VOICE_NOTE", "GROUP_CHAT", "MENTIONS", "RICH_BLOCKS"]) {
-    assert.ok(CHANNEL_CAPABILITIES[k], `missing capability: ${k}`);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// conversation-resolver
-// ---------------------------------------------------------------------------
-
-test("resolveConversation: Slack thread_ts and DM fall-back", () => {
-  const a = resolveConversation({
-    channel: "slack",
-    message_id: "1700.001",
-    thread_id: "1700.100",
-    from: { id: "U123" },
-    text: "hi",
-    timestamp: new Date().toISOString(),
-  });
-  assert.equal(a.channel, "slack");
-  assert.equal(a.threadId, "1700.100");
-  assert.equal(a.sessionKey, "slack:1700.100");
-
-  const b = resolveConversation({
-    channel: "slack",
-    message_id: "1700.002",
-    from: { id: "U123" },
-    text: "no-thread",
-    raw: { channel: "D099" },
-    timestamp: new Date().toISOString(),
-  });
-  assert.equal(b.threadId, "dm:D099");
-});
-
-test("resolveConversation: Gmail uses thread_id, then in_reply_to, then message_id", () => {
-  const a = resolveConversation({ channel: "gmail", thread_id: "T1", message_id: "M1", from: { email: "x@y.com" }, text: "hi", timestamp: "" });
-  const b = resolveConversation({ channel: "gmail", in_reply_to: "M0", message_id: "M1", from: { email: "x@y.com" }, text: "hi", timestamp: "" });
-  const c = resolveConversation({ channel: "gmail", message_id: "M1", from: { email: "x@y.com" }, text: "hi", timestamp: "" });
-  assert.equal(a.sessionKey, "gmail:T1");
-  assert.equal(b.sessionKey, "gmail:M0");
-  assert.equal(c.sessionKey, "gmail:M1");
-});
-
-test("resolveConversation: WhatsApp + SMS fall back to peer-keyed sessions", () => {
-  const wa = resolveConversation({ channel: "whatsapp", message_id: "X1", from: { phone: "+9715" }, text: "hi", timestamp: "" });
-  const sms = resolveConversation({ channel: "sms", message_id: "Y1", from: { phone: "+9715" }, text: "hi", timestamp: "" });
-  assert.equal(wa.sessionKey, "whatsapp:peer:+9715");
-  assert.equal(sms.sessionKey, "sms:peer:+9715");
-});
-
-test("resolveConversation: voice and calendar use call/event keys", () => {
-  const v = resolveConversation({ channel: "voice", message_id: "CALL-1", from: { phone: "+1" }, text: "(voice)", timestamp: "" });
-  const c = resolveConversation({ channel: "calendar", message_id: "EV-1", from: { id: "user@x" }, text: "meeting", timestamp: "" });
-  assert.equal(v.sessionKey, "voice:call:CALL-1");
-  assert.equal(c.sessionKey, "calendar:event:EV-1");
-});
-
-test("sameConversation flags messages with identical session keys", () => {
-  const a = { channel: "slack", thread_id: "T1", message_id: "M1", from: { id: "U" }, text: "", timestamp: "" };
-  const b = { channel: "slack", thread_id: "T1", message_id: "M2", from: { id: "U" }, text: "", timestamp: "" };
-  const c = { channel: "slack", thread_id: "T2", message_id: "M3", from: { id: "U" }, text: "", timestamp: "" };
-  assert.equal(sameConversation(a, b), true);
-  assert.equal(sameConversation(a, c), false);
-});
-
-test("sessionLockKey produces channel:threadId", () => {
-  const key = sessionLockKey({ channel: "slack", thread_id: "T9", message_id: "M", from: { id: "U" }, text: "", timestamp: "" });
-  assert.equal(key, "slack:T9");
-});
-
-// ---------------------------------------------------------------------------
-// registry
-// ---------------------------------------------------------------------------
-
-test("registry: registerChannel + getChannel + listChannels", () => {
-  clearChannels();
-  registerChannel("slack", fakeChannel("slack", ["send", "react"]));
-  registerChannel("gmail", fakeChannel("gmail", ["send", "thread"]));
-  assert.deepEqual(listChannels(), ["gmail", "slack"]);
-  assert.equal(getChannel("slack").name, "slack");
-  assert.equal(getChannel("nope"), undefined);
-  clearChannels();
-});
-
-test("registry: findChannelsWithCapability", () => {
-  clearChannels();
-  registerChannel("slack", fakeChannel("slack", ["send", "react", "rich_blocks"]));
-  registerChannel("sms", fakeChannel("sms", ["send"]));
-  registerChannel("voice", fakeChannel("voice", ["voice_note"]));
-  assert.deepEqual(findChannelsWithCapability("react"), ["slack"]);
-  assert.deepEqual(findChannelsWithCapability("send").sort(), ["slack", "sms"]);
-  assert.deepEqual(findChannelsWithCapability("voice_note"), ["voice"]);
-  clearChannels();
-});
-
-test("registry: startAllChannels fans out + teardown stops every channel", async () => {
-  clearChannels();
-  const slack = fakeChannel("slack");
-  const gmail = fakeChannel("gmail");
-  registerChannel("slack", slack);
-  registerChannel("gmail", gmail);
-  const received = [];
-  const stopAll = await startAllChannels((msg) => received.push(msg));
-  assert.equal(slack.started, true);
-  assert.equal(gmail.started, true);
-  // Simulate inbound on slack
-  slack.onInbound({ channel: "slack", message_id: "M1", from: { id: "U1" }, text: "hi", timestamp: "" });
-  assert.equal(received.length, 1);
-  assert.equal(received[0].channel, "slack");
-  await stopAll();
-  assert.equal(slack.stopped, true);
-  assert.equal(gmail.stopped, true);
-  clearChannels();
-});
-
-test("registry: startAllChannels stamps channel name when adapter forgot", async () => {
-  clearChannels();
-  // A buggy channel that emits a ChannelMessage without setting .channel
-  const buggy = {
-    ...fakeChannel("buggy"),
-    async start({ onInbound }) { this.onInbound = onInbound; this.started = true; },
-  };
-  registerChannel("buggy", buggy);
-  const received = [];
-  const stop = await startAllChannels((msg) => received.push(msg));
-  buggy.onInbound({ message_id: "X", from: { id: "U" }, text: "", timestamp: "" });
-  assert.equal(received[0].channel, "buggy", "registry should stamp channel name");
-  await stop();
-  clearChannels();
-});
-
-test("registry: registerChannel throws on duplicate name (L14)", () => {
-  clearChannels();
-  registerChannel("slack", fakeChannel("slack"));
-  assert.throws(
-    () => registerChannel("slack", fakeChannel("slack")),
-    /already registered/,
-    "duplicate registration must throw"
-  );
-  clearChannels();
-});
-
-test("registry: registerChannel { replace:true } stops the previous instance (L14)", async () => {
-  clearChannels();
-  const first = fakeChannel("slack");
-  registerChannel("slack", first);
-  const second = fakeChannel("slack");
-  await registerChannel("slack", second, { replace: true });
-  assert.equal(first.stopped, true, "previous instance must be stopped before swap");
-  assert.equal(getChannel("slack"), second, "new instance must take the slot");
-  clearChannels();
-});
-
-test("registry: startAllChannels surfaces a failing start and only stops started channels (L15)", async () => {
-  clearChannels();
-  const good = fakeChannel("good");
-  const bad = {
-    ...fakeChannel("bad"),
-    async start() {
-      throw new Error("boom-sync");
-    },
-  };
-  // An async-rejecting start must also be surfaced (not just sync throws).
-  const badAsync = {
-    ...fakeChannel("bad-async"),
-    async start() {
-      this.started = false;
-      return Promise.reject(new Error("boom-async"));
-    },
-  };
-  registerChannel("good", good);
-  registerChannel("bad", bad);
-  registerChannel("bad-async", badAsync);
-
-  const errors = [];
-  const stopAll = await startAllChannels(() => {}, {
-    onError: (name, err) => errors.push({ name, message: err.message }),
-  });
-
-  // Per-channel results are surfaced.
-  const byName = Object.fromEntries(stopAll.results.map((r) => [r.name, r]));
-  assert.equal(byName.good.ok, true);
-  assert.equal(byName.bad.ok, false);
-  assert.equal(byName.bad.error.message, "boom-sync");
-  assert.equal(byName["bad-async"].ok, false);
-  assert.equal(byName["bad-async"].error.message, "boom-async");
-
-  // onError fired for both failures (sync + async), not for the good one.
-  assert.deepEqual(
-    errors.map((e) => e.name).sort(),
-    ["bad", "bad-async"],
-    "onError must fire for every failed start"
-  );
-
-  // Tearing down must NOT call stop() on channels that never started.
-  await stopAll();
-  assert.equal(good.stopped, true, "started channel is stopped");
-  assert.equal(bad.stopped, false, "channel whose start() threw is NOT stopped");
-  assert.equal(badAsync.stopped, false, "channel whose start() rejected is NOT stopped");
-  clearChannels();
-});
-
-test("resolveConversation: case-variant emails resolve to ONE sessionKey (L16)", () => {
-  const a = resolveConversation({
-    channel: "Gmail",
-    thread_id: "T1",
-    message_id: "M1",
-    from: { email: "Casey@Example.COM" },
-    text: "hi",
-    timestamp: "",
-  });
-  const b = resolveConversation({
-    channel: "gmail",
-    thread_id: "T1",
-    message_id: "M1",
-    from: { email: "  casey@example.com  " },
-    text: "hi",
-    timestamp: "",
-  });
-  assert.equal(a.sessionKey, b.sessionKey, "case/whitespace variants must share a session key");
-  assert.equal(a.peerId, "casey@example.com", "email peerId is lowercased + trimmed");
-  assert.equal(a.peerId, b.peerId);
-});
-
-test("resolveConversation: two DMs with missing raw.channel do NOT collide (L17)", () => {
-  const u1 = resolveConversation({
-    channel: "slack",
-    message_id: "M1",
-    from: { id: "U111" },
-    text: "hi",
-    timestamp: "",
-  });
-  const u2 = resolveConversation({
-    channel: "slack",
-    message_id: "M2",
-    from: { id: "U222" },
-    text: "hi",
-    timestamp: "",
-  });
-  assert.equal(u1.threadId, "dm:u111", "DM without raw.channel falls back to peerId");
-  assert.equal(u2.threadId, "dm:u222");
-  assert.notEqual(u1.sessionKey, u2.sessionKey, "distinct DMs must not collapse to one session");
-});
-
-// ---------------------------------------------------------------------------
-// createChannel (lazy factory) — sanity-check it can load each adapter
-// ---------------------------------------------------------------------------
-
-test("createChannel lazily loads slack/gmail/sms/voice adapters", async () => {
-  const slack = await createChannel("slack", { agentRoot: "/tmp" });
-  const gmail = await createChannel("gmail", { agentRoot: "/tmp" });
-  const sms = await createChannel("sms", { agentRoot: "/tmp" });
-  const voice = await createChannel("voice", { agentRoot: "/tmp" });
-  const wa = await createChannel("whatsapp", { agentRoot: "/tmp" });
-  for (const ch of [slack, gmail, sms, voice, wa]) {
-    assert.ok(typeof ch.start === "function", `${ch.name} missing start`);
-    assert.ok(typeof ch.send === "function", `${ch.name} missing send`);
-    assert.ok(typeof ch.stop === "function", `${ch.name} missing stop`);
-  }
-});
-
-test("createChannel rejects unknown channels", async () => {
-  await assert.rejects(() => createChannel("does-not-exist"), /unknown channel/);
-});
-
-// ---------------------------------------------------------------------------
-// Slack adapter healthCheck path — verify behavior with/without send script
-// ---------------------------------------------------------------------------
-
-test("Slack adapter healthCheck reflects send-script presence", async () => {
-  const root = await makeAgentRoot();
-  try {
-    const slack = await createChannel("slack", { agentRoot: root });
-    let h = await slack.healthCheck();
-    assert.equal(h.ok, false, "no script → not ok");
-    // Now plant a stub.
-    mkdirSync(join(root, "scripts"), { recursive: true });
-    writeFileSync(join(root, "scripts/slack-send.sh"), "#!/bin/sh\necho ok\n");
-    chmodSync(join(root, "scripts/slack-send.sh"), 0o755);
-    const slack2 = await createChannel("slack", { agentRoot: root });
-    h = await slack2.healthCheck();
-    assert.equal(h.ok, true);
-  } finally { await rmRoot(root); }
-});

package/lib/channels/contract.test.mjs

@@ -1,162 +0,0 @@
-/**
- * contract.test.mjs — node:test coverage for lib/channels/contract.mjs
- *
- * Covers: EventKind set + normalization, makeMessageEvent defaults, and the
- * self-registering platform registry (definePlatform / getPlatform /
- * listPlatforms / clearPlatform). Pure, hermetic — no IO.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  EVENT_KINDS,
-  DEFAULT_EVENT_KIND,
-  normalizeKind,
-  makeMessageEvent,
-  definePlatform,
-  getPlatform,
-  listPlatforms,
-  clearPlatform,
-  DEDICATED_PLIST_PLATFORMS,
-  isDaemonManagedPlatform,
-} from "./contract.mjs";
-
-import { ChannelMessage } from "./index.mjs";
-
-test("EVENT_KINDS is the closed set from the design", () => {
-  // Two groups. The five CHAT kinds are the original design set and must not
-  // move — `message` in particular is the default and the byte-compat anchor.
-  // The eleven WORK-SURFACE kinds were added for wide org inbound
-  // (lib/org/inbound/surfaces.mjs): an org agent is addressed through board
-  // items, approvals, decisions, docs and mail as well as chat, and `kind` is
-  // the routing hint the daemon classifier reads. Adding one here without a
-  // matching SURFACES entry (or vice versa) is caught by
-  // lib/org/inbound/project.test.mjs.
-  assert.deepEqual([...EVENT_KINDS].sort(), [
-    "approval",
-    "calendar",
-    "call",
-    "channel_cc",
-    "decision",
-    "email",
-    "escalation",
-    "file_comment",
-    "handoff",
-    "mention",
-    "message",
-    "reaction",
-    "task_assigned",
-    "task_comment",
-    "thread_reply",
-    "voice_note",
-  ]);
-  assert.equal(DEFAULT_EVENT_KIND, "message");
-});
-
-test("normalizeKind passes known kinds and defaults unknown to message", () => {
-  assert.equal(normalizeKind("reaction"), "reaction");
-  assert.equal(normalizeKind("channel_cc"), "channel_cc");
-  assert.equal(normalizeKind("voice_note"), "voice_note");
-  assert.equal(normalizeKind(undefined), "message");
-  assert.equal(normalizeKind("bogus"), "message");
-  assert.equal(normalizeKind(null), "message");
-});
-
-test("makeMessageEvent fills kind default and preserves other fields", () => {
-  const ev = makeMessageEvent({ channel: "slack", message_id: "1.2", text: "hi" });
-  assert.equal(ev.kind, "message");
-  assert.equal(ev.channel, "slack");
-  assert.equal(ev.text, "hi");
-
-  const reaction = makeMessageEvent({ channel: "telegram", kind: "reaction", text: "" });
-  assert.equal(reaction.kind, "reaction");
-});
-
-test("ChannelMessage is exported as a back-compat alias for MessageEvent", () => {
-  // The alias must be re-exported from the channels facade so existing
-  // `import { ChannelMessage }` sites resolve. It's a typedef carrier — the
-  // runtime value is a harmless namespace/sentinel, just assert it exists.
-  assert.notEqual(ChannelMessage, undefined, "ChannelMessage alias must be exported");
-});
-
-// ---------------------------------------------------------------------------
-// Platform registry
-// ---------------------------------------------------------------------------
-
-test("definePlatform + getPlatform + listPlatforms round-trip", () => {
-  clearPlatform("test-plat-a");
-  clearPlatform("test-plat-b");
-
-  const factoryA = () => ({ name: "test-plat-a" });
-  const def = definePlatform({
-    name: "test-plat-a",
-    gateFile: "config/test-plat-a.yaml",
-    factory: factoryA,
-    capabilities: ["send", "react"],
-  });
-  assert.equal(def.name, "test-plat-a");
-  assert.equal(def.gateFile, "config/test-plat-a.yaml");
-  assert.deepEqual(def.capabilities, ["send", "react"]);
-
-  const got = getPlatform("test-plat-a");
-  assert.equal(got.factory, factoryA);
-  assert.deepEqual(got.capabilities, ["send", "react"]);
-
-  definePlatform({ name: "test-plat-b", gateFile: "config/test-plat-b.yaml", factory: () => ({}) });
-  const names = listPlatforms().map((p) => p.name);
-  assert.ok(names.includes("test-plat-a"));
-  assert.ok(names.includes("test-plat-b"));
-  // Sorted deterministically.
-  assert.deepEqual([...names].sort(), names);
-
-  clearPlatform("test-plat-a");
-  clearPlatform("test-plat-b");
-});
-
-test("definePlatform is idempotent by name (re-import safe)", () => {
-  clearPlatform("dup");
-  const f1 = () => ({ v: 1 });
-  const f2 = () => ({ v: 2 });
-  definePlatform({ name: "dup", gateFile: "config/dup.yaml", factory: f1 });
-  // Re-defining must NOT throw — it replaces (modules can re-eval in tests).
-  assert.doesNotThrow(() => definePlatform({ name: "dup", gateFile: "config/dup.yaml", factory: f2 }));
-  assert.equal(getPlatform("dup").factory, f2);
-  clearPlatform("dup");
-});
-
-test("definePlatform validates required fields", () => {
-  assert.throws(() => definePlatform(null), /def object required/);
-  assert.throws(() => definePlatform({ gateFile: "x", factory: () => {} }), /name required/);
-  assert.throws(() => definePlatform({ name: "x", factory: () => {} }), /gateFile required/);
-  assert.throws(() => definePlatform({ name: "x", gateFile: "x" }), /factory must be a function/);
-});
-
-test("capabilities default to an empty array and are copied (not aliased)", () => {
-  clearPlatform("nocap");
-  const src = ["send"];
-  const def = definePlatform({ name: "nocap", gateFile: "config/nocap.yaml", factory: () => {}, capabilities: src });
-  src.push("mutated");
-  assert.deepEqual(def.capabilities, ["send"], "registry must not alias the caller's array");
-  clearPlatform("nocap");
-});
-
-// ---------------------------------------------------------------------------
-// Single-owner rule (H2) — Slack must NOT be daemon-managed, because its
-// dedicated launchd `slack-socket` process owns the real-time connection.
-// Starting it in BOTH places double-ingests every DM. This invariant is the
-// guard that two Slack connections can't both be live.
-// ---------------------------------------------------------------------------
-
-test("H2: Slack is excluded from daemon-managed platforms (dedicated plist owns it)", () => {
-  assert.ok(DEDICATED_PLIST_PLATFORMS.has("slack"), "slack has a dedicated launchd owner");
-  assert.equal(isDaemonManagedPlatform("slack"), false,
-    "the daemon generic loop must NOT start Slack — its slack-socket plist is the single owner");
-});
-
-test("H2: daemon-only channels (telegram/whatsapp/voice) remain daemon-managed", () => {
-  for (const name of ["telegram", "whatsapp", "voice"]) {
-    assert.equal(isDaemonManagedPlatform(name), true, `${name} has no dedicated plist → daemon-managed`);
-    assert.equal(DEDICATED_PLIST_PLATFORMS.has(name), false);
-  }
-});