@basein/runner 0.2.12 → 0.3.0

package/dist/upstream/http-transport.d.ts

@@ -0,0 +1,143 @@
+/**
+ * http-transport — the one HTTP primitive the remote upstream (http-client.ts)
+ * sends through. Built on `node:http` / `node:https`, not on `fetch`.
+ *
+ * WHY NOT FETCH. Node's fetch runs on a global undici dispatcher whose defaults
+ * are a 300 s headers timeout and a 300 s body-idle timeout, and nothing short
+ * of a dependency (or a Node-internal symbol) changes them per request. Both cut
+ * off legitimate MCP traffic:
+ *
+ *   - a remote tool that works for more than five minutes before answering (a
+ *     report, a build, a crawl) was reported at 306 s as `upstream unreachable:
+ *     fetch failed`, however long the user had told Claude Code to wait;
+ *   - an SSE stream with nothing to say for five minutes (the legacy transport's
+ *     event stream, the standing GET, a slow tool's reply stream) was
+ *     terminated, which on the legacy transport killed the server for the rest
+ *     of the session.
+ *
+ * `node:http` has no implicit timeouts at all, so the bounds here are exactly
+ * the ones we choose:
+ *
+ *   - **connect**: DNS + TCP + TLS (+ a proxy tunnel) must finish within
+ *     `connectTimeoutMs`, so a blackholed or captive host fails in seconds
+ *     rather than after the OS connect timeout (21 s on Windows, 75 s on macOS);
+ *   - **after connect, none**: how long an answer may take is the host's call
+ *     (Claude Code's own tool timeouts, and its `notifications/cancelled`), never
+ *     ours. Dead peers are still noticed: sockets get TCP keep-alive probes.
+ *   - **idle in the pool**: a keep-alive socket nobody is using is closed after
+ *     4 s, or 1 s before the server's `Keep-Alive: timeout=N`, as undici did —
+ *     so we never reuse one the server is in the middle of closing.
+ *
+ * It also makes the failure reason concrete. fetch reports every network error
+ * as `fetch failed` and hides the cause; here the message is the socket's own
+ * (`connect ECONNREFUSED …`, `getaddrinfo ENOTFOUND …`, `self-signed
+ * certificate in certificate chain`), which is what a user or `bir doctor`
+ * needs to act on.
+ *
+ * WHAT FETCH DID THAT IS KEPT: redirects are followed (307/308 for any method,
+ * 301/302/303 for GET — Starlette answers `/mcp` with a 307 to `/mcp/`); a
+ * gzip/deflate/br body is decoded; `User-Agent: node` is sent, so a WAF rule
+ * written against the old client still matches. Compression is not *asked*
+ * for (no `Accept-Encoding`): an SSE reply behind a compressing middleware can
+ * sit in its buffer, and MCP messages are small.
+ *
+ * WHAT IS STRICTER THAN FETCH: the user's headers stay with the origin they
+ * were configured for. fetch drops only `Authorization`, `Cookie` and
+ * `Proxy-Authorization` when a redirect leaves the origin, but a remote
+ * server's credential is as often `X-Api-Key`, `Private-Token` or a tenancy
+ * header — so a redirect to another origin carries only the MCP protocol's own
+ * headers ({@link CROSS_ORIGIN_KEPT}), and every header that came from
+ * `BIR_UPSTREAM_HEADERS` or `--header` is dropped. And a redirect from https to
+ * plain http is refused outright (a loopback target excepted: it never leaves
+ * the machine): following it would send the request — the tool call, its
+ * arguments, the session id — in clear text.
+ *
+ * PROXIES (HTTPS_PROXY / HTTP_PROXY / NO_PROXY). Claude Code honours them, so a
+ * server it could reach through a corporate proxy must stay reachable once
+ * wrapped. The agents are built with `proxyEnv: process.env`, which Node's own
+ * http stack implements from Node 24.5 (and the 22.x line from 22.21); older
+ * Nodes ignore the option and connect directly — `upstream.proxy_env_ignored`
+ * in the audit log says so when that is the likely cause of a failure.
+ * Loopback targets (`localhost`, 127.0.0.0/8, ::1) always connect directly:
+ * Node's proxyEnv would tunnel them to the proxy unless NO_PROXY lists them,
+ * and a proxy can never reach the user's own machine — a local server that
+ * worked before must not break because a proxy variable is set. A proxy
+ * variable Node refuses as malformed is ignored (`upstream.proxy_env_invalid`),
+ * as fetch ignored them all: a bad variable must not break a server.
+ * `BIR_UPSTREAM_PROXY_ENV=0` turns it off (the old behaviour: always connect directly).
+ */
+import * as http from "node:http";
+import * as https from "node:https";
+import type { IncomingHttpHeaders } from "node:http";
+import { type Readable } from "node:stream";
+/** Keep-alive agents per upstream, so `close()` can drop its sockets. */
+export interface Agents {
+    /** May route through HTTP(S)_PROXY (see the header). */
+    http: http.Agent;
+    https: https.Agent;
+    /** Never proxied: for loopback targets. The same objects when proxying is off. */
+    directHttp: http.Agent;
+    directHttps: https.Agent;
+}
+/** `localhost`, `*.localhost`, 127.0.0.0/8, ::1 and 0.0.0.0 — this machine. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** Does this environment ask for the proxy variables to be honoured? */
+export declare function proxyEnvEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Node versions whose `http.Agent` implements `proxyEnv`. */
+export declare function nodeSupportsProxyEnv(version?: string): boolean;
+/** The proxy URL a request would go through, when one is configured. */
+export declare function configuredProxy(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * How long a pooled keep-alive socket may sit idle before we close it: undici's
+ * default, i.e. what the old fetch path did.
+ */
+export declare const DEFAULT_FREE_SOCKET_TIMEOUT_MS = 4000;
+export interface AgentOptions {
+    /** Honour HTTP(S)_PROXY / NO_PROXY. Default: {@link proxyEnvEnabled}. */
+    proxyEnv?: boolean;
+    /** Idle time after which a pooled socket is closed. Default {@link DEFAULT_FREE_SOCKET_TIMEOUT_MS}. */
+    freeSocketTimeoutMs?: number;
+}
+export declare function createAgents(opts?: AgentOptions): Agents;
+/** `http://user:secret@proxy` → `http://***@proxy`, anywhere in a message. */
+export declare function redactCredentials(text: string): string;
+export declare function destroyAgents(agents: Agents): void;
+export interface HttpRequestOptions {
+    method: "GET" | "POST" | "DELETE";
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    /** Bound on DNS + TCP + TLS (+ proxy tunnel). Nothing bounds the answer. */
+    connectTimeoutMs: number;
+    agents: Agents;
+}
+export interface HttpResponse {
+    status: number;
+    statusText: string;
+    ok: boolean;
+    headers: IncomingHttpHeaders;
+    /** The URL that answered, after redirects. */
+    url: string;
+    /** The body, already decompressed. Consume it, or `destroy()` it. */
+    body: Readable;
+    header(name: string): string | undefined;
+}
+/** Raised by {@link readBodyText} when a body outgrows its cap. */
+export declare class BodyTooLargeError extends Error {
+    constructor(limit: number);
+}
+/**
+ * Where a redirect from `current` to `next` may go, and with which headers.
+ * Throws when it may not be followed at all: a scheme other than http(s), or
+ * a step down from https to plain http off this machine. Exported for tests.
+ */
+export declare function redirectHeaders(current: URL, next: URL, headers: Record<string, string>): Record<string, string>;
+/**
+ * Send one request and resolve with the response head once it arrives. Rejects
+ * on a network error, a connect timeout, an abort, or a redirect that may not
+ * be followed ({@link redirectHeaders}). Follows the others.
+ */
+export declare function httpRequest(url: string, opts: HttpRequestOptions): Promise<HttpResponse>;
+/** Read a whole body as UTF-8, refusing past `maxBytes` (the body is destroyed). */
+export declare function readBodyText(body: Readable, maxBytes: number): Promise<string>;
+//# sourceMappingURL=http-transport.d.ts.map

package/dist/upstream/http-transport.js

@@ -0,0 +1,391 @@
+/**
+ * http-transport — the one HTTP primitive the remote upstream (http-client.ts)
+ * sends through. Built on `node:http` / `node:https`, not on `fetch`.
+ *
+ * WHY NOT FETCH. Node's fetch runs on a global undici dispatcher whose defaults
+ * are a 300 s headers timeout and a 300 s body-idle timeout, and nothing short
+ * of a dependency (or a Node-internal symbol) changes them per request. Both cut
+ * off legitimate MCP traffic:
+ *
+ *   - a remote tool that works for more than five minutes before answering (a
+ *     report, a build, a crawl) was reported at 306 s as `upstream unreachable:
+ *     fetch failed`, however long the user had told Claude Code to wait;
+ *   - an SSE stream with nothing to say for five minutes (the legacy transport's
+ *     event stream, the standing GET, a slow tool's reply stream) was
+ *     terminated, which on the legacy transport killed the server for the rest
+ *     of the session.
+ *
+ * `node:http` has no implicit timeouts at all, so the bounds here are exactly
+ * the ones we choose:
+ *
+ *   - **connect**: DNS + TCP + TLS (+ a proxy tunnel) must finish within
+ *     `connectTimeoutMs`, so a blackholed or captive host fails in seconds
+ *     rather than after the OS connect timeout (21 s on Windows, 75 s on macOS);
+ *   - **after connect, none**: how long an answer may take is the host's call
+ *     (Claude Code's own tool timeouts, and its `notifications/cancelled`), never
+ *     ours. Dead peers are still noticed: sockets get TCP keep-alive probes.
+ *   - **idle in the pool**: a keep-alive socket nobody is using is closed after
+ *     4 s, or 1 s before the server's `Keep-Alive: timeout=N`, as undici did —
+ *     so we never reuse one the server is in the middle of closing.
+ *
+ * It also makes the failure reason concrete. fetch reports every network error
+ * as `fetch failed` and hides the cause; here the message is the socket's own
+ * (`connect ECONNREFUSED …`, `getaddrinfo ENOTFOUND …`, `self-signed
+ * certificate in certificate chain`), which is what a user or `bir doctor`
+ * needs to act on.
+ *
+ * WHAT FETCH DID THAT IS KEPT: redirects are followed (307/308 for any method,
+ * 301/302/303 for GET — Starlette answers `/mcp` with a 307 to `/mcp/`); a
+ * gzip/deflate/br body is decoded; `User-Agent: node` is sent, so a WAF rule
+ * written against the old client still matches. Compression is not *asked*
+ * for (no `Accept-Encoding`): an SSE reply behind a compressing middleware can
+ * sit in its buffer, and MCP messages are small.
+ *
+ * WHAT IS STRICTER THAN FETCH: the user's headers stay with the origin they
+ * were configured for. fetch drops only `Authorization`, `Cookie` and
+ * `Proxy-Authorization` when a redirect leaves the origin, but a remote
+ * server's credential is as often `X-Api-Key`, `Private-Token` or a tenancy
+ * header — so a redirect to another origin carries only the MCP protocol's own
+ * headers ({@link CROSS_ORIGIN_KEPT}), and every header that came from
+ * `BIR_UPSTREAM_HEADERS` or `--header` is dropped. And a redirect from https to
+ * plain http is refused outright (a loopback target excepted: it never leaves
+ * the machine): following it would send the request — the tool call, its
+ * arguments, the session id — in clear text.
+ *
+ * PROXIES (HTTPS_PROXY / HTTP_PROXY / NO_PROXY). Claude Code honours them, so a
+ * server it could reach through a corporate proxy must stay reachable once
+ * wrapped. The agents are built with `proxyEnv: process.env`, which Node's own
+ * http stack implements from Node 24.5 (and the 22.x line from 22.21); older
+ * Nodes ignore the option and connect directly — `upstream.proxy_env_ignored`
+ * in the audit log says so when that is the likely cause of a failure.
+ * Loopback targets (`localhost`, 127.0.0.0/8, ::1) always connect directly:
+ * Node's proxyEnv would tunnel them to the proxy unless NO_PROXY lists them,
+ * and a proxy can never reach the user's own machine — a local server that
+ * worked before must not break because a proxy variable is set. A proxy
+ * variable Node refuses as malformed is ignored (`upstream.proxy_env_invalid`),
+ * as fetch ignored them all: a bad variable must not break a server.
+ * `BIR_UPSTREAM_PROXY_ENV=0` turns it off (the old behaviour: always connect directly).
+ */
+import * as http from "node:http";
+import * as https from "node:https";
+import { pipeline } from "node:stream";
+import { constants as zlib, createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+import { errText, logOnce } from "../util/log.js";
+/** `localhost`, `*.localhost`, 127.0.0.0/8, ::1 and 0.0.0.0 — this machine. */
+export function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "::1" ||
+        host === "0.0.0.0" ||
+        /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host));
+}
+/** Does this environment ask for the proxy variables to be honoured? */
+export function proxyEnvEnabled(env = process.env) {
+    const flag = env.BIR_UPSTREAM_PROXY_ENV?.trim().toLowerCase();
+    return !(flag === "0" || flag === "false" || flag === "off" || flag === "no");
+}
+/** Node versions whose `http.Agent` implements `proxyEnv`. */
+export function nodeSupportsProxyEnv(version = process.versions.node) {
+    const [major, minor] = version.split(".").map((n) => Number(n));
+    if (major > 24)
+        return true;
+    if (major === 24)
+        return minor >= 5;
+    if (major === 22)
+        return minor >= 21;
+    return false;
+}
+/** The proxy URL a request would go through, when one is configured. */
+export function configuredProxy(env = process.env) {
+    return env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy || undefined;
+}
+/**
+ * How long a pooled keep-alive socket may sit idle before we close it: undici's
+ * default, i.e. what the old fetch path did.
+ */
+export const DEFAULT_FREE_SOCKET_TIMEOUT_MS = 4_000;
+export function createAgents(opts = {}) {
+    const direct = {
+        keepAlive: true,
+        // Not a timeout on requests: the delay before the first TCP keep-alive probe
+        // on an idle socket, which is how a vanished peer (laptop sleep, a dropped
+        // NAT entry) turns into an error instead of a stream that never ends.
+        keepAliveMsecs: 15_000,
+        // Not a timeout on requests either. On an http.Agent `timeout` only ever
+        // destroys a socket that is idle *in the pool* (an in-use socket's timeout
+        // just emits an event nobody listens to), and it is what lets the agent
+        // honour a server's `Keep-Alive: timeout=N` (it closes at the lower of this
+        // and N - 1 s). Without it an idle socket is kept until the server or its
+        // load balancer closes it — and a POST that reuses a socket in the instant
+        // the server is closing it dies with ECONNRESET: a tool call that fails
+        // because of the runner (POSTs are not retried, see sendOnce). undici, which
+        // the old fetch path used, closes idle sockets after 4 s for the same reason.
+        timeout: opts.freeSocketTimeoutMs ?? DEFAULT_FREE_SOCKET_TIMEOUT_MS,
+    };
+    const directHttp = new http.Agent(direct);
+    const directHttps = new https.Agent(direct);
+    if (!(opts.proxyEnv ?? proxyEnvEnabled())) {
+        return { http: directHttp, https: directHttps, directHttp, directHttps };
+    }
+    // `proxyEnv` is newer than the @types/node this package builds against, and
+    // unknown to Node < 22.21, which ignores it — hence the untyped options bag.
+    const proxied = { ...direct, proxyEnv: process.env };
+    try {
+        return {
+            http: new http.Agent(proxied),
+            https: new https.Agent(proxied),
+            directHttp,
+            directHttps,
+        };
+    }
+    catch (err) {
+        // A malformed proxy variable (`http://`, `http://:3128`, a port out of
+        // range, an unencoded `%` in a password) makes Node's Agent throw — which,
+        // uncaught, took bir-proxy down at start and showed the wrapped server as
+        // failed in every session, even a loopback one that never uses a proxy.
+        // fetch used to ignore these variables, so ignoring a broken one is the old
+        // behaviour; the audit log says so (`bir doctor` reads it). The message can
+        // carry the proxy URL, credentials included, hence the redaction.
+        logOnce("upstream.proxy_env_invalid", "upstream.proxy_env_invalid", {
+            reason: redactCredentials(errText(err)),
+            effect: "the proxy variables are ignored; upstreams are reached directly",
+        });
+        return { http: directHttp, https: directHttps, directHttp, directHttps };
+    }
+}
+/** `http://user:secret@proxy` → `http://***@proxy`, anywhere in a message. */
+export function redactCredentials(text) {
+    return text.replace(/\/\/[^/@\s]*@/g, "//***@");
+}
+export function destroyAgents(agents) {
+    for (const agent of new Set([agents.http, agents.https, agents.directHttp, agents.directHttps])) {
+        agent.destroy();
+    }
+}
+/** Raised by {@link readBodyText} when a body outgrows its cap. */
+export class BodyTooLargeError extends Error {
+    constructor(limit) {
+        super(`response body exceeded ${limit} bytes`);
+        this.name = "BodyTooLargeError";
+    }
+}
+const MAX_REDIRECTS = 10;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+/**
+ * The only headers a redirect carries to another origin: the ones the MCP
+ * protocol itself puts on a request, which say nothing about the user. The
+ * session id is among them because the server that answered with the
+ * redirect is the one that issued it. Everything else — every header from
+ * `BIR_UPSTREAM_HEADERS` or `--header`, whatever its name — is dropped.
+ */
+const CROSS_ORIGIN_KEPT = new Set([
+    "accept",
+    "content-type",
+    "last-event-id",
+    "mcp-protocol-version",
+    "mcp-session-id",
+]);
+/**
+ * Where a redirect from `current` to `next` may go, and with which headers.
+ * Throws when it may not be followed at all: a scheme other than http(s), or
+ * a step down from https to plain http off this machine. Exported for tests.
+ */
+export function redirectHeaders(current, next, headers) {
+    if (next.protocol !== "http:" && next.protocol !== "https:") {
+        throw new Error(`redirected to an unsupported URL scheme (${next.protocol})`);
+    }
+    if (current.protocol === "https:" && next.protocol === "http:" && !isLoopbackHost(next.hostname)) {
+        throw new Error(`refused a redirect from https to plain http (${next.host})`);
+    }
+    if (next.origin === current.origin)
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => CROSS_ORIGIN_KEPT.has(key.toLowerCase())));
+}
+/**
+ * Send one request and resolve with the response head once it arrives. Rejects
+ * on a network error, a connect timeout, an abort, or a redirect that may not
+ * be followed ({@link redirectHeaders}). Follows the others.
+ */
+export async function httpRequest(url, opts) {
+    let current = new URL(url);
+    let headers = { ...opts.headers };
+    for (let hop = 0;; hop += 1) {
+        const res = await sendOnce(current, headers, opts, false);
+        const status = res.statusCode ?? 0;
+        const location = res.headers.location;
+        const followable = status === 307 || status === 308 || (opts.method === "GET" && REDIRECTS.has(status));
+        if (location && followable && hop < MAX_REDIRECTS) {
+            res.resume();
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                throw new Error("redirected to an invalid URL");
+            }
+            // Once dropped, a header stays dropped: a later hop back to the first
+            // origin does not bring it back (as fetch does it).
+            headers = redirectHeaders(current, next, headers);
+            current = next;
+            continue;
+        }
+        return wrap(res, current);
+    }
+}
+function sendOnce(url, headers, opts, isRetry) {
+    return new Promise((resolve, reject) => {
+        const signal = opts.signal;
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const isHttps = url.protocol === "https:";
+        if (!isHttps && url.protocol !== "http:") {
+            reject(new Error(`unsupported URL scheme (${url.protocol})`));
+            return;
+        }
+        const payload = opts.body === undefined ? undefined : Buffer.from(opts.body, "utf8");
+        const allHeaders = { "user-agent": "node", ...headers };
+        if (payload)
+            allHeaders["content-length"] = String(payload.length);
+        let req;
+        try {
+            req = (isHttps ? https : http).request(url, {
+                method: opts.method,
+                headers: allHeaders,
+                agent: agentFor(url, opts.agents),
+            });
+        }
+        catch (err) {
+            // An invalid header value (a newline in a pasted token) throws here.
+            reject(err);
+            return;
+        }
+        let settled = false;
+        let response;
+        // Aborted by hand rather than with http.request's own `signal`: that
+        // destroys the socket even when the exchange has just completed, and a
+        // keep-alive socket on its way back to the pool has no error listener in
+        // that instant — an uncaught error that would take the proxy down. Here an
+        // abort only ever tears down an exchange that is still going.
+        const onAbort = () => {
+            if (!response)
+                req.destroy(abortError());
+            else if (!response.complete)
+                response.destroy();
+        };
+        const release = () => signal?.removeEventListener("abort", onAbort);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(() => {
+            const err = new Error(`connect timed out after ${opts.connectTimeoutMs} ms (${url.host})`);
+            err.code = "ETIMEDOUT";
+            req.destroy(err);
+        }, opts.connectTimeoutMs);
+        timer.unref?.();
+        const connected = () => clearTimeout(timer);
+        req.on("socket", (socket) => {
+            socket.setKeepAlive?.(true, 15_000);
+            // A pooled socket is already connected; a fresh one says when it is.
+            if (!socket.connecting)
+                connected();
+            else
+                socket.once(isHttps ? "secureConnect" : "connect", connected);
+        });
+        // The request is on the wire, so the connection exists — covers transports
+        // (a proxy tunnel) whose socket does not emit the events above.
+        req.on("finish", connected);
+        req.on("response", (res) => {
+            connected();
+            settled = true;
+            response = res;
+            res.once("close", release);
+            resolve(res);
+        });
+        req.on("error", (err) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            release();
+            // The keep-alive race: the server closed an idle pooled socket just as we
+            // reused it. One retry on a fresh socket — the pattern Node's own
+            // documentation gives for `reusedSocket` — but only for GET and DELETE:
+            // a POST may be a tool call the server did receive before the reset, and
+            // running it twice is worse than one "socket hang up" (undici, which the
+            // old fetch path used, does not retry POSTs either). What keeps POSTs out
+            // of this race is the agents' idle timeout (createAgents).
+            if (!isRetry &&
+                opts.method !== "POST" &&
+                req.reusedSocket &&
+                err.code === "ECONNRESET" &&
+                !signal?.aborted) {
+                sendOnce(url, headers, opts, true).then(resolve, reject);
+                return;
+            }
+            reject(signal?.aborted ? abortError() : err);
+        });
+        req.end(payload);
+    });
+}
+function agentFor(url, agents) {
+    const direct = isLoopbackHost(url.hostname);
+    if (url.protocol === "https:")
+        return direct ? agents.directHttps : agents.https;
+    return direct ? agents.directHttp : agents.http;
+}
+function abortError() {
+    const err = new Error("request aborted");
+    err.name = "AbortError";
+    return err;
+}
+function wrap(res, url) {
+    const status = res.statusCode ?? 0;
+    const encoding = String(res.headers["content-encoding"] ?? "").trim().toLowerCase();
+    let body = res;
+    const decoder = encoding === "gzip" || encoding === "x-gzip"
+        ? createGunzip({ flush: zlib.Z_SYNC_FLUSH, finishFlush: zlib.Z_SYNC_FLUSH })
+        : encoding === "deflate"
+            ? createInflate({ flush: zlib.Z_SYNC_FLUSH, finishFlush: zlib.Z_SYNC_FLUSH })
+            : encoding === "br"
+                ? createBrotliDecompress({
+                    flush: zlib.BROTLI_OPERATION_FLUSH,
+                    finishFlush: zlib.BROTLI_OPERATION_FLUSH,
+                })
+                : undefined;
+    if (decoder) {
+        // pipeline() carries an error on either side to the other, so a reset
+        // mid-body still surfaces to whoever reads the decoded stream.
+        pipeline(res, decoder, () => undefined);
+        body = decoder;
+    }
+    return {
+        status,
+        statusText: res.statusMessage ?? "",
+        ok: status >= 200 && status < 300,
+        headers: res.headers,
+        url: url.toString(),
+        body,
+        header(name) {
+            const value = res.headers[name.toLowerCase()];
+            return Array.isArray(value) ? value.join(", ") : value;
+        },
+    };
+}
+/** Read a whole body as UTF-8, refusing past `maxBytes` (the body is destroyed). */
+export async function readBodyText(body, maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of body) {
+        const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        size += buf.length;
+        if (size > maxBytes) {
+            body.destroy();
+            throw new BodyTooLargeError(maxBytes);
+        }
+        chunks.push(buf);
+    }
+    const text = Buffer.concat(chunks, size).toString("utf8");
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+//# sourceMappingURL=http-transport.js.map

package/dist/upstream/lazy-client.d.ts

@@ -26,6 +26,14 @@ export declare class LazyUpstreamClient extends BaseUpstreamClient {
     constructor(create: () => UpstreamClient);
     private ensure;
     send(msg: JsonRpcMessage): void;
+    /**
+     * Proxy-originated calls go to the inner client, which owns their `bir:` ids:
+     * its `accept()` consumes the answer before this wrapper would ever see it,
+     * so a request tracked *here* would wait forever (the replay work loop did,
+     * for its full step timeout, on every `--lazy` server).
+     */
+    request(method: string, params?: unknown, signal?: AbortSignal): Promise<unknown>;
     close(): void;
+    shutdown(graceMs?: number): Promise<void>;
 }
 //# sourceMappingURL=lazy-client.d.ts.map

package/dist/upstream/lazy-client.js

@@ -15,7 +15,7 @@
  * The flag is opt-in for exactly that reason, and this comment is the measurement
  * the open question asks for: the saving is a property of the host, not of us.
  */
-import { BaseUpstreamClient } from "./client.js";
+import { BaseUpstreamClient, } from "./client.js";
 export class LazyUpstreamClient extends BaseUpstreamClient {
     ready;
     inner;
@@ -29,6 +29,9 @@ export class LazyUpstreamClient extends BaseUpstreamClient {
             this.resolveReady = resolve;
             this.rejectReady = reject;
         });
+        // Nobody may ever speak to a lazy upstream; an unobserved rejection of
+        // `ready` must not become an unhandled rejection.
+        this.ready.catch(() => undefined);
     }
     ensure() {
         if (this.inner)
@@ -37,6 +40,8 @@ export class LazyUpstreamClient extends BaseUpstreamClient {
         this.inner = inner;
         inner.onMessage((msg) => this.accept(msg));
         inner.onClose((info) => this.closed(info));
+        inner.onUndeliverable?.((info) => this.undeliverable(info));
+        inner.onRestart?.((info) => this.restarting(info));
         inner.ready.then(() => this.resolveReady(), (err) => this.rejectReady(err instanceof Error ? err : new Error(String(err))));
         return inner;
     }
@@ -45,9 +50,32 @@ export class LazyUpstreamClient extends BaseUpstreamClient {
             return;
         this.ensure().send(msg);
     }
+    /**
+     * Proxy-originated calls go to the inner client, which owns their `bir:` ids:
+     * its `accept()` consumes the answer before this wrapper would ever see it,
+     * so a request tracked *here* would wait forever (the replay work loop did,
+     * for its full step timeout, on every `--lazy` server).
+     */
+    request(method, params, signal) {
+        if (this.dead)
+            return Promise.reject(new Error("upstream is not available"));
+        // Refused here, before `ensure()`: a call nobody is waiting for must not
+        // be what starts the user's server.
+        if (signal?.aborted)
+            return Promise.reject(new Error(`${method} aborted`));
+        return this.ensure().request(method, params, signal);
+    }
     close() {
         this.inner?.close();
         this.closed({});
     }
+    async shutdown(graceMs) {
+        const inner = this.inner;
+        if (inner?.shutdown)
+            await inner.shutdown(graceMs);
+        else
+            inner?.close();
+        this.closed({});
+    }
 }
 //# sourceMappingURL=lazy-client.js.map