@cyanmycelium/mcp-broker 1.3.4 → 1.4.0

package/src/broker/broker.guides.ts

@@ -369,6 +369,28 @@ const GUIDE_PUBLISH_PROVIDER = [
     "serving. A throttled background tab answers pings and still never replies to a",
     "request; `providerRequestTimeoutMs` is what covers that case.",
     "",
+    "### Resource updates",
+    "",
+    "The broker answers `resources/subscribe` and `resources/unsubscribe` itself and",
+    "sends your provider **one** subscribe per URI, however many clients asked, and",
+    "one unsubscribe when the last of them leaves. Implement them the plain MCP way;",
+    "an mcp-core `McpServer` (1.3.0 or later) does it for you, and a behavior only",
+    "raises `onResourceUpdated(uri)` (an `McpAdapterBase` calls",
+    "`_forwardResourceContentChanged(uri)`).",
+    "",
+    "- Every `notifications/resources/updated` must carry `params.uri`, the exact",
+    "  string the client subscribed with. The broker delivers it to the sessions",
+    "  subscribed to that URI and to no one else. One without a usable `uri` is",
+    "  dropped and logged once per slot, never broadcast.",
+    "- After a reconnect the broker restores what clients still hold: it replays the",
+    "  last `initialize` a client sent on the slot, then `notifications/initialized`,",
+    "  then one `resources/subscribe` per URI. **Install your message handler before",
+    "  the socket opens**, or that handshake waits for `providerRequestTimeoutMs`.",
+    "  Each subscriber then gets one `notifications/resources/updated`, since the",
+    "  content may have changed while you were away.",
+    "- A URI you refuse on replay is dropped along with its subscribers; their",
+    "  re-read then fails, which is how they learn.",
+    "",
     "## 8. Refusals you can receive",
     "",
     "On the slot-scoped socket a refusal is a WebSocket close with code 1008; the",
@@ -454,6 +476,13 @@ const GUIDE_CONNECT_CLIENT = [
     "`broker://providers/{name}` and `broker://guide/{topic}`. It does not proxy any",
     "other provider. It is available from the moment the broker finishes starting.",
     "",
+    "`broker://providers` and `broker://providers/<name>` can be subscribed to: a",
+    "slot appearing, a provider attaching or detaching, a slot joining or leaving",
+    "`_all` each send `notifications/resources/updated`. Counters (`pendingCount`,",
+    "`clientCount`, `sessionCount`) never do, since reading moves them; read them",
+    "when you need them. A slot name is percent-encoded in its URI, so slot `a/b`",
+    "is `broker://providers/a%2Fb`.",
+    "",
     "### `_all`",
     "",
     "An aggregate, not a proxy. It presents the union of the tools and prompts of",
@@ -487,6 +516,26 @@ const GUIDE_CONNECT_CLIENT = [
     "changes its catalog. A client that subscribes sees a provider that arrives",
     "mid-session without reconnecting.",
     "",
+    "### Subscribing to resources",
+    "",
+    "On any slot but `_all`, `resources/subscribe` and `resources/unsubscribe` work on",
+    "every transport (WebSocket, SSE, Streamable HTTP, stdio). The broker keeps the",
+    "subscriptions per session and sends the provider one subscribe per URI, so N",
+    "clients cost the provider one. `notifications/resources/updated` reaches only",
+    "the sessions subscribed to that exact URI (no normalization); every other",
+    "notification is still broadcast to the whole slot.",
+    "",
+    "- Subscribing twice is one subscription; unsubscribing from something you do",
+    "  not hold succeeds.",
+    "- Closing the socket, the SSE stream, or sending `DELETE /<slot>/mcp` releases",
+    "  everything the session held. A Streamable HTTP session that is never deleted",
+    "  never expires, and neither do its subscriptions.",
+    "- Limits: 64 URIs per client, 1024 client subscriptions per slot, URIs of at",
+    "  most 2048 characters (`resourceSubscriptions` in the config). Past a limit the",
+    "  answer is `-32000`, an overlong URI `-32602`.",
+    "- If the provider disconnects, subscriptions are kept and restored when a",
+    "  provider comes back, followed by one `updated` per URI so you re-read.",
+    "",
     "## 4. Browser clients and the origin check",
     "",
     "All three HTTP client endpoints, `/<slot>/mcp`, `/<slot>/sse` and",
@@ -758,7 +807,8 @@ const GUIDE_DEPLOY = [
     '    "stdioUpstreams": [',
     '        { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"], "aggregate": true }',
     "    ],",
-    '    "mcpServers": [{ "name": "geo", "url": "https://geo.example.com/mcp" }]',
+    '    "mcpServers": [{ "name": "geo", "url": "https://geo.example.com/mcp" }],',
+    '    "resourceSubscriptions": { "maxSubscriptionsPerClient": 64, "maxSubscriptionsPerSlot": 1024, "maxResourceUriLength": 2048 }',
     "}",
     "```",
     "",
@@ -832,6 +882,9 @@ const GUIDE_TROUBLESHOOTING = [
     "| Browser provider gets a bare `error` event and never connects | provider auth is on; a browser cannot send the required header | run without a provider secret, or authenticate in a reverse proxy |",
     "| `-32601 Method not found` on `_all` for `resources/list` | `_all` covers tools and prompts only | connect to the provider's own slot for resources |",
     "| `-32602 Unknown aggregated tool` on a name you built yourself | prefixed names are capped, hashed and de-duplicated | re-run `tools/list` and pass the returned name back verbatim |",
+    "| Subscribed, but `notifications/resources/updated` never arrives | the provider's notification names a different URI (matching is exact), carries no `params.uri` (dropped and logged once), or your read grant was revoked (you were unsubscribed) | compare the URI byte for byte; check the broker log for a dropped update |",
+    "| `-32000 Subscription limit reached` | `maxSubscriptionsPerClient` or `maxSubscriptionsPerSlot` | unsubscribe what you no longer watch; raise the limit in `resourceSubscriptions` |",
+    "| `resourceSubscriptionCount` in `provider_status` only grows | Streamable HTTP clients leave without `DELETE`; their sessions and subscriptions never expire | send the DELETE on shutdown; restart the broker if the count is already large |",
     "",
     "## The transport/path mismatch, in detail",
     "",
@@ -907,7 +960,8 @@ const GUIDE_TROUBLESHOOTING = [
     "",
     "Streamable HTTP and SSE sessions do not expire. A client that closes its tab",
     "without sending `DELETE /<slot>/mcp` leaves its session alive, and every",
-    "notification the provider broadcasts is queued into it, without bound.",
+    "notification the provider broadcasts is queued into it, without bound, and",
+    "every resource subscription it took stays held, pinning the provider's own.",
     "",
     "The broker cannot tell a live session from an abandoned one, so no single",
     "reading proves a leak. `sessionCount` in `provider_status` growing monotonically",

package/src/config.ts

@@ -102,6 +102,18 @@ export interface IBrokerConfig {
      */
     providerRequestTimeoutMs?: number;
 
+    /**
+     * Bounds on `resources/subscribe` bookkeeping. Each field maps to an env
+     * var: `MCP_BROKER_MAX_SUBSCRIPTIONS_PER_CLIENT` (default 64),
+     * `MCP_BROKER_MAX_SUBSCRIPTIONS_PER_SLOT` (default 1024),
+     * `MCP_BROKER_MAX_RESOURCE_URI_LENGTH` (default 2048).
+     */
+    resourceSubscriptions?: {
+        maxSubscriptionsPerClient?: number;
+        maxSubscriptionsPerSlot?: number;
+        maxResourceUriLength?: number;
+    };
+
     /**
      * What happens when a provider connects to a slot another socket already
      * holds. Maps to `MCP_BROKER_PROVIDER_TAKEOVER`.

package/src/index.ts

@@ -6,6 +6,15 @@ export type { IStdioUpstreamConfig, StdioUpstreamConfig } from "./stdio.upstream
 export { RemoteUpstream } from "./remote.upstream";
 export type { IRemoteUpstreamConfig, RemoteUpstreamConfig } from "./remote.upstream";
 export type { IUpstream, Upstream } from "./upstream";
+export { ResourceSubscriptionRegistry, DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS, SUBSCRIPTION_LIMIT_ERROR_CODE } from "./subscriptions/resource.subscription.registry";
+export type {
+    ClientKey,
+    IReplayResult,
+    IResourceSubscriptionLimits,
+    IResourceSubscriptionUpstream,
+    SubscriptionOutcome,
+    SubscriptionState,
+} from "./subscriptions/resource.subscription.registry";
 
 // `.mcpb` bundle loading, verifies + unpacks a bundle into a stdio upstream.
 export { loadMcpbBundle } from "./mcpb/mcpb.loader";

package/src/subscriptions/resource.subscription.registry.ts

@@ -0,0 +1,370 @@
+/**
+ * Per-slot bookkeeping for `resources/subscribe`.
+ *
+ * A slot is one MCP server shared by every client attached to it, so the
+ * provider behind it must not see one subscription per browser tab: it sees
+ * one per URI. This registry owns that reference count. The first subscriber
+ * of a URI triggers the upstream `resources/subscribe`, the last one to leave
+ * triggers the upstream `resources/unsubscribe`, and everybody in between is
+ * answered locally.
+ *
+ * Every operation on one `(slot, uri)` pair runs through a queue, so two
+ * clients subscribing at the same instant cannot both send upstream, and an
+ * unsubscribe cannot overtake the subscribe it undoes. A second subscriber that
+ * arrives while the first upstream round trip is in flight waits for it: on
+ * success it is added locally, with no second upstream call; on failure it
+ * asks the provider itself, since the first refusal may have been transient.
+ *
+ * The registry does no I/O. The tunnel supplies the upstream calls through
+ * {@link IResourceSubscriptionUpstream} and decides what a subscriber is: `S`
+ * is whatever it needs to deliver a notification later.
+ */
+
+/** Identifies one consumer across transports, e.g. `ws:7`, `http:<session>`, `stdio`. */
+export type ClientKey = string;
+
+/** An upstream answer, reduced to what the registry needs. */
+export type SubscriptionOutcome = { readonly ok: true } | { readonly ok: false; readonly error: { readonly code: number; readonly message: string } };
+
+/** What the tunnel provides so the registry can talk to a provider. */
+export interface IResourceSubscriptionUpstream {
+    /** Sends one request to the provider behind `slot` and resolves with its answer, never rejects. */
+    request(slot: string, method: "resources/subscribe" | "resources/unsubscribe", uri: string): Promise<SubscriptionOutcome>;
+    /** `true` when a provider currently serves `slot`. */
+    isConnected(slot: string): boolean;
+}
+
+/**
+ * Bounds on what clients can make the broker hold. Without them one client, or
+ * many sessions a client never closes, could grow the registry without limit
+ * and pin upstream subscriptions forever.
+ */
+export interface IResourceSubscriptionLimits {
+    /** Distinct URIs one client may be subscribed to at once. */
+    readonly maxSubscriptionsPerClient: number;
+    /** Client/URI pairs one slot may hold at once. */
+    readonly maxSubscriptionsPerSlot: number;
+    /** Longest URI accepted, in UTF-16 code units. */
+    readonly maxResourceUriLength: number;
+}
+
+export const DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS: IResourceSubscriptionLimits = Object.freeze({
+    maxSubscriptionsPerClient: 64,
+    maxSubscriptionsPerSlot: 1024,
+    maxResourceUriLength: 2048,
+});
+
+/**
+ * Where a URI stands with the provider.
+ *
+ * - `inactive`: not subscribed upstream. Either nothing was ever sent, or the
+ *   provider disconnected and the subscription waits for {@link ResourceSubscriptionRegistry.replay}.
+ * - `subscribing` / `unsubscribing`: an upstream round trip is in flight.
+ * - `active`: the provider confirmed the subscription.
+ */
+export type SubscriptionState = "inactive" | "subscribing" | "active" | "unsubscribing";
+
+/** Error code for a subscription refused by a broker limit. JSON-RPC reserves -32000..-32099 for servers. */
+export const SUBSCRIPTION_LIMIT_ERROR_CODE = -32000;
+
+interface IUriEntry<S> {
+    state: SubscriptionState;
+    /** Confirmed subscribers: they receive `notifications/resources/updated`. */
+    readonly subscribers: Map<ClientKey, S>;
+    /** Tail of this URI's operation queue. */
+    tail: Promise<void>;
+}
+
+/** One URI whose upstream subscription was re-sent after a provider reconnected. */
+export interface IReplayResult<S> {
+    readonly uri: string;
+    readonly outcome: SubscriptionOutcome;
+    /** Who was subscribed at the time; they are dropped when the outcome is a failure. */
+    readonly subscribers: ReadonlyArray<{ readonly client: ClientKey; readonly sink: S }>;
+}
+
+const OK: SubscriptionOutcome = Object.freeze({ ok: true });
+
+export class ResourceSubscriptionRegistry<S> {
+    private readonly _upstream: IResourceSubscriptionUpstream;
+    private readonly _limits: IResourceSubscriptionLimits;
+
+    /** slot → uri → entry. */
+    private readonly _slots = new Map<string, Map<string, IUriEntry<S>>>();
+
+    /**
+     * client → slot → URIs, counting subscriptions still being confirmed.
+     * Counting those is what makes the per-client limit hold under concurrent
+     * requests: a reservation is taken before the upstream call, not after.
+     */
+    private readonly _clients = new Map<ClientKey, Map<string, Set<string>>>();
+
+    /** slot → number of client/URI pairs, reserved ones included. */
+    private readonly _slotCounts = new Map<string, number>();
+
+    constructor(upstream: IResourceSubscriptionUpstream, limits: Partial<IResourceSubscriptionLimits> = {}) {
+        this._upstream = upstream;
+        this._limits = { ...DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS, ...limits };
+    }
+
+    get limits(): IResourceSubscriptionLimits {
+        return this._limits;
+    }
+
+    /**
+     * Subscribes `client` to `uri` on `slot`. Idempotent: subscribing twice
+     * keeps one entry and answers success.
+     */
+    subscribe(slot: string, client: ClientKey, sink: S, uri: string): Promise<SubscriptionOutcome> {
+        if (uri.length === 0) return Promise.resolve(failure(-32602, "Missing required parameter: uri"));
+        if (uri.length > this._limits.maxResourceUriLength) {
+            return Promise.resolve(
+                failure(-32602, `Resource URI is ${uri.length} characters long; this broker accepts at most ${this._limits.maxResourceUriLength} (maxResourceUriLength).`)
+            );
+        }
+
+        const alreadyHeld = this._clients.get(client)?.get(slot)?.has(uri) ?? false;
+        if (!alreadyHeld) {
+            if (this._clientTotal(client) >= this._limits.maxSubscriptionsPerClient) {
+                return Promise.resolve(
+                    failure(
+                        SUBSCRIPTION_LIMIT_ERROR_CODE,
+                        `Subscription limit reached: this client already holds ${this._limits.maxSubscriptionsPerClient} resource subscriptions (maxSubscriptionsPerClient). Unsubscribe from one first.`
+                    )
+                );
+            }
+            if ((this._slotCounts.get(slot) ?? 0) >= this._limits.maxSubscriptionsPerSlot) {
+                return Promise.resolve(
+                    failure(
+                        SUBSCRIPTION_LIMIT_ERROR_CODE,
+                        `Subscription limit reached on slot "${slot}": it already holds ${this._limits.maxSubscriptionsPerSlot} client subscriptions (maxSubscriptionsPerSlot).`
+                    )
+                );
+            }
+            this._reserve(slot, client, uri);
+        }
+
+        const entry = this._entry(slot, uri, true)!;
+        return this._enqueue(entry, async () => {
+            // The client may have left while this waited in the queue.
+            if (!this._isReserved(slot, client, uri)) return OK;
+
+            if (entry.state === "active") {
+                entry.subscribers.set(client, sink);
+                return OK;
+            }
+
+            entry.state = "subscribing";
+            const outcome = await this._upstream.request(slot, "resources/subscribe", uri);
+            if (outcome.ok) {
+                entry.state = "active";
+                // Re-checked after the await, for the same reason as above.
+                if (this._isReserved(slot, client, uri)) entry.subscribers.set(client, sink);
+                return OK;
+            }
+
+            entry.state = "inactive";
+            this._release(slot, client, uri);
+            this._dropIfUnused(slot, uri, entry);
+            return outcome;
+        });
+    }
+
+    /**
+     * Unsubscribes `client` from `uri`. Always succeeds, including for a URI
+     * the client never subscribed to: the client asked not to be subscribed,
+     * and it is not. The provider is told only when the last subscriber leaves,
+     * and only when it is connected; its answer does not change ours.
+     */
+    unsubscribe(slot: string, client: ClientKey, uri: string): Promise<SubscriptionOutcome> {
+        if (!this._isReserved(slot, client, uri)) return Promise.resolve(OK);
+        this._release(slot, client, uri);
+
+        const entry = this._entry(slot, uri, false);
+        if (!entry) return Promise.resolve(OK);
+
+        return this._enqueue(entry, async () => {
+            entry.subscribers.delete(client);
+            if (entry.subscribers.size > 0 || this._hasReservation(slot, uri)) return OK;
+
+            if (entry.state === "active" && this._upstream.isConnected(slot)) {
+                entry.state = "unsubscribing";
+                await this._upstream.request(slot, "resources/unsubscribe", uri);
+            }
+            entry.state = "inactive";
+            this._dropIfUnused(slot, uri, entry);
+            return OK;
+        });
+    }
+
+    /** Confirmed subscribers of `uri` on `slot`, the only ones a notification may reach. */
+    subscribers(slot: string, uri: string): ReadonlyArray<{ readonly client: ClientKey; readonly sink: S }> {
+        const entry = this._slots.get(slot)?.get(uri);
+        if (!entry) return [];
+        return [...entry.subscribers].map(([client, sink]) => ({ client, sink }));
+    }
+
+    /** Where `uri` stands with the provider behind `slot`. */
+    stateOf(slot: string, uri: string): SubscriptionState {
+        return this._slots.get(slot)?.get(uri)?.state ?? "inactive";
+    }
+
+    /** Number of client/URI pairs on `slot`, subscriptions being confirmed included. */
+    countFor(slot: string): number {
+        return this._slotCounts.get(slot) ?? 0;
+    }
+
+    /** `true` when `slot` has at least one URI someone is subscribed to. */
+    hasSubscriptions(slot: string): boolean {
+        for (const entry of this._slots.get(slot)?.values() ?? []) {
+            if (entry.subscribers.size > 0) return true;
+        }
+        return false;
+    }
+
+    /**
+     * Drops every subscription `client` holds, on every slot. Safe to call
+     * repeatedly and for a client that holds nothing.
+     */
+    async removeClient(client: ClientKey): Promise<void> {
+        const perSlot = this._clients.get(client);
+        if (!perSlot) return;
+        const pending: Promise<SubscriptionOutcome>[] = [];
+        for (const [slot, uris] of [...perSlot]) {
+            for (const uri of [...uris]) pending.push(this.unsubscribe(slot, client, uri));
+        }
+        await Promise.all(pending);
+    }
+
+    /**
+     * Records that the provider behind `slot` went away: whatever it had
+     * subscribed is gone with it. Subscribers are kept, so {@link replay} can
+     * restore them when a provider comes back.
+     */
+    providerDisconnected(slot: string): void {
+        for (const entry of this._slots.get(slot)?.values() ?? []) entry.state = "inactive";
+    }
+
+    /**
+     * Re-sends one upstream `resources/subscribe` per URI that still has
+     * subscribers, after a provider (re)attached to `slot`. A URI the new
+     * provider refuses is dropped along with its subscribers, since nothing
+     * will ever notify them; the result lists them so the caller can tell them.
+     */
+    async replay(slot: string): Promise<IReplayResult<S>[]> {
+        const entries = [...(this._slots.get(slot) ?? [])].filter(([, entry]) => entry.subscribers.size > 0);
+        return Promise.all(
+            entries.map(([uri, entry]) =>
+                this._enqueue(entry, async (): Promise<IReplayResult<S>> => {
+                    const subscribers = [...entry.subscribers].map(([client, sink]) => ({ client, sink }));
+                    if (entry.state === "active" || entry.subscribers.size === 0) return { uri, outcome: OK, subscribers };
+                    entry.state = "subscribing";
+                    const outcome = await this._upstream.request(slot, "resources/subscribe", uri);
+                    if (outcome.ok) {
+                        entry.state = "active";
+                    } else {
+                        entry.state = "inactive";
+                        for (const { client } of subscribers) {
+                            entry.subscribers.delete(client);
+                            this._release(slot, client, uri);
+                        }
+                        this._dropIfUnused(slot, uri, entry);
+                    }
+                    return { uri, outcome, subscribers };
+                })
+            )
+        );
+    }
+
+    /** Forgets everything without calling upstream. Used when the broker stops. */
+    clear(): void {
+        this._slots.clear();
+        this._clients.clear();
+        this._slotCounts.clear();
+    }
+
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+
+    private _enqueue<T>(entry: IUriEntry<S>, op: () => Promise<T>): Promise<T> {
+        const run = entry.tail.then(op);
+        entry.tail = run.then(
+            () => undefined,
+            () => undefined
+        );
+        return run;
+    }
+
+    private _entry(slot: string, uri: string, create: boolean): IUriEntry<S> | undefined {
+        let uris = this._slots.get(slot);
+        if (!uris) {
+            if (!create) return undefined;
+            uris = new Map();
+            this._slots.set(slot, uris);
+        }
+        let entry = uris.get(uri);
+        if (!entry && create) {
+            entry = { state: "inactive", subscribers: new Map(), tail: Promise.resolve() };
+            uris.set(uri, entry);
+        }
+        return entry;
+    }
+
+    /** Removes an entry nobody holds or waits for, once its queue is idle. */
+    private _dropIfUnused(slot: string, uri: string, entry: IUriEntry<S>): void {
+        if (entry.subscribers.size > 0 || this._hasReservation(slot, uri) || entry.state !== "inactive") return;
+        const uris = this._slots.get(slot);
+        if (uris?.get(uri) !== entry) return;
+        uris.delete(uri);
+        if (uris.size === 0) this._slots.delete(slot);
+    }
+
+    private _reserve(slot: string, client: ClientKey, uri: string): void {
+        let perSlot = this._clients.get(client);
+        if (!perSlot) {
+            perSlot = new Map();
+            this._clients.set(client, perSlot);
+        }
+        let uris = perSlot.get(slot);
+        if (!uris) {
+            uris = new Set();
+            perSlot.set(slot, uris);
+        }
+        uris.add(uri);
+        this._slotCounts.set(slot, (this._slotCounts.get(slot) ?? 0) + 1);
+    }
+
+    private _release(slot: string, client: ClientKey, uri: string): void {
+        const perSlot = this._clients.get(client);
+        const uris = perSlot?.get(slot);
+        if (!uris?.delete(uri)) return;
+        if (uris.size === 0) perSlot!.delete(slot);
+        if (perSlot!.size === 0) this._clients.delete(client);
+        const count = (this._slotCounts.get(slot) ?? 1) - 1;
+        if (count > 0) this._slotCounts.set(slot, count);
+        else this._slotCounts.delete(slot);
+    }
+
+    private _isReserved(slot: string, client: ClientKey, uri: string): boolean {
+        return this._clients.get(client)?.get(slot)?.has(uri) ?? false;
+    }
+
+    /** `true` when some client reserved `uri` on `slot`, confirmed or not. */
+    private _hasReservation(slot: string, uri: string): boolean {
+        for (const perSlot of this._clients.values()) {
+            if (perSlot.get(slot)?.has(uri)) return true;
+        }
+        return false;
+    }
+
+    private _clientTotal(client: ClientKey): number {
+        let n = 0;
+        for (const uris of this._clients.get(client)?.values() ?? []) n += uris.size;
+        return n;
+    }
+}
+
+function failure(code: number, message: string): SubscriptionOutcome {
+    return { ok: false, error: { code, message } };
+}

package/src/ws/ws.interfaces.ts

@@ -6,6 +6,7 @@ import type { IStdioUpstreamConfig } from "../stdio.upstream";
 import type { IRemoteUpstreamConfig } from "../remote.upstream";
 import type { IResolvedAuth, IProviderAuthenticator, IPrincipal } from "../auth/index";
 import type { IPolicyAuthorization, ISlotResourceResolver } from "../authorization/index";
+import type { IResourceSubscriptionLimits } from "../subscriptions/resource.subscription.registry";
 
 /**
  * Every type the WebSocket tunnel exchanges or is configured with.
@@ -36,7 +37,10 @@ export type ResponseSink =
     | { type: "sse"; sessionId: string }
     | { type: "http-session"; sessionId: string }
     | { type: "stdio" }
-    | { type: "internal"; client: IInternalClient };
+    | { type: "internal"; client: IInternalClient }
+    // A request the broker itself sent (an aggregated `resources/subscribe`,
+    // the handshake before a replay). Its answer is consumed, never relayed.
+    | { type: "broker"; resolve: (frame: string) => void };
 
 /**
  * The client-transport handlers a provider route can resolve to.
@@ -191,6 +195,13 @@ export interface IProviderState {
     readonly internalClients: Set<IInternalClient>;
     /** Lazily built Streamable HTTP endpoint serving this slot. */
     httpEndpoint: StreamableHttpEndpoint | null;
+    /**
+     * `params` of the last `initialize` a client sent on this slot. Replayed
+     * to a provider that reconnects while subscriptions are held, so the
+     * broker can restore them on a session the provider considers open,
+     * instead of sending requests to one that was never initialized.
+     */
+    lastInitializeParams?: unknown;
 }
 
 // ---------------------------------------------------------------------------
@@ -363,6 +374,19 @@ export interface IWsTunnelOptions {
      */
     providerRequestTimeoutMs?: number;
 
+    /**
+     * Bounds on `resources/subscribe` bookkeeping. Every field is optional and
+     * falls back to {@link DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS}: 64 URIs per
+     * client, 1024 client subscriptions per slot, URIs of at most 2048
+     * characters. A subscription past a limit is refused with `-32000`, an
+     * overlong URI with `-32602`.
+     *
+     * The per-slot bound is what caps a Streamable HTTP client that closes its
+     * tab without `DELETE`: its session never expires, so neither do its
+     * subscriptions.
+     */
+    resourceSubscriptions?: Partial<IResourceSubscriptionLimits>;
+
     /**
      * Optional static-file mounts served over plain HTTP.
      * Matched by longest URL prefix; directory requests fall back to `index.html`.

package/src/ws/ws.tunnel.builder.ts

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import { WsTunnel } from "./ws.tunnel";
 import type { AllowedOrigins, IStaticMount, IWsTunnelOptions, ProviderTakeoverMode } from "./ws.interfaces";
+import type { IResourceSubscriptionLimits } from "../subscriptions/resource.subscription.registry";
 import type { IStdioUpstreamConfig } from "../stdio.upstream";
 import type { IRemoteUpstreamConfig } from "../remote.upstream";
 import { buildJwtAuth, SharedSecretProviderAuthenticator, type IJwtAuthOptions, type IResolvedAuth, type IProviderAuthenticator } from "../auth/index";
@@ -44,6 +45,7 @@ export class WsTunnelBuilder {
     private _providerHeartbeatIntervalMs: number | undefined = undefined;
     private _providerTakeover: ProviderTakeoverMode | undefined = undefined;
     private _providerRequestTimeoutMs: number | undefined = undefined;
+    private _resourceSubscriptions: Partial<IResourceSubscriptionLimits> | undefined = undefined;
     private _staticMounts: IStaticMount[] = [];
     private _stdioUpstreams: IStdioUpstreamConfig[] = [];
     private _remoteUpstreams: IRemoteUpstreamConfig[] = [];
@@ -212,6 +214,16 @@ export class WsTunnelBuilder {
         return this;
     }
 
+    /**
+     * Bounds what `resources/subscribe` can make the broker hold. Fields left
+     * out keep their default: 64 URIs per client, 1024 client subscriptions per
+     * slot, URIs of at most 2048 characters.
+     */
+    withResourceSubscriptionLimits(limits: Partial<IResourceSubscriptionLimits>): this {
+        this._resourceSubscriptions = { ...this._resourceSubscriptions, ...limits };
+        return this;
+    }
+
     /**
      * Adds a static-file mount served over plain HTTP.
      * Can be called multiple times; longest-prefix match wins at runtime.
@@ -373,6 +385,7 @@ export class WsTunnelBuilder {
             providerHeartbeatIntervalMs: this._providerHeartbeatIntervalMs,
             providerTakeover: this._providerTakeover,
             providerRequestTimeoutMs: this._providerRequestTimeoutMs,
+            resourceSubscriptions: this._resourceSubscriptions,
             staticMounts: this._staticMounts.length > 0 ? [...this._staticMounts] : undefined,
             stdioUpstreams: this._stdioUpstreams.length > 0 ? [...this._stdioUpstreams] : undefined,
             remoteUpstreams: this._remoteUpstreams.length > 0 ? [...this._remoteUpstreams] : undefined,