@cohortapp/agent-sdk 2.3.0

package/lib/voice/outbound.mjs

@@ -0,0 +1,542 @@
+/**
+ * Maestro — Outbound voice message dispatcher.
+ *
+ * Delivers a synthesized voice message to a peer over the right transport:
+ *
+ *   WhatsApp (E.164 phone via Baileys)  ── inline voice note (PTT, opus)
+ *   Slack    (channel / DM ID)          ── audio file upload to channel
+ *   PSTN     (E.164 phone via Twilio)   ── one-shot Twilio <Play> call
+ *   Live conversational PSTN            ── Twilio outbound + OpenAI SIP bridge
+ *
+ * The agent doesn't need to know which transport will be picked: the
+ * `to` field is parsed and we route accordingly. Operators can force a
+ * specific transport via the `transport` option.
+ *
+ * Public API:
+ *   sendVoiceMessage(opts) → { transport, message_id, duration_ms, cost_usd }
+ *   placeOutboundCall(opts) → { call_id, twilio_call_sid, status, context_delivered }  (Stage 2)
+ *
+ * Cost notes:
+ *   - TTS: ~$0.015/1k chars (gpt-4o-mini-tts)
+ *   - WhatsApp Baileys send: free (your own WA Web session)
+ *   - Slack upload: free
+ *   - Twilio outbound: ~$0.013-0.014/min for US numbers, varies internationally
+ *   - OpenAI Realtime via SIP: $0.40-0.80/min
+ *
+ * Operator-level safety: this module honours policies/action-classification.yaml
+ * indirectly — it's expected to be called via lib/voice/tool-bridge.mjs or
+ * via the daemon's action-executor, both of which already gate by risk.
+ */
+
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { synthesizeSpeech, pickDefaultVoice, ttsCostEstimate } from "./tts.mjs";
+
+const TWILIO_API_BASE = "https://api.twilio.com/2010-04-01";
+
+// ---------------------------------------------------------------------------
+// Transport detection
+// ---------------------------------------------------------------------------
+
+const E164_REGEX = /^\+[1-9]\d{6,14}$/;
+const SLACK_CHANNEL_REGEX = /^[CDG][A-Z0-9]{8,}$/;     // C/D/G prefix: channel/DM/group
+
+/**
+ * Decide which transport to use for an outbound voice message.
+ *
+ * Order of preference when only `to` is given:
+ *   1. Slack channel/DM id (C/D/G prefix)        → slack
+ *   2. WhatsApp JID ("...@s.whatsapp.net") or
+ *      E.164 phone when WhatsApp is configured   → whatsapp
+ *   3. E.164 phone otherwise                     → pstn (Twilio)
+ */
+export function pickTransport(opts) {
+  if (opts.transport) return opts.transport;
+  const to = String(opts.to || "").trim();
+  if (!to) throw new Error("pickTransport: to required");
+
+  if (to.includes("@s.whatsapp.net") || to.includes("@g.us")) return "whatsapp";
+  if (SLACK_CHANNEL_REGEX.test(to)) return "slack";
+  if (E164_REGEX.test(to)) {
+    // Prefer WhatsApp if the agent has the Baileys auth state populated;
+    // operators can override per-call by passing transport: "pstn".
+    if (opts.agentRoot && existsSync(join(opts.agentRoot, "state/whatsapp/auth/creds.json"))) {
+      return "whatsapp";
+    }
+    return "pstn";
+  }
+  throw new Error(`pickTransport: cannot infer transport for "${to}" (use transport: option to force)`);
+}
+
+// ---------------------------------------------------------------------------
+// sendVoiceMessage — top-level entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} VoiceMessageOpts
+ * @property {string}  to         Destination (E.164, Slack id, or WA jid)
+ * @property {string}  text       Spoken content (max 4096 chars)
+ * @property {string}  [voice]    TTS voice (default: pickDefaultVoice from agent config)
+ * @property {string}  [transport] Force "whatsapp" | "slack" | "pstn" (defaults: auto)
+ * @property {string}  [agentRoot] Agent repo root (default: $AGENT_ROOT)
+ * @property {string}  [model]    TTS model (default: gpt-4o-mini-tts)
+ * @property {string}  [format]   Audio format (default: per-transport)
+ * @property {object}  [meta]     Transport-specific metadata (slack channel id, etc.)
+ */
+
+/**
+ * @param {VoiceMessageOpts} opts
+ * @returns {Promise<{transport, message_id, audio_bytes, cost_usd}>}
+ */
+export async function sendVoiceMessage(opts = {}) {
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const voiceConfig = loadAgentVoiceConfig(agentRoot);
+  const transport = pickTransport({ ...opts, agentRoot });
+
+  // Per-transport defaults: WhatsApp wants opus PTT, Slack/PSTN are fine with mp3.
+  const fmt = opts.format || (transport === "whatsapp" ? "opus" : "mp3");
+  const voice = opts.voice || pickDefaultVoice(voiceConfig);
+
+  const audio = await synthesizeSpeech({
+    text: opts.text,
+    voice,
+    format: fmt,
+    model: opts.model,
+  });
+  const costUsd = ttsCostEstimate(opts.text, opts.model);
+
+  switch (transport) {
+    case "whatsapp": {
+      const result = await deliverViaWhatsApp({ to: opts.to, audio, fmt, agentRoot, text: opts.text });
+      return { transport, ...result, cost_usd: costUsd };
+    }
+    case "slack": {
+      const result = await deliverViaSlack({ to: opts.to, audio, fmt, agentRoot, text: opts.text, meta: opts.meta });
+      return { transport, ...result, cost_usd: costUsd };
+    }
+    case "pstn": {
+      const result = await deliverViaPSTN({ to: opts.to, audio, fmt, agentRoot, text: opts.text });
+      return { transport, ...result, cost_usd: costUsd };
+    }
+    default:
+      throw new Error(`sendVoiceMessage: unknown transport "${transport}"`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WhatsApp (Baileys) — sends an inline voice note (PTT)
+// ---------------------------------------------------------------------------
+
+async function deliverViaWhatsApp({ to, audio, fmt, agentRoot, text }) {
+  // Reuse the channel-bus registry — the daemon already keeps a Baileys
+  // session alive there. We import lazily so this module doesn't pull
+  // baileys for non-WA use cases.
+  const channelsMod = await import("../channels/index.mjs");
+  let channel = channelsMod.getChannel?.("whatsapp");
+  if (!channel) {
+    throw new Error(
+      "WhatsApp channel not registered. Either rename config/whatsapp.yaml.disabled → .yaml " +
+        "and restart the daemon, or pass transport: 'pstn' for Twilio."
+    );
+  }
+  if (typeof channel.send !== "function") {
+    throw new Error("WhatsApp channel has no send() method");
+  }
+  // Cache the audio to disk for replay/audit.
+  const outboundDir = join(agentRoot, "state/whatsapp/outbound");
+  mkdirSync(outboundDir, { recursive: true });
+  const filename = `${Date.now()}-voice-${slugify(text).slice(0, 24)}.${fmt}`;
+  writeFileSync(join(outboundDir, filename), audio);
+
+  const result = await channel.send({
+    to,
+    text: text, // human-readable fallback if the recipient's client can't play audio
+    attachments: [
+      {
+        type: "voice_note",
+        mime: fmt === "opus" ? "audio/ogg; codecs=opus" : "audio/mpeg",
+        buffer: audio,
+      },
+    ],
+  });
+  return {
+    message_id: result?.message_id || filename,
+    audio_bytes: audio.length,
+    cached_at: join(outboundDir, filename),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Slack — uploads the audio as a file attachment
+// ---------------------------------------------------------------------------
+
+async function deliverViaSlack({ to, audio, fmt, agentRoot, text: textArg, meta }) {
+  // Coerce text defensively: callers may pass null/undefined/non-string and we
+  // immediately .slice() it for the filename / title / initial_comment below.
+  const text = String(textArg || "");
+  const token = process.env.SLACK_USER_TOKEN || process.env.SLACK_BOT_TOKEN || process.env.SLACK_TOKEN;
+  if (!token) throw new Error("Slack delivery requires SLACK_USER_TOKEN or SLACK_BOT_TOKEN");
+
+  const ext = fmt === "opus" ? "ogg" : fmt;
+  const filename = `voice-${slugify(text).slice(0, 32)}.${ext}`;
+
+  // Slack's modern flow: files.getUploadURLExternal → PUT audio → files.completeUploadExternal
+  // We use it because files.upload was deprecated in 2024.
+  const getUrl = `https://slack.com/api/files.getUploadURLExternal?length=${audio.length}&filename=${encodeURIComponent(filename)}`;
+  const getResp = await (await fetch(getUrl, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+  })).json();
+  if (!getResp.ok) throw new Error(`slack getUploadURL failed: ${JSON.stringify(getResp)}`);
+
+  const putResp = await fetch(getResp.upload_url, {
+    method: "POST",
+    headers: { "Content-Type": fmt === "opus" ? "audio/ogg" : "audio/mpeg" },
+    body: audio,
+  });
+  if (!putResp.ok) throw new Error(`slack file upload failed: HTTP ${putResp.status}`);
+
+  const completeBody = {
+    files: [{ id: getResp.file_id, title: text.slice(0, 80) }],
+    channel_id: to,
+    initial_comment: text,
+  };
+  if (meta?.thread_ref) completeBody.thread_ts = meta.thread_ref;
+
+  const completeResp = await (await fetch("https://slack.com/api/files.completeUploadExternal", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(completeBody),
+  })).json();
+  if (!completeResp.ok) throw new Error(`slack files.completeUploadExternal: ${JSON.stringify(completeResp)}`);
+
+  return {
+    message_id: getResp.file_id,
+    audio_bytes: audio.length,
+    file_url: completeResp.files?.[0]?.permalink || null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PSTN (Twilio) — one-shot outbound call that plays the synthesized audio
+// ---------------------------------------------------------------------------
+
+async function deliverViaPSTN({ to, audio, fmt, agentRoot, text: textArg }) {
+  // Coerce text defensively: it is fed to slugify()/escapeXml() below, both of
+  // which expect a string (escapeXml in particular does text.replace()).
+  const text = String(textArg || "");
+  const sid = process.env.TWILIO_ACCOUNT_SID;
+  const token = process.env.TWILIO_AUTH_TOKEN;
+  const fromNumber = process.env.TWILIO_FROM_NUMBER || process.env.TWILIO_VOICE_FROM;
+  if (!sid || !token) throw new Error("PSTN delivery requires TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN");
+  if (!fromNumber) throw new Error("PSTN delivery requires TWILIO_FROM_NUMBER or TWILIO_VOICE_FROM");
+
+  // For Twilio <Play>, the audio must be reachable via a public HTTPS URL.
+  // We host it ourselves at the voice-webhook server's /voice/audio/<id>
+  // endpoint, which the voice-webhook server should serve. For now we
+  // fall back to Twilio's <Say> TwiML so the call works without a tunnel
+  // — the user gets the message spoken by Twilio's TTS instead of our
+  // higher-quality OpenAI TTS. Operators with a public webhook URL can
+  // configure VOICE_PUBLIC_BASE_URL to use <Play> instead.
+  const publicBase = process.env.VOICE_PUBLIC_BASE_URL;
+  let twiml;
+  if (publicBase) {
+    // Cache the audio and reference it via <Play>.
+    const cacheDir = join(agentRoot, "state/voice/outbound-audio");
+    mkdirSync(cacheDir, { recursive: true });
+    const audioId = `${Date.now()}-${slugify(text).slice(0, 16)}`;
+    const filename = `${audioId}.${fmt === "opus" ? "ogg" : fmt}`;
+    writeFileSync(join(cacheDir, filename), audio);
+    const audioUrl = `${publicBase.replace(/\/$/, "")}/voice/audio/${filename}`;
+    twiml = `<?xml version="1.0" encoding="UTF-8"?><Response><Play>${audioUrl}</Play></Response>`;
+  } else {
+    // Fall back to Twilio Say (Twilio synthesizes from text directly).
+    const safe = escapeXml(text);
+    twiml = `<?xml version="1.0" encoding="UTF-8"?><Response><Say voice="Polly.Joanna">${safe}</Say></Response>`;
+  }
+
+  const auth = Buffer.from(`${sid}:${token}`).toString("base64");
+  const params = new URLSearchParams({ To: to, From: fromNumber, Twiml: twiml });
+  const r = await fetch(`${TWILIO_API_BASE}/Accounts/${sid}/Calls.json`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${auth}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: params.toString(),
+  });
+  const data = await r.json();
+  if (!r.ok) throw new Error(`twilio call failed: ${JSON.stringify(data)}`);
+  return {
+    message_id: data.sid,
+    audio_bytes: audio.length,
+    twilio_status: data.status,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stage 2 — placeOutboundCall: live conversational PSTN via SIP bridge
+// ---------------------------------------------------------------------------
+
+/**
+ * Place an outbound PSTN call and bridge it to OpenAI Realtime for a
+ * live conversation. The agent's "brief" is loaded as the session
+ * instructions so the model knows what to say.
+ *
+ * Two transports (auto-selected based on env config):
+ *
+ * 1. **media_streams** (DEFAULT, recommended) — The Twilio call uses
+ *    TwiML <Connect><Stream> to open a WebSocket to our Railway voice
+ *    cloud-relay. The relay opens a parallel WebSocket to OpenAI's
+ *    Realtime API and bridges audio bidirectionally (g711_ulaw on
+ *    both sides — no transcoding). Works without OpenAI dashboard
+ *    SIP config and without OpenAI accepting inbound INVITES from
+ *    Twilio's outbound infrastructure.
+ *    Requires: VOICE_RELAY_URL, VOICE_TWIML_TOKEN, OPENAI_API_KEY (on Railway).
+ *
+ * 2. **sip** (legacy / experimental) — TwiML <Dial><Sip>OpenAI</Sip>.
+ *    Requires OpenAI's project to accept inbound SIP INVITES from
+ *    arbitrary Twilio outbound — which empirically does not work
+ *    today (Twilio's outbound SIP gets rejected by OpenAI for missing
+ *    auth/registration). Kept for future when OpenAI documents the
+ *    auth scheme.
+ *    Requires: OPENAI_SIP_URI or TWILIO_SIP_TRUNK_DOMAIN.
+ *
+ * @param {{ to: string, brief: string, agentRoot?: string, voice?: string,
+ *           transport?: "media_streams"|"sip", cancelOnContextFail?: boolean }} opts
+ *   cancelOnContextFail: when true, hard-cancel the dialed call if the brief
+ *   could not be pre-registered with the relay (default false — call proceeds
+ *   with the relay's fallback prompt, and context_delivered:false is returned).
+ * @returns {Promise<{ call_id, twilio_call_sid, status, transport,
+ *   context_delivered: boolean }>}
+ *   context_delivered is false when a media_streams brief failed to register
+ *   with the relay; true otherwise (including sip / no-relay paths that do not
+ *   pre-register context).
+ */
+export async function placeOutboundCall(opts = {}) {
+  const sid = process.env.TWILIO_ACCOUNT_SID;
+  const token = process.env.TWILIO_AUTH_TOKEN;
+  const fromNumber = process.env.TWILIO_FROM_NUMBER || process.env.TWILIO_VOICE_FROM;
+  if (!sid || !token || !fromNumber) {
+    throw new Error("placeOutboundCall requires TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER");
+  }
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+
+  // Pick transport. Default to media_streams when relay is configured
+  // (it's the only one that empirically works today). Fall back to SIP
+  // only when explicitly requested.
+  const relayUrl = (process.env.VOICE_RELAY_URL || "").replace(/\/$/, "");
+  const twimlToken = process.env.VOICE_TWIML_TOKEN || "";
+  const transport = opts.transport || (relayUrl ? "media_streams" : "sip");
+
+  const callId = `out-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  // Persist brief locally (always — for audit + later post-call processing)
+  const briefsDir = join(agentRoot, "state/voice/outbound-briefs");
+  mkdirSync(briefsDir, { recursive: true });
+  writeFileSync(join(briefsDir, `${callId}.json`), JSON.stringify({
+    call_id: callId,
+    to: opts.to,
+    brief: opts.brief,
+    voice: opts.voice || "cedar",
+    transport,
+    created_at: new Date().toISOString(),
+  }, null, 2));
+
+  // For media_streams, we use URL-based TwiML — Twilio fetches the TwiML
+  // from /twilio/twiml when the call connects, instead of us passing it
+  // inline. This gives us a server-side log of every TwiML request
+  // (proving Twilio is actually reaching Railway) and avoids any
+  // inline-TwiML parsing quirks.
+  let twiml = null;
+  let twimlUrl = null;
+  if (transport === "media_streams") {
+    if (!relayUrl) {
+      throw new Error("placeOutboundCall(media_streams) requires VOICE_RELAY_URL");
+    }
+    const tokenQp = twimlToken ? `?token=${encodeURIComponent(twimlToken)}` : "";
+    twimlUrl = `${relayUrl}/twilio/twiml${tokenQp}`;
+  } else if (transport === "sip") {
+    const sipTarget = process.env.OPENAI_SIP_URI || process.env.TWILIO_SIP_TRUNK_DOMAIN;
+    if (!sipTarget) {
+      throw new Error("placeOutboundCall(sip) requires OPENAI_SIP_URI or TWILIO_SIP_TRUNK_DOMAIN");
+    }
+    const baseUri = sipTarget.startsWith("sip:") ? sipTarget : `sip:${sipTarget}`;
+    const sipUri = `${baseUri}?X-Maestro-Call-Id=${encodeURIComponent(callId)}`;
+    twiml = `<?xml version="1.0" encoding="UTF-8"?><Response><Dial><Sip>${escapeXml(sipUri)}</Sip></Dial></Response>`;
+  } else {
+    throw new Error(`unknown transport: ${transport}`);
+  }
+
+  // Initiate the call via Twilio. Use Url= (Twilio fetches TwiML from
+  // our endpoint) for media_streams so we get a server-side log of every
+  // TwiML request; use Twiml= (inline) for SIP since there's no benefit
+  // to a round-trip there.
+  const auth = Buffer.from(`${sid}:${token}`).toString("base64");
+  const params = new URLSearchParams({ To: opts.to, From: fromNumber });
+  if (twimlUrl) {
+    params.set("Url", twimlUrl);
+    params.set("Method", "GET");
+  } else {
+    params.set("Twiml", twiml);
+  }
+  const r = await fetch(`${TWILIO_API_BASE}/Accounts/${sid}/Calls.json`, {
+    method: "POST",
+    headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/x-www-form-urlencoded" },
+    body: params.toString(),
+  });
+  const data = await r.json();
+  if (!r.ok) throw new Error(`twilio outbound failed: ${JSON.stringify(data)}`);
+
+  // For media_streams transport: pre-register this call's session config
+  // with the relay so it's ready when Twilio connects.
+  //
+  // Critical: we build the FULL contextual system prompt locally (agent
+  // identity from config/agent.json, top queue items, recent decisions,
+  // RAG hits, peer history, voice-mode rules) and ship it to Railway.
+  // The relay only injects strings into session.update — it has no
+  // access to ravi-ai's filesystem, so all context must come from here.
+  // Whether the call's context (system prompt / identity) successfully
+  // pre-registered with the relay. For transports that don't pre-register
+  // (sip, or media_streams with no relay) there is nothing to deliver, so the
+  // call is not context-dependent and this stays true. For media_streams with
+  // a relay it reflects the real outcome of the queue-outbound POST so callers
+  // can decide whether to keep the dialed call or hang up.
+  let contextDelivered = true;
+  if (transport === "media_streams" && relayUrl) {
+    contextDelivered = false;
+    let instructions = null;
+    try {
+      const ctxLoader = await import("./context-loader.mjs");
+      instructions = await ctxLoader.buildContextualInstructions({
+        agentRoot,
+        peer: opts.to,
+        callKind: "outbound",
+        brief: opts.brief,
+      });
+    } catch (err) {
+      // Fallback: hand-crafted minimal prompt that at least disambiguates
+      // who's the agent vs the caller. Better than nothing.
+      const id = opts.identity || {};
+      instructions = [
+        `# Identity`,
+        `You are ${id.fullName || id.name || "the agent"}, ${id.role || "an executive operator"} at ${id.company || "the company"}.`,
+        ``,
+        `# Your task on this call`,
+        `${opts.brief}`,
+        ``,
+        `# Caller`,
+        `You are calling ${opts.peer_name || opts.to}. They picked up. Greet them by name (NOT by your own name) and proceed with the task above.`,
+        ``,
+        `# Voice mode rules`,
+        `- Speak briefly: 1-2 sentences before pausing.`,
+        `- Confirm the listener can hear you on first turn.`,
+        `- If asked to invoke a high-risk action, read back the parameters and get verbal confirmation in the same turn before doing it.`,
+      ].join("\n");
+      console.warn(`[outbound] context-loader failed (${err.message}) — using fallback prompt`);
+    }
+
+    try {
+      const queueResp = await fetch(`${relayUrl}/twilio/queue-outbound`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...(twimlToken ? { Authorization: `Bearer ${twimlToken}` } : {}),
+        },
+        body: JSON.stringify({
+          call_sid: data.sid,
+          call_id: callId,
+          peer: opts.to,
+          peer_name: opts.peer_name || opts.to,
+          brief: opts.brief,
+          // Full pre-loaded system prompt (identity + memory + RAG + rules)
+          instructions,
+          voice: opts.voice || "cedar",
+          model: opts.model || "gpt-realtime-2",
+          identity: opts.identity || null,
+          tools: opts.tools || [],
+        }),
+      });
+      if (queueResp.ok) {
+        contextDelivered = true;
+      } else {
+        const errText = await queueResp.text();
+        console.warn(`[outbound] failed to queue brief at relay: HTTP ${queueResp.status} ${errText.slice(0, 200)}`);
+      }
+    } catch (err) {
+      console.warn(`[outbound] queue-outbound failed: ${err.message}`);
+    }
+
+    // The call is already dialing at this point. If the brief could not be
+    // pre-registered the relay will fall back to its own default prompt, so the
+    // model would speak without this agent's identity/brief. Operators can opt
+    // in to hard-cancelling the dialed call in that case via cancelOnContextFail
+    // (default off — preserves the existing "let the call proceed" behaviour).
+    if (!contextDelivered && opts.cancelOnContextFail) {
+      await cancelTwilioCall({ sid, token, callSid: data.sid }).catch((err) => {
+        console.warn(`[outbound] failed to cancel call after context-delivery failure: ${err.message}`);
+      });
+    }
+  }
+
+  return {
+    call_id: callId,
+    twilio_call_sid: data.sid,
+    status: data.status,
+    transport,
+    context_delivered: contextDelivered,
+  };
+}
+
+/**
+ * Best-effort cancel of an in-flight Twilio call (sets Status=completed).
+ * Used when a media_streams brief could not be pre-registered and the operator
+ * asked us not to let a context-less call proceed.
+ *
+ * @param {{ sid: string, token: string, callSid: string }} args
+ */
+async function cancelTwilioCall({ sid, token, callSid }) {
+  const auth = Buffer.from(`${sid}:${token}`).toString("base64");
+  const r = await fetch(`${TWILIO_API_BASE}/Accounts/${sid}/Calls/${encodeURIComponent(callSid)}.json`, {
+    method: "POST",
+    headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ Status: "completed" }).toString(),
+  });
+  if (!r.ok) {
+    const t = await r.text();
+    throw new Error(`twilio cancel failed: HTTP ${r.status} ${t.slice(0, 200)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function loadAgentVoiceConfig(agentRoot) {
+  const path = join(agentRoot, "config/voice.yaml");
+  if (!existsSync(path)) return {};
+  try {
+    // Tolerant minimal parse — we only need the top-level `voice:` key.
+    const body = readFileSync(path, "utf-8");
+    const m = body.match(/^voice:\s*([^\s#]+)/m);
+    return { voice: m ? m[1].trim() : null };
+  } catch {
+    return {};
+  }
+}
+
+function slugify(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function escapeXml(s) {
+  return String(s).replace(/[<>&"']/g, (c) => ({
+    "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;",
+  }[c]));
+}
+
+export default { sendVoiceMessage, placeOutboundCall, pickTransport };

package/lib/voice/outbound.test.mjs

@@ -0,0 +1,69 @@
+/**
+ * outbound.test.mjs — node:test coverage for outbound voice.
+ *
+ * No real network: synthesizeSpeech, Baileys, Slack, Twilio all stubbed
+ * via dependency injection / process.env manipulation.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { pickTransport } from "./outbound.mjs";
+import { pickDefaultVoice, ttsCostEstimate } from "./tts.mjs";
+
+// ---------------------------------------------------------------------------
+// pickTransport
+// ---------------------------------------------------------------------------
+
+test("pickTransport: explicit override wins", () => {
+  assert.equal(pickTransport({ to: "+14155551234", transport: "pstn" }), "pstn");
+  assert.equal(pickTransport({ to: "C12345678", transport: "whatsapp" }), "whatsapp");
+});
+
+test("pickTransport: Slack channel id (C/D/G prefix)", () => {
+  assert.equal(pickTransport({ to: "C012345678" }), "slack");
+  assert.equal(pickTransport({ to: "D099N1JE7NE" }), "slack");
+  assert.equal(pickTransport({ to: "GABC123456" }), "slack");
+});
+
+test("pickTransport: WhatsApp JID", () => {
+  assert.equal(pickTransport({ to: "447825004124@s.whatsapp.net" }), "whatsapp");
+  assert.equal(pickTransport({ to: "120363041234567890@g.us" }), "whatsapp");
+});
+
+test("pickTransport: E.164 without WA → pstn", () => {
+  // agentRoot pointing at a tmp dir without state/whatsapp/auth/creds.json
+  assert.equal(pickTransport({ to: "+14155551234", agentRoot: "/tmp/no-wa-here-xyz" }), "pstn");
+});
+
+test("pickTransport: refuses ambiguous targets", () => {
+  assert.throws(() => pickTransport({ to: "" }), /to required/);
+  assert.throws(() => pickTransport({ to: "Alex" }), /cannot infer/);
+  assert.throws(() => pickTransport({ to: "alex@example.com" }), /cannot infer/);
+});
+
+// ---------------------------------------------------------------------------
+// TTS helpers
+// ---------------------------------------------------------------------------
+
+test("pickDefaultVoice: maps Realtime-only voices to TTS equivalents", () => {
+  assert.equal(pickDefaultVoice({ voice: "cedar" }), "ash");
+  assert.equal(pickDefaultVoice({ voice: "marin" }), "shimmer");
+});
+
+test("pickDefaultVoice: passes through valid TTS voices", () => {
+  for (const v of ["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse"]) {
+    assert.equal(pickDefaultVoice({ voice: v }), v);
+  }
+});
+
+test("pickDefaultVoice: fallback to alloy on unknown/empty", () => {
+  assert.equal(pickDefaultVoice({}), "alloy");
+  assert.equal(pickDefaultVoice({ voice: "nonexistent" }), "alloy");
+});
+
+test("ttsCostEstimate: matches OpenAI's $0.015/1k chars", () => {
+  assert.equal(ttsCostEstimate(""), 0);
+  assert.equal(ttsCostEstimate("x".repeat(1000)), 0.015);
+  assert.equal(ttsCostEstimate("x".repeat(10000)), 0.15);
+});