tinyfish-mcp-lite 0.0.0-stage → 0.2.0

package/dist/core/errors.js

@@ -0,0 +1,214 @@
+/**
+ * Typed transport-level errors thrown by the proxy core, plus the only
+ * client-facing shaping functions: `toJsonRpcError` for pre-stream failures
+ * and `toStreamErrorFrame` for failures after an SSE relay started. Every
+ * adapter catch path routes through these two functions — no ad-hoc error
+ * bodies anywhere else, with exactly two deliberate exceptions: the adapter's
+ * ParseError reply (http/adapter.ts — built where the unparseable body is
+ * caught, since there is nothing to route), and the last-resort -32603
+ * backstop in http/index.ts's invokeSafely. Messages must never contain the
+ * API key (they describe network/protocol conditions only).
+ *
+ * HTTP status decision for locally shaped errors: the hosted server maps
+ * client-error JSON-RPC codes to HTTP 400 and everything else to 500. The
+ * proxy mirrors the 400 for client errors (-32700 ParseError) and picks
+ * **502 Bad Gateway** for the upstream-leg failures it shapes itself (-32000
+ * unreachable/stream-failed, -32001 auth rejection): the proxy is healthy,
+ * the upstream hop failed — distinguishing these from a genuine local proxy
+ * bug, which stays **500** with -32603 InternalError. Upstream-originated
+ * JSON-RPC errors are never shaped at all: they forward verbatim under
+ * upstream's own HTTP status.
+ */
+/** JSON-RPC error codes used by locally shaped errors. */
+export const JsonRpcErrorCodes = {
+    /** Upstream unreachable / upstream stream failed (server-side, HTTP 502). */
+    UpstreamUnavailable: -32000,
+    /** Upstream rejected auth — check TINYFISH_API_KEY (HTTP 502). */
+    UpstreamAuth: -32001,
+    /** Local proxy bug (HTTP 500). */
+    InternalError: -32603,
+    /** Malformed client JSON (HTTP 400, id -1 — mirrors upstream). */
+    ParseError: -32700,
+};
+/** Base class for all proxy-core errors (transport level, not JSON-RPC). */
+export class ProxyCoreError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** The upstream server could not be reached (DNS, TLS, refused, reset). */
+export class UpstreamUnreachableError extends ProxyCoreError {
+    /** Upstream "host[:port]" when known — used in the client-facing message. */
+    host;
+}
+/**
+ * Upstream answered 401/403 with a body that is NOT a JSON-RPC message (a
+ * JSON-RPC error body, whatever its HTTP status, forwards verbatim instead).
+ * Carries the upstream status and body text so the shaped
+ * client error can include them as diagnostics. The body text is truncated to
+ * ~2KB at construction; the Error message itself never includes it.
+ */
+export class UpstreamAuthError extends ProxyCoreError {
+    status;
+    /** Upstream response body text, truncated to AUTH_BODY_LIMIT chars. */
+    bodyText;
+    constructor(status, bodyText, options) {
+        super(`Upstream rejected the request as unauthorized (HTTP ${status})`, options);
+        this.status = status;
+        this.bodyText = bodyText.slice(0, AUTH_BODY_LIMIT);
+    }
+}
+/**
+ * ~2KB cap on the upstream auth-failure body relayed in error data.
+ *
+ * Measured in UTF-16 code units (String.prototype.slice), not bytes: for
+ * multi-byte scripts the UTF-8 wire size can reach ~3× (≤ ~6KB) — bounded
+ * either way, which is all the "~2KB" contract promises. A slice boundary can
+ * split a surrogate pair; harmless, since Node's well-formed JSON.stringify
+ * escapes the lone surrogate and the response stays valid JSON.
+ */
+export const AUTH_BODY_LIMIT = 2048;
+/**
+ * Delivering a relayed SSE frame to the LOCAL client failed (the transport's
+ * onEvent callback rejected — e.g. the client socket died mid-write). This is
+ * a client-side condition, never an upstream one: it must not be logged or
+ * classified as "Upstream unreachable".
+ */
+export class LocalWriteError extends ProxyCoreError {
+}
+/** An in-flight upstream request was aborted locally (session close / shutdown). */
+export class UpstreamAbortedError extends ProxyCoreError {
+}
+/**
+ * Upstream answered with something the core cannot interpret (non-JSON body,
+ * SSE stream that ends without a final response frame, unexpected empty body).
+ */
+export class UpstreamProtocolError extends ProxyCoreError {
+    /** Upstream HTTP status when one was received before the failure. */
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+    }
+}
+/** True for the AbortError DOMException fetch throws when its signal fires. */
+export function isAbortError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "name" in err &&
+        err.name === "AbortError");
+}
+/**
+ * Map a failure the upstream never answered (or answered unusably) to the
+ * client-facing JSON-RPC error + local HTTP status.
+ * Only failures upstream never saw as JSON-RPC get shaped here —
+ * upstream JSON-RPC errors forward verbatim and never reach this function.
+ * Never includes the API key: transport-error messages describe network and
+ * protocol conditions only, and unexpected local errors get a generic message
+ * (their stack goes to stderr at the catch site, not to the client).
+ */
+export function toJsonRpcError(failure, requestId) {
+    const id = requestId ?? null;
+    if (failure instanceof UpstreamAuthError) {
+        return {
+            httpStatus: 502,
+            body: {
+                jsonrpc: "2.0",
+                error: {
+                    code: JsonRpcErrorCodes.UpstreamAuth,
+                    message: `Upstream rejected the request (HTTP ${failure.status}) — ` +
+                        `check that TINYFISH_API_KEY is set to a valid TinyFish API key`,
+                    data: { upstreamStatus: failure.status, upstreamBody: failure.bodyText },
+                },
+                id,
+            },
+        };
+    }
+    if (failure instanceof UpstreamUnreachableError) {
+        const host = failure.host ?? "the upstream server";
+        return {
+            httpStatus: 502,
+            body: {
+                jsonrpc: "2.0",
+                error: {
+                    code: JsonRpcErrorCodes.UpstreamUnavailable,
+                    message: `cannot reach ${host} — check your network; ` +
+                        `the hosted MCP server may also be temporarily unavailable`,
+                },
+                id,
+            },
+        };
+    }
+    if (failure instanceof ProxyCoreError) {
+        // Remaining core classifications (protocol violation, local abort): the
+        // upstream leg failed but the proxy is healthy — same 502 / -32000 shape,
+        // with the classified message (never contains the key or body internals).
+        return {
+            httpStatus: 502,
+            body: {
+                jsonrpc: "2.0",
+                error: { code: JsonRpcErrorCodes.UpstreamUnavailable, message: failure.message },
+                id,
+            },
+        };
+    }
+    // Local proxy bug: generic message only; the stack goes to stderr.
+    return {
+        httpStatus: 500,
+        body: {
+            jsonrpc: "2.0",
+            error: { code: JsonRpcErrorCodes.InternalError, message: "Internal error" },
+            id,
+        },
+    };
+}
+/**
+ * Build the final SSE-framed JSON-RPC error for a failure AFTER the local SSE
+ * relay started (mid-stream upstream disconnect). A
+ * tools/call may have side effects, so the message warns that the run may
+ * still be executing and is never retried silently; when a run id was already
+ * seen in a progress frame's `_meta.runId` it is included in `data.runId`
+ * (camelCase, matching upstream's `_meta.runId` convention) and named in the
+ * message, else `data` is omitted entirely.
+ *
+ * The -32000 message differentiates the failure kind: a locally aborted
+ * upstream request (session close / shutdown mid-stream) reads differently
+ * from an upstream that died or broke protocol — but both keep the "run may
+ * still be executing" guidance, because in either case a live run could be
+ * left behind upstream.
+ */
+export function toStreamErrorFrame(failure, requestId, runId) {
+    const id = requestId ?? null;
+    if (failure instanceof ProxyCoreError) {
+        // Upstream died / broke protocol / was aborted mid-stream. Not -32603:
+        // this is an upstream-leg failure, mirrored to the pre-stream -32000.
+        const runHint = runId !== undefined
+            ? ` Check the run status with get_run id "${runId}" instead of retrying.`
+            : ` Check the run status before retrying.`;
+        const condition = failure instanceof UpstreamAbortedError
+            ? "The proxy aborted the upstream request mid-stream (local session closed or shutting down); "
+            : "Upstream stream ended unexpectedly before the final response; ";
+        return {
+            jsonrpc: "2.0",
+            error: {
+                code: JsonRpcErrorCodes.UpstreamUnavailable,
+                message: condition + "the run may still be executing — do not retry blindly." + runHint,
+                ...(runId !== undefined ? { data: { runId } } : {}),
+            },
+            id,
+        };
+    }
+    // Local proxy bug mid-stream: generic message (stack to stderr at the catch
+    // site); still include the run id when known — it is upstream-issued data
+    // the client already saw, and it is the only recovery handle left.
+    return {
+        jsonrpc: "2.0",
+        error: {
+            code: JsonRpcErrorCodes.InternalError,
+            message: "Internal error while relaying the upstream stream",
+            ...(runId !== undefined ? { data: { runId } } : {}),
+        },
+        id,
+    };
+}

package/dist/core/proxy-core.d.ts

@@ -0,0 +1,104 @@
+import { type FetchLike } from "./upstream.js";
+/**
+ * Plain callback invoked per intermediate SSE frame (progress notifications).
+ * May return a promise; forwardStream awaits each emission before reading the
+ * next frame, so a relaying transport can propagate write backpressure.
+ * `rawData` is the frame's original `data:` payload string
+ * (multi-line values joined with "\n") — relay it verbatim when possible; the
+ * parsed `message` is a fallback for transports that must re-serialize. A
+ * rejection from onEvent surfaces as LocalWriteError (client-side condition),
+ * never as an upstream transport error.
+ *
+ * DELIBERATE DROP: SSE `event:` and
+ * `id:` fields are parsed by core/sse.ts but NOT carried through this
+ * callback — only the `data:` payload is relayed. The verified upstream sends
+ * bare `data:` frames exclusively, so threading them through would be dead
+ * plumbing today; if upstream ever starts emitting these fields, extend
+ * OnEvent (SseEvent already surfaces them) and the adapter's writeSseFrame.
+ */
+export type OnEvent = (message: unknown, rawData?: string) => void | Promise<void>;
+/**
+ * A completed upstream exchange. `body` is the raw JSON-RPC response object,
+ * verbatim — success or error, never unwrapped. `status` is upstream's HTTP
+ * status (it must survive to the client). `sessionId` is the
+ * Mcp-Session-Id upstream echoed on JSON responses (null on SSE — upstream's
+ * SSE path sets no session header).
+ */
+export interface ProxyResponse {
+    status: number;
+    body: unknown;
+    sessionId: string | null;
+    /**
+     * Upstream's Content-Type header for JSON responses (adapter copies it
+     * through rather than hardcoding its own). Null when synthesized locally
+     * (e.g. the final frame of an SSE stream).
+     */
+    contentType: string | null;
+    /**
+     * SSE path only: the final frame's original `data:` payload string, so a
+     * relaying transport can emit upstream's bytes verbatim. Absent on plain
+     * JSON responses.
+     */
+    rawBody?: string;
+}
+export interface ProxyCore {
+    /**
+     * POST the client's initialize request upstream verbatim; capture
+     * Mcp-Session-Id from the response headers into the session map; return
+     * upstream's raw JSON-RPC response (upstream always answers
+     * protocolVersion 2025-11-25).
+     */
+    initialize(localKey: string, initializeRequest: unknown, clientProtocolVersion?: string, 
+    /**
+     * Mcp-Session-Id the CLIENT sent on this initialize, if any. The hosted
+     * server adopts a client-sent header id instead of minting one, so a
+     * re-initialize after a proxy restart must replay it. Never an
+     * adapter-invented key.
+     */
+    clientSessionId?: string): Promise<ProxyResponse>;
+    /**
+     * Forward a JSON-RPC notification; upstream answers 204; resolves void.
+     * `clientProtocolVersion` is the MCP-Protocol-Version the client sent on
+     * THIS call (headers are per-request on the wire); falls back to the value
+     * captured at initialize when omitted.
+     */
+    notify(localKey: string, notification: unknown, clientProtocolVersion?: string): Promise<void>;
+    /** Non-streaming forward with the stored session id; response verbatim. */
+    forward(localKey: string, request: unknown, clientProtocolVersion?: string): Promise<ProxyResponse>;
+    /**
+     * Forward a request that may stream. If upstream answers text/event-stream,
+     * onEvent is called per SSE frame that is a notification and the promise
+     * resolves with the frame that is the final JSON-RPC response (matching the
+     * request id). If upstream answers plain JSON, resolves with it directly.
+     *
+     * `signal` (optional) additionally aborts THIS request's upstream fetch —
+     * the transport fires it on local client disconnect so no upstream stream
+     * is orphaned. Distinct from close(), which tears down the whole session.
+     */
+    forwardStream(localKey: string, request: unknown, onEvent: OnEvent, clientProtocolVersion?: string, signal?: AbortSignal): Promise<ProxyResponse>;
+    /** Abort in-flight upstream fetches for the session, drop the mapping. Local-only. */
+    close(localKey: string): void;
+    /** Close every session (shutdown). */
+    closeAll(): void;
+}
+export interface ProxyCoreOptions {
+    upstreamUrl: string;
+    /** Never logged. */
+    apiKey: string;
+    /** X-TF-Client-Version override; defaults to the package version. */
+    clientVersion?: string;
+    /** Injectable fetch so unit tests need no network. */
+    fetchFn?: FetchLike;
+    /**
+     * Where to register session cleanup for process shutdown. Defaults to the
+     * process-wide shutdownHooks array; pass null to skip registration (tests).
+     */
+    hooks?: Array<() => void | Promise<void>> | null;
+}
+export declare function createProxyCore(options: ProxyCoreOptions): ProxyCore;
+/**
+ * The JSON-RPC id of a request message, undefined when absent. Single copy —
+ * the HTTP adapter imports this too; the shaping functions in core/errors.ts
+ * normalize undefined to null themselves.
+ */
+export declare function requestIdOf(request: unknown): unknown;

package/dist/core/proxy-core.js

@@ -0,0 +1,249 @@
+/**
+ * Transport-agnostic proxy core — the one module every transport wraps.
+ *
+ * Composes the upstream client (single fetch call site) with the session
+ * store (abort tracking + session/protocol-version bridging). Routes on
+ * JSON-RPC shape and response content type only; never inspects tool names or
+ * schemas. All signatures use web-standard types and plain callbacks — no
+ * node:http anywhere.
+ *
+ * SSE frames are parsed by the incremental parser in core/sse.ts and carry
+ * both the parsed JSON and the raw data payload string, so a relaying
+ * transport can pipe upstream's bytes through verbatim.
+ */
+import { log } from "../log.js";
+import { shutdownHooks } from "../shutdown.js";
+import { LocalWriteError, ProxyCoreError, UpstreamProtocolError } from "./errors.js";
+import { SessionStore } from "./session.js";
+import { parseSseStream } from "./sse.js";
+import { toTransportError, UpstreamClient } from "./upstream.js";
+export function createProxyCore(options) {
+    const upstream = new UpstreamClient({
+        url: options.upstreamUrl,
+        apiKey: options.apiKey,
+        clientVersion: options.clientVersion,
+        fetchFn: options.fetchFn,
+    });
+    const sessions = new SessionStore();
+    /**
+     * Run an upstream exchange with an abort controller tracked on the session.
+     * An optional external signal (per-request, e.g. local client disconnect)
+     * also fires the tracked controller, so session close and client disconnect
+     * abort through the same path.
+     */
+    async function withInflight(localKey, fn, externalSignal) {
+        const controller = sessions.beginRequest(localKey);
+        const onExternalAbort = () => controller.abort();
+        if (externalSignal !== undefined) {
+            if (externalSignal.aborted)
+                controller.abort();
+            else
+                externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        try {
+            return await fn(controller.signal);
+        }
+        finally {
+            externalSignal?.removeEventListener("abort", onExternalAbort);
+            sessions.endRequest(localKey, controller);
+        }
+    }
+    const core = {
+        async initialize(localKey, initializeRequest, clientProtocolVersion, clientSessionId) {
+            const entry = sessions.getOrCreate(localKey);
+            if (clientProtocolVersion !== undefined) {
+                entry.protocolVersion = clientProtocolVersion;
+            }
+            const response = await withInflight(localKey, (signal) => upstream.post(initializeRequest, {
+                // No localKey fallback here: upstream adopts any header id verbatim,
+                // so sending an adapter-invented key on initialize would prevent
+                // upstream from minting the session id. A CLIENT-sent id, however,
+                // must replay (upstream honors it — proxy-restart transparency).
+                sessionId: entry.upstreamSessionId ?? clientSessionId,
+                protocolVersion: entry.protocolVersion,
+                signal,
+            }));
+            if (response.kind !== "json") {
+                throw new UpstreamProtocolError(`Unexpected ${response.kind} response to initialize (HTTP ${response.status})`, response.status);
+            }
+            // Re-fetch: the session may have been closed while the fetch was in flight.
+            const live = sessions.get(localKey);
+            if (live !== undefined && response.sessionId !== null) {
+                live.upstreamSessionId = response.sessionId;
+                // Alias the entry under the upstream-issued id: the client re-sends
+                // upstream's id, so later calls arrive keyed by it.
+                sessions.alias(response.sessionId, live);
+            }
+            return {
+                status: response.status,
+                body: response.body,
+                sessionId: response.sessionId,
+                contentType: response.contentType,
+            };
+        },
+        async notify(localKey, notification, clientProtocolVersion) {
+            const entry = sessions.getOrCreate(localKey);
+            const response = await withInflight(localKey, (signal) => upstream.post(notification, {
+                // No captured id means the client is re-sending upstream's own id as
+                // the local key — replay the key itself.
+                sessionId: entry.upstreamSessionId ?? localKey,
+                protocolVersion: clientProtocolVersion ?? entry.protocolVersion,
+                signal,
+            }));
+            // Upstream's contract for notifications is HTTP 204, empty body.
+            // Deliberate: any other successful-fetch answer —
+            // including a JSON-RPC error body — is deliberately swallowed after a
+            // stderr warning, because a JSON-RPC notification has no response
+            // channel to relay it on (the local client still gets its 204).
+            // Transport/auth failures that THROW (unreachable, 401 with a
+            // non-JSON-RPC body) still propagate and are shaped by the adapter.
+            // Unreachable against today's real upstream, which 204s notifications
+            // before auth runs — revisit if the API-key branch changes that.
+            if (response.kind !== "empty") {
+                const errorCode = response.kind === "json" ? jsonRpcErrorCodeOf(response.body) : undefined;
+                const codeSuffix = errorCode !== undefined ? `, JSON-RPC error ${errorCode}` : "";
+                log.warn(`notification got unexpected ${response.kind} response ` +
+                    `(HTTP ${response.status}${codeSuffix}) — dropped; ` +
+                    `notifications have no response channel`);
+            }
+        },
+        async forward(localKey, request, clientProtocolVersion) {
+            const entry = sessions.getOrCreate(localKey);
+            const response = await withInflight(localKey, (signal) => upstream.post(request, {
+                sessionId: entry.upstreamSessionId ?? localKey,
+                protocolVersion: clientProtocolVersion ?? entry.protocolVersion,
+                signal,
+            }));
+            if (response.kind !== "json") {
+                throw new UpstreamProtocolError(`Unexpected ${response.kind} response to non-streaming request (HTTP ${response.status})`, response.status);
+            }
+            return {
+                status: response.status,
+                body: response.body,
+                sessionId: response.sessionId,
+                contentType: response.contentType,
+            };
+        },
+        async forwardStream(localKey, request, onEvent, clientProtocolVersion, abortSignal) {
+            const entry = sessions.getOrCreate(localKey);
+            return withInflight(localKey, async (signal) => {
+                const response = await upstream.post(request, {
+                    sessionId: entry.upstreamSessionId ?? localKey,
+                    protocolVersion: clientProtocolVersion ?? entry.protocolVersion,
+                    signal,
+                });
+                if (response.kind === "json") {
+                    return {
+                        status: response.status,
+                        body: response.body,
+                        sessionId: response.sessionId,
+                        contentType: response.contentType,
+                    };
+                }
+                if (response.kind === "sse") {
+                    const finalFrame = await readSseUntilFinal(response.stream, requestIdOf(request), onEvent);
+                    // Upstream SSE responses never carry Mcp-Session-Id; the final frame
+                    // is synthesized from the stream, so no upstream Content-Type applies.
+                    return {
+                        status: response.status,
+                        body: finalFrame.message,
+                        sessionId: null,
+                        contentType: null,
+                        rawBody: finalFrame.rawData,
+                    };
+                }
+                throw new UpstreamProtocolError(`Unexpected empty response to a request (HTTP ${response.status})`, response.status);
+            }, abortSignal);
+        },
+        close(localKey) {
+            sessions.close(localKey);
+        },
+        closeAll() {
+            sessions.closeAll();
+        },
+    };
+    const hooks = options.hooks === undefined ? shutdownHooks : options.hooks;
+    if (hooks !== null) {
+        hooks.push(() => core.closeAll());
+    }
+    return core;
+}
+// ---------------------------------------------------------------------------
+// SSE stream consumption (parser lives in core/sse.ts)
+// ---------------------------------------------------------------------------
+/** The JSON-RPC error code of a response body, if it is an error response. */
+function jsonRpcErrorCodeOf(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const error = body.error;
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === "number" ? code : undefined;
+}
+/**
+ * The JSON-RPC id of a request message, undefined when absent. Single copy —
+ * the HTTP adapter imports this too; the shaping functions in core/errors.ts
+ * normalize undefined to null themselves.
+ */
+export function requestIdOf(request) {
+    if (typeof request === "object" && request !== null && "id" in request) {
+        return request.id;
+    }
+    return undefined;
+}
+/** A JSON-RPC response frame: has result/error, no method; id must match. */
+function isFinalResponse(message, requestId) {
+    if (typeof message !== "object" || message === null)
+        return false;
+    const frame = message;
+    if ("method" in frame)
+        return false;
+    if (!("result" in frame) && !("error" in frame))
+        return false;
+    return requestId === undefined || frame.id === requestId;
+}
+/**
+ * Consume the SSE stream via parseSseStream, emitting notification frames via
+ * onEvent (each emission awaited — backpressure) and returning the final
+ * JSON-RPC response frame with its raw payload string. Reading stops at the
+ * final frame: breaking out of the for-await runs the generator's return
+ * path, which cancels the upstream stream — no waiting on upstream to close,
+ * and any spec-violating post-final frames never reach onEvent.
+ *
+ * Error classification: onEvent rejections (local client write failures) are
+ * wrapped as LocalWriteError; stream/read failures map to transport errors
+ * (abort → UpstreamAbortedError, network → UpstreamUnreachableError); parser
+ * failures are UpstreamProtocolError. Only genuinely unclassified errors go
+ * through toTransportError.
+ */
+async function readSseUntilFinal(stream, requestId, onEvent) {
+    let finalFrame;
+    try {
+        for await (const event of parseSseStream(stream)) {
+            if (isFinalResponse(event.message, requestId)) {
+                finalFrame = { message: event.message, rawData: event.rawData };
+                break;
+            }
+            // Tolerate and relay any notification method verbatim (future-proofing);
+            // a rejected write is a LOCAL failure, never an upstream one.
+            try {
+                await onEvent(event.message, event.rawData);
+            }
+            catch (err) {
+                throw new LocalWriteError(`Relaying SSE frame to the local client failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        }
+    }
+    catch (err) {
+        // Already-classified errors (LocalWriteError, UpstreamProtocolError from
+        // the parser, typed transport errors) pass through untouched.
+        if (err instanceof ProxyCoreError)
+            throw err;
+        throw toTransportError(err);
+    }
+    if (finalFrame === undefined) {
+        throw new UpstreamProtocolError("Upstream SSE stream ended without a final response frame");
+    }
+    return finalFrame;
+}

package/dist/core/session.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Session bridging state.
+ *
+ * The proxy relays session headers verbatim: the client re-sends upstream's
+ * own Mcp-Session-Id, so localKey is normally the upstream-issued id itself
+ * and the map's main job is abort tracking for in-flight upstream fetches.
+ * The upstreamSessionId / protocolVersion fields cost nothing and keep the
+ * door open for a future stdio transport that needs real id bridging.
+ *
+ * Close is local-only cleanup: the hosted server has no DELETE endpoint, so
+ * teardown just aborts in-flight fetches and drops the entry.
+ *
+ * Growth characteristic (deliberate): entries are created on first use and
+ * removed only by close()/closeAll(). The HTTP surface has no client-driven
+ * teardown signal (clients cannot DELETE), so a long-running proxy
+ * accumulates one small entry per distinct session key until process shutdown
+ * runs closeAll() via the shutdown hook. That is acceptable for a local
+ * single-user proxy — entries are a few strings plus an empty Set. Call
+ * core.close(localKey) wherever a transport does learn of a session's end
+ * (e.g. a future stdio transport's disconnect); an idle TTL can be added
+ * later if a real leak ever materializes.
+ */
+export interface SessionEntry {
+    /** Captured from the initialize response's Mcp-Session-Id header. */
+    upstreamSessionId?: string;
+    /** The client's MCP-Protocol-Version, replayed on subsequent calls. */
+    protocolVersion?: string;
+    /** AbortControllers for upstream fetches currently in flight. */
+    readonly inflight: Set<AbortController>;
+}
+export declare class SessionStore {
+    private readonly sessions;
+    get size(): number;
+    get(localKey: string): SessionEntry | undefined;
+    has(localKey: string): boolean;
+    /** Create-on-first-use lookup. */
+    getOrCreate(localKey: string): SessionEntry;
+    /**
+     * Map an additional key to an existing entry. Used by initialize() to make
+     * the upstream-issued Mcp-Session-Id resolve to the same session as the
+     * initialize-time local key: the client re-sends upstream's id, so later
+     * calls arrive keyed by that id.
+     */
+    alias(aliasKey: string, entry: SessionEntry): void;
+    /**
+     * Register a new in-flight upstream request for the session, creating the
+     * session on first use. Pair with endRequest once the request settles.
+     */
+    beginRequest(localKey: string): AbortController;
+    /** Forget a settled request's controller (no-op if the session was closed). */
+    endRequest(localKey: string, controller: AbortController): void;
+    /**
+     * Local-only teardown: abort every in-flight upstream fetch for the session
+     * and drop the entry — including every alias key that maps to the same
+     * entry. No upstream DELETE — the hosted server has no DELETE endpoint.
+     */
+    close(localKey: string): void;
+    /** Close every session (shutdown path). */
+    closeAll(): void;
+}