@cohortapp/agent-sdk 2.3.0

package/lib/channels/contract.mjs

@@ -0,0 +1,215 @@
+/**
+ * Maestro — Channel contract (one type, one serialization)
+ *
+ * WS2 (Hermes integration §5) unifies every channel onto a single message
+ * type + a self-registering platform registry. This module is the SoT for:
+ *
+ *   - `MessageEvent`  — the reconciled, canonical inbound event. It is a
+ *     superset of the legacy `ChannelMessage` (lib/channels/channel.mjs):
+ *     same fields, plus `kind`, `source`, and `thread_context`. We export
+ *     `ChannelMessage` as a back-compat alias so existing imports keep
+ *     working unchanged.
+ *   - `SessionSource` — the durable, channel-agnostic descriptor of *where*
+ *     an event came from, used to reply / set typing / react without the
+ *     adapter re-deriving channel-specific ids.
+ *   - `SendResult`    — the uniform return shape of every adapter `_send`.
+ *   - `EventKind`     — the closed set of inbound event kinds.
+ *   - The platform registry: `definePlatform` / `getPlatform` /
+ *     `listPlatforms`. Each concrete adapter file ends with a
+ *     `definePlatform({ name, gateFile, factory, capabilities })` call so the
+ *     daemon can discover channels by *dropping a file* (no core edit), the
+ *     same pattern WS1 uses for setup sections.
+ *
+ * This module is pure data + a tiny registry — no runtime IO, no network.
+ *
+ * @module lib/channels/contract
+ */
+
+"use strict";
+
+// ---------------------------------------------------------------------------
+// EventKind — the closed set of inbound event kinds.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {"message"|"reaction"|"channel_cc"|"voice_note"|"call"} EventKind
+ *
+ * - message     a normal directed message (DM, @mention, thread reply)
+ * - reaction    an emoji reaction add/remove (rarely action-required)
+ * - channel_cc  a non-directed message in a watched/cc channel (observe, don't reply)
+ * - voice_note  a voice note whose transcript becomes `text` (+ a voice_note attachment)
+ * - call        a live phone/voice call turn
+ */
+export const EVENT_KINDS = Object.freeze([
+  "message",
+  "reaction",
+  "channel_cc",
+  "voice_note",
+  "call",
+]);
+
+/** The default kind when an event/serialized item does not specify one. */
+export const DEFAULT_EVENT_KIND = "message";
+
+/** Normalise an arbitrary kind value to a known EventKind (defaults to "message"). */
+export function normalizeKind(kind) {
+  return EVENT_KINDS.includes(kind) ? kind : DEFAULT_EVENT_KIND;
+}
+
+// ---------------------------------------------------------------------------
+// Typedefs (JSDoc only — no runtime cost).
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} SessionSource
+ * @property {string}  channel     Channel name, e.g. "slack" | "telegram" | "whatsapp"
+ * @property {string}  chatId      The channel-native conversation/chat id (Slack channel id,
+ *                                  Telegram chat id, WhatsApp jid, …). Stable per-conversation.
+ * @property {string}  [threadRef] Thread / topic reference within the chat (Slack thread_ts,
+ *                                  Telegram message_thread_id), when threaded.
+ * @property {string}  [replyToRef] The specific message being replied to (for quoted replies).
+ * @property {string}  userScope   "dm" | "group" | "channel" — coarse audience scope, drives
+ *                                  whether pairing (DMs) or membership+directed-gate (group)
+ *                                  governs the event.
+ */
+
+/**
+ * @typedef {Object} SendResult
+ * @property {boolean} ok           Whether the send succeeded.
+ * @property {string}  [message_id] Provider message id on success.
+ * @property {string}  [error]      Error detail on failure.
+ * @property {object}  [raw]        Untouched provider response for diagnostics.
+ */
+
+/**
+ * MessageEvent — the canonical inbound event. Superset of ChannelMessage.
+ *
+ * @typedef {Object} MessageEvent
+ * @property {string} channel        Channel name, e.g. "slack" | "telegram" | "whatsapp"
+ * @property {string} message_id     Stable per-channel id (Slack ts, Telegram msg id, …)
+ * @property {string} [thread_id]    Thread / conversation id within the channel
+ * @property {import("./channel.mjs").ChannelIdentity} from
+ * @property {import("./channel.mjs").ChannelIdentity} [to]
+ * @property {string} text           Plain-text body (channel-specific formatting stripped)
+ * @property {string} [html]         Original HTML body if applicable
+ * @property {Array<import("./channel.mjs").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
+ * @property {EventKind} kind        WS2: the event kind (default "message")
+ * @property {SessionSource} [source] WS2: durable source descriptor for reply/typing/react
+ * @property {string|null} [thread_context] WS2: rendered prior-thread history (or null)
+ */
+
+/**
+ * Build a MessageEvent with the WS2 defaults applied. Accepts a partial and
+ * fills `kind` (default "message") + leaves `source`/`thread_context` as
+ * provided. Adapters typically return a full event from `_toEvent`; this
+ * helper is for tests + callers that want the defaults guaranteed.
+ *
+ * @param {Partial<MessageEvent>} partial
+ * @returns {MessageEvent}
+ */
+export function makeMessageEvent(partial = {}) {
+  return {
+    ...partial,
+    kind: normalizeKind(partial.kind),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Self-registering platform registry.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} PlatformDefinition
+ * @property {string} name                The platform name (== channel name), e.g. "telegram".
+ * @property {string} gateFile            Repo-relative gate file whose presence enables the
+ *                                        platform, e.g. "config/telegram.yaml".
+ * @property {(opts:object)=>object} factory  Factory returning an adapter (BaseAdapter subclass).
+ * @property {string[]} [capabilities]    Advertised capability strings.
+ */
+
+/** @type {Map<string, PlatformDefinition>} */
+const PLATFORMS = new Map();
+
+/**
+ * Register a platform. Called at module-eval time at the end of each adapter
+ * file. Idempotent by name: re-defining the same name replaces the prior
+ * definition (so a re-import during tests / hot-reload doesn't throw). The
+ * registry holds *definitions* (factories), not live instances — the daemon
+ * decides which to instantiate based on gate-file presence.
+ *
+ * @param {PlatformDefinition} def
+ * @returns {PlatformDefinition}
+ */
+export function definePlatform(def) {
+  if (!def || typeof def !== "object") throw new Error("definePlatform: def object required");
+  if (!def.name || typeof def.name !== "string") throw new Error("definePlatform: name required");
+  if (!def.gateFile || typeof def.gateFile !== "string") throw new Error("definePlatform: gateFile required");
+  if (typeof def.factory !== "function") throw new Error("definePlatform: factory must be a function");
+  const normalized = {
+    name: def.name,
+    gateFile: def.gateFile,
+    factory: def.factory,
+    capabilities: Array.isArray(def.capabilities) ? def.capabilities.slice() : [],
+  };
+  PLATFORMS.set(def.name, normalized);
+  return normalized;
+}
+
+/** Look up a platform definition by name (undefined when not registered). */
+export function getPlatform(name) {
+  return PLATFORMS.get(name);
+}
+
+/** List every registered platform definition (sorted by name for determinism). */
+export function listPlatforms() {
+  return Array.from(PLATFORMS.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Test/utility helper: drop a registration. */
+export function clearPlatform(name) {
+  return PLATFORMS.delete(name);
+}
+
+// ---------------------------------------------------------------------------
+// Single-owner rule (H2).
+// ---------------------------------------------------------------------------
+//
+// A platform whose real-time connection is owned by a DEDICATED launchd process
+// must NOT also be started by the maestro daemon's generic channel loop —
+// otherwise the channel is ingested TWICE (every DM answered twice).
+//
+//   - "slack" is owned by `ai.maestro.<agent>-slack-socket`
+//     (generate-plists.sh → scripts/poller/slack-socket-mode.mjs), which reads
+//     config/slack.yaml itself for reactions / cc-channels / thread enrichment.
+//
+// This set is the SoT both the daemon (to skip) and any reviewer can consult.
+// Platforms NOT in this set (telegram / whatsapp / voice) have no dedicated
+// plist and ARE daemon-managed.
+export const DEDICATED_PLIST_PLATFORMS = Object.freeze(new Set(["slack"]));
+
+/**
+ * Should the maestro daemon's generic channel loop start this platform itself?
+ * False for platforms with a dedicated launchd owner (see above). Pure.
+ *
+ * @param {string} name platform name (== channel name)
+ * @returns {boolean}
+ */
+export function isDaemonManagedPlatform(name) {
+  return !DEDICATED_PLIST_PLATFORMS.has(name);
+}
+
+export default {
+  EVENT_KINDS,
+  DEFAULT_EVENT_KIND,
+  normalizeKind,
+  makeMessageEvent,
+  definePlatform,
+  getPlatform,
+  listPlatforms,
+  clearPlatform,
+  DEDICATED_PLIST_PLATFORMS,
+  isDaemonManagedPlatform,
+};

package/lib/channels/contract.test.mjs

@@ -0,0 +1,137 @@
+/**
+ * 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", () => {
+  assert.deepEqual([...EVENT_KINDS].sort(), ["call", "channel_cc", "message", "reaction", "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);
+  }
+});

package/lib/channels/conversation-resolver.mjs

@@ -0,0 +1,95 @@
+/**
+ * Maestro — Conversation resolver
+ *
+ * Maps an inbound channel message → { agentId, sessionKey, threadId, channelName }
+ * so the dispatcher can deduplicate across channels and route a Slack-DM
+ * reply, a Gmail thread, a WhatsApp quoted-message, and a voice call to
+ * the same agent session if they belong to the same conversation.
+ *
+ * The resolver is pure (no IO). It accepts a ChannelMessage and returns
+ * a normalised key. Different inputs producing the same key SHOULD be
+ * treated as the same conversation by the daemon's session-lock layer.
+ *
+ * Drawn from the pattern in `openclaw/src/channels/conversation-resolution.ts`
+ * (MIT) but simplified to maestro's needs: we don't need a multi-agent
+ * routing layer because each maestro instance is single-agent.
+ */
+
+/**
+ * Resolve a conversation key for an inbound message.
+ *
+ * @param {import("./channel.mjs").ChannelMessage} msg
+ * @returns {{ channel: string, sessionKey: string, threadId: string, peerId: string }}
+ */
+export function resolveConversation(msg) {
+  if (!msg || typeof msg !== "object") {
+    throw new Error("resolveConversation: msg required");
+  }
+  const channel = String(msg.channel || "unknown").trim().toLowerCase();
+  // Normalise the identity components feeding the session key so that
+  // case-variant or whitespace-padded ids do NOT fork the session.
+  // Emails and ids are case-insensitive for routing purposes; phones are
+  // only trimmed (case has no meaning, casing them is a no-op but trim
+  // strips stray whitespace from upstream adapters).
+  const rawId = msg.from?.id;
+  const rawEmail = msg.from?.email;
+  const rawPhone = msg.from?.phone;
+  const peerId =
+    (rawId != null && String(rawId).trim().toLowerCase()) ||
+    (rawEmail != null && String(rawEmail).trim().toLowerCase()) ||
+    (rawPhone != null && String(rawPhone).trim()) ||
+    "unknown";
+  // threadId logic per channel — preserves existing maestro thread semantics.
+  let threadId;
+  switch (channel) {
+    case "slack":
+      // For Slack we treat thread_ts as the conversation; DMs without a
+      // thread collapse onto `dm:<channel>` so successive messages in
+      // the same DM bind to one session. When the Slack channel id is
+      // absent (some adapter paths omit msg.raw.channel) we fall back to
+      // the peerId so two different DMs do NOT collide on `dm:unknown`.
+      threadId = msg.thread_id || `dm:${msg.raw?.channel || peerId}`;
+      break;
+    case "gmail":
+      threadId = msg.thread_id || msg.in_reply_to || msg.message_id;
+      break;
+    case "whatsapp":
+      threadId = msg.thread_id || msg.in_reply_to || `peer:${peerId}`;
+      break;
+    case "sms":
+      threadId = `peer:${peerId}`;
+      break;
+    case "voice":
+      threadId = msg.thread_id || `call:${msg.message_id}`;
+      break;
+    case "calendar":
+      threadId = msg.thread_id || `event:${msg.message_id}`;
+      break;
+    default:
+      threadId = msg.thread_id || msg.message_id || "unknown";
+  }
+  const sessionKey = `${channel}:${threadId}`;
+  return { channel, sessionKey, threadId, peerId };
+}
+
+/**
+ * Decide whether two messages belong to the same conversation. Useful
+ * for dedup logic in the daemon's inbox processor.
+ */
+export function sameConversation(msgA, msgB) {
+  const a = resolveConversation(msgA);
+  const b = resolveConversation(msgB);
+  return a.sessionKey === b.sessionKey;
+}
+
+/**
+ * Build a deterministic session lock key from a conversation. Mirrors
+ * the keys used by scripts/daemon/session-lock.mjs so the channel bus
+ * can be wired in without breaking existing locks.
+ */
+export function sessionLockKey(msg) {
+  const { channel, threadId } = resolveConversation(msg);
+  return `${channel}:${threadId}`;
+}
+
+export default { resolveConversation, sameConversation, sessionLockKey };

package/lib/channels/gmail/adapter.mjs

@@ -0,0 +1,87 @@
+/**
+ * Maestro — Gmail channel adapter
+ *
+ * Wraps the existing scripts/send-email.sh + Python email helpers in the
+ * Channel interface. Ingestion stays with scripts/poller/gmail-poller.mjs.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+
+const DEFAULT_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.SEND,
+  CHANNEL_CAPABILITIES.THREAD,
+  CHANNEL_CAPABILITIES.MEDIA_IMAGE,
+  CHANNEL_CAPABILITIES.MEDIA_DOCUMENT,
+];
+
+export function createGmailChannel(opts = {}) {
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const sendScript = opts.sendScript || join(agentRoot, "scripts/send-email.sh");
+  const threadedScript = opts.threadedScript || join(agentRoot, "scripts/send-email-threaded.py");
+  const log = opts.log || ((lvl, m) => process.stdout.write(`[gmail-channel:${lvl}] ${m}\n`));
+
+  return {
+    name: "gmail",
+    capabilities: DEFAULT_CAPABILITIES,
+
+    async start({ onInbound }) {
+      if (typeof onInbound !== "function") {
+        throw new Error("Gmail.start: onInbound required");
+      }
+      const inboxDir = join(agentRoot, "state/inbox/gmail");
+      if (!existsSync(inboxDir)) {
+        log("warn", `gmail inbox dir ${inboxDir} not present; running in send-only mode`);
+      }
+    },
+
+    async send(msg) {
+      if (!msg || !msg.to) throw new Error("Gmail.send: msg.to required");
+      if (msg.thread_ref && existsSync(threadedScript)) {
+        // Use the Python threaded sender that preserves Message-ID / In-Reply-To.
+        const args = [
+          threadedScript,
+          "--to", msg.to,
+          "--subject", msg.meta?.subject || "(no subject)",
+          "--body", msg.text || "",
+          "--in-reply-to", String(msg.thread_ref),
+        ];
+        execFileSync("python3", args, {
+          encoding: "utf-8",
+          timeout: 60_000,
+          env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot },
+        });
+        return { message_id: "", raw: { threaded: true } };
+      }
+      if (!existsSync(sendScript)) {
+        throw new Error(`Gmail.send: ${sendScript} not found`);
+      }
+      const args = [
+        msg.to,
+        "--subject", msg.meta?.subject || "(no subject)",
+        "--body", msg.text || "",
+      ];
+      if (msg.meta?.cc) args.push("--cc", msg.meta.cc);
+      if (msg.meta?.bcc) args.push("--bcc", msg.meta.bcc);
+      const out = execFileSync(sendScript, args, {
+        encoding: "utf-8",
+        timeout: 60_000,
+        env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot },
+      });
+      const idMatch = out.match(/Message-ID:\s*<([^>]+)>/i);
+      return { message_id: idMatch?.[1] || "", raw: { stdout: out } };
+    },
+
+    async healthCheck() {
+      const present = existsSync(sendScript);
+      return { ok: present, detail: present ? "send-email.sh present" : `missing ${sendScript}` };
+    },
+
+    async stop() {},
+  };
+}
+
+export default createGmailChannel;