@cohortapp/agent-sdk 2.3.0

package/lib/channels/channel.mjs

@@ -0,0 +1,128 @@
+/**
+ * Maestro — Channel interface
+ *
+ * Defines the minimum contract every communication channel (Slack,
+ * Gmail, WhatsApp, SMS, Voice, Discord, Telegram, iMessage, …) must
+ * implement so the agent runtime can talk to it uniformly.
+ *
+ * This module is intentionally tiny: a contract + helper types, no
+ * runtime behaviour. Concrete channels live in lib/channels/<service>/.
+ *
+ * Inspired by openclaw's `ChannelPlugin` pattern (MIT-licensed) but
+ * pared back for maestro's daemon architecture, where pollers already
+ * exist as freestanding scripts. The bus is *additive*: existing
+ * scripts/poller/slack-poller.mjs etc. continue to work; the channel
+ * abstraction sits alongside them and lets future channels plug in
+ * without touching dispatcher.mjs.
+ *
+ * Lifecycle:
+ *   const ch = createSlackChannel({ ... });
+ *   await ch.start({ onInbound: (msg) => bus.publish(msg), … });
+ *   await ch.send({ to: …, text: …, threadRef: … });
+ *   await ch.react({ messageRef, emoji: "thumbsup" });
+ *   await ch.stop();
+ */
+
+/**
+ * @typedef {Object} ChannelIdentity
+ * @property {string} id         Unique within this channel's namespace
+ * @property {string} [name]     Human-readable name / handle
+ * @property {string} [email]    Email if applicable
+ * @property {string} [phone]    E.164 phone if applicable
+ * @property {Record<string,string>} [metadata]
+ */
+
+/**
+ * @typedef {Object} ChannelMessage
+ * @property {string} channel        Channel name, e.g. "slack" | "gmail" | "whatsapp"
+ * @property {string} message_id     Stable per-channel id (Slack ts, Gmail msgId, etc.)
+ * @property {string} [thread_id]    Thread / conversation id within the channel
+ * @property {ChannelIdentity} from
+ * @property {ChannelIdentity} [to]
+ * @property {string} text           Plain-text body (channel-specific formatting stripped)
+ * @property {string} [html]         Original HTML body if applicable
+ * @property {Array<Attachment>} [attachments]
+ * @property {string} timestamp      ISO 8601
+ * @property {string} [in_reply_to]  Parent message id for threaded replies
+ * @property {object} [raw]          Untouched provider payload for diagnostics
+ */
+
+/**
+ * @typedef {Object} Attachment
+ * @property {string} type           "image" | "audio" | "video" | "document" | "voice_note"
+ * @property {string} [mime]
+ * @property {string} [url]          HTTPS URL (may require auth)
+ * @property {string} [filename]
+ * @property {number} [size_bytes]
+ * @property {string} [transcript]   For voice notes: server-side transcript if available
+ */
+
+/**
+ * @typedef {Object} OutboundMessage
+ * @property {string} to             Channel-specific recipient (Slack channel id, email addr, phone)
+ * @property {string} text           Plain-text body; channel may format
+ * @property {object} [blocks]       Slack Block Kit / WhatsApp interactive / etc.
+ * @property {string} [thread_ref]   Reply within a thread
+ * @property {Array<Attachment>} [attachments]
+ * @property {object} [meta]         Channel-specific knobs (Slack unfurl, Gmail Cc/Bcc)
+ */
+
+/**
+ * @typedef {Object} ChannelOptions
+ * @property {object} [config]       Channel-specific config (loaded from config/<name>.yaml)
+ * @property {string} [agentRoot]    Agent repo root (for state + auth)
+ * @property {(level:string,msg:string)=>void} [log]
+ */
+
+/**
+ * The Channel interface. Concrete implementations export
+ * `create<Name>Channel(opts)` returning an object with these methods.
+ *
+ * @typedef {Object} Channel
+ * @property {string} name
+ * @property {Array<string>} capabilities  ["send", "react", "media", "voice_note", …]
+ * @property {(opts: { onInbound: (msg: ChannelMessage) => void, signal?: AbortSignal }) => Promise<void>} start
+ * @property {(msg: OutboundMessage) => Promise<{ message_id: string, raw?: object }>} send
+ * @property {(opts: { messageRef: string, emoji: string }) => Promise<void>} [react]
+ * @property {(opts: { url: string }) => Promise<Buffer>} [fetchAttachment]
+ * @property {() => Promise<{ ok: boolean, detail?: string }>} healthCheck
+ * @property {() => Promise<void>} stop
+ */
+
+// Capability constants used by ChannelRegistry to do feature-detection.
+export const CHANNEL_CAPABILITIES = Object.freeze({
+  SEND: "send",
+  REACT: "react",
+  THREAD: "thread",
+  MEDIA_IMAGE: "media.image",
+  MEDIA_AUDIO: "media.audio",
+  MEDIA_DOCUMENT: "media.document",
+  VOICE_NOTE: "voice_note",
+  TYPING_INDICATOR: "typing_indicator",
+  READ_RECEIPTS: "read_receipts",
+  GROUP_CHAT: "group_chat",
+  MENTIONS: "mentions",
+  RICH_BLOCKS: "rich_blocks",
+});
+
+/**
+ * Tiny runtime helper: assert that an object implements the Channel
+ * interface enough to be registered. Returns the channel or throws.
+ */
+export function validateChannel(channel) {
+  if (!channel || typeof channel !== "object") {
+    throw new Error("validateChannel: channel must be an object");
+  }
+  for (const k of ["name", "start", "send", "stop"]) {
+    if (!(k in channel)) throw new Error(`validateChannel: missing required member "${k}"`);
+  }
+  if (typeof channel.start !== "function") throw new Error("validateChannel: start must be a function");
+  if (typeof channel.send !== "function") throw new Error("validateChannel: send must be a function");
+  if (typeof channel.stop !== "function") throw new Error("validateChannel: stop must be a function");
+  if (channel.capabilities && !Array.isArray(channel.capabilities)) {
+    throw new Error("validateChannel: capabilities must be an array of strings");
+  }
+  return channel;
+}
+
+export default { validateChannel, CHANNEL_CAPABILITIES };

package/lib/channels/channels.test.mjs

@@ -0,0 +1,371 @@
+/**
+ * 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); }
+});