@absolutejs/voice 0.0.22-beta.472 → 0.0.22-beta.474

package/README.md

@@ -8,6 +8,107 @@ Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you wan
 
 ## What's new
 
+### 0.0.22-beta.474 · Phase 5 runtime hookup — auto-wire monitor sockets to live sessions
+
+The Phase 5 monitor primitive is now first-class in the voice runtime. Pass a `monitor` binding to `voice({...})` and every session opened against the voice plugin auto-registers in the monitor registry, outbound TTS audio auto-fans-out to all listeners, and the close/superseded/session-switch paths deregister automatically. Supervisors connecting to the listen route get a live audio stream without any manual `record.emit()` calls.
+
+```ts
+import { Elysia } from "elysia";
+import {
+  createVoiceInMemoryMonitorRegistry,
+  createVoiceLiveMonitorRoutes,
+  createVoiceMonitorRuntimeBinding,
+  voice,
+} from "@absolutejs/voice";
+
+const monitorRegistry = createVoiceInMemoryMonitorRegistry();
+
+const app = new Elysia()
+  .use(
+    voice({
+      path: "/voice/realtime",
+      stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+      tts: elevenlabs({ apiKey: process.env.ELEVENLABS_API_KEY! }),
+      onTurn: async (session, turn, api) => {
+        // your business logic
+      },
+      session: sessionStore,
+      monitor: createVoiceMonitorRuntimeBinding(monitorRegistry, {
+        audioFormat: { channels: 1, container: "raw", encoding: "pcm_s16le", sampleRateHz: 24_000 },
+      }),
+    }),
+  )
+  .use(
+    createVoiceLiveMonitorRoutes({
+      registry: monitorRegistry,
+      authenticate: async ({ request }) => await verifySupervisorJWT(request),
+    }),
+  );
+```
+
+Surface additions:
+- **`createVoiceMonitorRuntimeBinding(registry, { audioFormat?, defaultSource? })`** — returns a `VoiceMonitorRuntimeBinding` you pass to the voice plugin's new `monitor` option. Internally, each session open calls `registerSession({ handle, sessionId })`, audio fans out via `emitAudio()` on every binary `socket.send`, and the close/superseded/session-switch paths call `deregister(reason)`.
+- **`VoicePluginConfig.monitor?: VoiceMonitorRuntimeBinding`** — new optional field on the main voice plugin config.
+- **`VoiceMonitorMutableRegistry.deregister(sessionId, reason?)`** — explicit deregister path so the runtime binding can tear down stale records on re-register without throwing. The `register()`-returned deregister fn now also accepts an optional reason.
+- The runtime binding is **opt-in** — if you don't pass `monitor`, voice behaves exactly as before. No overhead on the audio-send hot path beyond a single `Map.get`.
+
+4 new tests cover the runtime binding's register/emit/deregister cycle, no-op-after-deregister, re-registration tear-down, and the audioFormat + defaultSource option threading. Full voice suite now 963 pass / 1 pre-existing fail.
+
+### 0.0.22-beta.473 · Phase 5 — live listen + control monitor sockets (Vapi `monitorPlan` parity)
+
+Two new WebSocket routes per session that mirror Vapi's `monitorPlan.listenUrl` + `monitorPlan.controlUrl`. Supervisors can subscribe to a live call's outbound audio and send control commands (transfer, hangup, escalate, voicemail, no-answer, plus caller-defined mute/say/inject) without touching the call itself.
+
+```ts
+import { Elysia } from "elysia";
+import {
+  buildVoiceMonitorPlan,
+  createVoiceInMemoryMonitorRegistry,
+  createVoiceLiveMonitorRoutes,
+  createVoiceMonitorSession,
+} from "@absolutejs/voice";
+
+const registry = createVoiceInMemoryMonitorRegistry();
+
+// In your runtime: when a session opens, register it so supervisors can listen.
+const record = createVoiceMonitorSession({ handle, sessionId: handle.id });
+const deregister = registry.register(record);
+// When audio leaves the assistant, fan it out:
+//   record.emit({ at: Date.now(), chunk, format, source: 'assistant' });
+// On call end:
+//   deregister();
+
+const app = new Elysia()
+  .use(
+    createVoiceLiveMonitorRoutes({
+      authenticate: async ({ sessionId, route, request }) =>
+        await verifySupervisorJWT(request),
+      controlHandlers: {
+        say: async ({ message, session }) => {
+          await yourTtsRuntime.sayInSession(session.sessionId, message.text);
+          return { detail: `Said: ${message.text}`, ok: true, type: "say" };
+        },
+      },
+      htmlPath: "/voice/monitor",
+      registry,
+    }),
+  );
+
+const plan = buildVoiceMonitorPlan({
+  baseUrl: "wss://api.example.com",
+  sessionId: handle.id,
+});
+// plan.listenUrl  → wss://api.example.com/api/voice/monitor/<sessionId>/listen
+// plan.controlUrl → wss://api.example.com/api/voice/monitor/<sessionId>/control
+```
+
+Surface summary:
+- **`createVoiceInMemoryMonitorRegistry()`** — `{ register, get, list, emit, emitClose }`. Voice's session runtime (or any caller) wires `register()` on open + the returned deregister on close; `emit()` fans out outbound audio frames; `emitClose()` notifies listeners that the call ended.
+- **`createVoiceLiveMonitorRoutes(options)`** — Elysia plugin that mounts two `.ws()` routes per session: `:sessionId/listen` (read-only outbound audio as binary frames) and `:sessionId/control` (JSON control messages). Default handlers map `transfer`/`hangup`/`escalate`/`voicemail`/`no-answer` onto `VoiceSessionHandle` verbs; `mute`/`say`/`inject` require caller-supplied handlers via `controlHandlers`.
+- **`buildVoiceMonitorPlan(input)`** — Vapi-shaped helper returning `{ listenUrl, controlUrl }` for inclusion in your call-create API response.
+- **Auth hook** — `authenticate?: ({ sessionId, route, request }) => Promise<boolean>` runs at the start of both routes; rejected connections get a 4401 close.
+
+This is a **primitive**: wiring voice's existing `activeSessions` runtime into the registry (so audio actually flows from a real call without manual `record.emit()` calls) is the next step and intentionally left out to keep this change additive. Until then, registries built by hand (e.g. from a custom telephony adapter where you control the outbound audio buffer) work out of the box.
+
 ### 0.0.22-beta.472 · Phase 6 — multilingual STT proof gate
 
 `runVoiceMultilingualProof(...)` turns the `voice-fixtures-multilingual` corpus (FLEURS + BSC Catalan-Spanish code-switch + CoSHE Hindi-English code-switch) into a gateable readiness/proof artifact. Buyers evaluating Vapi-replacement can now run any combination of STT adapters against the multilingual corpus and assert per-language WER / pass-rate / term-recall budgets in CI.

package/dist/index.d.ts

@@ -225,4 +225,6 @@ export { buildVoiceProofPackInput, buildVoiceProofPack, buildVoiceProofPackFromO
 export type { VoiceProofPack, VoiceProofPackBuildContext, VoiceProofPackBuildContextOptions, VoiceProofPackBuildTiming, VoiceProofPackEvidence, VoiceProofPackInput, VoiceProofPackInputBuilderLoaderInput, VoiceProofPackInputBuilderOperationsLoaderInput, VoiceProofPackInputBuilderOptions, VoiceProofPackInputBuilderSupportBundle, VoiceProofPackRefreshState, VoiceProofPackRefreshStatus, VoiceProofPackRoutesOptions, VoiceProofPackSection, VoiceProofPackSourceValue, VoiceProofPackStatus, VoiceProofPackStaleWhileRefreshSource, VoiceProofPackStaleWhileRefreshSourceOptions, VoiceProofPackWriteResult, VoiceProofRefreshSnapshot, VoiceProofRefreshSnapshotOptions, } from "./proofPack";
 export { buildVoiceMultilingualProofReadinessCheck, renderVoiceMultilingualProofMarkdown, runVoiceMultilingualProof, } from "./multilingualProof";
 export type { VoiceMultilingualLanguageCode, VoiceMultilingualProofAdapterEntry, VoiceMultilingualProofAdapterReport, VoiceMultilingualProofDefaultThresholds, VoiceMultilingualProofLanguageMetrics, VoiceMultilingualProofLanguageReport, VoiceMultilingualProofLanguageThresholds, VoiceMultilingualProofOptions, VoiceMultilingualProofReadinessCheck, VoiceMultilingualProofReadinessOptions, VoiceMultilingualProofReport, } from "./multilingualProof";
+export { buildVoiceMonitorPlan, createVoiceInMemoryMonitorRegistry, createVoiceLiveMonitorRoutes, createVoiceMonitorRuntimeBinding, createVoiceMonitorSession, } from "./monitor";
+export type { VoiceMonitorAudioEvent, VoiceMonitorAudioSource, VoiceMonitorAuthenticate, VoiceMonitorAuthenticateInput, VoiceMonitorControlAck, VoiceMonitorControlHandler, VoiceMonitorControlHandlerInput, VoiceMonitorControlMessage, VoiceMonitorMutableRegistry, VoiceMonitorPlan, VoiceMonitorPlanInput, VoiceMonitorRegistry, VoiceMonitorRegistryRegisterInput, VoiceLiveMonitorRoutesOptions, VoiceMonitorRuntimeBindingOptions, VoiceMonitorSessionRecord, } from "./monitor";
 export * from "./types";

package/dist/index.js

@@ -6265,6 +6265,7 @@ var voice = (config) => {
   if (!config.stt && !config.realtime) {
     throw new Error("voice requires either an stt or realtime adapter.");
   }
+  const monitorBindings = new Map;
   const runtime = {
     activeSessions: new Map,
     logger: resolveLogger(config.logger),
@@ -6272,6 +6273,57 @@ var voice = (config) => {
     profileSwitchGuardedSessions: new Set,
     socketSessions: new WeakMap
   };
+  const monitor = config.monitor;
+  const registerMonitorSession = (sessionId, handle) => {
+    if (!monitor)
+      return;
+    const existing = monitorBindings.get(sessionId);
+    if (existing) {
+      try {
+        existing.deregister("superseded");
+      } catch {}
+      monitorBindings.delete(sessionId);
+    }
+    try {
+      const binding = monitor.registerSession({ handle, sessionId });
+      monitorBindings.set(sessionId, binding);
+    } catch (error) {
+      runtime.logger.warn?.(`[voice] failed to register session "${sessionId}" with monitor runtime: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const deregisterMonitorSession = (sessionId, reason) => {
+    const binding = monitorBindings.get(sessionId);
+    if (!binding)
+      return;
+    monitorBindings.delete(sessionId);
+    try {
+      binding.deregister(reason);
+    } catch (error) {
+      runtime.logger.warn?.(`[voice] failed to deregister monitor binding for session "${sessionId}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const buildSocketAdapter = (ws, sessionId) => {
+    if (!monitor)
+      return createSocketAdapter(ws);
+    return {
+      close: async (code, reason) => {
+        ws.close(code, reason);
+      },
+      send: async (data) => {
+        if (typeof data !== "string") {
+          const binding = monitorBindings.get(sessionId);
+          if (binding) {
+            try {
+              binding.emitAudio(data);
+            } catch (error) {
+              runtime.logger.warn?.(`[voice] monitor emitAudio failed for session "${sessionId}": ${error instanceof Error ? error.message : String(error)}`);
+            }
+          }
+        }
+        ws.send(data);
+      }
+    };
+  };
   const onTurn = normalizeOnTurn(config.onTurn);
   const sessionOptions = resolveSessionOptions(config);
   const htmxOptions = config.htmx && typeof config.htmx === "object" ? config.htmx : undefined;
@@ -6394,6 +6446,7 @@ var voice = (config) => {
       }
       const session = runtime.activeSessions.get(socketState.sessionId);
       runtime.activeSessions.delete(socketState.sessionId);
+      deregisterMonitorSession(socketState.sessionId, reason ?? `ws-close-${String(code)}`);
       if (session) {
         await session.disconnect({
           code,
@@ -6417,6 +6470,7 @@ var voice = (config) => {
         if (message.type === "close" && current) {
           await current.close(message.reason);
           runtime.activeSessions.delete(sessionState.sessionId);
+          deregisterMonitorSession(sessionState.sessionId, message.reason);
         }
         if (message.type === "call_control" && current) {
           if (message.action === "transfer") {
@@ -6459,6 +6513,7 @@ var voice = (config) => {
           if (currentSession) {
             await currentSession.close("session-switch");
             runtime.activeSessions.delete(sessionState.sessionId);
+            deregisterMonitorSession(sessionState.sessionId, "session-switch");
           }
           sessionState.sessionId = message.sessionId;
           runtime.socketSessions.set(ws, {
@@ -6482,8 +6537,10 @@ var voice = (config) => {
       }
       const session = current ?? await createManagedSession(ws, sessionState.sessionId, sessionState.scenarioId ?? undefined);
       if (!current) {
-        runtime.activeSessions.set(sessionState.sessionId, session);
-        await session.connect(createSocketAdapter(ws));
+        const typedSession = session;
+        runtime.activeSessions.set(sessionState.sessionId, typedSession);
+        registerMonitorSession(sessionState.sessionId, typedSession);
+        await session.connect(buildSocketAdapter(ws, sessionState.sessionId));
       }
       await session.receiveAudio(audio);
     },
@@ -6493,10 +6550,13 @@ var voice = (config) => {
       if (existing) {
         await existing.close("superseded");
         runtime.activeSessions.delete(sessionState.sessionId);
+        deregisterMonitorSession(sessionState.sessionId, "superseded");
       }
       const session = await createManagedSession(ws, sessionState.sessionId, sessionState.scenarioId ?? undefined);
-      runtime.activeSessions.set(sessionState.sessionId, session);
-      await session.connect(createSocketAdapter(ws));
+      const typedSession = session;
+      runtime.activeSessions.set(sessionState.sessionId, typedSession);
+      registerMonitorSession(sessionState.sessionId, typedSession);
+      await session.connect(buildSocketAdapter(ws, sessionState.sessionId));
     }
   }).use(htmxRoutes());
 };
@@ -44454,6 +44514,466 @@ var buildVoiceMultilingualProofReadinessCheck = (report, options = {}) => {
     value: failedAdapters.length
   };
 };
+// src/monitor.ts
+import { Elysia as Elysia70 } from "elysia";
+var buildAudioFanout = () => {
+  const handlers = new Set;
+  return {
+    emit: (event) => {
+      for (const handler of handlers)
+        handler(event);
+    },
+    onAudio: (handler) => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    }
+  };
+};
+var buildCloseFanout = () => {
+  const handlers = new Set;
+  return {
+    emitClose: (reason) => {
+      for (const handler of handlers)
+        handler(reason);
+    },
+    onClose: (handler) => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    }
+  };
+};
+var createVoiceMonitorSession = (input) => {
+  const audio = buildAudioFanout();
+  const close = buildCloseFanout();
+  return {
+    emit: audio.emit,
+    emitClose: close.emitClose,
+    handle: input.handle,
+    metadata: input.metadata,
+    onAudio: audio.onAudio,
+    onClose: close.onClose,
+    sessionId: input.sessionId
+  };
+};
+var createVoiceInMemoryMonitorRegistry = () => {
+  const records = new Map;
+  const deregister = (sessionId, reason) => {
+    const existing = records.get(sessionId);
+    if (!existing)
+      return;
+    records.delete(sessionId);
+    existing.emitClose(reason ?? "deregistered");
+  };
+  return {
+    deregister,
+    emit: (sessionId, event) => {
+      records.get(sessionId)?.emit(event);
+    },
+    emitClose: (sessionId, reason) => {
+      records.get(sessionId)?.emitClose(reason);
+    },
+    get: (sessionId) => records.get(sessionId),
+    list: () => Array.from(records.keys()).map((sessionId) => ({ sessionId })),
+    register: (record) => {
+      const existing = records.get(record.sessionId);
+      if (existing) {
+        throw new Error(`VoiceMonitorRegistry already has a session "${record.sessionId}"; deregister it before re-registering.`);
+      }
+      const wrapped = "emit" in record && typeof record.emit === "function" ? record : createVoiceMonitorSession({
+        handle: record.handle,
+        metadata: record.metadata,
+        sessionId: record.sessionId
+      });
+      if (wrapped !== record) {
+        record.onAudio((event) => wrapped.emit(event));
+        record.onClose((reason) => wrapped.emitClose(reason));
+      }
+      records.set(record.sessionId, wrapped);
+      return (reason) => deregister(record.sessionId, reason);
+    }
+  };
+};
+var buildDefaultControlHandler = (type) => {
+  if (type === "transfer") {
+    return async ({ message, session }) => {
+      if (message.type !== "transfer") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.transfer({
+        metadata: message.metadata,
+        reason: message.reason,
+        target: message.target
+      });
+      return { detail: `Transferred to ${message.target}.`, ok: true, type };
+    };
+  }
+  if (type === "hangup") {
+    return async ({ message, session }) => {
+      if (message.type !== "hangup") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.complete();
+      return {
+        detail: message.reason ? `Hangup: ${message.reason}` : "Hangup.",
+        ok: true,
+        type
+      };
+    };
+  }
+  if (type === "escalate") {
+    return async ({ message, session }) => {
+      if (message.type !== "escalate") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.escalate({
+        metadata: message.metadata,
+        reason: message.reason ?? "monitor-requested-escalation"
+      });
+      return { detail: "Escalated.", ok: true, type };
+    };
+  }
+  if (type === "voicemail") {
+    return async ({ message, session }) => {
+      if (message.type !== "voicemail") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.markVoicemail({ metadata: message.metadata });
+      return { detail: "Voicemail marked.", ok: true, type };
+    };
+  }
+  if (type === "no-answer") {
+    return async ({ message, session }) => {
+      if (message.type !== "no-answer") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.markNoAnswer({ metadata: message.metadata });
+      return { detail: "Marked no-answer.", ok: true, type };
+    };
+  }
+  return;
+};
+var parseControlMessage = (raw) => {
+  if (!raw || typeof raw !== "object")
+    return;
+  const record = raw;
+  const type = record.type;
+  if (typeof type !== "string")
+    return;
+  if (type === "transfer") {
+    if (typeof record.target !== "string")
+      return;
+    return {
+      metadata: record.metadata,
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      target: record.target,
+      type
+    };
+  }
+  if (type === "hangup") {
+    return {
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      type
+    };
+  }
+  if (type === "escalate") {
+    return {
+      metadata: record.metadata,
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      type
+    };
+  }
+  if (type === "voicemail" || type === "no-answer") {
+    return {
+      metadata: record.metadata,
+      type
+    };
+  }
+  if (type === "mute") {
+    if (typeof record.muted !== "boolean" || record.target !== "assistant" && record.target !== "caller") {
+      return;
+    }
+    return { muted: record.muted, target: record.target, type };
+  }
+  if (type === "say") {
+    if (typeof record.text !== "string")
+      return;
+    return {
+      interrupt: typeof record.interrupt === "boolean" ? record.interrupt : undefined,
+      text: record.text,
+      type
+    };
+  }
+  if (type === "inject") {
+    if (typeof record.text !== "string" || record.role !== "assistant" && record.role !== "system" && record.role !== "user") {
+      return;
+    }
+    return { role: record.role, text: record.text, type };
+  }
+  return;
+};
+var DEFAULT_BASE_PATH = "/api/voice/monitor";
+var DEFAULT_LISTEN_PATH = ":sessionId/listen";
+var DEFAULT_CONTROL_PATH = ":sessionId/control";
+var joinPath = (...parts) => parts.filter((part) => part.length > 0).map((part) => part.replace(/^\/+|\/+$/g, "")).filter((part) => part.length > 0).reduce((path, part) => `${path}/${part}`, "");
+var substituteSessionId = (template, sessionId) => template.replace(":sessionId", encodeURIComponent(sessionId));
+var buildVoiceMonitorPlan = (input) => {
+  const basePath = input.basePath ?? DEFAULT_BASE_PATH;
+  const listenTemplate = input.listenPath ?? joinPath(basePath, DEFAULT_LISTEN_PATH);
+  const controlTemplate = input.controlPath ?? joinPath(basePath, DEFAULT_CONTROL_PATH);
+  const baseUrl = input.baseUrl.replace(/\/+$/, "");
+  return {
+    controlUrl: `${baseUrl}${substituteSessionId(controlTemplate, input.sessionId)}`,
+    listenUrl: `${baseUrl}${substituteSessionId(listenTemplate, input.sessionId)}`
+  };
+};
+var DEFAULT_RUNTIME_AUDIO_FORMAT = {
+  channels: 1,
+  container: "raw",
+  encoding: "pcm_s16le",
+  sampleRateHz: 16000
+};
+var toUint8 = (chunk) => chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+var createVoiceMonitorRuntimeBinding = (registry, options = {}) => {
+  const audioFormat = options.audioFormat ?? DEFAULT_RUNTIME_AUDIO_FORMAT;
+  const defaultSource = options.defaultSource ?? "assistant";
+  return {
+    registerSession: (input) => {
+      registry.deregister(input.sessionId, "superseded");
+      const record = createVoiceMonitorSession({
+        handle: input.handle,
+        metadata: input.metadata,
+        sessionId: input.sessionId
+      });
+      const deregisterFromRegistry = registry.register(record);
+      let closed = false;
+      return {
+        deregister: (reason) => {
+          if (closed)
+            return;
+          closed = true;
+          try {
+            deregisterFromRegistry(reason);
+          } catch {}
+        },
+        emitAudio: (chunk, opts) => {
+          if (closed)
+            return;
+          const bytes = toUint8(chunk);
+          if (bytes.byteLength === 0)
+            return;
+          record.emit({
+            at: Date.now(),
+            chunk: bytes,
+            format: audioFormat,
+            source: opts?.source ?? defaultSource
+          });
+        }
+      };
+    }
+  };
+};
+var resolveSessionId3 = (ws) => {
+  const params = ws.data?.params;
+  if (!params)
+    return;
+  const value = params.sessionId;
+  if (typeof value !== "string" || value.length === 0)
+    return;
+  return value;
+};
+var resolveAuthenticate = async (authenticate, input) => {
+  if (!authenticate)
+    return true;
+  return await authenticate(input);
+};
+var createVoiceLiveMonitorRoutes = (options) => {
+  const basePath = options.basePath ?? DEFAULT_BASE_PATH;
+  const listenPath = options.listenPath === undefined ? joinPath(basePath, DEFAULT_LISTEN_PATH) : options.listenPath;
+  const controlPath = options.controlPath === undefined ? joinPath(basePath, DEFAULT_CONTROL_PATH) : options.controlPath;
+  const handlers = {
+    escalate: options.controlHandlers?.escalate ?? buildDefaultControlHandler("escalate"),
+    hangup: options.controlHandlers?.hangup ?? buildDefaultControlHandler("hangup"),
+    inject: options.controlHandlers?.inject,
+    mute: options.controlHandlers?.mute,
+    "no-answer": options.controlHandlers?.["no-answer"] ?? buildDefaultControlHandler("no-answer"),
+    say: options.controlHandlers?.say,
+    transfer: options.controlHandlers?.transfer ?? buildDefaultControlHandler("transfer"),
+    voicemail: options.controlHandlers?.voicemail ?? buildDefaultControlHandler("voicemail")
+  };
+  const app = new Elysia70({ name: "absolutejs-voice-monitor" });
+  const unsubscribers = new WeakMap;
+  if (listenPath !== false && listenPath.length > 0) {
+    app.ws(`/${listenPath.replace(/^\/+/, "")}`, {
+      close: (ws) => {
+        const subs = unsubscribers.get(ws);
+        if (subs) {
+          for (const unsub of subs)
+            unsub();
+          unsubscribers.delete(ws);
+        }
+      },
+      open: async (ws) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            type: "error"
+          }));
+          webSocket.close(4400, "missing sessionId");
+          return;
+        }
+        const authed = await resolveAuthenticate(options.authenticate, {
+          request: webSocket.raw?.request,
+          route: "listen",
+          sessionId
+        });
+        if (!authed) {
+          webSocket.send(JSON.stringify({ error: "unauthorized", type: "error" }));
+          webSocket.close(4401, "unauthorized");
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            type: "error"
+          }));
+          webSocket.close(4404, "session not found");
+          return;
+        }
+        const subs = [];
+        webSocket.send(JSON.stringify({
+          sessionId,
+          type: "subscribed"
+        }));
+        subs.push(record.onAudio((event) => {
+          webSocket.send(event.chunk);
+        }));
+        subs.push(record.onClose((reason) => {
+          webSocket.send(JSON.stringify({
+            reason,
+            sessionId,
+            type: "session-closed"
+          }));
+          webSocket.close(1000, reason ?? "session-closed");
+        }));
+        unsubscribers.set(ws, subs);
+      }
+    });
+  }
+  if (controlPath !== false && controlPath.length > 0) {
+    app.ws(`/${controlPath.replace(/^\/+/, "")}`, {
+      close: (ws) => {
+        unsubscribers.delete(ws);
+      },
+      message: async (ws, raw) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            ok: false,
+            type: "error"
+          }));
+          return;
+        }
+        const message = parseControlMessage(raw);
+        if (!message) {
+          webSocket.send(JSON.stringify({
+            error: "invalid control message",
+            ok: false,
+            type: "error"
+          }));
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            ok: false,
+            type: message.type
+          }));
+          return;
+        }
+        const handler = handlers[message.type];
+        if (!handler) {
+          webSocket.send(JSON.stringify({
+            error: `no handler registered for control type "${message.type}"`,
+            ok: false,
+            type: message.type
+          }));
+          return;
+        }
+        try {
+          const ack = await handler({
+            message,
+            raw,
+            session: record
+          });
+          webSocket.send(JSON.stringify(ack));
+        } catch (error) {
+          webSocket.send(JSON.stringify({
+            error: error instanceof Error ? error.message : String(error),
+            ok: false,
+            type: message.type
+          }));
+        }
+      },
+      open: async (ws) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            type: "error"
+          }));
+          webSocket.close(4400, "missing sessionId");
+          return;
+        }
+        const authed = await resolveAuthenticate(options.authenticate, {
+          request: webSocket.raw?.request,
+          route: "control",
+          sessionId
+        });
+        if (!authed) {
+          webSocket.send(JSON.stringify({ error: "unauthorized", type: "error" }));
+          webSocket.close(4401, "unauthorized");
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            type: "error"
+          }));
+          webSocket.close(4404, "session not found");
+          return;
+        }
+        webSocket.send(JSON.stringify({
+          sessionId,
+          supports: Object.entries(handlers).filter(([, value]) => value !== undefined).map(([key]) => key),
+          type: "ready"
+        }));
+      }
+    });
+  }
+  if (options.htmlPath !== undefined && options.htmlPath !== false) {
+    const path = options.htmlPath;
+    app.get(path, () => {
+      const sessions = options.registry.list().map((entry) => `<li><code>${entry.sessionId}</code></li>`).join("");
+      const body = `<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>Voice Monitor</title><style>body{background:#0b1216;color:#f6f1e7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0;padding:32px}main{margin:auto;max-width:960px}h1{font-size:clamp(2rem,5vw,3.2rem);letter-spacing:-.04em;margin:.2rem 0 1rem}code{background:#171f25;border:1px solid #2c3a44;border-radius:8px;padding:2px 6px}ul{margin:8px 0;padding-left:18px}p.muted{color:#9aa8b2}</style></head><body><main><h1>Voice Monitor</h1><p class="muted">Active sessions registered with this monitor registry.</p><ul>${sessions || "<li><em>None.</em></li>"}</ul><p class="muted">Open <code>${listenPath}</code> and <code>${controlPath}</code> via WebSocket per session for live listen + control.</p></main></body></html>`;
+      return new Response(body, {
+        headers: { "content-type": "text/html; charset=utf-8" }
+      });
+    });
+  }
+  return app;
+};
 export {
   writeVoiceProofPack,
   writeVoiceMediaPipelineArtifacts,
@@ -44948,6 +45468,8 @@ export {
   createVoiceObservabilityExportRoutes,
   createVoiceObservabilityExportReplayRoutes,
   createVoiceMonitorWebhookNotifier,
+  createVoiceMonitorSession,
+  createVoiceMonitorRuntimeBinding,
   createVoiceMonitorRunnerRoutes,
   createVoiceMonitorRunner,
   createVoiceMonitorRoutes,
@@ -44967,6 +45489,7 @@ export {
   createVoiceMediaPipelineRoutes,
   createVoiceLiveOpsRoutes,
   createVoiceLiveOpsController,
+  createVoiceLiveMonitorRoutes,
   createVoiceLiveLatencyRoutes,
   createVoiceLinearIssueUpdateSink,
   createVoiceLinearIssueSyncSinks,
@@ -44978,6 +45501,7 @@ export {
   createVoiceIncidentTimelineRoutes,
   createVoiceIncidentBundleRoutes,
   createVoiceInMemoryRealCallProfileRecoveryJobStore,
+  createVoiceInMemoryMonitorRegistry,
   createVoiceHubSpotTaskUpdateSink,
   createVoiceHubSpotTaskSyncSinks,
   createVoiceHubSpotTaskSink,
@@ -45153,6 +45677,7 @@ export {
   buildVoiceObservabilityArtifactIndex,
   buildVoiceMultilingualProofReadinessCheck,
   buildVoiceMonitorRunReport,
+  buildVoiceMonitorPlan,
   buildVoiceMediaPipelineReport,
   buildVoiceMediaPipelineReadinessChecks,
   buildVoiceMediaPipelineIncidentEvents,

package/dist/monitor.d.ts

@@ -0,0 +1,148 @@
+import { Elysia } from "elysia";
+import type { AudioFormat, VoiceMonitorRuntimeBinding, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceMonitorAudioSource = "assistant" | "caller" | (string & {});
+export type VoiceMonitorAudioEvent = {
+    at: number;
+    chunk: Uint8Array;
+    format: AudioFormat;
+    source: VoiceMonitorAudioSource;
+};
+export type VoiceMonitorSessionRecord = {
+    handle: VoiceSessionHandle<unknown, VoiceSessionRecord, unknown>;
+    metadata?: Record<string, unknown>;
+    onAudio: (handler: (event: VoiceMonitorAudioEvent) => void) => () => void;
+    onClose: (handler: (reason?: string) => void) => () => void;
+    sessionId: string;
+};
+export type VoiceMonitorRegistry = {
+    get: (sessionId: string) => VoiceMonitorSessionRecord | undefined;
+    list: () => readonly {
+        sessionId: string;
+    }[];
+};
+export type VoiceMonitorMutableRegistry = VoiceMonitorRegistry & {
+    emit: (sessionId: string, event: VoiceMonitorAudioEvent) => void;
+    emitClose: (sessionId: string, reason?: string) => void;
+    /**
+     * Deregister a session by id. No-op if the id isn't registered. The
+     * `reason` flows into the close fan-out exactly once.
+     */
+    deregister: (sessionId: string, reason?: string) => void;
+    register: (record: VoiceMonitorSessionRecord) => (reason?: string) => void;
+};
+export type VoiceMonitorRegistryRegisterInput = {
+    handle: VoiceSessionHandle<unknown, VoiceSessionRecord, unknown>;
+    metadata?: Record<string, unknown>;
+    sessionId: string;
+};
+export declare const createVoiceMonitorSession: (input: VoiceMonitorRegistryRegisterInput) => VoiceMonitorSessionRecord & {
+    emit: (event: VoiceMonitorAudioEvent) => void;
+    emitClose: (reason?: string) => void;
+};
+export declare const createVoiceInMemoryMonitorRegistry: () => VoiceMonitorMutableRegistry;
+export type VoiceMonitorControlMessage = {
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    target: string;
+    type: "transfer";
+} | {
+    reason?: string;
+    type: "hangup";
+} | {
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    type: "escalate";
+} | {
+    metadata?: Record<string, unknown>;
+    type: "voicemail";
+} | {
+    metadata?: Record<string, unknown>;
+    type: "no-answer";
+} | {
+    muted: boolean;
+    target: "assistant" | "caller";
+    type: "mute";
+} | {
+    interrupt?: boolean;
+    text: string;
+    type: "say";
+} | {
+    role: "assistant" | "system" | "user";
+    text: string;
+    type: "inject";
+};
+export type VoiceMonitorControlAck = {
+    detail?: string;
+    ok: true;
+    type: VoiceMonitorControlMessage["type"];
+} | {
+    error: string;
+    ok: false;
+    type: VoiceMonitorControlMessage["type"];
+};
+export type VoiceMonitorControlHandlerInput = {
+    message: VoiceMonitorControlMessage;
+    raw: unknown;
+    session: VoiceMonitorSessionRecord;
+};
+export type VoiceMonitorControlHandler = (input: VoiceMonitorControlHandlerInput) => Promise<VoiceMonitorControlAck> | VoiceMonitorControlAck;
+export type VoiceMonitorAuthenticateInput = {
+    request: unknown;
+    route: "control" | "listen";
+    sessionId: string;
+};
+export type VoiceMonitorAuthenticate = (input: VoiceMonitorAuthenticateInput) => boolean | Promise<boolean>;
+export type VoiceLiveMonitorRoutesOptions = {
+    authenticate?: VoiceMonitorAuthenticate;
+    basePath?: string;
+    controlHandlers?: Partial<Record<VoiceMonitorControlMessage["type"], VoiceMonitorControlHandler>>;
+    controlPath?: false | string;
+    htmlPath?: false | string;
+    listenPath?: false | string;
+    registry: VoiceMonitorRegistry;
+};
+export type VoiceMonitorPlanInput = {
+    basePath?: string;
+    baseUrl: string;
+    controlPath?: string;
+    listenPath?: string;
+    sessionId: string;
+};
+export type VoiceMonitorPlan = {
+    controlUrl: string;
+    listenUrl: string;
+};
+export declare const buildVoiceMonitorPlan: (input: VoiceMonitorPlanInput) => VoiceMonitorPlan;
+export type VoiceMonitorRuntimeBindingOptions = {
+    audioFormat?: AudioFormat;
+    defaultSource?: VoiceMonitorAudioSource;
+};
+export declare const createVoiceMonitorRuntimeBinding: (registry: VoiceMonitorMutableRegistry, options?: VoiceMonitorRuntimeBindingOptions) => VoiceMonitorRuntimeBinding;
+export declare const createVoiceLiveMonitorRoutes: (options: VoiceLiveMonitorRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/types.d.ts

@@ -411,6 +411,20 @@ export type VoiceSocket = {
     send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
     close: (code?: number, reason?: string) => void | Promise<void>;
 };
+export type VoiceMonitorRuntimeSessionBinding = {
+    deregister: (reason?: string) => void;
+    emitAudio: (chunk: Uint8Array | ArrayBuffer, options?: {
+        source?: "assistant" | "caller" | (string & {});
+    }) => void;
+};
+export type VoiceMonitorRuntimeRegisterInput = {
+    handle: VoiceSessionHandle<unknown, VoiceSessionRecord, unknown>;
+    metadata?: Record<string, unknown>;
+    sessionId: string;
+};
+export type VoiceMonitorRuntimeBinding = {
+    registerSession: (input: VoiceMonitorRuntimeRegisterInput) => VoiceMonitorRuntimeSessionBinding;
+};
 export type VoiceSessionHandle<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     id: string;
     connect: (socket: VoiceSocket) => Promise<void>;
@@ -679,6 +693,7 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     handoff?: VoiceHandoffConfig<TContext, TSession, TResult>;
     ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
     liveOps?: VoiceLiveOpsRuntimeConfig;
+    monitor?: VoiceMonitorRuntimeBinding;
     profileSwitchGuard?: VoicePluginProfileSwitchGuardConfig<TContext, TSession, TResult>;
     trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.472",
+  "version": "0.0.22-beta.474",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",