@cohortapp/agent-sdk 2.3.0

package/lib/channels/voice/adapter.test.mjs

@@ -0,0 +1,278 @@
+/**
+ * adapter.test.mjs — Voice channel adapter as a BaseAdapter subclass.
+ * Run: node --test lib/channels/voice/adapter.test.mjs
+ *
+ * Task #30 hardening (PARTIAL refactor — see adapter docblock): the voice
+ * adapter 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, so:
+ *   - send() runs the ONE shared send-gate on the SPOKEN text/brief BEFORE the
+ *     call/message is placed (banned-phrase / AI-disclosure / barrier screening);
+ *   - inbound from the agent itself / a peer agent is dropped (bot-loop guard);
+ *   - each live call's provider is supervised so a mid-call drop is surfaced +
+ *     counted (RECONNECT_DOWN) instead of dying silently.
+ *
+ * Hermetic: no Twilio, no OpenAI, no network. The outbound transport (_send) is
+ * overridden in a test subclass so a clean send is observed without placing a
+ * real call; the per-call supervisor is injected.
+ */
+"use strict";
+
+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 { EventEmitter } from "node:events";
+
+import { createVoiceChannel, VoiceAdapter } from "./adapter.mjs";
+import { CHANNEL_COUNTERS } from "../base-adapter.mjs";
+import { CONN_STATE } from "../../util/reconnect.mjs";
+import { VOICE_EVENTS } from "../../voice/provider.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `voice-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 VoiceAdapter whose _send is recorded (not really placing a call) so we can
+ * assert the gate path and outbound routing without Twilio/OpenAI.
+ */
+class RecordingVoice extends VoiceAdapter {
+  constructor(opts) { super(opts); this.sent = []; }
+  async _send(out) { this.sent.push(out); return { ok: true, message_id: "rec-1", raw: { out } }; }
+}
+
+function makeVoice(opts = {}) {
+  const counters = [];
+  const a = new (opts.cls || RecordingVoice)({
+    agentRoot: opts.agentRoot,
+    bump: (name, attrs) => { counters.push({ name, attrs }); return 1; },
+    screenOutbound: opts.screenOutbound || (async () => ({ allow: true, reason: "" })),
+    ...opts,
+  });
+  return { a, counters, countOf: (name) => counters.filter((c) => c.name === name).length };
+}
+
+// ---------------------------------------------------------------------------
+// shape
+// ---------------------------------------------------------------------------
+
+test("createVoiceChannel returns a VoiceAdapter (BaseAdapter subclass)", () => {
+  const ch = createVoiceChannel({ agentRoot: "/tmp/x" });
+  assert.ok(ch instanceof VoiceAdapter);
+  assert.equal(ch.name, "voice");
+  assert.equal(typeof ch.start, "function");
+  assert.equal(typeof ch.send, "function");
+  assert.equal(typeof ch.sipHandler, "function");
+});
+
+// ---------------------------------------------------------------------------
+// send-gate (P0-3) — every voice send is screened before the transport runs
+// ---------------------------------------------------------------------------
+
+test("send() blocks a banned-phrase TTS message before the transport", async () => {
+  const root = await makeRoot();
+  try {
+    const { a, countOf } = makeVoice({ agentRoot: root, screenOutbound: undefined });
+    a._screenOutbound = (await import("../../comms/send-gate.mjs")).screenOutbound;
+    const res = await a.send({
+      to: "+14155550123",
+      text: "Sure — as an AI I can read that to you.",
+      source: { channel: "voice", chatId: "+14155550123" },
+    });
+    assert.equal(res.ok, false);
+    assert.equal(res.blocked, true);
+    assert.match(res.reason, /banned AI-tell|As an AI/i);
+    assert.equal(a.sent.length, 0, "the transport must never run for a blocked message");
+    assert.equal(countOf(CHANNEL_COUNTERS.SEND_GATE_BLOCKED), 1);
+  } finally { await rmRoot(root); }
+});
+
+test("send() screens the SPOKEN brief on the conversational call path (blocks a disclosure violation)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeVoice({ agentRoot: root, screenOutbound: undefined });
+    a._screenOutbound = (await import("../../comms/send-gate.mjs")).screenOutbound;
+    // brief — not text — carries what is spoken; the gate must still see it.
+    const res = await a.send({
+      to: "+14155550123",
+      brief: "Open by saying: I'm not a bot, I'm a real person.",
+      conversational: true,
+      source: { channel: "voice", chatId: "+14155550123" },
+    });
+    assert.equal(res.ok, false);
+    assert.equal(res.blocked, true);
+    assert.match(res.reason, /disclosure|denies AI/i);
+    assert.equal(a.sent.length, 0, "a disclosure-violating brief never places a call");
+  } finally { await rmRoot(root); }
+});
+
+test("send() lets a clean TTS message reach the transport with the right args", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeVoice({ agentRoot: root }); // allow-all gate stub
+    const res = await a.send({ to: "C012345678", text: "your 3pm is confirmed", meta: { transport: "slack" } });
+    assert.equal(res.ok, true);
+    assert.equal(a.sent.length, 1);
+    assert.equal(a.sent[0].to, "C012345678");
+    assert.equal(a.sent[0].text, "your 3pm is confirmed");
+  } finally { await rmRoot(root); }
+});
+
+test("send() lets a clean conversational brief reach the transport (brief routed through)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeVoice({ agentRoot: root });
+    const res = await a.send({ to: "+14155550123", brief: "remind them about the board pack", conversational: true });
+    assert.equal(res.ok, true);
+    assert.equal(a.sent.length, 1);
+    // The override copies brief→text for the gate; _send reads text||brief.
+    assert.equal(a.sent[0].text || a.sent[0].brief, "remind them about the board pack");
+  } finally { await rmRoot(root); }
+});
+
+test("_send requires `to`", async () => {
+  // Use the REAL _send (via a bare VoiceAdapter) but only the validation branch.
+  const a = new VoiceAdapter({ agentRoot: "/tmp", screenOutbound: async () => ({ allow: true }) });
+  await assert.rejects(() => a._send({ text: "hi" }), /to required/);
+});
+
+// ---------------------------------------------------------------------------
+// per-call supervision (P0-6) — a mid-call provider drop is surfaced + counted
+// ---------------------------------------------------------------------------
+
+test("a live-call provider CLOSED reports the drop to the per-call supervisor (counted)", async () => {
+  const root = await makeRoot();
+  try {
+    // Inject a fake per-call supervisor so the drop lifecycle is deterministic.
+    let cfg = null;
+    let downReason = null;
+    let stopped = false;
+    const fakeSuperviseCall = (c) => {
+      cfg = c;
+      Promise.resolve().then(() => c.connect()).then(() => c.onState(CONN_STATE.UP, { attempt: 1, reconnected: false }));
+      return {
+        notifyDown: (reason) => { downReason = reason; c.onState(CONN_STATE.DOWN, { attempt: 1, delayMs: 500, reason }); },
+        stop: () => { stopped = true; },
+        get state() { return CONN_STATE.DOWN; }, get connection() { return null; }, get attempts() { return 0; },
+        started: Promise.resolve(),
+      };
+    };
+    const { a, countOf } = makeVoice({ agentRoot: root, superviseCall: fakeSuperviseCall });
+    await a.start({ onInbound: () => {} });
+
+    // Stand in a fake provider (EventEmitter) and attach a call.
+    const provider = new EventEmitter();
+    provider.connect = async () => {};
+    provider.close = () => {};
+    a._attachCall(provider, { callId: "call-1", body: { from: "+1999" } });
+    assert.ok(cfg, "a per-call supervisor was built");
+    assert.equal(a._liveSessions.size, 1, "the call is tracked live");
+
+    // The provider drops mid-call.
+    provider.emit(VOICE_EVENTS.CLOSED, { reason: "ws-closed" });
+    assert.match(String(downReason), /ws-closed/, "the drop was reported to the supervisor");
+    assert.equal(countOf(CHANNEL_COUNTERS.RECONNECT_DOWN), 1, "the drop was counted (not silent)");
+    assert.equal(stopped, true, "the supervisor is stopped on teardown (no zombie)");
+    assert.equal(a._liveSessions.size, 0, "the dropped session is removed");
+  } finally { await rmRoot(root); }
+});
+
+test("the per-call supervisor falls back cleanly if it can't be built (fail-open)", async () => {
+  const root = await makeRoot();
+  try {
+    const throwingSupervise = () => { throw new Error("no supervisor"); };
+    const { a } = makeVoice({ agentRoot: root, superviseCall: throwingSupervise });
+    await a.start({ onInbound: () => {} });
+    const provider = new EventEmitter();
+    provider.connect = async () => {};
+    provider.close = () => {};
+    assert.doesNotThrow(() => a._attachCall(provider, { callId: "c2", body: {} }));
+    // A close still tears the session down cleanly.
+    provider.emit(VOICE_EVENTS.CLOSED, { reason: "x" });
+    assert.equal(a._liveSessions.size, 0);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// bot-loop guard — an inbound call from a peer agent is dropped
+// ---------------------------------------------------------------------------
+
+test("a call-connect event from a peer agent is dropped (bot-loop guard)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a, countOf } = makeVoice({ agentRoot: root, peerAgentIds: ["+1888"], superviseCall: () => ({ notifyDown(){}, stop(){}, get state(){return CONN_STATE.UP;}, get connection(){return null;}, get attempts(){return 0;}, started: Promise.resolve() }) });
+    const received = [];
+    await a.start({ onInbound: (ev) => received.push(ev) });
+    const provider = new EventEmitter();
+    provider.connect = async () => {};
+    provider.close = () => {};
+    a._attachCall(provider, { callId: "c3", body: { from: "+1888" } });
+    assert.equal(received.length, 0, "a peer-agent call must not be auto-handled");
+    assert.equal(countOf(CHANNEL_COUNTERS.PEER_AGENT_DROPPED), 1);
+  } finally { await rmRoot(root); }
+});
+
+test("a call-connect event from a human flows to onInbound", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeVoice({ agentRoot: root, superviseCall: () => ({ notifyDown(){}, stop(){}, get state(){return CONN_STATE.UP;}, get connection(){return null;}, get attempts(){return 0;}, started: Promise.resolve() }) });
+    const received = [];
+    await a.start({ onInbound: (ev) => received.push(ev) });
+    const provider = new EventEmitter();
+    provider.connect = async () => {};
+    provider.close = () => {};
+    a._attachCall(provider, { callId: "c4", body: { from: "+1777" } });
+    assert.equal(received.length, 1, "a human call connect is recorded in the inbox");
+    assert.equal(received[0].kind, "call");
+    assert.equal(received[0].message_id, "c4");
+    assert.equal(received[0].source.channel, "voice");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// facade behaviour preserved
+// ---------------------------------------------------------------------------
+
+test("sipHandler() returns a function (the mounted webhook handler)", () => {
+  // buildSipInboundHandler asserts OPENAI_API_KEY is present (same as before the
+  // refactor) — set a dummy so we can assert the handler shape without network.
+  const prev = process.env.OPENAI_API_KEY;
+  process.env.OPENAI_API_KEY = "sk-test-dummy";
+  try {
+    const a = createVoiceChannel({ agentRoot: "/tmp/x" });
+    assert.equal(typeof a.sipHandler(), "function");
+  } finally {
+    if (prev === undefined) delete process.env.OPENAI_API_KEY;
+    else process.env.OPENAI_API_KEY = prev;
+  }
+});
+
+test("healthCheck reports the live-session count", async () => {
+  const a = createVoiceChannel({ agentRoot: "/tmp/x" });
+  const hc = await a.healthCheck();
+  assert.equal(hc.ok, true);
+  assert.match(hc.detail, /0 active session/);
+});
+
+test("stop() closes live sessions and stops their supervisors", async () => {
+  const root = await makeRoot();
+  try {
+    let stopped = 0;
+    const { a } = makeVoice({ agentRoot: root, superviseCall: () => ({ notifyDown(){}, stop(){ stopped += 1; }, get state(){return CONN_STATE.UP;}, get connection(){return null;}, get attempts(){return 0;}, started: Promise.resolve() }) });
+    await a.start({ onInbound: () => {} });
+    let closed = false;
+    const provider = new EventEmitter();
+    provider.connect = async () => {};
+    provider.close = () => { closed = true; };
+    a._attachCall(provider, { callId: "c5", body: {} });
+    await a.stop();
+    assert.equal(closed, true, "the live provider was closed");
+    assert.equal(stopped >= 1, true, "the per-call supervisor was stopped");
+    assert.equal(a._liveSessions.size, 0);
+  } finally { await rmRoot(root); }
+});