mcp-teams 0.2.13 → 0.2.15

package/README.md

@@ -55,6 +55,16 @@ Teams reports the call's length, not each person's time in it, so attendance lis
 
 The AI can only **request** a send. The extension then opens its own window showing where the message goes (for a new chat: who will be in it, and its title), the post it replies to and the message itself. The message is posted, and a new chat created, only if you click **Send** there. Closing the window, clicking *Don't send*, or waiting 5 minutes all mean nothing is posted.
 
+If the AI stops waiting (it cancels, times out or loses its connection) while the window is open, the window closes and nothing is posted. If you had already clicked *Send* but no answer came back, the AI is told the message may have been posted and to check the chat before sending again, so it doesn't post twice.
+
+### When Teams is busy
+
+When Teams asks to slow down (HTTP 429), mcp-teams sends nothing more to that service, for that region or account, until Teams' wait is over. A call waits that out if it has time; otherwise it fails with "Teams is busy (throttled) for N s". A list that came back without some people's names says so in a `note`, instead of leaving them out silently.
+
+### When something hangs
+
+Several AI sessions share one connection to the browser: the first one runs it, the others go through it. They check on each other every 20 s. If the session running it stops responding (its app is suspended or hung), the others' calls fail within about 40 s with "The mcp-teams hub stopped responding; try again in a few seconds", and one of them takes over. A session that stops reading what it is sent is disconnected and reconnects. The extension reconnects by itself when it hasn't heard from the server for 45 s.
+
 ## Setup
 
 You need [Node.js](https://nodejs.org) 20 or later, and Chrome or Edge. Then, in a terminal:

package/dist/bridge.js

@@ -1,6 +1,7 @@
 import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { WebSocketServer, WebSocket } from "ws";
 import { EXTENSION_ORIGIN as TRUSTED_EXTENSION_ORIGIN } from "./extension.js";
+import { FairQueue } from "./fairqueue.js";
 /**
  * Local WebSocket bridge between MCP server processes and the browser extension.
  *
@@ -45,8 +46,57 @@ export const DEFAULT_BRIDGE_OPTIONS = Object.freeze({
     pickStatusTimeoutMs: 3_000,
     stepDownMaxWaitMs: 5 * 60_000,
     cancelGraceMs: 2_000,
+    maxPeerBufferedBytes: 64 * 1024 * 1024,
+    maxConcurrentCalls: 4,
 });
-const cancelledError = () => new Error("Cancelled: the request was withdrawn.");
+/**
+ * Calls that never wait for a turn: the connection's own (status, reload) answer at once, and a
+ * send waits for the user's click (up to minutes), so it must not hold a turn others wait for.
+ */
+const UNQUEUED = new Set(["status", "reload", "reloadAll", "requestSend"]);
+/**
+ * What a call fails with when it waited for a turn and was never sent: nothing reached Teams,
+ * so none of these is a lost call (isLostCall is false for each).
+ */
+export const NOT_SENT = Object.freeze({
+    cancelled: "Cancelled while it waited for its turn; it was not sent.",
+    waitedOut: (running) => `Busy: this call waited its whole time limit for a turn (${running} calls at once run on the Teams tab, shared between AI sessions) and was not sent; try again shortly.`,
+    gone: "The connection to the browser extension closed before this call's turn came; it was not sent. Try again.",
+});
+/** A peer's watchdog never waits less for its hub's ping: a busy machine runs timers late. */
+const MIN_HUB_SILENCE_MS = 2_000;
+/** Hub: a peer with more than this many times maxPeerBufferedBytes waiting is closed at once. */
+const PEER_BUFFER_HARD_CAP = 4;
+/**
+ * What a call fails with when the bridge lost it after sending it, so its outcome is unknown (a
+ * send may have been posted). A hub relays them to its peers word for word. src/tools.ts tells
+ * the AI to check before sending again on exactly these (isLostCall), so add any new one here.
+ */
+export const LOST_CALL = Object.freeze({
+    timedOut: (method) => `Extension call '${method}' timed out`,
+    withdrawn: "Cancelled: the request was withdrawn.",
+    disconnected: "Browser extension disconnected",
+    reconnected: "Browser extension reconnected; try again.",
+    hubRestarted: "The mcp-teams hub restarted; try again in a few seconds.",
+    hubSilent: "The mcp-teams hub stopped responding; try again in a few seconds.",
+    updated: "mcp-teams was updated; try again in a few seconds.",
+    shuttingDown: "mcp-teams is shutting down",
+    serverError: (detail) => `bridge server error: ${detail}`,
+    socketError: (detail) => `Bridge connection error: ${detail}`,
+    tooLarge: (limitMb) => `The response was too large (over ${limitMb} MB) and was dropped. The connection is re-established automatically.`,
+});
+// Each LOST_CALL message as a pattern: its text, with anything in the place of a value.
+const SLOT = "\u0000";
+const escapeRegExp = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const LOST_CALL_PATTERNS = Object.values(LOST_CALL).map((m) => {
+    const text = typeof m === "string" ? m : m(SLOT);
+    return new RegExp(`^${text.split(SLOT).map(escapeRegExp).join(".*")}`, "s");
+});
+/** True when `message` is one of LOST_CALL's: the call was sent, and its outcome is unknown. */
+export function isLostCall(message) {
+    return LOST_CALL_PATTERNS.some((p) => p.test(message));
+}
+const cancelledError = () => new Error(LOST_CALL.withdrawn);
 /** True when version a is newer than b (x.y.z; anything else never counts as newer). */
 export function isNewer(a, b) {
     const parse = (v) => (typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v) ? v.split(".").map(Number) : null);
@@ -60,9 +110,7 @@ export function isNewer(a, b) {
     return false;
 }
 function describeSocketError(err, limit) {
-    return err.code === "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH"
-        ? `The response was too large (over ${Math.round(limit / 1024 / 1024)} MB) and was dropped. The connection is re-established automatically.`
-        : `Bridge connection error: ${err.message}`;
+    return err.code === "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH" ? LOST_CALL.tooLarge(Math.round(limit / 1024 / 1024)) : LOST_CALL.socketError(err.message);
 }
 export class ExtensionBridge {
     requestedPort;
@@ -82,12 +130,16 @@ export class ExtensionBridge {
     hub; // peer: the hub
     peers = new Set();
     peerCalls = new Map(); // hub: each peer's calls, by the peer's id
+    /** Hub: per extension connection, its turns (keyed by session: null for the hub's own calls, else the peer) and who waits. */
+    turns = new Map();
     pending = new Map();
     keepAlive;
+    peerBeat; // hub: pings the peers
     retry;
     closed = false;
     steppingDown = false;
-    alive = new WeakSet(); // hub: extensions that answered the last ping
+    alive = new WeakSet(); // hub: extensions and peers that answered the last ping
+    backlogged = new WeakSet(); // hub: peers over maxPeerBufferedBytes at the last tick
     legacyReloaded = false; // hub: an extension of 0.2.0 or older was told to reload
     opts;
     boundPort; // hub: the port it listens on (port 0 picks a free one)
@@ -115,6 +167,13 @@ export class ExtensionBridge {
             peerCalls += calls.size;
         return { pending: this.pending.size, peerCalls };
     }
+    /** Read-only, for tests: hub calls waiting for a turn on an extension (not sent yet). */
+    get queued() {
+        let n = 0;
+        for (const t of this.turns.values())
+            n += t.queue.waiting;
+        return n;
+    }
     /** Becomes the hub, or a peer of the existing hub. Keeps retrying in the background if neither works. */
     async start() {
         if (this.closed)
@@ -157,7 +216,7 @@ export class ExtensionBridge {
             });
             wss.on("error", (err) => {
                 if (listening)
-                    return this.restartHub(`bridge server error: ${err.message}`);
+                    return this.restartHub(LOST_CALL.serverError(err.message));
                 if (err.code !== "EADDRINUSE")
                     this.listenError = err.message;
                 wss.close();
@@ -202,7 +261,7 @@ export class ExtensionBridge {
                 return;
             }
             if (this.sockets.has(ws))
-                this.onExtensionMessage(msg);
+                this.onExtensionMessage(ws, msg);
             else if (this.peers.has(ws))
                 this.onPeerMessage(ws, msg);
         });
@@ -222,7 +281,8 @@ export class ExtensionBridge {
             if (this.sockets.delete(ws)) {
                 if (this.preferred === ws)
                     this.preferred = undefined;
-                this.rejectAll("Browser extension disconnected", ws);
+                this.dropTurns(ws);
+                this.rejectAll(LOST_CALL.disconnected, ws);
                 this.updateExtensions();
                 if (!this.sockets.size)
                     clearInterval(this.keepAlive);
@@ -267,13 +327,15 @@ export class ExtensionBridge {
                 s.close(4000, "replaced");
                 // Its close event comes later and no longer finds it, so fail its calls now.
                 this.sockets.delete(s);
-                this.rejectAll("Browser extension reconnected; try again.", s);
+                this.dropTurns(s);
+                this.rejectAll(LOST_CALL.reconnected, s);
                 if (this.preferred === s)
                     this.preferred = undefined;
             }
         }
         this.sockets.set(ws, info);
-        ws.send(JSON.stringify({ type: "welcome", serverVersion: this.serverVersion, ...welcome }));
+        // heartbeatMs: this hub sends {type:"ping"} that often; the extension reconnects when they stop.
+        ws.send(JSON.stringify({ type: "welcome", serverVersion: this.serverVersion, heartbeatMs: this.opts.keepAliveMs, ...welcome }));
         this.startKeepAlive(ws);
         this.updateExtensions();
     }
@@ -315,7 +377,16 @@ export class ExtensionBridge {
     }
     acceptPeer(ws, peerVersion, welcome) {
         this.peers.add(ws);
-        ws.send(JSON.stringify({ type: "peer-welcome", serverVersion: this.serverVersion, extension: this.extension ?? null, extensions: this.extensions, ...welcome }));
+        // heartbeatMs: this hub pings the peer that often, so the peer can tell when it stops.
+        ws.send(JSON.stringify({
+            type: "peer-welcome",
+            serverVersion: this.serverVersion,
+            extension: this.extension ?? null,
+            extensions: this.extensions,
+            heartbeatMs: this.opts.keepAliveMs,
+            ...welcome,
+        }));
+        this.startPeerBeat(ws);
         // A newer server joined: hand the port to it, so its fixes (and what the newer
         // extension expects) take effect without restarting this AI session.
         if (isNewer(peerVersion, this.serverVersion))
@@ -332,12 +403,12 @@ export class ExtensionBridge {
             return;
         this.steppingDown = true;
         const end = Date.now() + this.opts.stepDownMaxWaitMs;
-        while (this.pending.size && Date.now() < end && !this.closed)
+        while ((this.pending.size || this.queued) && Date.now() < end && !this.closed)
             await new Promise((r) => setTimeout(r, 500));
         if (this.closed || this.role !== "hub")
             return void (this.steppingDown = false);
         console.error(`[mcp-teams ${this.serverVersion}] handing the bridge to mcp-teams ${newer}`);
-        this.restartHub("mcp-teams was updated; try again in a few seconds.", this.opts.retryMs);
+        this.restartHub(LOST_CALL.updated, this.opts.retryMs);
         this.steppingDown = false;
     }
     /** Hub: closes the server and every connection, then becomes a hub or peer again. */
@@ -347,6 +418,8 @@ export class ExtensionBridge {
         this.boundPort = undefined;
         this.role = "none";
         clearInterval(this.keepAlive);
+        this.stopPeerBeat();
+        this.dropTurns();
         this.rejectAll(reason);
         for (const s of this.sockets.keys())
             s.close(1012, "restarting");
@@ -364,9 +437,33 @@ export class ExtensionBridge {
         this.retry = setTimeout(() => void this.start(), delayMs);
         this.retry.unref();
     }
-    onExtensionMessage(msg) {
-        if (msg.type === "response" && typeof msg.id === "string")
-            this.settle(msg);
+    onExtensionMessage(ws, msg) {
+        if (typeof msg.id !== "string")
+            return;
+        if (msg.type === "response")
+            return this.settle(msg);
+        // A queued call waiting out a throttle (35): {type:"gate-wait"} gives its turn back to the
+        // others, {type:"gate-open"} asks for one again, and {type:"turn"} says it may go on.
+        const p = this.pending.get(msg.id);
+        const turn = p?.socket === ws ? p.turn : undefined;
+        if (!turn || turn.done)
+            return;
+        if (msg.type === "gate-wait" && turn.held) {
+            turn.held = false;
+            turn.queue.release(turn.session);
+        }
+        else if (msg.type === "gate-open" && !turn.held && !turn.rejoin) {
+            const rejoin = (turn.rejoin = new AbortController());
+            // Not given in time: the call's own timer withdraws it (it may have sent requests already).
+            this.takeTurn(ws, turn.session, turn.end, rejoin.signal).then(() => {
+                turn.rejoin = undefined;
+                if (turn.done)
+                    return turn.queue.release(turn.session);
+                turn.held = true;
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(JSON.stringify({ type: "turn", id: msg.id }));
+            }, () => (turn.rejoin = undefined));
+        }
     }
     /** Runs a peer's call against the extension and sends back the outcome; {type:"cancel", id} withdraws it. */
     onPeerMessage(ws, msg) {
@@ -376,8 +473,7 @@ export class ExtensionBridge {
             return;
         const reply = (body) => {
             try {
-                if (ws.readyState === WebSocket.OPEN)
-                    ws.send(JSON.stringify({ type: "response", id: msg.id, ...body }));
+                this.sendToPeer(ws, JSON.stringify({ type: "response", id: msg.id, ...body }));
             }
             catch (err) {
                 console.error(`[mcp-teams] could not answer a peer: ${err.message}`);
@@ -388,15 +484,37 @@ export class ExtensionBridge {
             this.peerCalls.set(ws, (calls = new Map()));
         const ac = new AbortController();
         calls.set(msg.id, ac);
-        this.call(String(msg.method), msg.params ?? {}, Number(msg.timeoutMs) || undefined, ac.signal)
+        // The peer's deadline stays the call's deadline: the extension must not go on after the peer gave up.
+        this.run(ws, String(msg.method), msg.params ?? {}, Number(msg.timeoutMs) || undefined, ac.signal, Number(msg.deadline) || undefined)
             .then((result) => reply({ ok: true, result }), (err) => reply({ ok: false, error: err.message }))
             .finally(() => calls.delete(msg.id));
     }
     broadcastState() {
         const state = JSON.stringify({ type: "ext-state", extension: this.extension ?? null, extensions: this.extensions });
         for (const peer of this.peers)
-            if (peer.readyState === WebSocket.OPEN)
-                peer.send(state);
+            this.sendToPeer(peer, state);
+    }
+    /**
+     * Hub: sends to a peer that is open and keeping up. One with over 4x maxPeerBufferedBytes
+     * waiting is closed instead; a smaller backlog only when it lasts (see startPeerBeat), so a
+     * burst of large answers doesn't drop a healthy peer.
+     */
+    sendToPeer(ws, text) {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        if (ws.bufferedAmount > this.opts.maxPeerBufferedBytes * PEER_BUFFER_HARD_CAP)
+            return this.closeSlowPeer(ws);
+        ws.send(text);
+    }
+    /** Hub: closes a peer that isn't reading its answers (1013); its calls are withdrawn and it connects again. */
+    closeSlowPeer(ws) {
+        console.error(`[mcp-teams] closing a peer that doesn't read its answers (${Math.round(ws.bufferedAmount / 1024 / 1024)} MB waiting)`);
+        this.peers.delete(ws);
+        // Its close may wait for the backlog; its calls are withdrawn now (as on close).
+        for (const ac of this.peerCalls.get(ws)?.values() ?? [])
+            ac.abort();
+        this.peerCalls.delete(ws);
+        ws.close(1013, "too slow");
     }
     /**
      * Pings keep the MV3 service worker alive while connected. A connection that didn't
@@ -423,6 +541,49 @@ export class ExtensionBridge {
         }, this.opts.keepAliveMs);
         this.keepAlive.unref();
     }
+    /**
+     * Hub: pings each peer every keepAliveMs; one that didn't answer the previous ping (a
+     * suspended or hung session) is dropped, within 2 periods. The peers in turn drop a hub
+     * that stops pinging them (see join). A peer over maxPeerBufferedBytes at this tick and the
+     * previous one isn't draining its answers and is closed (1013).
+     */
+    startPeerBeat(ws) {
+        this.alive.add(ws);
+        ws.on("pong", () => this.alive.add(ws));
+        if (this.peerBeat)
+            return;
+        this.peerBeat = setInterval(() => {
+            if (!this.peers.size)
+                return this.stopPeerBeat();
+            for (const p of this.peers) {
+                if (p.readyState !== WebSocket.OPEN)
+                    continue;
+                const backlog = p.bufferedAmount > this.opts.maxPeerBufferedBytes;
+                if (backlog && this.backlogged.has(p)) {
+                    this.closeSlowPeer(p);
+                    continue;
+                }
+                if (backlog)
+                    this.backlogged.add(p);
+                else
+                    this.backlogged.delete(p);
+                // With a backlog, the last ping may still wait behind the data, so a missing pong says
+                // nothing: the next tick closes the peer if the backlog lasts. It is still pinged (the
+                // ping queues behind the data), so a peer that drains it in time hears from its hub.
+                if (!backlog && !this.alive.has(p)) {
+                    p.terminate();
+                    continue;
+                }
+                this.alive.delete(p);
+                p.ping();
+            }
+        }, this.opts.keepAliveMs);
+        this.peerBeat.unref();
+    }
+    stopPeerBeat() {
+        clearInterval(this.peerBeat);
+        this.peerBeat = undefined;
+    }
     // ------------------------------------------------------------------ peer
     join() {
         return new Promise((resolve) => {
@@ -432,6 +593,23 @@ export class ExtensionBridge {
             let forged = false;
             const nonce = newNonce();
             const timer = setTimeout(() => ws.terminate(), this.opts.joinTimeoutMs);
+            // A hub that declares heartbeatMs pings that often. When its pings stop for 2 periods, never
+            // under 2 s (a busy machine runs timers late), the hub is suspended or hung: its calls fail
+            // now and the takeover path runs, instead of them hanging until they time out. Hubs of
+            // 0.2.13 and older never ping peers: no watchdog.
+            let watchdog;
+            let heartbeatMs = 0;
+            const watch = () => {
+                clearTimeout(watchdog);
+                watchdog = setTimeout(() => {
+                    if (this.hub !== ws)
+                        return;
+                    this.rejectAll(LOST_CALL.hubSilent);
+                    ws.terminate();
+                }, Math.max(MIN_HUB_SILENCE_MS, 2 * heartbeatMs));
+                watchdog.unref();
+            };
+            ws.on("ping", () => heartbeatMs && watch());
             ws.on("message", (raw) => {
                 let msg;
                 try {
@@ -458,6 +636,9 @@ export class ExtensionBridge {
                     this.hubVersion = String(msg.serverVersion ?? "unknown");
                     this.extension = msg.extension ?? undefined;
                     this.extensions = msg.extensions ?? (msg.extension ? [msg.extension] : []);
+                    heartbeatMs = Number(msg.heartbeatMs) > 0 ? Number(msg.heartbeatMs) : 0;
+                    if (heartbeatMs)
+                        watch();
                     resolve(true);
                 }
                 else if (msg.type === "ext-state") {
@@ -474,6 +655,7 @@ export class ExtensionBridge {
             });
             ws.on("close", (code) => {
                 clearTimeout(timer);
+                clearTimeout(watchdog);
                 if (!joined) {
                     this.listenError =
                         code === 4401
@@ -491,7 +673,7 @@ export class ExtensionBridge {
                 this.extension = undefined;
                 this.extensions = [];
                 this.role = "none";
-                this.rejectAll("The mcp-teams hub restarted; try again in a few seconds.");
+                this.rejectAll(LOST_CALL.hubRestarted);
                 if (!this.closed) {
                     clearTimeout(this.retry);
                     this.retry = setTimeout(() => void this.start(), 100 + Math.random() * 400);
@@ -501,8 +683,15 @@ export class ExtensionBridge {
         });
     }
     // ------------------------------------------------------------------ calls
-    /** Calls the extension. Aborting `signal` withdraws the call (see withdraw). */
-    async call(method, params = {}, timeoutMs = 60_000, signal) {
+    /**
+     * Calls the extension. Aborting `signal` withdraws the call (see withdraw). `deadline` (ms since
+     * 1970) ends it earlier than timeoutMs, for a call relayed from a peer.
+     */
+    call(method, params = {}, timeoutMs, signal, deadline) {
+        return this.run(null, method, params, timeoutMs, signal, deadline);
+    }
+    /** A call from `session` (null: this server's own, else the peer it came from). */
+    async run(session, method, params = {}, timeoutMs = 60_000, signal, deadline) {
         if (method === "reloadAll" && this.role === "hub")
             return this.reloadAll(timeoutMs);
         const target = this.role === "hub" ? await this.pickExtension() : this.role === "peer" ? this.hub : undefined;
@@ -512,13 +701,74 @@ export class ExtensionBridge {
                 : "Browser extension is not connected. Open Chrome or Edge with the mcp-teams extension installed (run `mcp-teams setup`).";
             throw new Error(reason);
         }
-        const result = await this.send(target, method, params, timeoutMs, signal);
+        let result;
+        if (this.role === "hub" && !UNQUEUED.has(method)) {
+            // The call's time limit includes its wait for a turn.
+            const end = Math.min(Date.now() + timeoutMs, deadline ?? Infinity);
+            const turn = { queue: await this.takeTurn(target, session, end, signal), session, end, held: true };
+            try {
+                if (signal?.aborted)
+                    throw new Error(NOT_SENT.cancelled);
+                result = await this.send(target, method, params, timeoutMs, signal, end, turn);
+            }
+            finally {
+                turn.done = true;
+                turn.rejoin?.abort();
+                if (turn.held)
+                    turn.queue.release(session); // handed to the next waiting call, if any
+            }
+        }
+        else {
+            result = await this.send(target, method, params, timeoutMs, signal, deadline);
+        }
         if (this.role === "hub" && this.preferred !== target && this.sockets.has(target)) {
             this.preferred = target;
             this.updateExtensions();
         }
         return result;
     }
+    /**
+     * Hub: waits for one of the extension's maxConcurrentCalls turns, fairly between sessions.
+     * Cancelling or reaching `end` first leaves the line, and the call is never sent.
+     */
+    takeTurn(target, session, end, signal) {
+        let turns = this.turns.get(target);
+        if (!turns)
+            this.turns.set(target, (turns = { queue: new FairQueue(this.opts.maxConcurrentCalls), waiting: new Set() }));
+        const { queue, waiting } = turns;
+        if (signal?.aborted)
+            return Promise.reject(new Error(NOT_SENT.cancelled));
+        if (queue.tryTake(session))
+            return Promise.resolve(queue);
+        return new Promise((resolve, reject) => {
+            const done = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                waiting.delete(leave);
+            };
+            const leaveLine = queue.wait(session, () => (done(), resolve(queue)));
+            const leave = (err) => {
+                if (!leaveLine())
+                    return; // already given its turn
+                done();
+                reject(err);
+            };
+            const onAbort = () => leave(new Error(NOT_SENT.cancelled));
+            const timer = setTimeout(() => leave(new Error(NOT_SENT.waitedOut(queue.max))), Math.max(0, end - Date.now()));
+            signal?.addEventListener("abort", onAbort, { once: true });
+            waiting.add(leave);
+        });
+    }
+    /** Hub: fails the calls still waiting for a turn on `socket` (every socket when not given); they were never sent. */
+    dropTurns(socket) {
+        for (const [s, { waiting }] of this.turns) {
+            if (socket && s !== socket)
+                continue;
+            this.turns.delete(s);
+            for (const leave of [...waiting])
+                leave(new Error(NOT_SENT.gone));
+        }
+    }
     /** Hub: asks every connected browser's extension to reload itself. */
     async reloadAll(timeoutMs) {
         const open = [...this.sockets.keys()].filter((s) => s.readyState === WebSocket.OPEN);
@@ -531,25 +781,32 @@ export class ExtensionBridge {
         return { reloading: results.length - failed.length };
     }
     /** Sends one request on a connection (an extension for the hub, the hub for a peer). */
-    send(target, method, params, timeoutMs, signal) {
+    send(target, method, params, timeoutMs, signal, deadline, turn) {
         if (signal?.aborted)
             return Promise.reject(cancelledError());
         const id = randomUUID();
+        const now = Date.now();
+        // Taken before the timer starts, so the timer never fires before it.
+        const end = Math.min(now + timeoutMs, deadline ?? Infinity);
         // A peer waits a little longer than the hub, so the hub's own timeout message wins.
-        const wait = this.role === "peer" ? timeoutMs + 5_000 : timeoutMs;
+        const wait = Math.max(0, end - now) + (this.role === "peer" ? 5_000 : 0);
         return new Promise((resolve, reject) => {
             const onAbort = () => this.withdraw(id, target, cancelledError());
             const done = () => signal?.removeEventListener("abort", onAbort);
-            const timer = setTimeout(() => this.withdraw(id, target, new Error(`Extension call '${method}' timed out`)), wait);
+            const timer = setTimeout(() => this.withdraw(id, target, new Error(LOST_CALL.timedOut(method))), wait);
             this.pending.set(id, {
                 resolve: (v) => (done(), resolve(v)),
                 reject: (e) => (done(), reject(e)),
                 timer,
                 grace: method === "requestSend",
                 socket: this.role === "hub" ? target : undefined,
+                turn,
             });
             signal?.addEventListener("abort", onAbort, { once: true });
-            target.send(JSON.stringify({ type: "request", id, method, params, timeoutMs }));
+            // deadline: when this side stops waiting (same machine, same clock), so the extension
+            // sends nothing to Teams after it, however long the request took to arrive. turn: it holds
+            // a turn, which it gives back while it waits out a throttle (see onExtensionMessage).
+            target.send(JSON.stringify({ type: "request", id, method, params, timeoutMs, deadline: end, ...(turn ? { turn: true } : {}) }));
         });
     }
     /**
@@ -631,7 +888,9 @@ export class ExtensionBridge {
         this.closed = true;
         clearTimeout(this.retry);
         clearInterval(this.keepAlive);
-        this.rejectAll("mcp-teams is shutting down");
+        this.stopPeerBeat();
+        this.dropTurns();
+        this.rejectAll(LOST_CALL.shuttingDown);
         this.hub?.close();
         for (const s of this.sockets.keys())
             s.close();