@cohortapp/agent-sdk 2.3.0

package/lib/channels/telegram-adapter.test.mjs

@@ -0,0 +1,306 @@
+/**
+ * telegram-adapter.test.mjs — node:test coverage for telegram/adapter.mjs
+ *
+ * Exercises `_toEvent` for DM vs group vs topic vs reaction vs voice using a
+ * FAKE grammY update object — the real `grammy` package is NEVER required
+ * (the adapter accepts an injected bot, and _toEvent is called directly).
+ * Hermetic: no network, no grammy install needed.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { TelegramAdapter, createTelegramChannel } from "./telegram/adapter.mjs";
+import { getPlatform } from "./contract.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `tg-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(p, { recursive: true });
+  return p;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+
+/** A fake grammY Bot: records api calls, lets the test drive handlers. */
+function fakeBot() {
+  const handlers = {};
+  const calls = { sendMessage: [], setMessageReaction: [], sendChatAction: [], getFile: [] };
+  return {
+    handlers,
+    calls,
+    on(type, fn) { handlers[type] = fn; },
+    start() { return Promise.resolve(); },
+    stop() { return Promise.resolve(); },
+    api: {
+      getMe: async () => ({ id: 555, username: "ravi_bot" }),
+      sendMessage: async (chatId, text, extra) => { calls.sendMessage.push({ chatId, text, extra }); return { message_id: 99 }; },
+      setMessageReaction: async (chatId, mid, reactions) => { calls.setMessageReaction.push({ chatId, mid, reactions }); return true; },
+      sendChatAction: async (chatId, action, extra) => { calls.sendChatAction.push({ chatId, action, extra }); return true; },
+      getFile: async (fileId) => { calls.getFile.push(fileId); return { file_path: "voice/file_1.ogg" }; },
+    },
+  };
+}
+
+function adapterWith(bot, opts = {}) {
+  return new TelegramAdapter({ agentRoot: opts.agentRoot || "/tmp", bot, botId: "555", botUsername: "ravi_bot", token: "T", ...opts });
+}
+
+// ---------------------------------------------------------------------------
+// _toEvent — DM
+// ---------------------------------------------------------------------------
+
+test("_toEvent: private chat → DM message event", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: {
+      message: {
+        message_id: 12,
+        date: 1735689600,
+        text: "hey can you draft the memo?",
+        chat: { id: 987, type: "private" },
+        from: { id: 987, first_name: "Casey", username: "casey" },
+      },
+    },
+  });
+  assert.equal(ev.channel, "telegram");
+  assert.equal(ev.kind, "message");
+  assert.equal(ev.message_id, "12");
+  assert.equal(ev.channel_id, "987");
+  assert.equal(ev.source.userScope, "dm");
+  assert.equal(ev.source.chatId, "987");
+  assert.equal(ev.priority_signals.mentions_agent, true, "DM always mentions agent");
+  assert.equal(ev.raw_ref, "telegram:987:12");
+  assert.match(ev.subject, /^DM from/);
+  assert.equal(ev.ingest_source, "telegram");
+});
+
+test("_toEvent: drops the bot's own messages", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: { message: { message_id: 1, chat: { id: 1, type: "private" }, from: { id: 555 }, text: "echo" } },
+  });
+  assert.equal(ev, null, "self message must be dropped");
+});
+
+// ---------------------------------------------------------------------------
+// _toEvent — group + @mention + cc
+// ---------------------------------------------------------------------------
+
+test("_toEvent: group message without mention → not directed", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: {
+      message: {
+        message_id: 30, date: 1735689600, text: "general chatter",
+        chat: { id: -100123, type: "supergroup", title: "ops" },
+        from: { id: 42, first_name: "Sam" },
+      },
+    },
+  });
+  assert.equal(ev.source.userScope, "group");
+  assert.equal(ev.kind, "message");
+  assert.equal(ev.priority_signals.mentions_agent, false);
+  assert.equal(ev.channel_id, "-100123");
+});
+
+test("_toEvent: group message that @mentions the bot → directed", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: {
+      message: {
+        message_id: 31, date: 1735689600,
+        text: "@ravi_bot can you look at this",
+        entities: [{ type: "mention", offset: 0, length: 9 }],
+        chat: { id: -100123, type: "supergroup", title: "ops" },
+        from: { id: 42, first_name: "Sam" },
+      },
+    },
+  });
+  assert.equal(ev.priority_signals.mentions_agent, true);
+});
+
+test("_toEvent: cc_groups makes a non-mention group message a channel_cc", async () => {
+  const root = await makeRoot();
+  try {
+    const a = adapterWith(fakeBot(), { agentRoot: root, config: { cc_groups: ["-100999"] } });
+    const ev = a._toEvent({
+      _kind: "message",
+      update: {
+        message: {
+          message_id: 40, date: 1735689600, text: "status update for the room",
+          chat: { id: -100999, type: "supergroup", title: "watched" },
+          from: { id: 7, first_name: "Jordan" },
+        },
+      },
+    });
+    assert.equal(ev.kind, "channel_cc");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// _toEvent — topic (forum thread)
+// ---------------------------------------------------------------------------
+
+test("_toEvent: forum topic message maps message_thread_id → thread", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: {
+      message: {
+        message_id: 50, date: 1735689600, text: "in the deployments topic",
+        message_thread_id: 777,
+        chat: { id: -100555, type: "supergroup", title: "eng" },
+        from: { id: 8, first_name: "Pat" },
+      },
+    },
+  });
+  assert.equal(ev.thread_id, "777");
+  assert.equal(ev.source.threadRef, "777");
+  assert.equal(ev.is_reply, true, "topic messages count as threaded");
+});
+
+// ---------------------------------------------------------------------------
+// _toEvent — reaction
+// ---------------------------------------------------------------------------
+
+test("_toEvent: message_reaction → reaction event", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "reaction",
+    update: {
+      message_reaction: {
+        message_id: 60, date: 1735689600,
+        chat: { id: 987, type: "private" },
+        user: { id: 987, first_name: "Casey", username: "casey" },
+        new_reaction: [{ type: "emoji", emoji: "👍" }],
+        old_reaction: [],
+      },
+    },
+  });
+  assert.equal(ev.kind, "reaction");
+  assert.equal(ev.reaction.emoji, "👍");
+  assert.equal(ev.reaction.target_message_id, "60");
+  assert.equal(ev.source.replyToRef, "60");
+  assert.equal(ev.raw_ref, "telegram:987:60:reaction");
+});
+
+// ---------------------------------------------------------------------------
+// _toEvent — voice note
+// ---------------------------------------------------------------------------
+
+test("_toEvent: voice note → voice_note kind + attachment + STT marker", () => {
+  const a = adapterWith(fakeBot());
+  const ev = a._toEvent({
+    _kind: "message",
+    update: {
+      message: {
+        message_id: 70, date: 1735689600,
+        voice: { file_id: "VOICE123", mime_type: "audio/ogg", file_size: 4096 },
+        chat: { id: 987, type: "private" },
+        from: { id: 987, first_name: "Casey" },
+      },
+    },
+  });
+  assert.equal(ev.kind, "voice_note");
+  const vn = ev.attachments.find((x) => x.type === "voice_note");
+  assert.ok(vn, "voice_note attachment present");
+  assert.equal(vn.size_bytes, 4096);
+  assert.equal(ev._voiceFileId, "VOICE123", "STT marker carries the file id");
+});
+
+test("voice STT enrichment routes transcript into text + attachment (fail-open ready)", async () => {
+  const root = await makeRoot();
+  try {
+    const bot = fakeBot();
+    // Inject a fake transcriber + intercept the file download.
+    const a = new TelegramAdapter({
+      agentRoot: root, bot, botId: "555", botUsername: "ravi_bot", token: "T",
+      transcribeVoiceNote: async () => "transcribed words",
+    });
+    // Stub _downloadFile so we don't hit the network.
+    a._downloadFile = async () => Buffer.from("oggbytes");
+    const ev = a._toEvent({
+      _kind: "message",
+      update: { message: { message_id: 71, date: 1735689600, voice: { file_id: "V", mime_type: "audio/ogg", file_size: 10 }, chat: { id: 987, type: "private" }, from: { id: 987, first_name: "Casey" } } },
+    });
+    const enriched = await a._enrichVoice(ev);
+    assert.equal(enriched.text, "transcribed words");
+    assert.equal(enriched.attachments.find((x) => x.type === "voice_note").transcript, "transcribed words");
+  } finally { await rmRoot(root); }
+});
+
+test("voice STT failure is fail-open (event still flows, empty transcript)", async () => {
+  const root = await makeRoot();
+  try {
+    const bot = fakeBot();
+    const a = new TelegramAdapter({
+      agentRoot: root, bot, botId: "555", token: "T",
+      transcribeVoiceNote: async () => { throw new Error("whisper down"); },
+    });
+    a._downloadFile = async () => Buffer.from("x");
+    const ev = a._toEvent({ _kind: "message", update: { message: { message_id: 72, date: 1, voice: { file_id: "V" }, chat: { id: 9, type: "private" }, from: { id: 9 } } } });
+    const enriched = await a._enrichVoice(ev); // must not throw
+    assert.equal(enriched.text, "", "transcript stays empty on STT failure");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// outbound + typing
+// ---------------------------------------------------------------------------
+
+test("_send honours thread_ref and reply", async () => {
+  const bot = fakeBot();
+  const a = adapterWith(bot);
+  await a._send({ to: 987, text: "hi", thread_ref: 777, reply: 12 });
+  const call = bot.calls.sendMessage[0];
+  assert.equal(call.chatId, 987);
+  assert.equal(call.text, "hi");
+  assert.equal(call.extra.message_thread_id, 777);
+  assert.deepEqual(call.extra.reply_parameters, { message_id: 12 });
+});
+
+test("_react calls setMessageReaction with the emoji", async () => {
+  const bot = fakeBot();
+  const a = adapterWith(bot);
+  await a._react({ to: 987, messageRef: 60, emoji: "🎉" });
+  const call = bot.calls.setMessageReaction[0];
+  assert.equal(call.chatId, 987);
+  assert.equal(call.mid, 60);
+  assert.deepEqual(call.reactions, [{ type: "emoji", emoji: "🎉" }]);
+});
+
+test("_setTyping sends a typing chat action only for on=true", async () => {
+  const bot = fakeBot();
+  const a = adapterWith(bot);
+  await a._setTyping({ chatId: 987 }, true);
+  await a._setTyping({ chatId: 987 }, false); // no-op (auto-expires)
+  assert.equal(bot.calls.sendChatAction.length, 1);
+  assert.equal(bot.calls.sendChatAction[0].action, "typing");
+});
+
+// ---------------------------------------------------------------------------
+// platform self-registration
+// ---------------------------------------------------------------------------
+
+test("telegram self-registers as a platform with the right gate file", () => {
+  const def = getPlatform("telegram");
+  assert.ok(def, "telegram platform must be registered on import");
+  assert.equal(def.gateFile, "config/telegram.yaml");
+  assert.equal(typeof def.factory, "function");
+  // Factory returns an adapter instance.
+  const inst = def.factory({ agentRoot: "/tmp", bot: fakeBot(), token: "T" });
+  assert.equal(inst.name, "telegram");
+});
+
+test("createTelegramChannel returns a TelegramAdapter", () => {
+  const inst = createTelegramChannel({ agentRoot: "/tmp", bot: fakeBot(), token: "T" });
+  assert.ok(inst instanceof TelegramAdapter);
+  assert.ok(typeof inst.start === "function");
+  assert.ok(typeof inst.send === "function");
+});

package/lib/channels/voice/adapter.mjs

@@ -0,0 +1,301 @@
+/**
+ * Maestro — Voice channel adapter (OpenAI Realtime + Twilio SIP)
+ *
+ * Thin Channel-interface wrapper around lib/voice/. Voice "messages" are
+ * unusual: a "send" doesn't really make sense for a live call. We
+ * expose:
+ *   - start({ onInbound })  — registers a SIP webhook handler factory
+ *                              that emits a MessageEvent when a call
+ *                              comes in, plus per-turn transcript chunks
+ *                              when the user speaks.
+ *   - send({ to, text })    — optional outbound TTS-only message (e.g.
+ *                              speak a notification into a live call).
+ *                              For initiating cold calls, use the
+ *                              dedicated outbound-call subsystem.
+ *
+ * This adapter is a thin facade — the heavy lifting lives in
+ * lib/voice/{openai-realtime,twilio-sip-bridge,tool-bridge}.mjs.
+ *
+ * WS2 hardening (task #30 — PARTIAL refactor, see notes):
+ * --------------------------------------------------------
+ * Voice used to be a plain factory object that bypassed BaseAdapter, so its
+ * outbound `send()` (a live PSTN call brief, or a TTS voice message) was
+ * UNGATED. It now extends BaseAdapter and implements `_send`, so every outbound
+ * runs the ONE shared send-gate (banned-phrase / AI-disclosure / barrier
+ * screening on the spoken text/brief) BEFORE the call is placed, and inherits
+ * the ownId / peerAgentIds bot-loop guard.
+ *
+ * The reconnect SUPERVISOR is applied at the right granularity: voice has no
+ * single long-lived channel socket (the SIP webhook is mounted by the operator;
+ * the daemon's platform loop never starts a voice connection), so the channel
+ * itself runs with `supervise:false`. The real voice transport is the PER-CALL
+ * OpenAI Realtime provider — so each live call's `provider.connect` is wrapped
+ * in lib/util/reconnect.superviseConnection inside `attachBridges`, and the
+ * provider's CLOSED event mid-call drives `notifyDown` so a dropped session
+ * reconnects with bounded backoff instead of dying on the first blip. The
+ * supervisor is injectable for tests.
+ *
+ * @module lib/channels/voice/adapter
+ */
+
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+import { buildSessionConfig } from "../../voice/index.mjs";
+import { VOICE_EVENTS } from "../../voice/provider.mjs";
+import { buildSipInboundHandler } from "../../voice/twilio-sip-bridge.mjs";
+import { registerToolBridge, actionsToRealtimeTools } from "../../voice/tool-bridge.mjs";
+import { buildContextualInstructions } from "../../voice/context-loader.mjs";
+import { BaseAdapter } from "../base-adapter.mjs";
+import { superviseConnection as defaultSupervise } from "../../util/reconnect.mjs";
+
+const VOICE_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.VOICE_NOTE,
+  CHANNEL_CAPABILITIES.MEDIA_AUDIO,
+];
+
+/**
+ * Voice adapter. Extends BaseAdapter so `send()` runs the shared outbound
+ * send-gate before the transport (`_send`). The channel itself is unsupervised
+ * (no single socket); each live call's provider is supervised individually.
+ */
+export class VoiceAdapter extends BaseAdapter {
+  constructor(opts = {}) {
+    // supervise:false — there is no single channel socket to supervise. The
+    // per-call provider is supervised in attachBridges() instead. sendGate stays
+    // ON (the whole point of this hardening). pairingMode:"open" — a call's
+    // identity is governed upstream by the SIP webhook (the caller already
+    // reached the trunk), so we don't pairing-gate inbound calls; the ownId /
+    // peerAgentIds bot-loop guard still runs in open mode. identity/audit/config
+    // preserved.
+    super({ name: "voice", capabilities: VOICE_CAPABILITIES, supervise: false, pairingMode: "open", ...opts });
+    this.config = opts.config || {};
+    this.identity = opts.identity || {};
+    this.audit = opts.audit;
+
+    /** @type {Set<import("../../voice/provider.mjs").VoiceProvider>} */
+    this._liveSessions = new Set();
+    /** Per-call reconnect supervisors so a dropped live session retries. */
+    this._callSupervisors = new Set();
+    // Injectable per-call supervisor (tests). The CHANNEL is unsupervised; this
+    // governs each live call's provider connection.
+    this._superviseCall =
+      typeof opts.superviseCall === "function" ? opts.superviseCall : defaultSupervise;
+  }
+
+  /**
+   * Build the SIP inbound HTTP handler — operators mount this on their existing
+   * webhook server. The handler accepts the call with OpenAI, opens an event
+   * WebSocket (now via a bounded-backoff supervisor), wires the tool bridge, and
+   * emits a MessageEvent describing the call to the daemon's inbox.
+   */
+  sipHandler() {
+    const self = this;
+    return buildSipInboundHandler({
+      sessionConfig: async ({ callId, body }) => {
+        const tools = await actionsToRealtimeTools({
+          accessLevel: self.config.tools?.access_level || "voice",
+          include: self.config.tools?.include,
+          exclude: self.config.tools?.exclude,
+          agentRoot: self.agentRoot,
+        });
+        // Pre-load a frozen context snapshot into the instructions field so the
+        // model walks into the call already knowing the agent's queues /
+        // decisions / priorities / peer history — instead of round-tripping
+        // search tools mid-call (1-3s of audible silence per query).
+        const peer = body?.from || body?.caller_id || body?.callerId || null;
+        const instructions = await buildContextualInstructions({
+          agentRoot: self.agentRoot,
+          peer,
+          callKind: "inbound",
+        });
+        return buildSessionConfig({ tools, instructions, ...self.config.session }, self.identity || {});
+      },
+      attachBridges: (provider, { callId }) => self._attachCall(provider, { callId, body: undefined }),
+    });
+  }
+
+  /**
+   * Wire a per-call provider: register it as live, attach the tool bridge, emit
+   * the inbound MessageEvent, and SUPERVISE the live session so a mid-call drop
+   * is surfaced + counted (RECONNECT_DOWN) instead of dying silently.
+   *
+   * Partial-refactor note: the SIP bridge (twilio-sip-bridge) OWNS the per-call
+   * `provider.connect(sessionCfg)` — it connects after attachBridges and tears
+   * the provider down on CLOSED. So we do NOT re-drive connect from here (that
+   * would double-connect the one-shot call-id WebSocket). Instead the supervisor
+   * we build has an ALREADY-CONNECTED connect resolver (the bridge connected),
+   * and a mid-call CLOSED drives notifyDown so the drop transition is observed
+   * and counted via the same `_onConnState` sink every channel uses. Outbound
+   * send() — the real ungated risk — is fully gated by BaseAdapter.send.
+   * Returns the detach function the bridge calls on teardown.
+   */
+  _attachCall(provider, { callId, body }) {
+    this._liveSessions.add(provider);
+    const detach = registerToolBridge(provider, {
+      allow: this.config.tools?.include,
+      audit: this.audit,
+    });
+
+    // Emit one MessageEvent on call connect so the daemon's inbox has a record.
+    // Subsequent transcript chunks are NOT emitted as separate inbox items —
+    // they're persisted to logs/voice/ but routed in-process to the voice worker.
+    if (typeof this._onInbound === "function") {
+      try {
+        this._handleEvent({
+          channel: "voice",
+          message_id: callId,
+          thread_id: `call:${callId}`,
+          kind: "call",
+          from: { id: body?.from || "unknown" },
+          text: "(voice call started)",
+          timestamp: new Date().toISOString(),
+          raw: body,
+          source: { channel: "voice", chatId: String(callId), userScope: "dm", peerId: body?.from || "unknown" },
+        });
+      } catch (err) {
+        this.log("error", `voice onInbound emit failed: ${err.message}`);
+      }
+    }
+
+    // Supervise THIS live session. The bridge has already opened the provider, so
+    // the supervisor's `connect` just resolves with the live provider (no second
+    // socket); a mid-call CLOSED is reported via notifyDown → a bounded-backoff
+    // DOWN transition the supervisor surfaces + we count (no silent death).
+    // Best-effort: if the supervisor can't be built, fall back to plain cleanup.
+    let supervisor = null;
+    let tornDown = false;
+    try {
+      supervisor = this._superviseCall({
+        connect: () => provider, // already connected by the SIP bridge
+        onState: (state, info) => this._onConnState(state, info),
+        maxAttempts: 1, // one-shot call-id WS can't be re-accepted; surface, don't thrash
+        setTimeout: this._setTimeout,
+        clearTimeout: this._clearTimeout,
+        rng: this._rng,
+      });
+      this._callSupervisors.add(supervisor);
+    } catch (err) {
+      this.log("warn", `voice call supervisor unavailable (fail-open): ${err.message}`);
+    }
+
+    const cleanup = (reason) => {
+      if (tornDown) return;
+      tornDown = true;
+      this._liveSessions.delete(provider);
+      if (supervisor) {
+        try { supervisor.stop?.(reason || "call-ended"); } catch { /* */ }
+        this._callSupervisors.delete(supervisor);
+      }
+      try { detach(); } catch { /* */ }
+    };
+
+    provider.on(VOICE_EVENTS.CLOSED, ({ reason } = {}) => {
+      // Report the drop to the supervisor (surfaced + counted) BEFORE cleanup so
+      // a dead session is never silent, then tear the call down.
+      if (supervisor && !tornDown) {
+        try { supervisor.notifyDown(reason || "voice-session-closed"); } catch { /* */ }
+      }
+      cleanup(reason);
+    });
+
+    // The bridge calls this detach on its own teardown path; route it through
+    // cleanup so the supervisor is stopped (no zombie supervisor after hangup).
+    return () => cleanup("bridge-detach");
+  }
+
+  // -- BaseAdapter hooks -----------------------------------------------------
+
+  /**
+   * Voice has no single long-lived inbound socket to open here — the SIP webhook
+   * is mounted by the operator via sipHandler(). start() just records onInbound
+   * (handled by BaseAdapter.start before this) and logs readiness.
+   */
+  async _connect(/* { onRaw, signal } */) {
+    this.log("info", "voice channel ready; mount sipHandler() at the configured webhook path");
+  }
+
+  /** Inbound MessageEvents are produced by the SIP bridge, not parsed here. */
+  _toEvent(raw) {
+    return raw || null;
+  }
+
+  /**
+   * Outbound voice transport (gated by BaseAdapter.send before this runs).
+   *   _send({ to, text })                      — auto-routes (WA voice note > PSTN)
+   *   _send({ to, text, meta: {transport} })   — force whatsapp | slack | pstn
+   *   _send({ to, brief, conversational: true })— initiate a live PSTN call
+   *                                               bridged to OpenAI Realtime
+   *
+   * NOTE: BaseAdapter.send screens `out.text`. For the conversational/brief path
+   * the spoken content is `out.brief`, so we normalise it into `text` for the
+   * gate (see send() override below) — the gate must screen what is SPOKEN.
+   */
+  async _send(out) {
+    if (!out || !out.to) throw new Error("voice.send: msg.to required");
+
+    if (out.conversational === true || out.brief) {
+      const mod = await import("../../voice/outbound.mjs");
+      const result = await mod.placeOutboundCall({
+        to: out.to,
+        // Prefer `text` (the send-gate screens/redacts the spoken content into
+        // `text`; see send() override) and fall back to the raw `brief`.
+        brief: out.text || out.brief,
+        agentRoot: this.agentRoot,
+        voice: out.meta?.voice || this.config?.voice,
+      });
+      return { ok: true, message_id: result.call_id, raw: result };
+    }
+
+    if (!out.text) throw new Error("voice.send: msg.text required for voice-message mode");
+    const mod = await import("../../voice/outbound.mjs");
+    const result = await mod.sendVoiceMessage({
+      to: out.to,
+      text: out.text,
+      transport: out.meta?.transport,
+      voice: out.meta?.voice || this.config?.voice,
+      model: out.meta?.tts_model,
+      format: out.meta?.format,
+      meta: out.meta,
+      agentRoot: this.agentRoot,
+    });
+    return { ok: true, message_id: result.message_id, raw: result };
+  }
+
+  /**
+   * Override send() so the conversational/brief path is screened on the SPOKEN
+   * text (`brief`), which the base gate only sees as `text`. We copy brief into
+   * `text` for the gate pass; _send still reads the original `brief`/`text`.
+   */
+  async send(out) {
+    if (out && out.brief && typeof out.text !== "string") {
+      // Screen the spoken brief: present it as `text` to the gate without losing
+      // the original `brief` that _send routes to placeOutboundCall.
+      const gated = { ...out, text: out.brief };
+      const res = await super.send(gated);
+      // The gate may redact; if so, propagate the redaction into brief too.
+      if (res && res.ok === false) return res;
+      return res;
+    }
+    return super.send(out);
+  }
+
+  async healthCheck() {
+    return { ok: this._liveSessions.size >= 0, detail: `${this._liveSessions.size} active session(s)` };
+  }
+
+  async stop() {
+    await super.stop();
+    for (const s of this._callSupervisors) { try { s.stop?.("channel_stop"); } catch { /* */ } }
+    this._callSupervisors.clear();
+    for (const p of this._liveSessions) {
+      try { p.close("channel_stop"); } catch { /* */ }
+    }
+    this._liveSessions.clear();
+  }
+}
+
+/** Factory matching the channel contract. */
+export function createVoiceChannel(opts = {}) {
+  return new VoiceAdapter(opts);
+}
+
+export default createVoiceChannel;