@sphoro/bugcatch-web-sdk 0.13.1

package/src/live-call.js

@@ -0,0 +1,870 @@
+// Two people, talking directly.
+//
+// The agent call next door is a microphone, a socket and a codec: the browser
+// sends µ-law up to sphoro.voice, a model answers, and every sample passes
+// through a server. This is the opposite arrangement. The audio here goes
+// straight from one browser to the other over WebRTC, and sphoro.voice's part is
+// only to introduce them — it passes an offer, an answer and a handful of ICE
+// candidates between the two sockets and then has nothing left to do.
+//
+// Which means there is no codec in this file, no resampler, and no audio path
+// at all. The browser's own WebRTC stack owns those, and it is better at them
+// than anything hand-written: Opus at whatever rate the two ends agree on,
+// echo cancellation, jitter buffering and packet loss concealment, none of
+// which the µ-law path can have because a telephone carrier cannot receive
+// them. A live call sounds better than the agent call, and costs nothing per
+// minute, because nobody is in the middle of it.
+//
+// # Shared with the dashboard
+//
+// Both ends of a live call run this file: the reporter's widget and the member
+// who answers in the portal, which imports it from here rather than keeping a
+// second copy. The two sides differ by one flag — who makes the offer — and it
+// arrives from the server rather than being decided here, so the two ends
+// cannot both sit waiting for the other to go first.
+//
+// # The one exception: the copy that gets kept
+//
+// An agent that is set to record or transcribe cannot do either from here —
+// the audio it would need never reaches it. So sphoro.voice asks instead: it
+// names, in `session.created`, what this call is keeping and in what format,
+// and each browser uplinks a copy of *its own* microphone over the signaling
+// socket it already has open. That copy is the only way a recording or a
+// transcript of a peer-to-peer call can exist at all, and it is why the codec
+// this file said it did not have is imported below.
+//
+// It is a copy and not the call. The conversation still runs browser to
+// browser; an uplink that stalls or is refused costs a recording, never a call.
+//
+// Nothing outside the package is imported to do any of it. The SDK runs on
+// someone else's page and has no dependencies, and that rule does not bend for
+// a peer connection.
+
+import { createContext, resumeContext, tapMicrophone } from './audio.js';
+
+/**
+ * sphoro.voice's realtime protocol, sent as the WebSocket subprotocol. The same
+ * one the agent call speaks — a bridged call is a different conversation over
+ * the same envelope, not a different protocol.
+ */
+const SUBPROTOCOL = 'voiceai.realtime.v1';
+
+/**
+ * Where a browser looks to find its way to the other one, when the server names
+ * nowhere.
+ *
+ * The server almost always does name somewhere — it is configured per
+ * deployment, because a network behind symmetric NAT needs a TURN relay and
+ * that costs money. This is the floor: a public STUN server, which is enough
+ * for most home and office networks and free.
+ */
+const FALLBACK_ICE = [{ urls: 'stun:stun.l.google.com:19302' }];
+
+/**
+ * Ask for the microphone.
+ *
+ * Separate from joining, and deliberately. The permission prompt takes as long
+ * as the person takes to read it, and both ends have something they should not
+ * do until it is answered: the reporter should not make a room full of
+ * dashboards ring before knowing they can speak, and whoever answers should not
+ * claim a call they then cannot take. So both ask first and act second.
+ *
+ * @returns {Promise<MediaStream>}
+ */
+export function openMicrophone() {
+  return navigator.mediaDevices.getUserMedia({
+    audio: {
+      // Both ends are on speakers as often as not. Without cancellation each
+      // hears themselves back through the other, half a second late, which is
+      // the single most effective way to make a conversation impossible.
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true,
+      channelCount: 1,
+    },
+  });
+}
+
+/** Whether this browser can be on a live call at all. */
+export function liveCallSupported() {
+  return typeof window !== 'undefined'
+    && typeof window.RTCPeerConnection === 'function'
+    && Boolean(navigator.mediaDevices?.getUserMedia);
+}
+
+/**
+ * Join a live call and stay on it until somebody hangs up.
+ *
+ * @param {object} opts
+ * @param {string} opts.realtimeUrl  From the API, carrying its own credential
+ *   and its own seat. Never log it and never build one by hand.
+ * @param {MediaStream} [opts.stream]  A microphone already opened by
+ *   `openMicrophone`. One is opened here if not, which is the wrong order for
+ *   anything that had a decision to make first.
+ * @param {string} [opts.ringsUntil]  ISO-8601, on the caller's side only: when
+ *   the ringing stops. The browser is the thing that decides it has, because it
+ *   is the one client guaranteed to still be listening at that moment.
+ * @param {(state: string, detail?: object) => void} [opts.onState]
+ *   'ringing' | 'connecting' | 'connected' | 'reconnecting' | 'ended' | 'missed'
+ *   | 'failed'. 'reconnecting' is not a failure and never ends a call — see
+ *   `routeChanged`.
+ * @param {(blocked: boolean) => void} [opts.onAudioBlocked]  The browser refused
+ *   to play the other person, or has since started. Its own callback rather
+ *   than a state, because it is orthogonal to every one of them: the call is
+ *   connected and working, and one end cannot hear it. See `playRemote`.
+ * @param {(live: boolean) => void} [opts.onMicrophone]  Whether this person's
+ *   microphone is still reaching the call. Also orthogonal, and for the same
+ *   reason: the call is up, the other end is audible, and nothing this person
+ *   says is going anywhere. See `watchMicrophone`.
+ * @returns {Promise<{hangUp: () => void, setMuted: (muted: boolean) => boolean,
+ *   isMuted: () => boolean}>}
+ */
+export async function joinLiveCall({
+  realtimeUrl, stream, ringsUntil, onState, onAudioBlocked, onMicrophone,
+}) {
+  const emit = (state, detail) => { try { onState?.(state, detail); } catch { /* theirs */ } };
+  const sayBlocked = (blocked) => {
+    try { onAudioBlocked?.(blocked); } catch { /* theirs */ }
+  };
+  const sayMicrophone = (live) => {
+    try { onMicrophone?.(live); } catch { /* theirs */ }
+  };
+
+  if (!liveCallSupported()) {
+    const err = new Error('[BugCatch] this browser cannot make live calls.');
+    emit('failed', { reason: 'unsupported' });
+    throw err;
+  }
+
+  let microphone = stream;
+  if (!microphone) {
+    try {
+      microphone = await openMicrophone();
+    } catch (err) {
+      emit('failed', { reason: 'microphone', error: String(err?.name || err) });
+      throw err;
+    }
+  }
+
+  let socket;
+  try {
+    socket = await openSocket(realtimeUrl);
+  } catch (err) {
+    stopStream(microphone);
+    emit('failed', { reason: 'connect' });
+    throw err;
+  }
+
+  let peer = null;
+  let remoteAudio = null;
+  let finished = false;
+  let ringTimer = null;
+  // What sphoro.voice said this call is keeping, and the tap feeding it. Both
+  // stay null on the ordinary call, which keeps nothing and uplinks nothing.
+  let capture = null;
+  let uplink = null;
+  // Whether the browser is currently refusing to play the other person, and the
+  // teardown for the gesture listeners armed to try again. See playRemote.
+  let blocked = false;
+  let disarmGesture = null;
+  /** Teardown for the microphone watch, armed once the peer connection is built. */
+  let unwatchMicrophone = null;
+  // Claimed synchronously, before the first await below, because the seat that
+  // answers is told the call has started twice — once in its own
+  // `session.created`, which says somebody is already waiting, and again in the
+  // `peer.joined` that goes to both ends a moment later. Two starts that both
+  // check `uplink` before either has set it are two taps on one microphone, and
+  // two copies of every frame interleaved into one recording.
+  let starting = false;
+  // Candidates that arrived before there was anywhere to put them.
+  //
+  // The offer and the first candidates are sent within a millisecond of each
+  // other and arrive in that order, but `setRemoteDescription` is a promise —
+  // so a candidate can be in hand while the description it belongs to is still
+  // being applied. Adding one then throws, and the call comes up with a worse
+  // route than it could have had, or none.
+  const pending = [];
+
+  // --- surviving a change of network ------------------------------------------------
+  //
+  // A phone call moves. Somebody walks out of the office and the handset hands the
+  // connection from Wi-Fi to cellular; a lift takes the signal for four seconds; a laptop
+  // wakes on a different access point. Every one of those changes the local address the
+  // call was negotiated against, and WebRTC's answer to all of them is the same: the ICE
+  // agent reports `disconnected`, and unless somebody restarts it, `failed` a moment later.
+  //
+  // Before this, `failed` ended the call and `disconnected` was not handled at all — so a
+  // call that would have recovered on its own in two seconds was hung up on, and one that
+  // needed a restart was hung up on with no attempt made. On a desk that is rare. On the
+  // phone this app also ships as, it is what happens when you stand up.
+  //
+  // What replaces it is a grace period, then an ICE restart, then a deadline. Each is
+  // there for a distinct reason:
+  //
+  //   the grace   `disconnected` is frequently transient — a couple of lost packets on a
+  //               route that is still fine. Restarting immediately would tear down a
+  //               working connection to rebuild the same one, and take audio with it.
+  //
+  //   the restart Renegotiation from scratch over the signaling socket, which is still
+  //               open: it never depended on the media route. This is the part that
+  //               actually crosses a network change.
+  //
+  //   the deadline Reconnecting forever is its own failure. Somebody staring at a card
+  //               that says "reconnecting" for five minutes has been abandoned more
+  //               thoroughly than somebody told the call dropped.
+  //
+  // Only one side offers, and it is the side the server nominated at the start. Both ends
+  // see the drop, so if the two sides both restarted there would be two offers crossing —
+  // a glare condition WebRTC resolves badly. The other side asks instead, over the
+  // signaling socket, and its request is best-effort: the offerer's own detection is what
+  // this actually rests on.
+
+  /** Which side was told to make the offer. Set from `peer.joined`, for both ends. */
+  let shouldOffer = false;
+  /** Whether the two ends have ever been connected. A drop before that is a failed setup. */
+  let connectedOnce = false;
+  let reconnecting = false;
+  let recoverTimer = null;
+  let giveUpTimer = null;
+  let restarts = 0;
+
+  /** How long `disconnected` is allowed to resolve itself before a restart is attempted. */
+  const RECOVER_GRACE_MS = 2000;
+  /** How long between one restart and the next, when the first did not take. */
+  const RECOVER_RETRY_MS = 5000;
+  /** How long a call may spend off the air in total before it is called dropped. */
+  const RECOVER_DEADLINE_MS = 30000;
+  const MAX_RESTARTS = 4;
+
+  /** Everything ends here, whatever ended it, exactly once. */
+  const finish = (state, detail) => {
+    if (finished) return;
+    finished = true;
+    if (ringTimer) { clearTimeout(ringTimer); ringTimer = null; }
+    // Before the peer is closed, and before the stream is stopped. Closing a connection
+    // moves it to `closed` and stopping a track fires `ended`, and both would otherwise
+    // reach handlers that would report a dropped call and a dead microphone to somebody
+    // who has just hung up.
+    clearRecovery();
+    unwatchMicrophone?.();
+    unwatchMicrophone = null;
+    stopUplink();
+    // Before anything else is torn down: these are listeners on `window`, and a
+    // call that left them behind would keep retrying playback on an element
+    // that is about to be removed — once per click, for the rest of the session.
+    disarmGesture?.();
+    disarmGesture = null;
+    try { peer?.close(); } catch { /* already gone */ }
+    stopStream(microphone);
+    if (remoteAudio) {
+      remoteAudio.srcObject = null;
+      remoteAudio.remove();
+      remoteAudio = null;
+    }
+    try {
+      if (socket.readyState === WebSocket.OPEN) socket.close(1000, 'call over');
+    } catch { /* already closing */ }
+    emit(state, detail);
+  };
+
+  const send = (message) => {
+    if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message));
+  };
+
+  /**
+   * Start sending sphoro.voice a copy of this person's microphone.
+   *
+   * Only when it asked, and only once both people are on the call. The server
+   * throws away anything that arrives while the phone is still ringing — a
+   * recording is timed from the moment the second person joined, and a minute
+   * of somebody waiting alone at the head of the file is a timeline that
+   * disagrees with the call's own duration. Sending it anyway would just be
+   * bandwidth spent on audio that gets dropped, on the same network carrying
+   * the call.
+   *
+   * Every failure here is survivable and none of them ends the call. A browser
+   * with no Web Audio, a context the autoplay policy will not start, a format
+   * this version does not know how to produce — each costs the recording and
+   * leaves two people talking, which is the right way round. It is said out
+   * loud, though: an agent set to record whose calls silently arrive with no
+   * audio is the failure that is impossible to diagnose from the outside.
+   */
+  const startUplink = async () => {
+    if (starting || uplink || finished || !capture) return;
+    if (!capture.audio && !capture.transcript) return;
+    starting = true;
+
+    // The server names the format rather than assuming one, so a client that
+    // does not recognise it sends nothing rather than sending µ-law into a
+    // recording that expected something else — which would store a file of
+    // noise and read as a working recording to everything downstream.
+    const encoding = capture.encoding || 'mulaw';
+    if (encoding !== 'mulaw') {
+      warn(`this call is kept as ${encoding}, which this SDK cannot produce.`);
+      return;
+    }
+
+
+    const rate = Number(capture.sample_rate) || 8000;
+    try {
+      const context = createContext(rate);
+      // A context built without a user gesture starts suspended, and a
+      // suspended context's ScriptProcessorNode never fires — so nothing would
+      // be uplinked and nothing would say why. Both ends granted microphone
+      // access a moment ago, which is the activation this spends.
+      await resumeContext(context);
+      if (finished) {
+        try { context.close(); } catch { /* already closed */ }
+        return;
+      }
+
+      const tap = tapMicrophone(context, microphone, (bytes) => {
+        // Binary, not the base64 envelope the protocol also accepts: this is a
+        // second copy of audio going up a network that is already carrying the
+        // call, and base64 would make it a third larger for nothing.
+        if (socket.readyState === WebSocket.OPEN) socket.send(bytes);
+      }, rate);
+
+      uplink = { context, tap };
+    } catch (err) {
+      warn(`could not send the copy this call is keeping: ${String(err?.message || err)}`);
+    }
+  };
+
+  /**
+   * Stop sending it.
+   *
+   * The microphone track is deliberately left alone — `finish` stops the whole
+   * stream a moment later, and stopping it here would cut the conversation off
+   * to end a recording.
+   */
+  function stopUplink() {
+    starting = false;
+    if (!uplink) return;
+    const { context, tap } = uplink;
+    uplink = null;
+    try { tap.stop(); } catch { /* already gone */ }
+    try { context.close(); } catch { /* already closed */ }
+  }
+
+  /**
+   * Play the other person, and do something about it when the browser says no.
+   *
+   * The refusal used to be swallowed: `play().catch(() => {})`, on the reasoning
+   * that both ends had granted microphone access a moment earlier and that
+   * satisfies every autoplay policy. It does not always. A call answered from a
+   * notification arrives with no user gesture on the page at all — the tap
+   * happened on a system notification, which is not this document — and inside
+   * an Android WebView that is exactly the case that fails.
+   *
+   * What that produced is the worst shape a bug can have: the call connects,
+   * every state says `connected`, both ends are billed for it, and one person
+   * hears nothing. Nothing is logged, because the rejection was caught and
+   * dropped, so there is no evidence anywhere that it happened.
+   *
+   * So now it is reported and it is retried. The retry is armed on the next
+   * gesture anywhere on the page, which is the one thing that reliably lifts an
+   * autoplay block, and it is armed in capture so a handler calling
+   * `stopPropagation` cannot hide the gesture from it. Whoever is on the call is
+   * about to touch something — the mute button, the hang-up button, the report
+   * they are talking about — and the sound comes up when they do, with the
+   * caller free to say so on screen in the meantime.
+   */
+  function playRemote() {
+    if (!remoteAudio || finished) return;
+    let attempt;
+    try {
+      attempt = remoteAudio.play?.();
+    } catch {
+      // A synchronous throw, which some engines do instead of rejecting.
+      markBlocked();
+      return;
+    }
+    if (!attempt || typeof attempt.then !== 'function') {
+      // No promise: an older engine, or a stub. Nothing to wait on and nothing
+      // to report — it either made a sound or it did not.
+      markPlaying();
+      return;
+    }
+    attempt.then(markPlaying, markBlocked);
+  }
+
+  function markPlaying() {
+    disarmGesture?.();
+    disarmGesture = null;
+    if (!blocked) return;
+    blocked = false;
+    sayBlocked(false);
+  }
+
+  function markBlocked() {
+    if (finished) return;
+    if (!blocked) {
+      blocked = true;
+      sayBlocked(true);
+    }
+    armGesture();
+  }
+
+  /** Try again on the next thing the person touches. Armed once. */
+  function armGesture() {
+    if (disarmGesture) return;
+    // Guarded rather than assumed: this file is also loaded by a host page's
+    // bundler into environments that define a partial `window`, and a retry
+    // that cannot be armed is a quieter failure than one that throws inside a
+    // promise nobody is awaiting.
+    if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
+    const retry = () => playRemote();
+    const events = ['pointerdown', 'keydown', 'touchstart'];
+    for (const name of events) {
+      window.addEventListener(name, retry, { capture: true, passive: true });
+    }
+    disarmGesture = () => {
+      for (const name of events) {
+        try { window.removeEventListener(name, retry, { capture: true }); } catch { /* gone */ }
+      }
+    };
+  }
+
+  /**
+   * Build the peer connection.
+   *
+   * Made on `session.created` rather than lazily on the first signal, because
+   * the ICE gathering it starts is the slowest part of connecting and the whole
+   * of it can happen while the phone is still ringing. Waiting until somebody
+   * answers would add that delay to the exact moment a person says hello, which
+   * is the one moment on this call where it is audible.
+   */
+  const build = (iceServers) => {
+    peer = new RTCPeerConnection({ iceServers: iceServers?.length ? iceServers : FALLBACK_ICE });
+
+    for (const track of microphone.getAudioTracks()) peer.addTrack(track, microphone);
+
+    // Armed here rather than at the top, so a call that never got a peer connection has
+    // nothing to tear down — and so the watch covers exactly the span in which being
+    // unheard is a problem worth telling somebody about.
+    unwatchMicrophone = watchMicrophone();
+
+    peer.onicecandidate = (event) => {
+      if (!event.candidate) return;
+      send({ type: 'signal', signal: { kind: 'candidate', payload: event.candidate.toJSON() } });
+    };
+
+    peer.ontrack = (event) => {
+      const [incoming] = event.streams;
+      if (!incoming) return;
+      // An element rather than the Web Audio API. Audio routed through a
+      // MediaStreamAudioSourceNode loses the browser's own echo cancellation on
+      // several engines, and this call has a live microphone next to it.
+      if (!remoteAudio) {
+        remoteAudio = document.createElement('audio');
+        remoteAudio.autoplay = true;
+        // Inline, for a WebView that would otherwise hand a media element to a
+        // full-screen player — which on a call is a black rectangle over the
+        // dashboard.
+        remoteAudio.playsInline = true;
+        remoteAudio.setAttribute?.('playsinline', '');
+        // Off-screen rather than display:none — a hidden media element is
+        // treated as invisible by some autoplay heuristics and refused.
+        remoteAudio.style.cssText = 'position:fixed;width:0;height:0;opacity:0;pointer-events:none';
+        document.body.appendChild(remoteAudio);
+      }
+      remoteAudio.srcObject = incoming;
+      playRemote();
+    };
+
+    peer.onconnectionstatechange = routeChanged;
+    // The same signal, read the other way, for the engines that do not give a reliable
+    // `connectionState`. WebKit — which is every browser on iOS and the WebView this app
+    // ships inside there — has historically fired `iceconnectionstatechange` and not the
+    // aggregate one. Both are wired to the same handler, which reads whichever of the two
+    // the engine actually maintains, so a duplicate event costs one comparison.
+    peer.oniceconnectionstatechange = routeChanged;
+  };
+
+  /**
+   * What the media route is doing, and what to do about it.
+   *
+   * Reads whichever state the engine keeps up to date, and treats `completed` — which only
+   * the ICE-level state has — as connected, because it is: it means a route was found and
+   * checking has stopped.
+   */
+  function routeChanged() {
+    if (!peer || finished) return;
+    const state = peer.connectionState || peer.iceConnectionState;
+
+    if (state === 'connected' || state === 'completed') {
+      connectedOnce = true;
+      restarts = 0;
+      clearRecovery();
+      // Emitted whether or not this is a reconnection. The caller renders one state, and a
+      // card that came back from "reconnecting" has to be told the call is up again.
+      reconnecting = false;
+      emit('connected');
+      return;
+    }
+
+    if (state === 'disconnected') {
+      // Before the two ends ever met, a `disconnected` is ICE still working — it goes
+      // there between checking one candidate pair and the next. Only `failed` is final at
+      // that stage, and it is handled below.
+      if (!connectedOnce) return;
+      enterRecovery(RECOVER_GRACE_MS);
+      return;
+    }
+
+    if (state === 'failed') {
+      if (!connectedOnce) {
+        // The two browsers never found a route to each other at all. Almost always a
+        // network that needs a TURN relay the deployment has not configured; reported as
+        // its own reason so that is diagnosable from a support ticket rather than from a
+        // packet capture. A restart would try the same candidates again.
+        finish('failed', { reason: 'ice' });
+        return;
+      }
+      // A route that worked and then stopped. That is a network change, and a restart is
+      // exactly the remedy — no grace, because `failed` is not going to resolve itself.
+      enterRecovery(0);
+    }
+  }
+
+  /** Say the call is off the air, and line up an attempt to bring it back. */
+  function enterRecovery(delay) {
+    if (finished) return;
+    if (!reconnecting) {
+      reconnecting = true;
+      emit('reconnecting');
+      giveUpTimer = setTimeout(() => finish('failed', { reason: 'network' }), RECOVER_DEADLINE_MS);
+    }
+    // One attempt in flight at a time. `disconnected` and `failed` both arrive on the way
+    // down, and two timers would mean two offers crossing on one connection.
+    if (recoverTimer) return;
+    recoverTimer = setTimeout(recover, delay);
+  }
+
+  function clearRecovery() {
+    if (recoverTimer) { clearTimeout(recoverTimer); recoverTimer = null; }
+    if (giveUpTimer) { clearTimeout(giveUpTimer); giveUpTimer = null; }
+  }
+
+  /**
+   * Renegotiate the media route over the signaling socket, which never left.
+   *
+   * `createOffer({ iceRestart: true })` rather than `restartIce()`: the latter is the
+   * modern spelling and does the same thing by firing `negotiationneeded`, but it is
+   * missing from engines this SDK is expected to run in and the explicit form works
+   * everywhere. It also keeps the offer on the same path as the original one, so there is a
+   * single place where an offer is made.
+   */
+  async function recover() {
+    recoverTimer = null;
+    if (finished || !peer) return;
+    // It came back on its own while the grace period was running, which is the common case
+    // and the reason the grace period exists.
+    const state = peer.connectionState || peer.iceConnectionState;
+    if (state === 'connected' || state === 'completed') return;
+
+    if (!shouldOffer) {
+      // Not this side's to restart. Ask, and keep asking — the offerer sees the same drop
+      // and is very likely already doing it, so this is the belt to that braces.
+      send({ type: 'signal', signal: { kind: 'restart', payload: {} } });
+      recoverTimer = setTimeout(recover, RECOVER_RETRY_MS);
+      return;
+    }
+
+    if (restarts >= MAX_RESTARTS) return; // the deadline is what ends it
+    restarts += 1;
+    await restartIce();
+    recoverTimer = setTimeout(recover, RECOVER_RETRY_MS);
+  }
+
+  /** The restart itself, also reachable from the other side's request. */
+  async function restartIce() {
+    if (finished || !peer) return;
+    try {
+      const description = await peer.createOffer({ iceRestart: true });
+      await peer.setLocalDescription(description);
+      send({ type: 'signal', signal: { kind: 'offer', payload: peer.localDescription.toJSON() } });
+    } catch {
+      // Nothing to do here but let the next attempt or the deadline decide. Ending the
+      // call on one refused renegotiation would throw away the retries that follow.
+    }
+  }
+
+  /**
+   * Whether this person is still being heard.
+   *
+   * A track's `muted` is not the mute button — that is `enabled`, which this file sets and
+   * therefore already knows about. `muted` is the *source* stopping: the OS handed the
+   * microphone to an incoming phone call, a headset was unplugged, or — the case this app
+   * meets daily — Android revoked microphone access because the app went to the background.
+   *
+   * Which produces the same shape as every other bug on this path: the call is up, the
+   * other person is audible, both ends are billed, and nothing this person says goes
+   * anywhere. They find out when the other person says "hello? are you there?".
+   *
+   * The loss is reported on a short delay and the recovery immediately. Several engines
+   * flick `muted` on for a few frames while a track settles, and a card that said "your
+   * microphone was cut off" for 200ms at the start of every call would be noise — while a
+   * microphone that came back and was still reported lost is the error saying the wrong
+   * thing.
+   */
+  function watchMicrophone() {
+    const SETTLE_MS = 600;
+    let settle = null;
+    let lost = false;
+
+    const say = (live) => {
+      if (settle) { clearTimeout(settle); settle = null; }
+      if (live) {
+        if (!lost) return;
+        lost = false;
+        sayMicrophone(true);
+        return;
+      }
+      if (lost) return;
+      settle = setTimeout(() => {
+        settle = null;
+        if (finished) return;
+        lost = true;
+        sayMicrophone(false);
+      }, SETTLE_MS);
+    };
+
+    for (const track of microphone.getAudioTracks()) {
+      track.onmute = () => say(false);
+      track.onunmute = () => say(true);
+      // An ended track never comes back — the device is gone. Said at once rather than
+      // after the settle, because there is nothing to wait for.
+      track.onended = () => {
+        if (settle) { clearTimeout(settle); settle = null; }
+        if (lost) return;
+        lost = true;
+        sayMicrophone(false);
+      };
+    }
+    return () => {
+      if (settle) { clearTimeout(settle); settle = null; }
+      for (const track of microphone.getAudioTracks()) {
+        track.onmute = null;
+        track.onunmute = null;
+        track.onended = null;
+      }
+    };
+  }
+
+  const offer = async () => {
+    try {
+      const description = await peer.createOffer();
+      await peer.setLocalDescription(description);
+      send({ type: 'signal', signal: { kind: 'offer', payload: peer.localDescription.toJSON() } });
+    } catch {
+      finish('failed', { reason: 'negotiation' });
+    }
+  };
+
+  const accept = async (payload) => {
+    try {
+      await peer.setRemoteDescription(new RTCSessionDescription(payload));
+      const answer = await peer.createAnswer();
+      await peer.setLocalDescription(answer);
+      send({ type: 'signal', signal: { kind: 'answer', payload: peer.localDescription.toJSON() } });
+      await drainCandidates();
+    } catch {
+      finish('failed', { reason: 'negotiation' });
+    }
+  };
+
+  const drainCandidates = async () => {
+    while (pending.length) {
+      const candidate = pending.shift();
+      try {
+        await peer.addIceCandidate(new RTCIceCandidate(candidate));
+      } catch {
+        // One unusable candidate is not a failed call — there are usually
+        // several, and the connection needs only one of them to work.
+      }
+    }
+  };
+
+  /**
+   * One message at a time, in the order they arrived.
+   *
+   * Handling is asynchronous — `setRemoteDescription` and `createAnswer` are
+   * promises — and the socket does not wait. Without this chain a candidate
+   * arriving mid-answer is examined while the description it belongs to is
+   * still being applied, so it goes on the pending list a moment after the
+   * pending list was drained, and stays there for the rest of the call.
+   */
+  let handling = Promise.resolve();
+  socket.onmessage = (event) => {
+    handling = handling.then(() => handle(event)).catch(() => { /* one bad frame */ });
+  };
+
+  const handle = async (event) => {
+    if (typeof event.data !== 'string') return;
+    let message;
+    try { message = JSON.parse(event.data); } catch { return; }
+
+    switch (message.type) {
+      case 'session.created': {
+        build(message.data?.ice_servers);
+        // What this call keeps, and in what format. Held rather than acted on:
+        // nothing is uplinked until somebody is actually on the other end.
+        capture = message.data?.capture || null;
+        // Ringing, until somebody is on the other side. Whoever answers finds
+        // the caller already waiting and skips straight past it — the
+        // `peer.joined` that follows a moment later says the same thing, and
+        // this is what keeps the answerer's first frame from being silence.
+        if (message.data?.peer_present) {
+          emit('connecting');
+          void startUplink();
+          break;
+        }
+        emit('ringing');
+        armRingTimer();
+        break;
+      }
+
+      case 'peer.joined': {
+        if (ringTimer) { clearTimeout(ringTimer); ringTimer = null; }
+        emit('connecting');
+        // Told, not inferred. Both ends learn somebody arrived in the same
+        // frame, and only one of them is asked to go first.
+        //
+        // Remembered as well as acted on: it is also the answer to "whose job is it to
+        // renegotiate when the network changes", and that question is asked later, when
+        // the frame that answered it is long gone. See `recover`.
+        shouldOffer = Boolean(message.data?.should_offer);
+        if (shouldOffer) await offer();
+        // After the offer, and not awaited: opening an audio context is
+        // milliseconds, but they would be milliseconds added to the moment
+        // somebody says hello, which is the one place on this call where they
+        // are audible.
+        void startUplink();
+        break;
+      }
+
+      case 'signal': {
+        if (!peer) break;
+        const { kind, payload } = message.data || {};
+        if (kind === 'offer') {
+          await accept(payload);
+        } else if (kind === 'answer') {
+          try {
+            await peer.setRemoteDescription(new RTCSessionDescription(payload));
+            await drainCandidates();
+          } catch {
+            finish('failed', { reason: 'negotiation' });
+          }
+        } else if (kind === 'candidate') {
+          if (peer.remoteDescription) {
+            try { await peer.addIceCandidate(new RTCIceCandidate(payload)); } catch { /* see above */ }
+          } else {
+            pending.push(payload);
+          }
+        } else if (kind === 'restart') {
+          // The other side lost the route and cannot renegotiate itself. Honoured only by
+          // the side that was nominated to offer, so a request arriving at both ends of a
+          // mis-signalled call cannot produce two offers crossing.
+          if (shouldOffer) await restartIce();
+        }
+        break;
+      }
+
+      case 'peer.left':
+        finish('ended', { reason: 'peer_left' });
+        break;
+
+      case 'error':
+        finish('failed', { reason: 'server', detail: message.error?.detail });
+        break;
+
+      case 'session.ended':
+        finish('ended', { reason: 'server' });
+        break;
+
+      default:
+        // Every message the agent conversation has — audio deltas, transcripts,
+        // state changes. None of them happen on a bridged call, and one
+        // arriving is not worth ending a working call over.
+        break;
+    }
+  };
+
+  socket.onclose = () => finish('ended', { reason: 'disconnected' });
+  socket.onerror = () => finish('failed', { reason: 'socket' });
+
+  /**
+   * Stop waiting.
+   *
+   * The deadline comes from the server, which wrote it down when the call was
+   * created — so a browser with a slow clock waits a little longer rather than
+   * hanging up on somebody mid-answer, and the server refuses a give-up that
+   * arrives early in any case.
+   */
+  function armRingTimer() {
+    if (!ringsUntil) return;
+    const remaining = new Date(ringsUntil).getTime() - Date.now();
+    if (!Number.isFinite(remaining)) return;
+    ringTimer = setTimeout(() => finish('missed'), Math.max(0, remaining));
+  }
+
+  return {
+    hangUp() {
+      // Said out loud before the socket closes. A close on its own would end
+      // the call too — sphoro.voice ends a bridge the moment one side leaves —
+      // but saying so first is what distinguishes hanging up from a tunnel.
+      send({ type: 'session.end' });
+      finish('ended', { reason: 'hung_up' });
+    },
+    setMuted(muted) {
+      for (const track of microphone.getAudioTracks()) track.enabled = !muted;
+      return muted;
+    },
+    isMuted() {
+      return microphone.getAudioTracks().every((track) => !track.enabled);
+    },
+  };
+}
+
+/** Open the socket, resolving only once it is actually open. */
+function openSocket(url) {
+  return new Promise((resolve, reject) => {
+    let socket;
+    try {
+      socket = new WebSocket(url, SUBPROTOCOL);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    socket.onopen = () => {
+      socket.onopen = null;
+      socket.onerror = null;
+      resolve(socket);
+    };
+    socket.onerror = () => {
+      socket.onopen = null;
+      socket.onerror = null;
+      reject(new Error('[BugCatch] could not connect the call.'));
+    };
+  });
+}
+
+/**
+ * Say something went wrong with the copy, without ending anything.
+ *
+ * `console.warn` and not a state: every caller of this file renders the states
+ * to somebody who is mid-conversation, and "the recording did not start" is not
+ * news to the two people talking. It is news to whoever turned recording on,
+ * and the console is where they will look.
+ */
+function warn(message) {
+  try { console.warn(`[BugCatch] ${message}`); } catch { /* no console */ }
+}
+
+function stopStream(stream) {
+  for (const track of stream?.getTracks?.() ?? []) {
+    try { track.stop(); } catch { /* already stopped */ }
+  }
+}