@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/voice-webhook-server.mjs

@@ -0,0 +1,804 @@
+#!/usr/bin/env node
+/**
+ * voice-webhook-server.mjs — HTTP/WebSocket server for the voice channel.
+ *
+ * Sits between external audio sources (Twilio SIP, browser widgets,
+ * Media Streams) and OpenAI Realtime. Started as its own launchd job
+ * (ai.maestro.<agent>-voice-webhook.plist) so it stays up independently
+ * of the reactive daemon — voice calls shouldn't drop when the agent
+ * daemon restarts.
+ *
+ * Mounted endpoints (all configurable in `config/voice.yaml`):
+ *   POST  /voice/sip/incoming  — OpenAI's `realtime.call.incoming` webhook
+ *                                 (native SIP path). Hands the call to
+ *                                 lib/voice/twilio-sip-bridge.mjs.
+ *   POST  /voice/twiml         — Twilio Voice webhook returns TwiML
+ *                                 `<Connect><Stream>` for Media Streams.
+ *   WS    /voice/stream        — Twilio Media Streams audio frames.
+ *   WS    /voice/browser       — Direct browser WebSocket (HTML widget).
+ *   GET   /voice/token         — Mints an ephemeral OpenAI client_secret
+ *                                 for browser-side WebRTC.
+ *   GET   /voice/test          — Minimal HTML widget for manual testing.
+ *   GET   /health              — Health check.
+ *
+ * Auth model:
+ *   - Twilio webhooks: validated via X-Twilio-Signature when
+ *     TWILIO_AUTH_TOKEN is set.
+ *   - Browser endpoints: protected by a static bearer token from
+ *     VOICE_BROWSER_TOKEN (set in .env). The /voice/test page injects
+ *     it; external callers pass it in `Authorization: Bearer …`.
+ *
+ * Failure mode: every handler is wrapped so a fault in one endpoint
+ * doesn't take the whole server down. Failures emit structured logs
+ * via console.log/console.error captured by launchd's redirect.
+ */
+
+import http from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+// Framework primitives are colocated with this script via `npx @cohortapp/agent-sdk upgrade`
+// (which ships lib/ into the agent repo). Imports are done as bare relative paths
+// (../../lib/...) so the agent never depends on a separate /Users/<u>/maestro checkout.
+
+// Source .env from the agent repo. launchd's bare environment doesn't
+// include OPENAI_API_KEY / TWILIO_AUTH_TOKEN / VOICE_BROWSER_TOKEN — and
+// we don't want to put secrets in the plist. Minimal parser; honours
+// `KEY=value` lines and ignores comments / blanks.
+function loadDotEnv(path) {
+  if (!existsSync(path)) return;
+  for (const raw of readFileSync(path, "utf-8").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    // Strip surrounding quotes if present.
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    if (key && !(key in process.env)) process.env[key] = val;
+  }
+}
+loadDotEnv(join(AGENT_DIR, ".env"));
+
+const PORT = parseInt(process.env.VOICE_WEBHOOK_PORT || "3200", 10);
+
+// ---------------------------------------------------------------------------
+// Load voice config
+// ---------------------------------------------------------------------------
+
+let voiceConfig = {};
+const voiceCfgPath = join(AGENT_DIR, "config/voice.yaml");
+if (!existsSync(voiceCfgPath)) {
+  console.error(`[voice-webhook] config/voice.yaml not present — exiting.`);
+  process.exit(0);
+}
+try {
+  const yaml = await import("js-yaml");
+  voiceConfig = yaml.load(readFileSync(voiceCfgPath, "utf-8"));
+} catch (err) {
+  console.error(`[voice-webhook] failed to parse voice.yaml: ${err.message}`);
+  process.exit(78);
+}
+
+const inbound = voiceConfig.inbound || {};
+const sipEnabled = inbound.twilio_sip?.enabled === true;
+const streamsEnabled = inbound.twilio_media_streams?.enabled === true;
+const browserEnabled = inbound.browser_ws?.enabled === true;
+
+// ---------------------------------------------------------------------------
+// Singleton + identity
+// ---------------------------------------------------------------------------
+
+try {
+  const { acquireLock } = await import("../../lib/singleton.js");
+  if (!acquireLock("voice-webhook")) {
+    console.log("[voice-webhook] already running — exiting");
+    process.exit(0);
+  }
+} catch { /* singleton unavailable — proceed without */ }
+
+let identity = { name: "Agent", role: "agent", company: "Northwind" };
+try {
+  const aj = JSON.parse(readFileSync(join(AGENT_DIR, "config/agent.json"), "utf-8"));
+  identity = {
+    name: aj.firstName || "Agent",
+    role: aj.title || "agent",
+    company: aj.company || "Northwind",
+  };
+} catch { /* fall through */ }
+
+// ---------------------------------------------------------------------------
+// Load framework modules
+// ---------------------------------------------------------------------------
+
+const { buildSessionConfig } = await import("../../lib/voice/index.mjs");
+const { actionsToRealtimeTools, registerToolBridge } = await import("../../lib/voice/tool-bridge.mjs");
+const sipBridge = await import("../../lib/voice/twilio-sip-bridge.mjs");
+const { createOpenAIRealtimeProvider } = await import("../../lib/voice/openai-realtime.mjs");
+const { buildContextualInstructions } = await import("../../lib/voice/context-loader.mjs");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function nowIso() { return new Date().toISOString(); }
+function log(level, msg, extra = {}) {
+  console.log(JSON.stringify({ ts: nowIso(), level, msg, ...extra }));
+}
+
+function respond(res, status, body, contentType = "application/json") {
+  res.writeHead(status, { "Content-Type": contentType });
+  res.end(typeof body === "string" ? body : JSON.stringify(body));
+}
+
+// Translate a legacy session config (flat: voice + input_audio_format +
+// turn_detection at top level) into the GA `{session:{audio:{input,output}}}`
+// shape required by /v1/realtime/client_secrets.
+function toGASessionShape(legacy) {
+  const fmtMap = {
+    pcm16: { type: "audio/pcm", rate: 24000 },
+    g711_ulaw: { type: "audio/pcmu" },
+    g711_alaw: { type: "audio/pcma" },
+  };
+  const inputFmt = fmtMap[legacy.input_audio_format] || { type: "audio/pcm", rate: 24000 };
+  const outputFmt = fmtMap[legacy.output_audio_format] || { type: "audio/pcm", rate: 24000 };
+  return {
+    session: {
+      type: "realtime",
+      model: legacy.model,
+      output_modalities: legacy.output_modalities || ["audio"],
+      instructions: legacy.instructions,
+      tools: legacy.tools || [],
+      tool_choice: legacy.tool_choice || "auto",
+      audio: {
+        input: {
+          format: inputFmt,
+          transcription: legacy.input_audio_transcription || null,
+          turn_detection: legacy.turn_detection || null,
+        },
+        output: {
+          format: outputFmt,
+          voice: legacy.voice || "cedar",
+        },
+      },
+    },
+  };
+}
+
+async function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    req.on("data", (c) => { buf += c; });
+    req.on("end", () => resolve(buf));
+    req.on("error", reject);
+  });
+}
+
+function verifyTwilioSignature(req, rawBody) {
+  // Twilio signs: HMAC-SHA1(authToken, url + sorted form params).
+  // For JSON bodies we sign url + raw body as documented in
+  // https://www.twilio.com/docs/usage/webhooks/webhooks-security
+  const token = process.env.TWILIO_AUTH_TOKEN;
+  const sig = req.headers["x-twilio-signature"];
+  if (!token || !sig) return !token; // when no token configured, accept (dev mode)
+  const url = `https://${req.headers.host}${req.url}`;
+  const data = url + (rawBody || "");
+  const expected = createHmac("sha1", token).update(data).digest("base64");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(sig);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Verify an OpenAI webhook signature. OpenAI signs realtime webhook
+ * payloads using HMAC-SHA256 with the webhook's signing secret. The
+ * signature header is `openai-signature: <hex>` (or sometimes
+ * `webhook-signature: t=<ts>,v1=<hex>` depending on the API era).
+ * We accept either format. Configure the secret via OPENAI_WEBHOOK_SECRET.
+ *
+ * When OPENAI_WEBHOOK_SECRET is not set (dev mode), we accept all
+ * payloads but log a warning so the operator notices.
+ */
+function verifyOpenAISignature(req, rawBody) {
+  const secret = process.env.OPENAI_WEBHOOK_SECRET;
+  if (!secret) {
+    log("warn", "openai_webhook_unverified", { reason: "OPENAI_WEBHOOK_SECRET not set" });
+    return true; // dev mode
+  }
+  const headerSig = req.headers["openai-signature"] || req.headers["webhook-signature"] || "";
+  if (!headerSig) return false;
+  // Format A: bare hex digest
+  // Format B: "t=<ts>,v1=<hex>" (Stripe-style)
+  let providedHex = headerSig;
+  if (headerSig.includes(",")) {
+    const parts = Object.fromEntries(
+      headerSig.split(",").map((kv) => kv.split("=").map((s) => s.trim()))
+    );
+    providedHex = parts.v1 || parts.v0 || "";
+  }
+  const expected = createHmac("sha256", secret).update(rawBody || "").digest("hex");
+  if (providedHex.length !== expected.length) return false;
+  return timingSafeEqual(Buffer.from(providedHex), Buffer.from(expected));
+}
+
+function checkBrowserAuth(req) {
+  const required = process.env.VOICE_BROWSER_TOKEN;
+  if (!required) return true; // no token set → open (dev mode)
+  const header = req.headers.authorization || "";
+  if (!header.startsWith("Bearer ")) return false;
+  const provided = header.slice("Bearer ".length).trim();
+  if (provided.length !== required.length) return false;
+  return timingSafeEqual(Buffer.from(provided), Buffer.from(required));
+}
+
+// ---------------------------------------------------------------------------
+// Inbox writer — emits voice events as JSON files under
+// state/inbox/voice/ so voice-poller.mjs (and via it, the daemon's
+// classifier → dispatcher pipeline) can consume them like any other
+// channel.
+// ---------------------------------------------------------------------------
+
+import { mkdirSync, writeFileSync as fsWriteFile } from "node:fs";
+const VOICE_INBOX_DIR = join(AGENT_DIR, "state/inbox/voice");
+try { mkdirSync(VOICE_INBOX_DIR, { recursive: true }); } catch { /* */ }
+
+function writeInboxEvent(payload) {
+  try {
+    const id = (payload.call_id || "noid").toString().replace(/\W/g, "_").slice(0, 24);
+    const evt = (payload.event_type || "event").replace(/\W/g, "_");
+    const filename = `${Date.now()}-${id}-${evt}.json`;
+    fsWriteFile(join(VOICE_INBOX_DIR, filename), JSON.stringify(payload, null, 2));
+  } catch (err) {
+    log("warn", "inbox_write_failed", { error: err.message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool bridge attach helper — also accumulates the transcript +
+// tool-call timeline for this call and writes call.started /
+// call.ended events into the daemon's voice inbox.
+// ---------------------------------------------------------------------------
+
+async function attachBridges(provider, context = {}) {
+  const callId = context.call_id || `call-${Date.now()}`;
+  const startedAt = new Date().toISOString();
+  const transcriptChunks = [];
+  const toolCalls = [];
+
+  // Surface the inbound call to the daemon's inbox right away so the
+  // classifier can mark it Critical if it's the CEO / leadership, etc.
+  writeInboxEvent({
+    event_type: "call.started",
+    call_id: callId,
+    transport: context.transport || "unknown",
+    peer: context.peer || null,
+    peer_name: context.peer_name || null,
+    started_at: startedAt,
+    timestamp: startedAt,
+  });
+
+  // Buffer transcript + tools as the call progresses.
+  const onTranscriptDelta = (e) => {
+    if (e?.delta) transcriptChunks.push(e.delta);
+  };
+  const onTranscriptDone = (e) => {
+    if (e?.transcript) transcriptChunks.push(e.transcript);
+  };
+  const onTurnDone = () => { transcriptChunks.push("\n"); };
+
+  provider.on("transcript.delta", onTranscriptDelta);
+  provider.on("transcript.done", onTranscriptDone);
+  provider.on("turn.done", onTurnDone);
+
+  let detachTools = () => {};
+  try {
+    detachTools = registerToolBridge(provider, {
+      allow: voiceConfig.tools?.include,
+      classification: undefined,
+      audit: (entry) => {
+        toolCalls.push({
+          name: entry.name,
+          args: entry.args,
+          risk: entry.risk,
+          error: entry.error,
+          started_at: entry.started_at,
+          finished_at: entry.finished_at,
+        });
+        log("info", "voice.tool", { ...entry, ...context });
+        // Surface high-risk tool calls as their own inbox items so the
+        // audit / decision-capture pipeline sees them immediately
+        // (rather than waiting for the call to end).
+        if (entry.risk === "high") {
+          writeInboxEvent({
+            event_type: "call.tool_call",
+            call_id: callId,
+            tool_name: entry.name,
+            args: entry.args,
+            risk: entry.risk,
+            result_summary: entry.error ? `error: ${entry.error}` : "ok",
+            timestamp: entry.finished_at,
+          });
+        }
+      },
+    });
+  } catch (err) {
+    log("error", "tool_bridge_failed", { error: err.message });
+  }
+
+  // On session close: write the call summary to the inbox.
+  const onClosed = (info) => {
+    const endedAt = new Date().toISOString();
+    const durationMs = Date.now() - new Date(startedAt).getTime();
+    writeInboxEvent({
+      event_type: "call.ended",
+      call_id: callId,
+      transport: context.transport || "unknown",
+      peer: context.peer || null,
+      peer_name: context.peer_name || null,
+      started_at: startedAt,
+      ended_at: endedAt,
+      duration_ms: durationMs,
+      transcript: transcriptChunks.join("").trim(),
+      tool_calls: toolCalls,
+      reason: info?.reason || "client_close",
+      timestamp: endedAt,
+    });
+    // Also persist a transcript-only file under logs/voice/sessions/
+    // so it's discoverable without going through inbox processing.
+    try {
+      const sessionsDir = join(AGENT_DIR, "logs/voice/sessions");
+      mkdirSync(sessionsDir, { recursive: true });
+      fsWriteFile(
+        join(sessionsDir, `${callId}.json`),
+        JSON.stringify({
+          call_id: callId, started_at: startedAt, ended_at: endedAt,
+          duration_ms: durationMs, transcript: transcriptChunks.join(""),
+          tool_calls: toolCalls,
+        }, null, 2)
+      );
+    } catch { /* */ }
+  };
+  provider.on("closed", onClosed);
+
+  return () => {
+    try { detachTools(); } catch { /* */ }
+    provider.off?.("transcript.delta", onTranscriptDelta);
+    provider.off?.("transcript.done", onTranscriptDone);
+    provider.off?.("turn.done", onTurnDone);
+    provider.off?.("closed", onClosed);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP server + handlers
+// ---------------------------------------------------------------------------
+
+const server = http.createServer(async (req, res) => {
+  try {
+    if (req.url === "/health" && req.method === "GET") {
+      respond(res, 200, {
+        ok: true,
+        agent: identity.name,
+        sipEnabled, streamsEnabled, browserEnabled,
+        openai_key_loaded: !!process.env.OPENAI_API_KEY,
+        ts: nowIso(),
+      });
+      return;
+    }
+
+    // Polite no-op for the browser favicon request (avoids noisy 404s in
+    // the JS console of the /voice/test page).
+    if (req.url === "/favicon.ico") {
+      respond(res, 204, "", "image/x-icon");
+      return;
+    }
+
+    // Serve cached outbound-audio files so Twilio <Play> can fetch them.
+    // URL: /voice/audio/<filename>. Path-traversal is blocked by
+    // restricting filename to a safe character set that MUST start with
+    // [A-Za-z0-9_-] so naked `.` / `..` are rejected, then defence-in-depth
+    // verifying the resolved path stays inside the cache dir.
+    if (req.url.startsWith("/voice/audio/") && req.method === "GET") {
+      const filename = req.url.slice("/voice/audio/".length).split("?")[0];
+      if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(filename) || filename.length > 200) {
+        respond(res, 400, { ok: false, error: "bad_filename" });
+        return;
+      }
+      const audioDir = join(AGENT_DIR, "state/voice/outbound-audio");
+      const audioPath = join(audioDir, filename);
+      // Defence-in-depth: resolved path must remain inside audioDir even
+      // if the regex was bypassed.
+      const { resolve: pathResolve } = await import("node:path");
+      if (!pathResolve(audioPath).startsWith(pathResolve(audioDir) + "/")) {
+        respond(res, 400, { ok: false, error: "path_traversal" });
+        return;
+      }
+      if (!existsSync(audioPath)) {
+        respond(res, 404, { ok: false, error: "not_found" });
+        return;
+      }
+      const buf = readFileSync(audioPath);
+      const ext = filename.split(".").pop().toLowerCase();
+      const mime = {
+        mp3: "audio/mpeg", ogg: "audio/ogg", opus: "audio/ogg",
+        wav: "audio/wav", flac: "audio/flac", aac: "audio/aac",
+      }[ext] || "application/octet-stream";
+      res.writeHead(200, {
+        "Content-Type": mime,
+        "Content-Length": buf.length,
+        "Cache-Control": "public, max-age=3600",
+      });
+      res.end(buf);
+      return;
+    }
+
+    // SIP path — also functions as the OpenAI realtime.call.incoming webhook.
+    if (sipEnabled && req.url === (inbound.twilio_sip?.inbound_webhook_path || "/voice/sip/incoming") && req.method === "POST") {
+      // OpenAI signs the webhook body — verify before accepting.
+      const rawBody = await readBody(req);
+      if (!verifyOpenAISignature(req, rawBody)) {
+        log("warn", "openai_webhook_signature_mismatch", {});
+        respond(res, 403, { ok: false, error: "openai_signature_invalid" });
+        return;
+      }
+      // Re-attach the body so the downstream handler can read it.
+      req._cachedBody = rawBody;
+      let parsedBody;
+      try { parsedBody = JSON.parse(rawBody || "{}"); } catch { parsedBody = {}; }
+
+      // Detect outbound-initiated calls (we set X-Maestro-Call-Id when
+      // bridging via Twilio outbound → SIP). If present, load the brief
+      // from state/voice/outbound-briefs/ and use it as the session
+      // instructions instead of the inbound context.
+      const xMaestro = parsedBody?.data?.headers?.["X-Maestro-Call-Id"] ||
+                       parsedBody?.headers?.["X-Maestro-Call-Id"] || null;
+
+      const sessionConfigFactory = async ({ callId, body }) => {
+        const tools = await actionsToRealtimeTools({
+          accessLevel: voiceConfig.tools?.access_level || "voice",
+          include: voiceConfig.tools?.include,
+          exclude: voiceConfig.tools?.exclude,
+          agentRoot: AGENT_DIR,
+        });
+        const peer = body?.from || body?.caller_id || parsedBody?.data?.from || null;
+        let callKind = "inbound";
+        let brief = null;
+        if (xMaestro) {
+          callKind = "outbound";
+          try {
+            const briefPath = join(AGENT_DIR, "state/voice/outbound-briefs", `${xMaestro}.json`);
+            if (existsSync(briefPath)) {
+              const j = JSON.parse(readFileSync(briefPath, "utf-8"));
+              brief = j.brief;
+            }
+          } catch { /* */ }
+        }
+        const instructions = await buildContextualInstructions({
+          agentRoot: AGENT_DIR,
+          peer,
+          callKind,
+          brief,
+        });
+        return buildSessionConfig({ tools, instructions, ...voiceConfig.session }, identity);
+      };
+      // The cloud-relay accepts the call itself before buffering (because
+      // the Mac→Railway round-trip blows OpenAI's accept window). When it
+      // does, the relay-poller forwards the event with this header set so
+      // the local handler doesn't try to re-accept (which would 404).
+      const acceptedByRelay = req.headers["x-maestro-relay-accepted"] === "1";
+      const handler = sipBridge.buildSipInboundHandler({
+        sessionConfig: sessionConfigFactory,
+        acceptedByRelay,
+        attachBridges: (provider, { callId }) =>
+          attachBridges(provider, {
+            call_id: callId,
+            transport: "sip",
+            peer: parsedBody?.data?.from || null,
+            kind: xMaestro ? "outbound" : "inbound",
+          }),
+      });
+      // Patch readBody so the handler doesn't try to re-read the consumed stream.
+      const patchedReq = Object.create(req);
+      patchedReq.body = parsedBody;
+      await handler(patchedReq, res);
+      return;
+    }
+
+    // TwiML for Media Streams
+    if (streamsEnabled && req.url === (inbound.twilio_media_streams.voice_webhook_path || "/voice/twiml") && req.method === "POST") {
+      const rawBody = await readBody(req);
+      if (!verifyTwilioSignature(req, rawBody)) {
+        respond(res, 403, { ok: false, error: "twilio_signature_invalid" });
+        return;
+      }
+      const host = req.headers.host;
+      const proto = host?.startsWith("localhost") ? "ws" : "wss";
+      const streamUrl = `${proto}://${host}${inbound.twilio_media_streams.stream_path || "/voice/stream"}`;
+      const twiml = sipBridge.issueTwiml({ streamUrl });
+      respond(res, 200, twiml, "text/xml");
+      return;
+    }
+
+    // Mint ephemeral OpenAI token for browser
+    if (browserEnabled && req.url === (inbound.browser_ws.ephemeral_token_path || "/voice/token") && req.method === "GET") {
+      if (!checkBrowserAuth(req)) {
+        respond(res, 401, { ok: false, error: "unauthorized" });
+        return;
+      }
+      const apiKey = process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        respond(res, 500, { ok: false, error: "OPENAI_API_KEY not set" });
+        return;
+      }
+      let tools;
+      try {
+        tools = await actionsToRealtimeTools({
+          accessLevel: voiceConfig.tools?.access_level || "voice",
+          include: voiceConfig.tools?.include,
+          exclude: voiceConfig.tools?.exclude,
+          agentRoot: AGENT_DIR,
+        });
+      } catch (err) {
+        log("warn", "tool_load_failed", { error: err.message });
+        tools = [];
+      }
+      // Pre-load context so browser-side voice sessions also benefit from
+      // the agent's memory — the model walks into the call with the
+      // current queues / decisions / priorities already in its prompt.
+      let instructions;
+      try {
+        instructions = await buildContextualInstructions({
+          agentRoot: AGENT_DIR,
+          callKind: "browser_test",
+        });
+      } catch (err) {
+        log("warn", "context_load_failed", { error: err.message });
+        instructions = undefined; // fall back to buildSessionConfig's defaults
+      }
+      const fullSession = buildSessionConfig({ tools, instructions, ...voiceConfig.session }, identity);
+      // The GA endpoint (POST /v1/realtime/client_secrets) uses a nested
+      // audio: { input: {format,transcription,turn_detection},
+      //         output: {format,voice} } schema. buildSessionConfig
+      // emits the LEGACY flat shape (voice/input_audio_format at top
+      // level) — translate here so the existing helper stays compatible
+      // with /v1/realtime/sessions consumers.
+      const isGAModel = /realtime-(2|translate|whisper)/.test(String(fullSession.model || ""));
+      const mintBody = isGAModel
+        ? toGASessionShape(fullSession)
+        : { session: fullSession };
+      try {
+        // Use GA `/client_secrets` endpoint for gpt-realtime-2 et al.
+        // The older `/sessions` endpoint is for preview models.
+        const endpoint = isGAModel
+          ? "https://api.openai.com/v1/realtime/client_secrets"
+          : "https://api.openai.com/v1/realtime/sessions";
+        const headers = {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        };
+        if (!isGAModel) headers["OpenAI-Beta"] = "realtime=v1";
+        const r = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(mintBody),
+        });
+        const text = await r.text();
+        if (!r.ok) log("warn", "session_mint_failed", { endpoint, status: r.status, body: text.slice(0, 500) });
+        respond(res, r.status, text, "application/json");
+      } catch (err) {
+        respond(res, 502, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    // Minimal HTML widget for manual testing.
+    if (req.url === "/voice/test" && req.method === "GET") {
+      respond(res, 200, renderTestPage(identity, voiceConfig), "text/html");
+      return;
+    }
+
+    // Catch-all
+    respond(res, 404, { ok: false, error: "not_found", url: req.url });
+  } catch (err) {
+    log("error", "handler_failed", { url: req.url, error: err.message });
+    try { respond(res, 500, { ok: false, error: err.message }); } catch { /* */ }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// WebSocket upgrade — Twilio Media Streams + browser WS
+// ---------------------------------------------------------------------------
+
+server.on("upgrade", async (req, socket) => {
+  try {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    if (streamsEnabled && url.pathname === (inbound.twilio_media_streams.stream_path || "/voice/stream")) {
+      // Twilio Media Streams WS — we need to upgrade then forward µ-law frames.
+      // We deliberately don't pull in `ws` here — for a minimal proof-of-life
+      // we close politely and direct operators to enable SIP path instead.
+      // A full Media Streams adapter belongs in lib/voice/twilio-media-streams-server.mjs.
+      socket.write("HTTP/1.1 501 Not Implemented\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    if (browserEnabled && url.pathname === (inbound.browser_ws.path || "/voice/browser")) {
+      // Same treatment — browser path is best served by the official
+      // WebRTC flow via /voice/token; raw WS bridging is left as a
+      // future enhancement.
+      socket.write("HTTP/1.1 501 Not Implemented\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+    socket.destroy();
+  } catch (err) {
+    log("error", "upgrade_failed", { error: err.message });
+    try { socket.destroy(); } catch { /* */ }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Test page (HTML/JS)
+// ---------------------------------------------------------------------------
+
+function renderTestPage(identity, voiceConfig) {
+  const safeName = String(identity.name).replace(/[<>]/g, "");
+  const voice = (voiceConfig.voice || "cedar").replace(/[<>]/g, "");
+  return `<!doctype html>
+<meta charset="utf-8" />
+<title>Voice test — ${safeName}</title>
+<style>
+  body { font: 14px/1.4 system-ui, sans-serif; max-width: 720px; margin: 2em auto; padding: 0 1em; }
+  h1 { font-weight: 600; font-size: 1.4em; }
+  .pill { display: inline-block; padding: 2px 8px; border-radius: 999px; background: #eee; font-size: 12px; }
+  button { padding: 8px 16px; border-radius: 6px; border: 1px solid #ccc; background: #fff; cursor: pointer; font: inherit; }
+  button:hover { background: #f5f5f5; }
+  pre { background: #f8f8f8; padding: 8px; border-radius: 4px; font-size: 12px; overflow-x: auto; }
+  .ok { color: #060; }
+  .err { color: #c00; }
+</style>
+<h1>Voice mode — ${safeName} <span class="pill">${voice}</span></h1>
+<p>This page mints an OpenAI Realtime ephemeral token from the agent's server, then opens a WebRTC peer connection so your browser's microphone talks directly to OpenAI. The agent's tool bridge (Slack, Gmail, etc.) is wired server-side.</p>
+<p><label>Auth token: <input id="tok" type="password" placeholder="VOICE_BROWSER_TOKEN (leave blank in dev mode)" style="width: 360px" /></label></p>
+<p><label>Mic: <select id="mic" style="min-width: 280px"></select></label> <button id="rescan">Rescan</button></p>
+<p>
+  <button id="connect">Connect</button>
+  <button id="disconnect" disabled>Disconnect</button>
+  <span id="status" class="pill">idle</span>
+</p>
+<h2>Log</h2>
+<pre id="log"></pre>
+<script type="module">
+  const $ = (id) => document.getElementById(id);
+  const log = (msg, cls) => { const p = document.createElement("div"); p.textContent = new Date().toISOString() + " " + msg; if (cls) p.className = cls; $("log").appendChild(p); };
+  let pc, dc, micStream;
+
+  function clearChildren(el) { while (el.firstChild) el.removeChild(el.firstChild); }
+  function makeOption(value, label) {
+    const o = document.createElement("option");
+    o.value = value;
+    o.textContent = label;
+    return o;
+  }
+
+  async function listMics() {
+    const sel = $("mic");
+    clearChildren(sel);
+    sel.appendChild(makeOption("", "— default —"));
+    try {
+      // First-time call: triggers permission prompt so labels are populated.
+      const tmp = await navigator.mediaDevices.getUserMedia({ audio: true }).catch(() => null);
+      tmp?.getTracks().forEach((t) => t.stop());
+      const devs = await navigator.mediaDevices.enumerateDevices();
+      const mics = devs.filter((d) => d.kind === "audioinput");
+      if (mics.length === 0) {
+        log("No microphone detected. Connect AirPods, a USB mic, or use 'iPhone as Microphone' (Continuity).", "err");
+      } else {
+        log("Detected " + mics.length + " mic(s)");
+        for (const m of mics) {
+          sel.appendChild(makeOption(m.deviceId, m.label || m.deviceId.slice(0, 20)));
+        }
+      }
+    } catch (err) {
+      log("device enumeration failed: " + err.message, "err");
+    }
+  }
+  listMics();
+  $("rescan").onclick = listMics;
+
+  $("connect").onclick = async () => {
+    try {
+      $("status").textContent = "minting token…";
+      const r = await fetch("/voice/token", { headers: { Authorization: "Bearer " + $("tok").value } });
+      if (!r.ok) {
+        const body = await r.text();
+        throw new Error("token mint failed: HTTP " + r.status + " " + body.slice(0, 200));
+      }
+      const session = await r.json();
+      const clientSecret = session.value || session.client_secret?.value || session.client_secret;
+      const model = session.session?.model || session.model || "gpt-realtime-2";
+      log("token minted, model=" + model);
+
+      $("status").textContent = "opening mic…";
+      const deviceId = $("mic").value;
+      const constraints = { audio: deviceId ? { deviceId: { exact: deviceId } } : true };
+      try {
+        micStream = await navigator.mediaDevices.getUserMedia(constraints);
+      } catch (err) {
+        const why = err.name === "NotFoundError"
+          ? "No microphone available. Connect AirPods/USB mic/iPhone-as-mic and click Rescan."
+          : err.name === "NotAllowedError"
+            ? "Mic permission denied. Allow it in browser settings for this site."
+            : err.message;
+        throw new Error(why);
+      }
+      log("mic opened: " + (micStream.getAudioTracks()[0]?.label || "(unlabelled)"));
+
+      $("status").textContent = "creating peer connection…";
+      pc = new RTCPeerConnection();
+      pc.ontrack = (e) => {
+        const audio = new Audio();
+        audio.autoplay = true;
+        audio.srcObject = e.streams[0];
+      };
+      dc = pc.createDataChannel("oai-events");
+      dc.onmessage = (e) => log("← " + e.data.slice(0, 200));
+      micStream.getTracks().forEach((t) => pc.addTrack(t, micStream));
+      const offer = await pc.createOffer();
+      await pc.setLocalDescription(offer);
+      $("status").textContent = "negotiating with OpenAI…";
+      const sdpResp = await fetch("https://api.openai.com/v1/realtime/calls?model=" + encodeURIComponent(model), {
+        method: "POST",
+        body: offer.sdp,
+        headers: { "Content-Type": "application/sdp", Authorization: "Bearer " + clientSecret },
+      });
+      if (!sdpResp.ok) throw new Error("OpenAI SDP exchange failed: HTTP " + sdpResp.status + " " + (await sdpResp.text()).slice(0, 200));
+      const answer = { type: "answer", sdp: await sdpResp.text() };
+      await pc.setRemoteDescription(answer);
+      $("status").textContent = "CONNECTED";
+      $("connect").disabled = true;
+      $("disconnect").disabled = false;
+      log("connected — speak now", "ok");
+    } catch (err) {
+      $("status").textContent = "error";
+      log(err.message, "err");
+    }
+  };
+  $("disconnect").onclick = () => {
+    micStream?.getTracks().forEach((t) => t.stop());
+    dc?.close(); pc?.close();
+    $("status").textContent = "idle";
+    $("connect").disabled = false;
+    $("disconnect").disabled = true;
+    log("disconnected");
+  };
+</script>
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+server.listen(PORT, "127.0.0.1", () => {
+  log("info", "voice_webhook_started", {
+    port: PORT,
+    sipEnabled, streamsEnabled, browserEnabled,
+    endpoints: {
+      health: `http://localhost:${PORT}/health`,
+      test_widget: browserEnabled ? `http://localhost:${PORT}/voice/test` : null,
+      sip: sipEnabled ? `http://localhost:${PORT}${inbound.twilio_sip.inbound_webhook_path || "/voice/sip/incoming"}` : null,
+    },
+  });
+});
+
+process.on("SIGINT", () => { server.close(); process.exit(0); });
+process.on("SIGTERM", () => { server.close(); process.exit(0); });