@cohortapp/agent-sdk 2.3.0

package/lib/channels/sms/adapter.mjs

@@ -0,0 +1,43 @@
+/**
+ * Maestro — SMS (Twilio) channel adapter
+ *
+ * Wraps scripts/send-sms.sh + scripts/sms-handler.mjs (Twilio webhook).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+
+export function createSmsChannel(opts = {}) {
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const sendScript = opts.sendScript || join(agentRoot, "scripts/send-sms.sh");
+  return {
+    name: "sms",
+    capabilities: [CHANNEL_CAPABILITIES.SEND],
+
+    async start({ onInbound }) {
+      if (typeof onInbound !== "function") throw new Error("SMS.start: onInbound required");
+    },
+
+    async send(msg) {
+      if (!msg?.to) throw new Error("SMS.send: msg.to (E.164 phone) required");
+      if (!existsSync(sendScript)) throw new Error(`SMS.send: ${sendScript} not found`);
+      const out = execFileSync(sendScript, [msg.to, msg.text || ""], {
+        encoding: "utf-8",
+        timeout: 20_000,
+        env: { ...process.env, AGENT_ROOT: agentRoot },
+      });
+      return { message_id: out.trim(), raw: { stdout: out } };
+    },
+
+    async healthCheck() {
+      const present = existsSync(sendScript);
+      return { ok: present, detail: present ? "send-sms.sh present" : `missing ${sendScript}` };
+    },
+
+    async stop() {},
+  };
+}
+
+export default createSmsChannel;

package/lib/channels/telegram/adapter.mjs

@@ -0,0 +1,432 @@
+/**
+ * Maestro — Telegram channel adapter (grammY, long-poll, no relay)
+ *
+ * Telegram is added via grammY in long-polling mode so it works behind NAT
+ * with no public webhook and no extra process — it runs *inside* the daemon
+ * like baileys. grammY is dynamically imported (mirrors baileys' optional-dep
+ * handling) so the maestro package installs without it; the operator opts in
+ * with `npm i grammy` in the agent repo.
+ *
+ * `_toEvent` maps the grammY update shapes to the unified MessageEvent
+ * contract:
+ *   - DM            update.message in a `private` chat              → message
+ *   - group/topic   update.message in a group; `message_thread_id` → thread
+ *   - reaction      update.message_reaction                        → reaction
+ *   - media         photo/document/etc.                            → attachments
+ *   - voice         update.message.voice → getFile → download → STT → text +
+ *                   a voice_note attachment (same hook baileys uses).
+ *
+ * Outbound: `_send` → bot.api.sendMessage (honours thread_ref/reply),
+ * `_react` → bot.api.setMessageReaction, `_setTyping` → sendChatAction("typing").
+ *
+ * @module lib/channels/telegram/adapter
+ */
+
+"use strict";
+
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+import { definePlatform } from "../contract.mjs";
+import { BaseAdapter } from "../base-adapter.mjs";
+
+const TELEGRAM_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.SEND,
+  CHANNEL_CAPABILITIES.REACT,
+  CHANNEL_CAPABILITIES.THREAD,
+  CHANNEL_CAPABILITIES.MEDIA_IMAGE,
+  CHANNEL_CAPABILITIES.MEDIA_AUDIO,
+  CHANNEL_CAPABILITIES.MEDIA_DOCUMENT,
+  CHANNEL_CAPABILITIES.VOICE_NOTE,
+  CHANNEL_CAPABILITIES.GROUP_CHAT,
+  CHANNEL_CAPABILITIES.MENTIONS,
+  CHANNEL_CAPABILITIES.TYPING_INDICATOR,
+];
+
+let _grammyCache = null;
+/**
+ * Dynamic-import grammY (mirrors adapter-baileys.mjs loadBaileys): resolve
+ * from the agent's node_modules first, then framework-relative, then the bare
+ * specifier. Helpful error when it isn't installed.
+ */
+async function loadGrammy(agentRoot) {
+  if (_grammyCache) return _grammyCache;
+  const candidates = [];
+  if (agentRoot) {
+    candidates.push(`file://${agentRoot}/node_modules/grammy/out/mod.js`);
+    candidates.push(`file://${agentRoot}/node_modules/grammy/out/index.js`);
+    candidates.push(`file://${agentRoot}/node_modules/grammy/dist/esm/mod.js`);
+  }
+  candidates.push("grammy");
+  const errors = [];
+  for (const spec of candidates) {
+    try {
+      const mod = await import(spec);
+      _grammyCache = mod;
+      return mod;
+    } catch (err) {
+      errors.push(`${spec}: ${err.message}`);
+    }
+  }
+  throw new Error(
+    "Telegram requires the `grammy` package installed in the agent repo. " +
+      "Run: `npm i grammy` in your agent repo. " +
+      `Tried resolutions:\n  - ${errors.join("\n  - ")}`
+  );
+}
+
+export class TelegramAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.token]            bot token (else TELEGRAM_BOT_TOKEN)
+   * @param {(buf:Buffer, meta:object)=>Promise<string>} [opts.transcribeVoiceNote]
+   * @param {object} [opts.bot]              injected grammY Bot (tests)
+   * @param {boolean} [opts.transcription]   enable voice→STT (default true)
+   */
+  constructor(opts = {}) {
+    super({ name: "telegram", capabilities: TELEGRAM_CAPABILITIES, ...opts });
+    this.token = opts.token || process.env.TELEGRAM_BOT_TOKEN || "";
+    this.transcribe = typeof opts.transcribeVoiceNote === "function" ? opts.transcribeVoiceNote : null;
+    this.transcriptionEnabled = opts.transcription !== false;
+    /** @type {any} grammY Bot instance */
+    this._bot = opts.bot || null;
+    this._botUsername = opts.botUsername || "";
+    this._botId = opts.botId || "";
+  }
+
+  // -- connect: long-poll via grammY ----------------------------------------
+
+  async _connect({ onRaw, signal }) {
+    if (!this._bot) {
+      const grammy = await loadGrammy(this.agentRoot);
+      const Bot = grammy.Bot || grammy.default;
+      if (!Bot) throw new Error("grammy module did not export Bot");
+      if (!this.token) throw new Error("Telegram: no bot token (set TELEGRAM_BOT_TOKEN or pass opts.token)");
+      this._bot = new Bot(this.token);
+    }
+    const bot = this._bot;
+
+    // Resolve our own bot identity so we can drop self-echo + detect @mentions.
+    try {
+      const me = await bot.api?.getMe?.();
+      if (me) {
+        this._botUsername = me.username || this._botUsername;
+        this._botId = String(me.id || this._botId);
+        if (!this.ownId) this.ownId = this._botId;
+      }
+    } catch { /* getMe is best-effort; tests inject identity */ }
+
+    // grammY's update handlers — we funnel each into onRaw, tagged with a
+    // `_kind` discriminator so _toEvent can branch without re-sniffing.
+    bot.on?.("message", (ctx) => onRaw({ _kind: "message", update: ctx.update, ctx }));
+    bot.on?.("message_reaction", (ctx) => onRaw({ _kind: "reaction", update: ctx.update, ctx }));
+
+    if (signal) signal.addEventListener?.("abort", () => { try { bot.stop?.(); } catch { /* */ } });
+
+    // Long-poll only the update types we handle (no webhook → works behind NAT).
+    // bot.start resolves once polling stops; we DON'T await it (mirrors baileys).
+    const startOpts = { allowed_updates: ["message", "message_reaction"] };
+    if (typeof bot.start === "function") {
+      Promise.resolve(bot.start(startOpts)).catch((err) => this.log("warn", `bot.start ended: ${err.message}`));
+    }
+  }
+
+  // -- translate: grammY update → MessageEvent ------------------------------
+
+  _toEvent(raw) {
+    if (!raw || typeof raw !== "object") return null;
+    if (raw._kind === "reaction") return this._reactionToEvent(raw.update);
+    return this._messageToEvent(raw);
+  }
+
+  _messageToEvent(raw) {
+    const update = raw.update || {};
+    const msg = update.message || update.edited_message;
+    if (!msg) return null;
+
+    const chat = msg.chat || {};
+    const from = msg.from || {};
+    const chatId = String(chat.id ?? "");
+    const fromId = String(from.id ?? "");
+    const isDm = chat.type === "private";
+    const isTopic = !!msg.message_thread_id;
+
+    // Drop the bot's own messages defensively (BaseAdapter also gates on ownId).
+    if (this._botId && fromId === String(this._botId)) return null;
+
+    const userScope = isDm ? "dm" : "group";
+    const threadRef = isTopic ? String(msg.message_thread_id) : "";
+    const replyToRef = msg.reply_to_message?.message_id ? String(msg.reply_to_message.message_id) : "";
+
+    const senderName = telegramDisplayName(from);
+    const channelLabel = isDm ? `dm/${senderName}` : (chat.title ? `${chat.title}` : chatId);
+    const subject = isDm ? `DM from ${senderName}` : `#${chat.title || chatId}`;
+
+    // Body + attachments.
+    let text = typeof msg.text === "string" ? msg.text : (typeof msg.caption === "string" ? msg.caption : "");
+    const attachments = [];
+    let kind = "message";
+
+    if (msg.photo) attachments.push({ type: "image", mime: "image/jpeg" });
+    if (msg.document) attachments.push({ type: "document", mime: msg.document.mime_type || null, filename: msg.document.file_name || null });
+    if (msg.video) attachments.push({ type: "video", mime: msg.video.mime_type || "video/mp4" });
+    if (msg.audio) attachments.push({ type: "audio", mime: msg.audio.mime_type || "audio/mpeg" });
+    if (msg.voice) {
+      kind = "voice_note";
+      attachments.push({
+        type: "voice_note",
+        mime: msg.voice.mime_type || "audio/ogg",
+        size_bytes: msg.voice.file_size || 0,
+        _fileId: msg.voice.file_id, // marker for the async STT pass
+        transcript: "",
+      });
+    }
+
+    // @mention detection (group). entities give exact spans; fall back to text.
+    const mentionsAgent =
+      isDm ||
+      hasBotMention(msg, this._botUsername);
+
+    // channel_cc: a non-directed group message in a watched group. The
+    // membership/directed-gate still governs; we only flag the kind so the
+    // classifier routes it to observe-not-reply.
+    const ccGroups = toIdSet(this.config?.cc_groups);
+    if (!isDm && !mentionsAgent && ccGroups.has(chatId)) {
+      kind = "channel_cc";
+    }
+
+    const ev = {
+      channel: "telegram",
+      service: "telegram",
+      message_id: String(msg.message_id ?? ""),
+      from: { id: fromId, name: senderName, metadata: { username: from.username || "" } },
+      to: { id: chatId },
+      text,
+      attachments: attachments.length ? attachments : undefined,
+      timestamp: msg.date ? new Date(msg.date * 1000).toISOString() : new Date().toISOString(),
+      in_reply_to: replyToRef || undefined,
+      kind,
+      thread_context: null,
+      thread_id: threadRef,
+      raw: msg,
+      sender: senderName,
+      sender_privilege: "unknown",
+      subject,
+      channel_id: chatId,
+      channel_label: channelLabel,
+      is_reply: !!replyToRef || isTopic,
+      priority_signals: {
+        from_ceo: false,
+        tagged_urgent: /\b(urgent|emergency|asap|blocker|critical)\b/i.test(text),
+        contains_deadline: false,
+        mentions_agent: mentionsAgent,
+      },
+      raw_ref: `telegram:${chatId}:${msg.message_id ?? ""}`,
+      ingest_source: "telegram",
+      source: {
+        channel: "telegram",
+        chatId,
+        threadRef: threadRef || undefined,
+        replyToRef: replyToRef || undefined,
+        userScope,
+        peerId: fromId,
+      },
+      // Attach the async-enrichment hook so BaseAdapter.start can be kept pure;
+      // we resolve voice transcripts here before returning when possible.
+      _voiceFileId: msg.voice?.file_id || null,
+    };
+    return ev;
+  }
+
+  _reactionToEvent(update = {}) {
+    const r = update.message_reaction;
+    if (!r) return null;
+    const chat = r.chat || {};
+    const user = r.user || {};
+    const chatId = String(chat.id ?? "");
+    const fromId = String(user.id ?? "");
+    const isDm = chat.type === "private";
+    const emoji = pickReactionEmoji(r.new_reaction);
+    const senderName = telegramDisplayName(user);
+
+    return {
+      channel: "telegram",
+      service: "telegram",
+      message_id: `${r.message_id}-reaction-${fromId}`,
+      from: { id: fromId, name: senderName },
+      to: { id: chatId },
+      text: emoji ? `reacted ${emoji}` : "reacted",
+      timestamp: r.date ? new Date(r.date * 1000).toISOString() : new Date().toISOString(),
+      kind: "reaction",
+      thread_context: null,
+      thread_id: "",
+      raw: r,
+      sender: senderName,
+      sender_privilege: "unknown",
+      subject: `reaction on ${r.message_id}`,
+      channel_id: chatId,
+      channel_label: isDm ? `dm/${senderName}` : (chat.title || chatId),
+      is_reply: false,
+      priority_signals: { from_ceo: false, tagged_urgent: false, contains_deadline: false, mentions_agent: isDm },
+      raw_ref: `telegram:${chatId}:${r.message_id}:reaction`,
+      ingest_source: "telegram",
+      source: {
+        channel: "telegram",
+        chatId,
+        replyToRef: String(r.message_id),
+        userScope: isDm ? "dm" : "group",
+        peerId: fromId,
+      },
+      reaction: { emoji, target_message_id: String(r.message_id) },
+    };
+  }
+
+  // -- voice STT enrichment (fail-open) -------------------------------------
+  //
+  // Override _handleEvent to resolve a voice transcript before the pairing
+  // gate forwards the event, mirroring how baileys surfaces the transcript as
+  // the message body. Background/STT is fail-open: a failure leaves the
+  // transcript empty and the event still flows.
+
+  async _enrichVoice(ev) {
+    if (!ev || !ev._voiceFileId || !this.transcriptionEnabled) return ev;
+    try {
+      const buf = await this._downloadFile(ev._voiceFileId);
+      if (buf && this.transcribe) {
+        const transcript = await this.transcribe(buf, { mime: "audio/ogg" });
+        if (transcript) {
+          ev.text = transcript;
+          if (Array.isArray(ev.attachments)) {
+            const vn = ev.attachments.find((a) => a.type === "voice_note");
+            if (vn) vn.transcript = transcript;
+          }
+        }
+      }
+    } catch (err) {
+      this.log("warn", `voice transcription failed (fail-open): ${err.message}`);
+    }
+    return ev;
+  }
+
+  async _downloadFile(fileId) {
+    const bot = this._bot;
+    if (!bot?.api?.getFile) return null;
+    const file = await bot.api.getFile(fileId);
+    const path = file?.file_path;
+    if (!path) return null;
+    const url = `https://api.telegram.org/file/bot${this.token}/${path}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`getFile download failed: HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  // BaseAdapter calls _handleEvent synchronously; we wrap to do async voice
+  // enrichment first, then defer to the base gate. Voice notes are rare, so
+  // the extra await is acceptable; non-voice events take the fast path.
+  _handleEvent(ev) {
+    if (ev && ev._voiceFileId && this.transcriptionEnabled && this.transcribe) {
+      this._enrichVoice(ev)
+        .then((enriched) => super._handleEvent(enriched))
+        .catch(() => super._handleEvent(ev));
+      return;
+    }
+    super._handleEvent(ev);
+  }
+
+  // -- outbound --------------------------------------------------------------
+
+  async _send(out) {
+    const bot = this._bot;
+    if (!bot?.api?.sendMessage) throw new Error("Telegram not connected — call start() first");
+    const chatId = out.to ?? out.source?.chatId;
+    if (chatId == null) throw new Error("Telegram._send: `to` (chat id) required");
+    const extra = {};
+    const threadRef = out.thread_ref ?? out.source?.threadRef;
+    if (threadRef) extra.message_thread_id = Number(threadRef);
+    const replyTo = out.reply ?? out.source?.replyToRef;
+    if (replyTo) extra.reply_parameters = { message_id: Number(replyTo) };
+    const res = await bot.api.sendMessage(chatId, out.text || "", extra);
+    return { ok: true, message_id: String(res?.message_id ?? ""), raw: res };
+  }
+
+  async _react(out) {
+    const bot = this._bot;
+    if (!bot?.api?.setMessageReaction) return { ok: false, error: "react-not-supported" };
+    const chatId = out.to ?? out.source?.chatId;
+    const messageId = out.messageRef ?? out.reply ?? out.source?.replyToRef;
+    if (chatId == null || messageId == null) return { ok: false, error: "react requires to + messageRef" };
+    const emoji = out.emoji || "👍";
+    await bot.api.setMessageReaction(chatId, Number(messageId), [{ type: "emoji", emoji }]);
+    return { ok: true };
+  }
+
+  async _setTyping(source, on) {
+    const bot = this._bot;
+    if (!on) return; // Telegram typing auto-expires after ~5s; nothing to clear.
+    if (!bot?.api?.sendChatAction) return;
+    const chatId = source?.chatId;
+    if (chatId == null) return;
+    const extra = source?.threadRef ? { message_thread_id: Number(source.threadRef) } : undefined;
+    await bot.api.sendChatAction(chatId, "typing", extra);
+  }
+
+  async healthCheck() {
+    const connected = !!this._bot;
+    return { ok: connected, detail: connected ? `telegram bot ${this._botUsername || this._botId || ""}`.trim() : "not connected" };
+  }
+
+  async stop() {
+    await super.stop();
+    try { await this._bot?.stop?.(); } catch { /* */ }
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function telegramDisplayName(user = {}) {
+  if (user.username) return user.username;
+  const name = [user.first_name, user.last_name].filter(Boolean).join(" ").trim();
+  return name || String(user.id ?? "unknown");
+}
+
+function hasBotMention(msg, botUsername) {
+  if (!botUsername) return false;
+  const handle = `@${botUsername}`.toLowerCase();
+  const text = (msg.text || msg.caption || "").toLowerCase();
+  if (text.includes(handle)) return true;
+  // entity-based mention (text_mention/mention)
+  const entities = msg.entities || msg.caption_entities || [];
+  for (const e of entities) {
+    if (e.type === "mention") {
+      const span = (msg.text || msg.caption || "").slice(e.offset, e.offset + e.length).toLowerCase();
+      if (span === handle) return true;
+    }
+  }
+  return false;
+}
+
+function pickReactionEmoji(newReaction) {
+  if (!Array.isArray(newReaction) || newReaction.length === 0) return "";
+  const first = newReaction[0];
+  return first?.emoji || first?.custom_emoji_id || "";
+}
+
+function toIdSet(v) {
+  if (!v) return new Set();
+  const arr = Array.isArray(v) ? v : [v];
+  return new Set(arr.map((x) => String(x)));
+}
+
+/** Factory matching the channel/platform contract. */
+export function createTelegramChannel(opts = {}) {
+  return new TelegramAdapter(opts);
+}
+
+// Self-register so the daemon's generic platform loop can discover Telegram
+// by the presence of config/telegram.yaml (no core edit).
+definePlatform({
+  name: "telegram",
+  gateFile: "config/telegram.yaml",
+  factory: createTelegramChannel,
+  capabilities: TELEGRAM_CAPABILITIES,
+});
+
+export default createTelegramChannel;