@basein/runner 0.2.11 → 0.3.0

package/dist/upstream/http-client.js

@@ -11,243 +11,1109 @@
  *     message is a POST to one endpoint. The reply comes back as a JSON body or
  *     as an SSE stream carrying it. A session id handed out in the
  *     `Mcp-Session-Id` response header must be echoed on every later request.
- *     Server-initiated messages arrive on a standing GET stream, opened lazily
- *     after `initialize` and skipped when the server answers 405.
+ *     Server-initiated messages arrive on a standing GET stream, opened once the
+ *     handshake is done and skipped when the server answers 405.
  *   - **legacy SSE** (`--transport sse`): a long-lived GET carries every reply
  *     and announces the POST endpoint with an `endpoint` event, so the handshake
  *     is inverted — you must be listening before you can send.
  *
+ * THE RULES THIS FILE KEEPS, because a wrapped server must behave at least as
+ * well as the same server connected directly:
+ *
+ *   1. **Every request the host sends is answered.** A network error, a non-2xx,
+ *      an HTML page from an SSO or captive proxy, a body that is not the
+ *      JSON-RPC answer, an SSE reply that ends or resets before the answer, an
+ *      answer over the size cap, a legacy event stream that drops with requests
+ *      in flight — each becomes a short, fixed JSON-RPC error for that id. The
+ *      upstream's body is never echoed (it can be a login page or carry gateway
+ *      internals), and 401/403 say "requires sign-in" rather than dumping HTML.
+ *   2. **Only the handshake is ordered.** `initialize` and then
+ *      `notifications/initialized` go one after the other (the session id comes
+ *      back on the first, and Python-SDK servers refuse traffic before the
+ *      second). Every later POST is independent, as in the MCP SDK the host
+ *      would otherwise use: parallel tool calls run in parallel, a
+ *      `notifications/cancelled` is not queued behind the call it cancels, and
+ *      the host's answer to a server-initiated request (roots, elicitation,
+ *      sampling) is never stuck behind the very tool call waiting for it —
+ *      which, serialised, was a deadlock.
+ *   3. **Legacy SSE sends wait for the endpoint.** Nothing is POSTed until the
+ *      stream has announced where to POST (sent to the GET URL, the host's
+ *      `initialize` got a 405 and the server showed as failed every session).
+ *      A stream that ends — cleanly or not — is noticed, the requests riding it
+ *      are answered, and it is re-established with backoff; the new session is
+ *      re-initialised with the host's own `initialize` before anything else.
+ *   4. **Session expiry is survivable.** A 404 to a request that carried a
+ *      session means the server forgot us (a redeploy, an idle timeout). The
+ *      spec says start a new session; the proxy does it for the host — replays
+ *      the host's cached `initialize` under a `bir:` id, sends `initialized`,
+ *      and retries the request once.
+ *   5. **No timeout shorter than the host's.** The transport (http-transport.ts)
+ *      bounds the connect only; how long a tool may take is Claude Code's call,
+ *      and its cancellation reaches the server immediately (rule 2). What no
+ *      host waits on is bounded here instead, so nothing holds a connection
+ *      forever: the proxy's own calls (a replayed scenario step) are cancelled
+ *      upstream when their caller gives up, and a notification or response the
+ *      server has not answered in 60 s is dropped.
+ *
  * AUTH (§9). The host's own OAuth authenticates the server it is *configured*
  * with, which is now the proxy — so a remote upstream's credentials have to
  * reach us some other way. They come from `--header` / the environment at spawn
- * time and are held in memory only; nothing is written to disk here.
+ * time and are held in memory only; nothing is written to disk here. They are
+ * sent only to the configured origin: a legacy `endpoint` elsewhere is refused
+ * (as the MCP SDK does), a redirect off-origin drops every one of them, and a
+ * redirect from https to plain http is refused (http-transport.ts).
+ *
+ * STDERR IS FOR NEWS. Claude Code files every stderr line of bir-proxy as a
+ * "Server stderr" error, so what a remote server does routinely — a load
+ * balancer cutting an idle event stream every minute or two (60 s on an AWS
+ * ALB, 100 s on Cloudflare), and the reconnect and re-initialise that follow —
+ * is `BIR_VERBOSE` detail. What stays on stderr: requests answered with an
+ * error because a stream was lost, the first failure of an outage and its
+ * recovery, a session the server forgot, and a stream that keeps dropping as
+ * soon as it opens (once an hour per server at most).
  */
 import { readFrames } from "../jsonrpc/framing.js";
-import { logDetail, logLine, errText } from "../util/log.js";
-import { BaseUpstreamClient } from "./client.js";
+import { paramsObject } from "../jsonrpc/types.js";
+import { logDetail, logEvery, logLine, logOnce, errText } from "../util/log.js";
+import { BaseUpstreamClient, BIR_ID_PREFIX, isBirId } from "./client.js";
 import { Readable } from "node:stream";
+import { BodyTooLargeError, configuredProxy, createAgents, destroyAgents, httpRequest, nodeSupportsProxyEnv, proxyEnvEnabled, readBodyText, } from "./http-transport.js";
+import { readSseStream, SseTooLargeError } from "./sse.js";
+/** Legacy SSE connect budget (headers + `endpoint`), and the replayed-`initialize` wait. */
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
+/** DNS + TCP + TLS. A blackholed host fails in this, not the OS's 21-75 s. */
+const DEFAULT_SOCKET_CONNECT_TIMEOUT_MS = 10_000;
+const DEFAULT_RECONNECT_BASE_MS = 500;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+/** A standing stream that stayed up this long was healthy: its drop restarts the backoff. */
+const HEALTHY_STREAM_MS = 60_000;
+/**
+ * A stream that keeps dropping as soon as it opens is said on stderr at most
+ * this often per server; the drops in between are `BIR_VERBOSE` detail.
+ */
+const STREAM_NEWS_INTERVAL_MS = 60 * 60_000;
+/** close(): the session DELETE is best effort and must never hold up an exit. */
+const DELETE_TIMEOUT_MS = 1_000;
+/**
+ * The longest one handshake message holds up the traffic behind it. The POST
+ * itself is not cut off — a server that never answers `initialized` just stops
+ * being waited for, rather than wedging every later request with it.
+ */
+const HANDSHAKE_GATE_MS = 10_000;
+/**
+ * The largest answer relayed. A bound against runaway memory, not a judgement
+ * on size: a directly connected server has none, so it is set well above any
+ * real tool result (a base64 screenshot or file is a few MiB to a few tens).
+ */
+const DEFAULT_MAX_MESSAGE_BYTES = 128 * 1024 * 1024;
+/**
+ * A notification or a response is answered with a bare 202 at once; one still
+ * unanswered after this is hung, and holding its socket forever helps nobody.
+ */
+const DEFAULT_UNANSWERED_POST_TIMEOUT_MS = 60_000;
+/** What the host is told. Short and fixed: never the upstream's body. */
+const ANSWER = {
+    tooLarge: "upstream answer too large",
+    closedEarly: "upstream closed the connection before it answered",
+    lost: "upstream connection was lost before it answered",
+    streamDown: "upstream is not reachable (its event stream is down)",
+};
+function statusAnswer(status, statusText) {
+    if (status === 401 || status === 403)
+        return `upstream requires sign-in (HTTP ${status})`;
+    return `upstream HTTP ${status}${statusText ? ` ${statusText}` : ""}`;
+}
+/** `text/html; charset=utf-8` → `text/html`. */
+function mediaType(contentType) {
+    return contentType.split(";")[0].trim();
+}
+function socketConnectTimeoutFromEnv() {
+    return positiveFromEnv("BIR_UPSTREAM_CONNECT_TIMEOUT_MS");
+}
+function positiveFromEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+const noop = () => undefined;
+/** Settles when `promise` does or after `ms`, whichever is first; never rejects. */
+function settledWithin(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        promise.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
 export class HttpUpstreamClient extends BaseUpstreamClient {
     ready;
     url;
+    origin;
     transport;
     headers;
     label;
     connectTimeoutMs;
+    socketConnectTimeoutMs;
+    reconnectBaseMs;
+    maxMessageBytes;
+    unansweredPostTimeoutMs;
+    healthyStreamMs;
+    agents;
     sessionId;
-    /** Legacy SSE only: where to POST, announced by the stream's `endpoint` event. */
+    /** Negotiated in `initialize`, echoed as `MCP-Protocol-Version` afterwards. */
+    protocolVersion;
+    /** The host's `initialize` params, replayed when the server loses our session. */
+    initParams;
+    hostInitId;
+    reinitCount = 0;
+    /**
+     * The handshake gate. `initialize` and `notifications/initialized` chain onto
+     * it; every other message waits for it and then goes on its own (rule 2).
+     */
+    gate;
+    recovery;
+    outstanding = new Map();
+    /** Every in-flight POST's aborter, so close() can drop them all. */
+    inflight = new Set();
+    /** Answers to this client's own replayed `initialize`, consumed before the relay. */
+    internalWaiters = new Map();
+    // ── legacy SSE ──
+    /** Where to POST, announced by the stream's `endpoint` event. Unset while down. */
     postUrl;
-    abort = new AbortController();
-    /** Serialises POSTs so messages leave in the order the host sent them. */
-    chain = Promise.resolve();
-    standingStreamOpened = false;
+    /** Bumped per announced stream; a request's answer can only ride the stream it was posted on. */
+    generation = 0;
+    streamAbort;
+    connecting;
+    reconnectTimer;
+    reconnectFailures = 0;
+    /** Streams that ended soon after connecting, in a row: they back off like failures. */
+    streamDrops = 0;
+    streamOpenedAt = 0;
+    // ── streamable HTTP's standing GET ──
+    standing = "idle";
+    standingAbort;
+    standingTimer;
+    standingDrops = 0;
+    standingLastEventId;
+    standingRetryMs;
+    standingParser;
     constructor(opts) {
         super();
         this.url = opts.url;
+        this.origin = new URL(opts.url).origin;
         this.transport = opts.transport ?? "http";
         this.headers = opts.headers ?? {};
         this.label = opts.label ?? new URL(opts.url).host;
-        this.connectTimeoutMs = opts.connectTimeoutMs ?? 15_000;
-        this.ready = this.connect();
+        this.connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+        this.socketConnectTimeoutMs =
+            opts.socketConnectTimeoutMs ?? socketConnectTimeoutFromEnv() ?? DEFAULT_SOCKET_CONNECT_TIMEOUT_MS;
+        this.reconnectBaseMs = opts.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
+        this.maxMessageBytes =
+            opts.maxMessageBytes ?? positiveFromEnv("BIR_UPSTREAM_MAX_MESSAGE_BYTES") ?? DEFAULT_MAX_MESSAGE_BYTES;
+        this.unansweredPostTimeoutMs = opts.unansweredPostTimeoutMs ?? DEFAULT_UNANSWERED_POST_TIMEOUT_MS;
+        this.healthyStreamMs = opts.healthyStreamMs ?? HEALTHY_STREAM_MS;
+        this.agents = createAgents({ freeSocketTimeoutMs: opts.idleSocketTimeoutMs });
+        if (this.transport === "sse") {
+            this.ready = this.openSseEndpointStream();
+            // A server that cannot even be connected is dead, not "alive and silent":
+            // marking it so lets the relay answer every request at once (§10) instead
+            // of queueing them behind a stream that will never come.
+            this.ready.catch((err) => {
+                if (this.dead)
+                    return;
+                this.closed({ error: err instanceof Error ? err : new Error(String(err)) });
+                this.teardown();
+            });
+        }
+        else {
+            // Streamable HTTP needs no connect step: the first POST is the handshake,
+            // and that POST is the host's own `initialize` relayed verbatim.
+            this.ready = Promise.resolve();
+        }
+        this.gate = this.ready.then(noop, noop);
     }
-    async connect() {
-        if (this.transport === "sse")
-            await this.openSseEndpointStream();
-        // Streamable HTTP needs no connect step: the first POST is the handshake,
-        // and that POST is the host's own `initialize` relayed verbatim.
+    // ── sending ───────────────────────────────────────────────────────────────
+    send(msg) {
+        if (this.dead)
+            return;
+        const method = msg.method;
+        const id = msg.id;
+        logDetail("upstream.send", { server: this.label, method });
+        let entry;
+        if (typeof method === "string" && (typeof id === "string" || typeof id === "number")) {
+            entry = { id, method, abort: new AbortController() };
+            this.outstanding.set(id, entry);
+        }
+        if (method === "initialize" || method === "notifications/initialized") {
+            if (method === "initialize" && entry)
+                this.hostInitId = entry.id;
+            const previous = this.gate;
+            const sent = previous.then(() => this.postMessage(msg, entry));
+            this.gate = previous.then(() => settledWithin(sent, HANDSHAKE_GATE_MS));
+            return;
+        }
+        if (method === "notifications/cancelled") {
+            const target = paramsObject(msg.params).requestId;
+            const cancelled = typeof target === "string" || typeof target === "number" ? this.outstanding.get(target) : undefined;
+            if (cancelled)
+                cancelled.cancelled = true;
+            void this.gate
+                .then(() => this.postMessage(msg, undefined))
+                .finally(() => {
+                // The server has been told. Stop holding the connection that was
+                // carrying an answer nobody is waiting for any more.
+                if (cancelled && this.outstanding.get(cancelled.id) === cancelled) {
+                    this.outstanding.delete(cancelled.id);
+                    cancelled.abort.abort();
+                }
+            });
+            return;
+        }
+        void this.gate.then(() => this.postMessage(msg, entry));
     }
-    // ── legacy SSE: listen first, then learn where to POST ────────────────────
-    async openSseEndpointStream() {
-        const res = await fetch(this.url, {
-            method: "GET",
-            headers: { accept: "text/event-stream", ...this.headers },
-            signal: this.abort.signal,
-        });
-        if (!res.ok || !res.body) {
-            throw new Error(`SSE connect failed: ${res.status} ${res.statusText}`);
+    /*
+     * The proxy's own calls (`bir:` ids — a replayed scenario step) need no
+     * override here. When the caller's signal fires, BaseUpstreamClient.request
+     * rejects locally and sends `notifications/cancelled` through send(), and the
+     * cancel path above releases the abandoned POST's connection once the server
+     * has been told — so a timed-out step leaks neither work nor a socket. An
+     * already-aborted signal is refused before anything is sent.
+     */
+    /** Never rejects: whatever goes wrong, a request still gets its answer. */
+    async postMessage(msg, entry, opts = {}) {
+        try {
+            await this.postOnce(msg, entry, opts);
         }
-        let announce;
-        const announced = new Promise((resolve) => {
-            announce = resolve;
-        });
-        void this.pumpSse(res.body, (event, data) => {
-            if (event === "endpoint") {
-                this.postUrl = new URL(data, this.url).toString();
-                announce?.();
+        catch (err) {
+            logLine("upstream.send_failed", { server: this.label, error: errText(err) });
+            this.answerError(entry, `upstream unreachable: ${errText(err)}`);
+        }
+    }
+    async postOnce(msg, entry, opts) {
+        if (this.dead || entry?.cancelled)
+            return;
+        const method = msg.method;
+        if (this.transport === "sse") {
+            // The replayed handshake runs inside a reconnect, so it must not wait for
+            // that reconnect; everything else waits for a live endpoint (rule 3).
+            const up = opts.internal ? Boolean(this.postUrl) : await this.ensureStream();
+            if (this.dead || entry?.cancelled)
+                return;
+            if (!up) {
+                this.answerError(entry, ANSWER.streamDown);
                 return;
             }
-            this.dispatch(data);
-        }).catch((err) => {
-            if (!this.dead) {
-                logLine("upstream.stream_ended", { server: this.label, error: errText(err) });
-                this.closed({ error: err instanceof Error ? err : new Error(String(err)) });
-            }
-        });
-        const timer = setTimeout(() => announce?.(), this.connectTimeoutMs);
-        await announced;
-        clearTimeout(timer);
-        if (!this.postUrl)
-            throw new Error("SSE server never announced its endpoint");
-    }
-    /**
-     * Streamable HTTP: open the standing GET stream that carries server-initiated
-     * requests (`sampling/createMessage`, `elicitation/create`, list-changed
-     * notifications). A 405 means this server does not offer one — normal, and not
-     * an error: everything it sends will ride the POST responses instead.
-     */
-    async openStandingStream() {
-        if (this.standingStreamOpened || this.transport !== "http")
+        }
+        const target = this.transport === "sse" ? this.postUrl : this.url;
+        if (!target) {
+            this.answerError(entry, ANSWER.streamDown);
             return;
-        this.standingStreamOpened = true;
+        }
+        // Which session this POST speaks for: a 404 only means "expired" if the
+        // session it carried is still the current one (see recoverSession).
+        const sentOn = this.sessionKey();
+        const generation = this.generation;
+        const controller = entry?.abort ?? new AbortController();
+        this.inflight.add(controller);
+        // A request is bounded by the host (its timeout, its cancel). A message
+        // with no id has no one to do that: a server that never answers it would
+        // hold a socket for the life of the proxy. Its reply stream (below) is the
+        // exception — a server that streams is live, not hung.
+        let abandonTimer;
+        if (!entry) {
+            abandonTimer = setTimeout(() => {
+                logDetail("upstream.post_abandoned", { server: this.label, method: method ?? "response" });
+                controller.abort();
+            }, this.unansweredPostTimeoutMs);
+            abandonTimer.unref?.();
+        }
+        let res;
         try {
-            const res = await fetch(this.url, {
-                method: "GET",
-                headers: { accept: "text/event-stream", ...this.sessionHeaders(), ...this.headers },
-                signal: this.abort.signal,
-            });
-            if (!res.ok || !res.body) {
-                logDetail("upstream.no_standing_stream", { server: this.label, status: res.status });
+            res = await this.call("POST", target, {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+                ...this.sessionHeaders(method === "initialize"),
+                ...this.headers,
+            }, JSON.stringify(msg), controller.signal);
+        }
+        catch (err) {
+            clearTimeout(abandonTimer);
+            this.inflight.delete(controller);
+            if (this.dead || controller.signal.aborted)
+                return;
+            logLine("upstream.send_failed", { server: this.label, method, error: errText(err) });
+            this.proxyHint();
+            this.answerError(entry, `upstream unreachable: ${errText(err)}`);
+            return;
+        }
+        let handedOff = false;
+        try {
+            if (this.dead || controller.signal.aborted) {
+                res.body.destroy();
                 return;
             }
-            void this.pumpSse(res.body, (_event, data) => this.dispatch(data)).catch(() => {
-                logDetail("upstream.standing_stream_ended", { server: this.label });
-            });
+            if (this.transport === "http") {
+                // The server assigns the session at `initialize`. Adopting an id from
+                // any other answer would let a slow reply from a session that has since
+                // been replaced (see recoverSession) put the old one back.
+                const sid = res.header("mcp-session-id");
+                if (sid && (method === "initialize" || !this.sessionId))
+                    this.sessionId = sid;
+            }
+            // Kept only once the server has taken it: replaying a handshake the host
+            // never completed would give a fresh session two `initialize`s.
+            if (res.ok && method === "initialize" && !opts.internal) {
+                this.initParams = msg.params ?? {};
+            }
+            if (!res.ok) {
+                res.body.destroy();
+                logLine("upstream.http_error", { server: this.label, status: res.status, method });
+                if (res.status === 401 || res.status === 403) {
+                    if (method === "initialize")
+                        this.noteAuthRequired(res.status);
+                    else {
+                        logOnce(`upstream.needs_sign_in:${this.label}`, "upstream.needs_sign_in", {
+                            server: this.label,
+                            status: res.status,
+                        });
+                    }
+                }
+                // Only a 404 to a request that carried a session says "forgotten": from
+                // a stateless server (no session id) it is just a 404, and recovering
+                // would add three round trips to every such request for nothing.
+                const expired = res.status === 404 &&
+                    entry !== undefined &&
+                    !opts.retried &&
+                    method !== "initialize" &&
+                    this.initParams !== undefined &&
+                    (this.transport === "sse" || sentOn !== "");
+                if (expired && (await this.recoverSession(sentOn)) && !this.dead && !entry.cancelled) {
+                    handedOff = true; // the retry owns the aborter now
+                    this.inflight.delete(controller);
+                    await this.postOnce(msg, entry, { retried: true });
+                    return;
+                }
+                this.answerError(entry, statusAnswer(res.status, res.statusText));
+                return;
+            }
+            if (this.transport === "sse") {
+                // Legacy: the answer rides the event stream; this body is an
+                // acknowledgement. If that stream went down while we were posting, the
+                // answer can never arrive — say so now rather than never.
+                res.body.resume();
+                if (entry && this.outstanding.get(entry.id) === entry) {
+                    if (generation !== this.generation || !this.postUrl)
+                        this.answerError(entry, ANSWER.lost);
+                    else
+                        entry.postedOn = generation;
+                }
+                return;
+            }
+            const contentType = (res.header("content-type") ?? "").toLowerCase();
+            if (contentType.includes("text/event-stream")) {
+                handedOff = true;
+                void this.pumpReply(res, entry, controller);
+            }
+            else {
+                await this.readReply(res, contentType, entry, controller);
+            }
+            // As the MCP SDK does: the standing stream opens once the handshake is done.
+            if (method === "notifications/initialized")
+                void this.openStandingStream();
         }
-        catch {
-            // No standing stream. Not fatal — see the doc comment above.
+        finally {
+            clearTimeout(abandonTimer);
+            if (!handedOff)
+                this.inflight.delete(controller);
         }
     }
-    /** Read an SSE body, calling `onEvent(eventName, data)` per complete event. */
-    async pumpSse(body, onEvent) {
-        const reader = body.getReader();
-        const decoder = new TextDecoder();
-        let buf = "";
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
+    /** A JSON (or unexpected) reply body. Whatever it holds, the request gets an answer. */
+    async readReply(res, contentType, entry, controller) {
+        let text;
+        try {
+            text = await readBodyText(res.body, this.maxMessageBytes);
+        }
+        catch (err) {
+            if (this.dead || controller.signal.aborted)
+                return;
+            logLine("upstream.reply_failed", { server: this.label, method: entry?.method, error: errText(err) });
+            this.answerError(entry, err instanceof BodyTooLargeError ? ANSWER.tooLarge : ANSWER.closedEarly);
+            return;
+        }
+        const empty = text.trim().length === 0;
+        const parsed = empty ? true : this.dispatchData(text);
+        if (!entry || this.outstanding.get(entry.id) !== entry)
+            return; // answered (or a notification)
+        if (empty) {
+            // A bare 202 for a request is outside the spec, but the MCP SDK tolerates
+            // it when a standing stream could carry the answer, so we do too.
+            if (this.standing === "open" || this.standing === "opening") {
+                entry.onStandingStream = true;
                 return;
-            buf += decoder.decode(value, { stream: true });
-            let sep;
-            // Events are separated by a blank line; \r\n is legal too.
-            while ((sep = buf.search(/\r?\n\r?\n/)) !== -1) {
-                const raw = buf.slice(0, sep);
-                buf = buf.slice(sep + (buf[sep] === "\r" ? 4 : 2));
-                let event = "message";
-                const data = [];
-                for (const line of raw.split(/\r?\n/)) {
-                    if (line.startsWith("event:"))
-                        event = line.slice(6).trim();
-                    else if (line.startsWith("data:"))
-                        data.push(line.slice(5).replace(/^ /, ""));
-                }
-                if (data.length)
-                    onEvent(event, data.join("\n"));
             }
+            logLine("upstream.unanswered", { server: this.label, method: entry.method, status: res.status });
+            this.answerError(entry, `upstream accepted the request but sent no answer (HTTP ${res.status})`);
+            return;
         }
+        logLine("upstream.unexpected_answer", {
+            server: this.label,
+            method: entry.method,
+            status: res.status,
+            contentType: contentType ? mediaType(contentType) : "none",
+            json: parsed,
+        });
+        this.answerError(entry, `upstream returned an unexpected answer (HTTP ${res.status}${contentType ? `, ${mediaType(contentType)}` : ""})`);
     }
-    /** Hand one inbound JSON-RPC payload to the relay (or to a `bir:` waiter). */
-    dispatch(raw) {
-        let msg;
+    /** A reply delivered as an SSE body. If it ends before the answer, answer anyway. */
+    async pumpReply(res, entry, controller) {
+        let failure;
         try {
-            msg = JSON.parse(raw);
+            await readSseStream(res.body, (event) => void this.dispatchData(event.data), {
+                maxEventBytes: this.maxMessageBytes,
+                onHandlerError: (err) => this.handlerFailed(err),
+            });
+        }
+        catch (err) {
+            failure = err instanceof SseTooLargeError ? ANSWER.tooLarge : ANSWER.closedEarly;
+            if (!this.dead && !controller.signal.aborted) {
+                logLine("upstream.reply_stream_failed", {
+                    server: this.label,
+                    method: entry?.method,
+                    error: errText(err),
+                });
+            }
+        }
+        finally {
+            this.inflight.delete(controller);
+        }
+        if (this.dead || controller.signal.aborted || !entry)
+            return;
+        if (this.outstanding.get(entry.id) !== entry)
+            return;
+        if (!failure)
+            logLine("upstream.unanswered", { server: this.label, method: entry.method, why: "stream ended" });
+        this.answerError(entry, failure ?? "upstream ended its reply stream without answering");
+    }
+    // ── receiving ─────────────────────────────────────────────────────────────
+    /** Parse one inbound payload (a body or an SSE event). False if it was not JSON. */
+    dispatchData(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
         }
         catch {
             logDetail("upstream.unparseable", { server: this.label, sample: raw.slice(0, 120) });
-            return;
+            return false;
         }
-        if (!msg || typeof msg !== "object" || Array.isArray(msg))
+        // A JSON-RPC batch is legal on the wire; the host only ever sees single messages.
+        if (Array.isArray(parsed))
+            for (const item of parsed)
+                this.deliver(item);
+        else
+            this.deliver(parsed);
+        return true;
+    }
+    /** Hand one inbound JSON-RPC message to the relay (or to a `bir:` waiter). */
+    deliver(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
             return;
+        const msg = value;
+        const hasMethod = typeof msg.method === "string";
+        const isAnswer = !hasMethod && "id" in msg && ("result" in msg || "error" in msg);
+        if (!hasMethod && !isAnswer) {
+            // `{"status":"ok"}` from a health route is not JSON-RPC, and the host's
+            // stream must only ever carry JSON-RPC.
+            logDetail("upstream.not_jsonrpc", { server: this.label });
+            return;
+        }
+        if (isAnswer) {
+            const id = msg.id;
+            if (typeof id === "string") {
+                const waiter = this.internalWaiters.get(id);
+                if (waiter) {
+                    this.internalWaiters.delete(id);
+                    this.outstanding.delete(id);
+                    waiter(msg);
+                    return;
+                }
+            }
+            if (typeof id === "string" || typeof id === "number") {
+                this.outstanding.delete(id);
+                if (id === this.hostInitId)
+                    this.noteProtocolVersion(msg.result);
+            }
+        }
         this.accept(msg);
     }
-    target() {
-        return this.transport === "sse" ? (this.postUrl ?? this.url) : this.url;
+    /** Answer a request ourselves, once, unless the host no longer wants it. */
+    answerError(entry, message) {
+        if (!entry || this.outstanding.get(entry.id) !== entry)
+            return;
+        this.outstanding.delete(entry.id);
+        const waiter = typeof entry.id === "string" ? this.internalWaiters.get(entry.id) : undefined;
+        if (waiter) {
+            this.internalWaiters.delete(entry.id);
+            waiter({ jsonrpc: "2.0", id: entry.id, error: { code: -32000, message } });
+            return;
+        }
+        // Cancelled: the host stopped waiting. Dead: the relay has answered it.
+        if (entry.cancelled || this.dead)
+            return;
+        this.accept({ jsonrpc: "2.0", id: entry.id, error: { code: -32000, message } });
     }
-    sessionHeaders() {
-        return this.sessionId ? { "mcp-session-id": this.sessionId } : {};
+    noteProtocolVersion(result) {
+        const version = paramsObject(result).protocolVersion;
+        if (typeof version === "string" && version)
+            this.protocolVersion = version;
     }
-    send(msg) {
-        if (this.dead)
-            return;
-        logDetail("upstream.send", {
-            server: this.label,
-            method: msg.method,
+    handlerFailed(err) {
+        logLine("upstream.dispatch_failed", { server: this.label, error: errText(err) });
+    }
+    /**
+     * The server refused the handshake for want of credentials. Said once per
+     * server, as `upstream.auth_required`, so `bir doctor` can explain a remote
+     * server that was wrapped without the headers it needs (an opt-in remote
+     * entry whose sign-in only the host could do) instead of "it fails".
+     */
+    noteAuthRequired(status) {
+        logOnce(`upstream.auth_required:${this.label}`, "upstream.auth_required", { server: this.label, status });
+    }
+    // ── session expiry (rule 4) ───────────────────────────────────────────────
+    /**
+     * The server answered 404 to a request sent on session `staleKey`. Start a
+     * new session once, however many requests noticed at the same moment, and
+     * hold new traffic until it exists. Resolves true when a retry makes sense.
+     */
+    recoverSession(staleKey) {
+        if (this.recovery?.key === staleKey)
+            return this.recovery.promise;
+        if (this.sessionKey() !== staleKey)
+            return Promise.resolve(true); // already recovered: just retry
+        const promise = (async () => {
+            logLine("upstream.session_expired", { server: this.label, transport: this.transport });
+            if (this.transport === "http") {
+                this.sessionId = undefined;
+                this.resetStandingStream();
+                return this.reinitialize();
+            }
+            // Legacy: the session *is* the event stream. Drop it and open a new one;
+            // reconnect() replays the handshake. A reconnect already under way (the
+            // stream dropped, and the generation moves only once the new one
+            // announces itself) is opening that new session: join it. Aborting
+            // `streamAbort` then would kill it — mid-connect it is the new stream's.
+            if (this.connecting)
+                return this.connecting;
+            if (this.postUrl) {
+                // `session_expired` above is the line; this drop is its consequence.
+                this.onSseStreamLost(this.generation, "session expired", true);
+                this.streamAbort?.abort();
+            }
+            return this.reconnect(true);
+        })();
+        this.recovery = { key: staleKey, promise };
+        // Settled, it no longer stands for the live session: a later 404 on the
+        // same key (a recovery that failed) gets a fresh attempt, one per request.
+        void promise.finally(() => {
+            if (this.recovery?.promise === promise)
+                this.recovery = undefined;
         });
-        // Serialised: MCP is order-sensitive (`initialize` before anything else, and
-        // `notifications/initialized` before the first call), and parallel fetches
-        // would let a later POST overtake an earlier one.
-        this.chain = this.chain.then(() => this.post(msg)).catch(() => undefined);
+        this.gate = Promise.all([this.gate, promise]).then(noop, noop);
+        return promise;
     }
-    async post(msg) {
-        const isInitialize = msg.method === "initialize";
-        try {
-            const res = await fetch(this.target(), {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    accept: "application/json, text/event-stream",
-                    ...this.sessionHeaders(),
-                    ...this.headers,
-                },
-                body: JSON.stringify(msg),
-                signal: this.abort.signal,
+    /** Which session a POST speaks for: the session id, or the legacy stream generation. */
+    sessionKey() {
+        return this.transport === "http" ? (this.sessionId ?? "") : String(this.generation);
+    }
+    /**
+     * Replay the host's `initialize` (under a `bir:` id) and `initialized`.
+     * `news`: say it on stderr when it worked — after a forgotten session or an
+     * outage; after a routine reconnect it is detail. A failure is always said.
+     */
+    async reinitialize(news = true) {
+        if (this.initParams === undefined || this.dead)
+            return false;
+        this.reinitCount += 1;
+        const id = `${BIR_ID_PREFIX}reinit:${this.reinitCount}`;
+        const entry = { id, method: "initialize", abort: new AbortController() };
+        this.outstanding.set(id, entry);
+        const answered = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.internalWaiters.delete(id);
+                if (this.outstanding.get(id) === entry)
+                    this.outstanding.delete(id);
+                entry.abort.abort();
+                resolve(undefined);
+            }, this.connectTimeoutMs);
+            timer.unref?.();
+            this.internalWaiters.set(id, (msg) => {
+                clearTimeout(timer);
+                resolve(msg);
             });
-            const sid = res.headers.get("mcp-session-id");
-            if (sid)
-                this.sessionId = sid;
+        });
+        await this.postMessage({ jsonrpc: "2.0", id, method: "initialize", params: this.initParams }, entry, { retried: true, internal: true });
+        const reply = await answered;
+        if (this.dead)
+            return false;
+        if (!reply || !("result" in reply)) {
+            const error = reply ? paramsObject(reply.error).message : "no answer";
+            logLine("upstream.reinitialize_failed", { server: this.label, error: String(error ?? "error") });
+            return false;
+        }
+        this.noteProtocolVersion(reply.result);
+        await settledWithin(this.postMessage({ jsonrpc: "2.0", method: "notifications/initialized" }, undefined, {
+            retried: true,
+            internal: true,
+        }), HANDSHAKE_GATE_MS);
+        (news ? logLine : logDetail)("upstream.session_reinitialized", { server: this.label, transport: this.transport });
+        return true;
+    }
+    // ── legacy SSE: listen first, then learn where to POST (rule 3) ────────────
+    /**
+     * Open the event stream and resolve once it has announced its endpoint. The
+     * whole connect — response headers included — is bounded by
+     * `connectTimeoutMs`: a server that never sent headers used to hold `ready`
+     * for fetch's 300 s, far past the host's own MCP connect timeout.
+     */
+    async openSseEndpointStream() {
+        const controller = new AbortController();
+        this.streamAbort = controller;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.connectTimeoutMs);
+        timer.unref?.();
+        try {
+            let res;
+            try {
+                res = await this.call("GET", this.url, { accept: "text/event-stream", ...this.headers }, undefined, controller.signal);
+            }
+            catch (err) {
+                throw timedOut ? new Error(`SSE connect timed out after ${this.connectTimeoutMs} ms`) : err;
+            }
             if (!res.ok) {
-                // A transport-level failure toward a request needs an answer, or the
-                // host waits forever. The relay owns that decision, so surface it as a
-                // JSON-RPC error response on the inbound path.
-                const id = msg.id;
-                const text = await res.text().catch(() => "");
-                logLine("upstream.http_error", {
+                res.body.destroy();
+                // Legacy SSE's handshake starts here, with the GET: a 401/403 now is
+                // the same "no credentials" as one to a streamable `initialize`.
+                if (res.status === 401 || res.status === 403)
+                    this.noteAuthRequired(res.status);
+                throw new Error(`SSE connect failed: ${statusAnswer(res.status, res.statusText)}`);
+            }
+            const contentType = (res.header("content-type") ?? "").toLowerCase();
+            if (contentType && !contentType.includes("text/event-stream")) {
+                res.body.destroy();
+                throw new Error(`SSE connect failed: the server answered ${mediaType(contentType)}, not an event stream`);
+            }
+            const generation = this.generation + 1;
+            await new Promise((resolve, reject) => {
+                let announced = false;
+                const onAbort = () => {
+                    if (announced)
+                        return;
+                    reject(new Error(timedOut
+                        ? `SSE server did not announce its endpoint within ${this.connectTimeoutMs} ms`
+                        : "SSE connect aborted"));
+                };
+                controller.signal.addEventListener("abort", onAbort, { once: true });
+                const onEvent = (event) => {
+                    if (event.event.trim() !== "endpoint") {
+                        this.dispatchData(event.data);
+                        return;
+                    }
+                    let next;
+                    try {
+                        next = new URL(event.data.trim(), this.url);
+                    }
+                    catch {
+                        next = undefined;
+                    }
+                    if (!next || next.origin !== this.origin) {
+                        // The endpoint decides where every POST — and the user's credential
+                        // headers — go. The MCP SDK refuses a foreign origin; so do we.
+                        logLine("upstream.endpoint_rejected", {
+                            server: this.label,
+                            reason: next ? "different origin" : "invalid URL",
+                        });
+                        if (!announced) {
+                            reject(new Error("SSE server announced an endpoint on a different origin"));
+                            controller.abort();
+                        }
+                        return;
+                    }
+                    this.postUrl = next.toString();
+                    if (!announced) {
+                        announced = true;
+                        this.generation = generation;
+                        this.streamOpenedAt = Date.now();
+                        controller.signal.removeEventListener("abort", onAbort);
+                        resolve();
+                    }
+                };
+                const ended = (why) => {
+                    if (!announced) {
+                        reject(new Error(`SSE stream ${why === "ended" ? "ended" : `failed (${why})`} before announcing its endpoint`));
+                        return;
+                    }
+                    // Closed, or dropped on purpose by a recovery that handles it itself.
+                    if (this.dead || controller.signal.aborted)
+                        return;
+                    // A server that accepts and then drops every stream at once must not
+                    // be reconnected (and re-initialised) twice a second forever.
+                    const healthy = Date.now() - this.streamOpenedAt >= this.healthyStreamMs;
+                    this.streamDrops = healthy ? 0 : this.streamDrops + 1;
+                    // A healthy stream's end is a load balancer's idle cut, and so
+                    // routine; the first quick drop of a run is news.
+                    this.onSseStreamLost(generation, why, healthy || this.streamDrops > 1);
+                    this.scheduleReconnect();
+                };
+                readSseStream(res.body, onEvent, {
+                    maxEventBytes: this.maxMessageBytes,
+                    onHandlerError: (err) => this.handlerFailed(err),
+                }).then(() => ended("ended"), (err) => ended(errText(err)));
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * The stream a set of requests was answered on is gone. Their answers can
+     * never arrive (a new stream is a new session), so answer them now.
+     *
+     * Said on stderr when that cost the host an answer. Otherwise `routine`
+     * (a healthy stream's idle cut, a drop a recovery already said) is detail,
+     * and anything else — a stream that dropped soon after it opened — is said
+     * once an hour per server at most.
+     */
+    onSseStreamLost(generation, why, routine = false) {
+        if (generation !== this.generation || !this.postUrl)
+            return; // already handled
+        this.postUrl = undefined;
+        let lost = 0;
+        for (const entry of [...this.outstanding.values()]) {
+            if (entry.postedOn !== generation)
+                continue;
+            if (!entry.cancelled)
+                lost += 1;
+            this.answerError(entry, ANSWER.lost);
+        }
+        const fields = { server: this.label, why, lost: lost || undefined };
+        if (lost > 0)
+            logLine("upstream.stream_ended", fields);
+        else if (routine || !logEvery(`upstream.stream_ended:${this.label}`, STREAM_NEWS_INTERVAL_MS, "upstream.stream_ended", fields)) {
+            logDetail("upstream.stream_ended", fields);
+        }
+    }
+    /** Legacy: is there an endpoint to POST to? Waits for one reconnect attempt at most. */
+    async ensureStream() {
+        if (this.connecting)
+            return this.connecting;
+        if (this.postUrl)
+            return true;
+        if (this.dead)
+            return false;
+        return this.reconnect();
+    }
+    /**
+     * One reconnect attempt (shared by everyone who asks meanwhile). A host
+     * request that arrives while the stream is down pulls the next attempt
+     * forward rather than waiting out the backoff, and gets an error — not a
+     * hang — if that attempt fails.
+     *
+     * `afterExpiry`: the server forgot the session (a 404), which is worth a
+     * line when the new one is initialised. A routine reconnect that works at
+     * the first try is detail; one that ends an outage is said.
+     */
+    reconnect(afterExpiry = false) {
+        if (this.connecting)
+            return this.connecting;
+        if (this.dead)
+            return Promise.resolve(false);
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        const attempt = (async () => {
+            try {
+                await this.openSseEndpointStream();
+            }
+            catch (err) {
+                if (this.dead)
+                    return false;
+                this.reconnectFailures += 1;
+                // The first failure is news; the rest of an outage is noise.
+                (this.reconnectFailures === 1 ? logLine : logDetail)("upstream.reconnect_failed", {
                     server: this.label,
-                    status: res.status,
-                    method: msg.method,
+                    attempts: this.reconnectFailures,
+                    error: errText(err),
                 });
-                if (id !== undefined && id !== null) {
-                    this.accept({
-                        jsonrpc: "2.0",
-                        id: id,
-                        error: {
-                            code: -32000,
-                            message: `upstream HTTP ${res.status} ${res.statusText}${text ? ` — ${text.slice(0, 500)}` : ""}`,
-                        },
-                    });
-                }
+                this.scheduleReconnect();
+                return false;
+            }
+            const recovered = this.reconnectFailures > 0;
+            (recovered ? logLine : logDetail)("upstream.stream_reconnected", {
+                server: this.label,
+                failedAttempts: this.reconnectFailures,
+            });
+            this.reconnectFailures = 0;
+            // A new event stream is a new, uninitialised session: replay the host's
+            // handshake before anything else is let through.
+            if (this.initParams !== undefined)
+                await this.reinitialize(recovered || afterExpiry);
+            return true;
+        })();
+        this.connecting = attempt;
+        void attempt.finally(() => {
+            if (this.connecting === attempt)
+                this.connecting = undefined;
+        });
+        return attempt;
+    }
+    scheduleReconnect() {
+        if (this.dead || this.reconnectTimer)
+            return;
+        const setbacks = Math.max(this.reconnectFailures, this.streamDrops - 1);
+        const delay = Math.min(MAX_RECONNECT_DELAY_MS, this.reconnectBaseMs * 2 ** Math.min(setbacks, 10));
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.reconnect();
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    // ── streamable HTTP: the standing GET ─────────────────────────────────────
+    /**
+     * Open the standing GET stream that carries server-initiated requests
+     * (`sampling/createMessage`, `elicitation/create`, list-changed
+     * notifications). A 405 means this server does not offer one — normal, and
+     * not an error: everything it sends will ride the POST responses instead.
+     * When it drops it is re-opened with backoff (with `Last-Event-ID` when the
+     * server numbers its events), so a load balancer's idle cut does not silently
+     * lose every later list-changed or elicitation.
+     */
+    async openStandingStream() {
+        if (this.transport !== "http" || this.dead || this.standing !== "idle")
+            return;
+        clearTimeout(this.standingTimer);
+        this.standingTimer = undefined;
+        this.standing = "opening";
+        const controller = new AbortController();
+        this.standingAbort = controller;
+        const session = this.sessionId;
+        let res;
+        try {
+            res = await this.call("GET", this.url, {
+                accept: "text/event-stream",
+                ...(this.standingLastEventId ? { "last-event-id": this.standingLastEventId } : {}),
+                ...this.sessionHeaders(false),
+                ...this.headers,
+            }, undefined, controller.signal);
+        }
+        catch (err) {
+            if (this.dead || controller.signal.aborted)
                 return;
+            this.standingDown();
+            this.standingDrops += 1;
+            // The first failed re-open of a run is news — until the stream is back,
+            // what the server sends on its own (list changes, elicitations) is not
+            // heard — once an hour per server at most; the retries are detail.
+            const fields = { server: this.label, error: errText(err), drops: this.standingDrops };
+            if (this.standingDrops > 1 ||
+                !logEvery(`upstream.standing_stream_failed:${this.label}`, STREAM_NEWS_INTERVAL_MS, "upstream.standing_stream_failed", fields)) {
+                logDetail("upstream.standing_stream_failed", fields);
             }
-            const contentType = res.headers.get("content-type") ?? "";
-            if (contentType.includes("text/event-stream") && res.body) {
-                void this.pumpSse(res.body, (_event, data) => this.dispatch(data)).catch(() => undefined);
+            this.scheduleStandingReopen();
+            return;
+        }
+        if (this.dead || controller.signal.aborted) {
+            res.body.destroy();
+            return;
+        }
+        const contentType = (res.header("content-type") ?? "").toLowerCase();
+        if (!res.ok || !contentType.includes("text/event-stream")) {
+            res.body.destroy();
+            logDetail("upstream.no_standing_stream", { server: this.label, status: res.status });
+            if (res.ok || res.status === 405) {
+                this.standingDown("unsupported");
             }
-            else if (this.transport !== "sse") {
-                const text = await res.text();
-                if (text.trim())
-                    this.dispatch(text);
-                // An empty body is a 202-style acknowledgement — normal for notifications.
+            else if (res.status >= 500 || res.status === 409 || res.status === 429) {
+                // Busy or briefly broken: ask again later.
+                this.standingDown();
+                this.standingDrops += 1;
+                this.scheduleStandingReopen();
             }
-            if (isInitialize)
-                void this.openStandingStream();
+            else {
+                // 4xx (a forgotten session among them): the next request's recovery
+                // re-initialises, and the new handshake opens it again.
+                this.standingDown();
+            }
+            return;
+        }
+        this.standing = "open";
+        const openedAt = Date.now();
+        let why = "ended";
+        try {
+            await readSseStream(res.body, (event) => {
+                if (event.id)
+                    this.standingLastEventId = event.id;
+                this.dispatchData(event.data);
+            }, {
+                maxEventBytes: this.maxMessageBytes,
+                onHandlerError: (err) => this.handlerFailed(err),
+                parser: (parser) => {
+                    this.standingParser = parser;
+                },
+            });
         }
         catch (err) {
-            if (this.abort.signal.aborted)
-                return;
-            const id = msg.id;
-            logLine("upstream.send_failed", { server: this.label, error: errText(err) });
-            if (id !== undefined && id !== null) {
-                this.accept({
-                    jsonrpc: "2.0",
-                    id: id,
-                    error: { code: -32000, message: `upstream unreachable: ${errText(err)}` },
-                });
-            }
+            why = errText(err);
+        }
+        const retryHint = this.standingParser?.retryMs;
+        this.standingParser = undefined;
+        if (this.dead || controller.signal.aborted)
+            return;
+        if (retryHint !== undefined)
+            this.standingRetryMs = Math.max(100, retryHint);
+        this.standingDown();
+        const lived = Date.now() - openedAt;
+        const healthy = lived >= this.healthyStreamMs;
+        this.standingDrops = healthy ? 0 : this.standingDrops + 1;
+        // A stream that stayed up and is simply re-opened is routine: a load
+        // balancer's idle cut ends it every minute or two for the whole session,
+        // and a stderr line each time is an error in the host's MCP log every
+        // minute. Detail. The first quick drop of a run is news, but once an hour
+        // per server at most: a server that closes every GET at once (some
+        // stateless deployments do) is re-opened every 30 s, and a cut that lands
+        // right on the threshold alternates between "healthy" and "quick".
+        const fields = { server: this.label, why, drops: this.standingDrops, livedMs: lived };
+        if (healthy ||
+            this.standingDrops > 1 ||
+            !logEvery(`upstream.standing_stream_ended:${this.label}`, STREAM_NEWS_INTERVAL_MS, "upstream.standing_stream_ended", fields)) {
+            logDetail("upstream.standing_stream_ended", fields);
         }
+        // After a recovery the new handshake has opened (or will open) its own.
+        if (this.sessionId === session)
+            this.scheduleStandingReopen();
+    }
+    /** The standing stream is not open: anything that was promised an answer on it gets one now. */
+    standingDown(state = "idle") {
+        this.standing = state;
+        for (const entry of [...this.outstanding.values()]) {
+            if (entry.onStandingStream)
+                this.answerError(entry, ANSWER.lost);
+        }
+    }
+    scheduleStandingReopen() {
+        if (this.dead || this.standingTimer)
+            return;
+        const base = this.standingRetryMs ?? this.reconnectBaseMs * 2;
+        const delay = Math.min(MAX_RECONNECT_DELAY_MS, base * 2 ** Math.min(this.standingDrops, 10));
+        this.standingTimer = setTimeout(() => {
+            this.standingTimer = undefined;
+            void this.openStandingStream();
+        }, delay);
+        this.standingTimer.unref?.();
+    }
+    /** A new session is starting: the old standing stream belongs to the old one. */
+    resetStandingStream() {
+        this.standingAbort?.abort();
+        clearTimeout(this.standingTimer);
+        this.standingTimer = undefined;
+        this.standingLastEventId = undefined;
+        this.standingDrops = 0;
+        // A server that has no standing stream will not grow one with a new session.
+        this.standingDown(this.standing === "unsupported" ? "unsupported" : "idle");
+    }
+    // ── plumbing ──────────────────────────────────────────────────────────────
+    call(method, url, headers, body, signal) {
+        return httpRequest(url, {
+            method,
+            headers,
+            body,
+            signal,
+            connectTimeoutMs: this.socketConnectTimeoutMs,
+            agents: this.agents,
+        });
+    }
+    sessionHeaders(isInitialize) {
+        if (this.transport !== "http")
+            return {};
+        const out = {};
+        if (this.sessionId)
+            out["mcp-session-id"] = this.sessionId;
+        // The spec (2025-06-18) asks for the negotiated version on every request
+        // after the handshake; the MCP SDK sends it, so a server may rely on it.
+        if (this.protocolVersion && !isInitialize)
+            out["mcp-protocol-version"] = this.protocolVersion;
+        return out;
+    }
+    /**
+     * A network failure with a proxy configured that this process cannot use is
+     * the likeliest cause; say so once in the audit log (`bir doctor` reads it).
+     */
+    proxyHint() {
+        if (!configuredProxy())
+            return;
+        const enabled = proxyEnvEnabled();
+        if (enabled && nodeSupportsProxyEnv())
+            return;
+        logOnce("upstream.proxy_env_ignored", "upstream.proxy_env_ignored", {
+            server: this.label,
+            node: process.versions.node,
+            reason: enabled
+                ? "HTTPS_PROXY is set but this Node cannot route through it (needs Node 24.5+ or 22.21+)"
+                : "HTTPS_PROXY is set but BIR_UPSTREAM_PROXY_ENV=0",
+        });
     }
     close() {
         if (this.dead)
             return;
+        const sessionId = this.transport === "http" ? this.sessionId : undefined;
         this.closed({});
-        this.abort.abort();
+        this.teardown(sessionId);
+    }
+    /** Stop every timer, stream and request; end the server-side session if there is one. */
+    teardown(sessionId) {
+        clearTimeout(this.reconnectTimer);
+        clearTimeout(this.standingTimer);
+        this.reconnectTimer = undefined;
+        this.standingTimer = undefined;
+        for (const controller of this.inflight)
+            controller.abort();
+        for (const entry of this.outstanding.values())
+            entry.abort.abort();
+        this.inflight.clear();
+        this.outstanding.clear();
+        this.streamAbort?.abort();
+        this.standingAbort?.abort();
+        for (const waiter of this.internalWaiters.values())
+            waiter(undefined);
+        this.internalWaiters.clear();
+        if (!sessionId) {
+            destroyAgents(this.agents);
+            return;
+        }
+        // The spec's session DELETE lets the server free our session now rather
+        // than at its own idle timeout. Best effort, one second, never an error.
+        const headers = { "mcp-session-id": sessionId, ...this.headers };
+        if (this.protocolVersion)
+            headers["mcp-protocol-version"] = this.protocolVersion;
+        httpRequest(this.url, {
+            method: "DELETE",
+            headers,
+            signal: AbortSignal.timeout(DELETE_TIMEOUT_MS),
+            connectTimeoutMs: DELETE_TIMEOUT_MS,
+            agents: this.agents,
+        })
+            .then((res) => {
+            res.body.resume();
+            logDetail("upstream.session_deleted", { server: this.label, status: res.status });
+        }, () => undefined)
+            .finally(() => destroyAgents(this.agents));
     }
 }
 /**