@coventia/softphone 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -92,7 +92,7 @@ var init_token_cache = __esm({
 });
 
 // src/coventia/api.ts
-function createGet(config) {
+function createRequest(config, method) {
   const doFetch = config.fetch ? config.fetch : (...args) => globalThis.fetch(...args);
   const base = config.baseUrl.replace(/\/+$/, "");
   async function attempt(path, params, signal) {
@@ -103,6 +103,7 @@ function createGet(config) {
     }
     const query = qs.toString();
     const res = await doFetch(`${base}${path}${query ? `?${query}` : ""}`, {
+      method,
       // The RAW token, no `Bearer ` prefix — see `VoiceToken.token` (SPEC §6.1).
       headers: { Authorization: token },
       ...signal ? { signal } : {}
@@ -115,7 +116,7 @@ function createGet(config) {
     }
     return body;
   }
-  return async function get(path, params = {}, signal) {
+  return async function request(path, params = {}, signal) {
     try {
       return await attempt(path, params, signal);
     } catch (error) {
@@ -125,6 +126,12 @@ function createGet(config) {
     }
   };
 }
+function createGet(config) {
+  return createRequest(config, "GET");
+}
+function createPost(config) {
+  return createRequest(config, "POST");
+}
 var ApiError;
 var init_api = __esm({
   "src/coventia/api.ts"() {
@@ -167,6 +174,7 @@ function resolverFromContacts(contacts) {
 }
 function coventiaSources(config) {
   const get = createGet(config);
+  const post = createPost(config);
   const base = config.basePath ?? "/phone";
   const org = config.organizationId ? { organization_id: config.organizationId } : {};
   const coventiaContacts = async ({ search, skip, limit }) => {
@@ -251,12 +259,93 @@ function coventiaSources(config) {
       people: (body.people ?? []).map(toAgent)
     };
   };
+  const coventiaTransferOutcomes = async ({ since }) => {
+    const body = await get(
+      `${base}/transfers/outcomes`,
+      { ...org, since }
+    );
+    return {
+      cursor: body.cursor ?? "0",
+      outcomes: (body.outcomes ?? []).map(toTransferOutcome)
+    };
+  };
+  const coventiaPresence = (callbacks) => {
+    const WS = config.WebSocket ?? globalThis.WebSocket;
+    return new Promise((resolve2, reject) => {
+      void (async () => {
+        let ticket;
+        try {
+          const body = await post(`${base}/presence/ticket`, org);
+          if (!body.ticket) throw new Error("presence ticket mint returned no ticket");
+          ticket = body.ticket;
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        const wsUrl = `${toWebSocketUrl(config.baseUrl)}${base}/presence?ticket=${encodeURIComponent(ticket)}`;
+        const ws = new WS(wsUrl);
+        let settled = false;
+        ws.onopen = () => {
+          if (settled) return;
+          settled = true;
+          resolve2({
+            reportCallState: (onCall) => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "call-state", onCall }));
+            },
+            bye: () => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "bye" }));
+            },
+            close: () => {
+              ws.onclose = null;
+              ws.onerror = null;
+              ws.close();
+            }
+          });
+        };
+        ws.onmessage = (event) => {
+          let data;
+          try {
+            data = JSON.parse(String(event.data));
+          } catch {
+            return;
+          }
+          const msg = data;
+          if (msg.type === "snapshot") {
+            callbacks.onSnapshot((msg.agents ?? []).map(toPresenceEntry));
+          } else if (msg.type === "delta" && msg.agent) {
+            callbacks.onDelta(toPresenceEntry(msg.agent));
+          }
+        };
+        ws.onclose = () => {
+          if (!settled) {
+            settled = true;
+            reject(new Error("presence socket closed before opening"));
+            return;
+          }
+          callbacks.onClose();
+        };
+        ws.onerror = () => {
+        };
+      })();
+    });
+  };
   const contacts = config.contacts ?? coventiaContacts;
   const resolve = config.resolveContact ?? (config.contacts ? resolverFromContacts(config.contacts) : coventiaResolve);
   const history = withNameResolution(rawHistory, resolve);
-  return { contacts, history, resolveContact: resolve, listAgents: coventiaListAgents };
+  const transferOutcomes = config.transferOutcomes ?? coventiaTransferOutcomes;
+  const presence = config.presence ?? coventiaPresence;
+  return {
+    contacts,
+    history,
+    resolveContact: resolve,
+    listAgents: coventiaListAgents,
+    transferOutcomes,
+    presence
+  };
 }
-var toContact, toDirection, otherParty, isMissed, toOutcome, toDate;
+var toContact, toDirection, otherParty, isMissed, toOutcome, toDate, toTransferOutcome, toPresenceState, toPresenceEntry, toWebSocketUrl;
 var init_sources2 = __esm({
   "src/coventia/sources.ts"() {
     init_sources();
@@ -291,6 +380,20 @@ var init_sources2 = __esm({
       const d = new Date(raw);
       return Number.isNaN(d.getTime()) ? /* @__PURE__ */ new Date(0) : d;
     };
+    toTransferOutcome = (row) => ({
+      id: row.id ?? "",
+      target: row.target ?? "",
+      status: row.status === "connected" ? "connected" : "not-connected",
+      at: toDate(row.at)
+    });
+    toPresenceState = (raw) => raw === "disponible" || raw === "en_llamada" ? raw : "desconectado";
+    toPresenceEntry = (row) => ({
+      userId: row.userId ?? "",
+      extension: row.extension ?? "",
+      name: row.name ?? null,
+      state: toPresenceState(row.state)
+    });
+    toWebSocketUrl = (httpUrl) => httpUrl.replace(/^http/, "ws").replace(/\/+$/, "");
   }
 });
 
@@ -746,6 +849,14 @@ var init_ua = __esm({
       #uaInFlight = null;
       #domain = "";
       #activeCall = null;
+      /**
+       * The consult leg from `startConsult` (SPEC §5.6), if one is live on this UA right now.
+       *
+       * Tracked separately from `#activeCall` so `#maybeTeardownUA` can tell "both legs are actually gone"
+       * apart from "the main leg ended, but a consult is still up" — see that method's own comment for the
+       * bug this exists to prevent.
+       */
+      #consultCall = null;
       /** The chosen microphone, or `null` for the browser default. Read fresh by every new leg's
        *  `mediaConstraints`, and pushed live to `#activeCall` by `setInputDevice`. */
       #inputDeviceId = null;
@@ -864,9 +975,7 @@ var init_ua = __esm({
         const ms = this.provider.quirks?.noInviteTeardownMs;
         if (!ms) return;
         this.#clearNoInviteTimer();
-        this.#noInviteTimer = setTimeout(() => {
-          if (!this.#activeCall) this.#teardownUA();
-        }, ms);
+        this.#noInviteTimer = setTimeout(() => this.#maybeTeardownUA(), ms);
       }
       /**
        * Rebuild the incoming-signal channel with fresh credentials, after a registration failure.
@@ -988,6 +1097,7 @@ var init_ua = __esm({
         }
         this.#ua = null;
         this.#activeCall = null;
+        this.#consultCall = null;
       }
       /** Place a call once the UA is registered (its 200 OK for REGISTER has arrived). */
       /**
@@ -1030,7 +1140,7 @@ var init_ua = __esm({
             const code = missed ? "call/missed" : CALL_END_CODES[event.reason];
             if (code) this.#reportError(code, event.cause);
             if (this.#activeCall === call) this.#activeCall = null;
-            if (this.provider.registrationMode === "on-demand") this.#teardownUA();
+            this.#maybeTeardownUA();
           }
         });
         return call;
@@ -1041,12 +1151,38 @@ var init_ua = __esm({
           mediaConstraints: buildAudioConstraints(this.#inputDeviceId),
           pcConfig: PC_CONFIG
         });
-        return new SipEngineCall(consultSession, {
+        const consultCall = new SipEngineCall(consultSession, {
           id: nextCallId(),
           buildTarget: (x) => this.#buildTarget(x),
           placeConsult: () => Promise.reject(new Error("cannot consult from a consult leg")),
           iceGatheringCapMs: this.provider.quirks?.iceGatheringCapMs ?? DEFAULT_ICE_CAP_MS
         });
+        this.#consultCall = consultCall;
+        consultCall.onEvent((event) => {
+          if (event.type === "ended") {
+            if (this.#consultCall === consultCall) this.#consultCall = null;
+            this.#maybeTeardownUA();
+          }
+        });
+        return consultCall;
+      }
+      /**
+       * On-demand registration (SPEC §3.3): the UA is disposable once NOTHING is left on it — but "the
+       * main leg ended" (or "no INVITE followed this push") is not the same fact as "nothing is left."
+       * `completeTransfer()` (SPEC §5.6) ends the main leg via a REFER…Replaces BYE *while the consult leg
+       * is still what the PBX needs to bridge the caller onto* — tearing the UA down (and with it, EVERY
+       * session on it, via `terminateSessions`) the instant the main leg's `ended` fires killed that
+       * consult leg out from under the transfer before the bridge could use it, and the caller was simply
+       * gone. Two real call sites hit this independently (found live, 2026-08-04): the main leg's own
+       * `ended` handler, and `#armNoInviteTeardown`'s 5s timer — the latter re-arms on EVERY push,
+       * including unrelated "answered" pushes Zadarma sends around other account activity, so it can fire
+       * minutes after a transfer with no `#activeCall` and no idea a consult leg is mid-handoff. Both now
+       * route through here rather than checking `#activeCall` alone.
+       */
+      #maybeTeardownUA() {
+        if (this.provider.registrationMode !== "on-demand") return;
+        if (this.#activeCall || this.#consultCall) return;
+        this.#teardownUA();
       }
       #startRejectGuard() {
         const ms = this.provider.quirks?.rejectGuardMs;
@@ -1090,11 +1226,13 @@ function buildPushUrl(key, sip) {
   const params = new URLSearchParams({ key, integrationType: "site", sipId: sip });
   return `wss://ws.zadarma.com/webrtc_pushes?${params.toString()}`;
 }
-var PING, KEY_REFRESH_BUFFER_MS, ZADARMA_QUIRKS, ZadarmaPushSignal, ZadarmaProvider;
+var PING, KEY_REFRESH_BUFFER_MS, REBUILD_CONNECT_TIMEOUT_MS, REBUILD_RETRY_MS, ZADARMA_QUIRKS, ZadarmaPushSignal, ZadarmaProvider;
 var init_zadarma = __esm({
   "src/transports/providers/zadarma.ts"() {
     PING = { localMs: 3e4, globalMs: 6e4 };
     KEY_REFRESH_BUFFER_MS = 2 * 60 * 60 * 1e3;
+    REBUILD_CONNECT_TIMEOUT_MS = 1e4;
+    REBUILD_RETRY_MS = 3e4;
     ZADARMA_QUIRKS = {
       // Zadarma's registrar REFUSES to register a WebRTC client with any other User-Agent — a clean 401
       // after a valid digest challenge, indistinguishable from a wrong password (§3.1). The old CRM
@@ -1118,6 +1256,12 @@ var init_zadarma = __esm({
       #connected = false;
       #pingTimers = [];
       #refreshTimer;
+      /** The replacement socket of a rebuild in flight, not yet current. */
+      #candidate = null;
+      /** Abandons the rebuild in flight (closing its candidate). */
+      #abortRebuild = null;
+      #rebuilding = false;
+      #retryTimer;
       #unwatchBackground;
       #closed = false;
       #listeners = /* @__PURE__ */ new Set();
@@ -1133,20 +1277,35 @@ var init_zadarma = __esm({
         if (this.#closed) return;
         const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
         this.#socket = socket;
+        this.#attach(socket);
+        this.#armRefresh(keyExpiresAt);
+      }
+      /**
+       * Wires one socket's events. `this.#socket` is read when an event FIRES, not when it is wired: a socket that
+       * has been replaced must stop driving connectivity (our own `close()` of it emits `disconnect`, which would
+       * otherwise flip the state to offline right after a perfectly healthy swap). `update` is the exception — it is
+       * forwarded from any socket not yet closed, because a push seen twice is harmless (the engine ignores a
+       * repeated signal mid-call and reuses a UA that already exists) while one seen by neither is a missed call.
+       *
+       * With `hooks`, the socket is a rebuild's candidate: its first `connect` or failure goes to the rebuild instead
+       * of changing the connection state (it is not current yet).
+       */
+      #attach(socket, hooks) {
         socket.on("connect", () => {
+          if (hooks && socket === this.#candidate) return hooks.onConnect();
+          if (socket !== this.#socket) return;
           this.#setConnected(true);
           this.#startPings(socket);
         });
         socket.on("update", () => this.#emit());
-        socket.on("disconnect", () => {
-          this.#stopPings();
-          this.#setConnected(false);
-        });
-        socket.on("connect_error", () => {
+        const lost = () => {
+          if (hooks && socket === this.#candidate) return hooks.onFailure();
+          if (socket !== this.#socket) return;
           this.#stopPings();
           this.#setConnected(false);
-        });
-        this.#armRefresh(keyExpiresAt);
+        };
+        socket.on("disconnect", lost);
+        socket.on("connect_error", lost);
       }
       /**
        * Presence pings — **the reason an idle tab keeps receiving calls**.
@@ -1185,22 +1344,92 @@ var init_zadarma = __esm({
         if (!Number.isFinite(ms) || ms <= 0) return;
         this.#refreshTimer = setTimeout(() => void this.#reopen(), ms);
       }
+      /**
+       * Replaces the push socket with a fresh one — MAKE-BEFORE-BREAK (presence-client-reporting.md §4.1, T8).
+       *
+       * Why it must happen at all: Zadarma's gateway decides the extension is alive from the raw Engine.IO ping, which
+       * a hidden tab's throttled timers silently stop sending, so while the tab is hidden the socket is rebuilt every
+       * 20 s (`push-socket-reliability.md` §5.3), and once before the key expires. Why it must not leave a gap: the
+       * old close-then-reopen reported `connected = false` for the ~0.5 s in between, which took the softphone
+       * `offline`, tore down the presence socket and left Zadarma with no socket to push an incoming call to.
+       *
+       * Now the OLD socket stays up and stays current until the NEW one has actually connected; only then do we swap,
+       * move the pings and close the old one. A healthy rebuild never changes `connected`. A failed one — the key fetch
+       * throws, the socket errors, or it has not connected within `REBUILD_CONNECT_TIMEOUT_MS` — keeps the old socket
+       * and retries, instead of leaving the tab disconnected. Zadarma does not evict the older of two sockets for one
+       * sip (multi-tab-leader-election.md §1), so the overlap is safe.
+       */
       async #reopen() {
-        if (this.#closed) return;
-        this.#stopPings();
-        this.#socket?.close();
-        this.#socket = null;
-        this.#setConnected(false);
+        if (this.#closed || this.#rebuilding) return;
+        if (!this.#socket) {
+          try {
+            await this.#open();
+          } catch {
+          }
+          return;
+        }
+        this.#rebuilding = true;
         try {
-          await this.#open();
+          const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
+          if (this.#closed) return;
+          const swapped = await new Promise((resolve) => {
+            const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
+            this.#candidate = socket;
+            let settled = false;
+            const finish = (ok) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              this.#abortRebuild = null;
+              if (ok && socket.connected) {
+                this.#swapIn(socket, keyExpiresAt);
+              } else {
+                this.#candidate = null;
+                socket.close();
+              }
+              resolve(ok && socket.connected);
+            };
+            const timer = setTimeout(() => finish(false), REBUILD_CONNECT_TIMEOUT_MS);
+            this.#abortRebuild = () => finish(false);
+            this.#attach(socket, { onConnect: () => finish(true), onFailure: () => finish(false) });
+          });
+          if (!swapped) this.#armRetry();
         } catch {
+          this.#armRetry();
+        } finally {
+          this.#rebuilding = false;
         }
       }
+      /**
+       * The moment of the swap — synchronous, called from the candidate's own `connect` event so nothing can run
+       * between "the new socket is up" and "it is the current one". Order matters: `#socket` moves first, so the old
+       * socket's `disconnect` (our own `close()` of it, just below) is ignored by `#attach`.
+       */
+      #swapIn(socket, keyExpiresAt) {
+        const previous = this.#socket;
+        this.#socket = socket;
+        this.#candidate = null;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = void 0;
+        this.#stopPings();
+        this.#startPings(socket);
+        this.#setConnected(true);
+        previous?.close();
+        this.#armRefresh(keyExpiresAt);
+      }
+      #armRetry() {
+        if (this.#closed) return;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = setTimeout(() => void this.#reopen(), REBUILD_RETRY_MS);
+      }
       disconnect() {
         this.#closed = true;
         this.#stopPings();
         clearTimeout(this.#refreshTimer);
         this.#refreshTimer = void 0;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = void 0;
+        this.#abortRebuild?.();
         this.#unwatchBackground?.();
         this.#unwatchBackground = void 0;
         this.#socket?.close();
@@ -1517,6 +1746,8 @@ var SoftphoneEvent = /* @__PURE__ */ ((SoftphoneEvent2) => {
   SoftphoneEvent2["DeviceChange"] = "deviceChange";
   SoftphoneEvent2["Error"] = "error";
   SoftphoneEvent2["LeaderChanged"] = "leaderChanged";
+  SoftphoneEvent2["TransferOutcome"] = "transferOutcome";
+  SoftphoneEvent2["PresenceChanged"] = "presenceChanged";
   return SoftphoneEvent2;
 })(SoftphoneEvent || {});
 var CallEvent = /* @__PURE__ */ ((CallEvent2) => {
@@ -1555,13 +1786,17 @@ function canTransition(from, to) {
 function isTerminal(state) {
   return CALL_TRANSITIONS[state].length === 0;
 }
+function isOnCallState(state) {
+  return state !== "ringing" && !isTerminal(state);
+}
 
 // src/core/call-impl.ts
 var CallImpl = class _CallImpl extends Emitter {
-  constructor(engineCall, onListenerError, onInternalError) {
+  constructor(engineCall, onListenerError, onInternalError, onTransfer) {
     super(onListenerError);
     this.engineCall = engineCall;
     this.onInternalError = onInternalError;
+    this.onTransfer = onTransfer;
     this.#onListenerError = onListenerError;
     this.#state = INITIAL_STATES[engineCall.direction];
     this.#remote = {
@@ -1573,6 +1808,7 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   engineCall;
   onInternalError;
+  onTransfer;
   #state;
   #remote;
   #answeredAt = null;
@@ -1658,7 +1894,10 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   async hangup() {
     if (isTerminal(this.#state)) return;
-    await this.engineCall.hangup();
+    const consult = this.#consultCall;
+    this.#consultCall = null;
+    this.#consultEngineCall = null;
+    await Promise.all([consult?.hangup() ?? Promise.resolve(), this.engineCall.hangup()]);
   }
   mute(muted) {
     if (this.#muted === muted) return;
@@ -1680,6 +1919,7 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   async transfer(target) {
     await this.engineCall.transfer(target);
+    this.onTransfer?.(target, this.#remote.number.trim() || null);
   }
   async startConsult(target) {
     await this.hold();
@@ -1715,6 +1955,12 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   #end(reason) {
     if (isTerminal(this.#state)) return;
+    if (this.#consultCall) {
+      const consult = this.#consultCall;
+      this.#consultCall = null;
+      this.#consultEngineCall = null;
+      void consult.hangup();
+    }
     const from = this.#state;
     this.#state = "ended";
     this.emit("stateChanged" /* StateChanged */, { state: "ended", previous: from });
@@ -1758,7 +2004,9 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
     contacts: async (params) => (await load()).contacts(params),
     history: async (params) => (await load()).history(params),
     resolveContact: async (number) => (await load()).resolveContact(number),
-    listAgents: async () => (await load()).listAgents()
+    listAgents: async () => (await load()).listAgents(),
+    transferOutcomes: async (params) => (await load()).transferOutcomes(params),
+    presence: async (callbacks) => (await load()).presence(callbacks)
   };
 }
 
@@ -1806,9 +2054,176 @@ function webLocksTabLock(lockName = LOCK_NAME) {
   };
 }
 
+// src/core/transfer-watch.ts
+var FAST_INTERVAL_MS = 2e3;
+var FAST_WINDOW_MS = 1e4;
+var SLOW_INTERVAL_MS = 5e3;
+var DEADLINE_MS = 9e4;
+var EXTENSION_LIKE = /^\d{1,6}$/;
+function startTransferWatch(params) {
+  const {
+    target,
+    callerNumber,
+    source,
+    getIsLeader,
+    emit,
+    setTimeout: scheduleTimeout = globalThis.setTimeout,
+    clearTimeout: cancelTimeout = globalThis.clearTimeout,
+    now = () => Date.now()
+  } = params;
+  if (!EXTENSION_LIKE.test(target)) return () => {
+  };
+  if (!getIsLeader()) return () => {
+  };
+  let stopped = false;
+  let timer = null;
+  let cursor = null;
+  const startedAt = now();
+  const stop = () => {
+    stopped = true;
+    if (timer !== null) {
+      cancelTimeout(timer);
+      timer = null;
+    }
+  };
+  const finish = (status) => {
+    stop();
+    emit({ status, target, caller: callerNumber, at: new Date(now()) });
+  };
+  const scheduleNext = () => {
+    if (stopped) return;
+    const elapsed = now() - startedAt;
+    if (elapsed >= DEADLINE_MS) {
+      stop();
+      return;
+    }
+    timer = scheduleTimeout(() => void poll(), elapsed < FAST_WINDOW_MS ? FAST_INTERVAL_MS : SLOW_INTERVAL_MS);
+  };
+  const poll = async () => {
+    if (stopped) return;
+    if (!getIsLeader()) {
+      stop();
+      return;
+    }
+    let page;
+    try {
+      page = await source(cursor === null ? {} : { since: cursor });
+    } catch {
+      if (!stopped) scheduleNext();
+      return;
+    }
+    if (stopped) return;
+    if (cursor === null) {
+      cursor = page.cursor;
+    } else {
+      cursor = page.cursor;
+      const match = page.outcomes.find((o) => o.target === target);
+      if (match) {
+        finish(match.status);
+        return;
+      }
+    }
+    scheduleNext();
+  };
+  void poll();
+  return stop;
+}
+
+// src/core/presence-socket.ts
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var NOOP_WATCH = { reportCallState: () => {
+}, stop: () => {
+} };
+function startPresenceSocket(params) {
+  const {
+    source,
+    getIsLeader,
+    onAgentsChanged,
+    setTimeout: scheduleTimeout = globalThis.setTimeout,
+    clearTimeout: cancelTimeout = globalThis.clearTimeout,
+    random = Math.random
+  } = params;
+  if (!getIsLeader()) return NOOP_WATCH;
+  let stopped = false;
+  let attempt = 0;
+  let reconnectTimer = null;
+  let agents = /* @__PURE__ */ new Map();
+  let lastReportedOnCall = null;
+  let connection = null;
+  let byeOnArrival = false;
+  const stop = (options) => {
+    if (stopped) return;
+    stopped = true;
+    if (reconnectTimer !== null) {
+      cancelTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (options?.bye) {
+      byeOnArrival = true;
+      connection?.bye?.();
+    }
+    connection?.close();
+    connection = null;
+  };
+  const scheduleReconnect = () => {
+    if (stopped) return;
+    attempt += 1;
+    const capped = Math.min(RECONNECT_BASE_MS * 2 ** (attempt - 1), RECONNECT_MAX_MS);
+    const delay = capped * random();
+    reconnectTimer = scheduleTimeout(() => void connect(), delay);
+  };
+  const connect = async () => {
+    if (stopped) return;
+    if (!getIsLeader()) {
+      stop();
+      return;
+    }
+    let opened;
+    try {
+      opened = await source({
+        onSnapshot: (snapshot) => {
+          agents = new Map(snapshot.map((agent) => [agent.userId, agent]));
+          onAgentsChanged([...agents.values()]);
+        },
+        onDelta: (agent) => {
+          agents.set(agent.userId, agent);
+          onAgentsChanged([...agents.values()]);
+        },
+        onClose: () => {
+          if (connection === null) return;
+          connection = null;
+          scheduleReconnect();
+        }
+      });
+    } catch {
+      if (!stopped) scheduleReconnect();
+      return;
+    }
+    if (stopped) {
+      if (byeOnArrival) opened.bye?.();
+      opened.close();
+      return;
+    }
+    connection = opened;
+    attempt = 0;
+    if (lastReportedOnCall !== null) connection.reportCallState(lastReportedOnCall);
+  };
+  void connect();
+  return {
+    reportCallState: (onCall) => {
+      if (onCall === lastReportedOnCall) return;
+      lastReportedOnCall = onCall;
+      connection?.reportCallState(onCall);
+    },
+    stop
+  };
+}
+
 // src/core/softphone-impl.ts
 init_errors();
 var liveInstance = false;
+var PRESENCE_TEARDOWN_GRACE_MS = 1e4;
 var BrowserAudioDevices = class {
   inputs = [];
   outputs = [];
@@ -1869,6 +2284,23 @@ var SoftphoneImpl = class extends Emitter {
   /** Contacts + history, whenever there is a Coventia backend to reach. The widget reads these. */
   sources;
   audio;
+  /**
+   * Every in-flight transfer-outcome watch (Phase A), so `destroy()` can stop all of them. Never
+   * pruned as individual watches finish on their own — `stop()` is idempotent and cheap to call again,
+   * and a session accumulating a handful of closures for however many transfers it makes is not worth
+   * the bookkeeping a self-removing set would add.
+   */
+  #activeWatches = /* @__PURE__ */ new Set();
+  /**
+   * Phase B (presence-gated transfer picker). ONE long-lived watch, not a member of `#activeWatches`
+   * — that set is per-transfer instances a live call spawns and forgets; this is a single background
+   * connection tied to the softphone's own lifecycle, started and stopped by `#syncPresenceWatch`
+   * rather than by any one call.
+   */
+  #presenceWatch = null;
+  /** A pending state-driven teardown of the watch — see `PRESENCE_TEARDOWN_GRACE_MS`. */
+  #presenceTeardownTimer = null;
+  #presenceAgents = [];
   /**
    * `tabLock` defaults to the real Web Locks implementation — not part of `SoftphoneConfig` (an
    * internal seam, not something an integrator tunes). Tests construct this class directly with a
@@ -1901,6 +2333,9 @@ var SoftphoneImpl = class extends Emitter {
   get activeCall() {
     return this.#activeCall;
   }
+  get presence() {
+    return this.#presenceAgents;
+  }
   get canPlayAudio() {
     return true;
   }
@@ -1924,6 +2359,7 @@ var SoftphoneImpl = class extends Emitter {
   }
   async stop() {
     if (!this.#startedHere) return;
+    this.#sayGoodbye();
     this.#tabLock.release();
     if (this.#isLeader) {
       await this.#engine.stop();
@@ -1937,6 +2373,9 @@ var SoftphoneImpl = class extends Emitter {
   async destroy() {
     if (this.#destroyed) return;
     this.#destroyed = true;
+    for (const stopWatch of this.#activeWatches) stopWatch();
+    this.#activeWatches.clear();
+    this.#sayGoodbye();
     await this.stop().catch(() => {
     });
     this.#setState("destroyed");
@@ -1967,14 +2406,19 @@ var SoftphoneImpl = class extends Emitter {
     const call = new CallImpl(
       engineCall,
       (event, error) => this.#reportListenerError("call", event, error),
-      (message) => this.#reportInternalError(message)
+      (message) => this.#reportInternalError(message),
+      (target, callerNumber) => this.#onTransfer(target, callerNumber)
     );
     this.#activeCall = call;
+    const offState = call.on("stateChanged" /* StateChanged */, () => this.#syncCallState());
+    this.#syncCallState();
     const off = call.on("ended" /* Ended */, () => {
       off();
+      offState();
       if (this.#activeCall === call) {
         this.#activeCall = null;
         this.emit("activeCallChanged" /* ActiveCallChanged */, { call: null });
+        this.#syncCallState();
       }
     });
     if (this.#resolveContact) {
@@ -1992,11 +2436,125 @@ var SoftphoneImpl = class extends Emitter {
     this.#state = state;
     if (state === "online") this.#lastError = null;
     this.emit("stateChanged" /* StateChanged */, { state, previous });
+    this.#syncPresenceWatch();
+  }
+  /**
+   * Whether this softphone is on a call right now, as presence means it (`isOnCallState`). There is a single
+   * active-call slot, and a consult leg is a child of that call, so the parent staying alive covers a consult.
+   */
+  #isOnCall() {
+    return this.#activeCall !== null && isOnCallState(this.#activeCall.state);
+  }
+  /**
+   * Reports the current on-a-call value to the backend. The watch de-duplicates (it only sends on change) and
+   * remembers the latest value to replay after a reconnect, so this can be called on every transition without
+   * ceremony. A no-op while there is no presence watch (not online, not the leader, no backend configured).
+   */
+  #syncCallState() {
+    this.#presenceWatch?.reportCallState(this.#isOnCall());
   }
   #setLeader(isLeader) {
     if (isLeader === this.#isLeader) return;
     this.#isLeader = isLeader;
     this.emit("leaderChanged" /* LeaderChanged */, { isLeader });
+    this.#syncPresenceWatch();
+  }
+  /**
+   * Phase B (presence-gated transfer picker, `docs/specs/transfer-presence-picker.md` plan T6/T7).
+   * The ONE place that decides whether the presence connection should be running right now — called
+   * after every `#setState`/`#setLeader` transition rather than left to either alone, since either
+   * one flipping can change the answer. No-ops entirely when no Coventia backend is configured
+   * (`sources` is null) — same guard `#onTransfer` uses, and for the same reason: nothing to open.
+   *
+   * `presence-socket.ts`'s own `getIsLeader` is checked at start and before each reconnect attempt,
+   * not on a poll tick the way `startTransferWatch`'s is — see that module's own doc comment for why.
+   * This still passes `getIsLeader: () => this.#isLeader` for that narrower, defensive recheck; the
+   * BROAD online/leader gate — whether to be connected AT ALL — is owned entirely here, the same
+   * split `#onTransfer` already has with `startTransferWatch`.
+   *
+   * One exception to "tear down the moment `online` is lost": a leader that is merely `offline` or
+   * `reconnecting` keeps its watch for `PRESENCE_TEARDOWN_GRACE_MS` — a blip shorter than that never touches
+   * the presence socket at all. Anything else (stopped, starting, destroyed, or no longer the leader) still
+   * tears it down at once: those are not blips, and a follower must never hold a connection.
+   */
+  #syncPresenceWatch() {
+    const eligible = Boolean(this.sources) && this.#isLeader;
+    const shouldRun = eligible && this.#state === "online";
+    const blip = eligible && (this.#state === "offline" || this.#state === "reconnecting");
+    if (!blip) this.#cancelPresenceTeardown();
+    if (blip && this.#presenceWatch !== null) {
+      this.#schedulePresenceTeardown();
+      return;
+    }
+    if (shouldRun === (this.#presenceWatch !== null)) return;
+    if (shouldRun) {
+      this.#presenceWatch = startPresenceSocket({
+        source: this.sources.presence,
+        getIsLeader: () => this.#isLeader,
+        onAgentsChanged: (agents) => {
+          this.#presenceAgents = agents;
+          this.emit("presenceChanged" /* PresenceChanged */, { agents });
+        }
+      });
+      this.#syncCallState();
+    } else {
+      this.#stopPresence();
+    }
+  }
+  /**
+   * Starts the grace period before an `offline` / `reconnecting` leader loses its presence socket. Idempotent
+   * on purpose: a second notification inside the same blip must NOT push the deadline back.
+   */
+  #schedulePresenceTeardown() {
+    if (this.#presenceTeardownTimer !== null) return;
+    this.#presenceTeardownTimer = setTimeout(() => {
+      this.#presenceTeardownTimer = null;
+      if (this.#state === "online" && this.#isLeader) return;
+      this.#stopPresence();
+    }, PRESENCE_TEARDOWN_GRACE_MS);
+  }
+  #cancelPresenceTeardown() {
+    if (this.#presenceTeardownTimer === null) return;
+    clearTimeout(this.#presenceTeardownTimer);
+    this.#presenceTeardownTimer = null;
+  }
+  /**
+   * Stops the presence watch and forgets its roster. A STATE-DRIVEN teardown (the softphone left `online`
+   * for good, or lost leadership) passes nothing and says no goodbye; only a deliberate stop passes `bye`.
+   * Any pending grace-period teardown is cancelled — there is nothing left for it to do.
+   */
+  #stopPresence(options) {
+    this.#cancelPresenceTeardown();
+    if (!this.#presenceWatch) return;
+    this.#presenceWatch.stop(options);
+    this.#presenceWatch = null;
+    this.#presenceAgents = [];
+    this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+  }
+  /**
+   * A DELIBERATE stop (`stop()` / `destroy()`): say any call is over, then say goodbye, so the backend drops
+   * this phone at once instead of waiting out the close grace. Idempotent — a second call finds no watch.
+   */
+  #sayGoodbye() {
+    this.#presenceWatch?.reportCallState(false);
+    this.#stopPresence({ bye: true });
+  }
+  /**
+   * Phase A (transfer outcome relay, `docs/specs/transfer-outcome-relay.md`) — `CallImpl.transfer()`'s
+   * internal seam calls this. No-ops entirely when no Coventia backend is configured (`sources` is
+   * null): there is then nothing to poll, and behaviour is exactly what it was before this feature
+   * existed (spec §5.4).
+   */
+  #onTransfer(target, callerNumber) {
+    if (!this.sources) return;
+    const stopWatch = startTransferWatch({
+      target,
+      callerNumber,
+      source: this.sources.transferOutcomes,
+      getIsLeader: () => this.#isLeader,
+      emit: (payload) => this.emit("transferOutcome" /* TransferOutcome */, payload)
+    });
+    this.#activeWatches.add(stopWatch);
   }
   /**
    * Re-emit an engine failure to the host, and remember it if it is fatal.
@@ -2116,7 +2674,7 @@ function isCallEngine(value) {
 
 // src/index.ts
 init_errors();
-var VERSION = "0.0.0";
+var VERSION = "0.2.1";
 
 exports.CALL_TRANSITIONS = CALL_TRANSITIONS;
 exports.CallEvent = CallEvent;