@cyanmycelium/mcp-broker 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _cyanmycelium_mcp_core from '@cyanmycelium/mcp-core';
-import { McpBehavior, McpResource, McpTool, McpResourceTemplate, GrammarResolverOptions, IMcpServer, IMessageTransport, McpGrammar, IAccessTokenClaims, IMcpPrincipal, McpAuthError, ITokenValidator, IProtectedResourceMetadata } from '@cyanmycelium/mcp-core';
+import { McpBehavior, McpResource, McpTool, McpResourceTemplate, GrammarResolverOptions, IMcpServer, IMessageTransport, McpGrammar, IAccessTokenClaims, IMcpPrincipal, McpAuthError, ITokenValidator, IProtectedResourceMetadata, McpAdapterBase, McpResourceContent, McpToolResult } from '@cyanmycelium/mcp-core';
 export { IAccessTokenClaims, IProtectedResourceMetadata, ITokenValidator } from '@cyanmycelium/mcp-core';
 import { IncomingMessage, ServerResponse } from 'http';
 
@@ -37,6 +37,49 @@ interface IBrokerContext {
     getProvidersInfo(): IBrokerProviderInfo[];
     /** Snapshot of a single provider slot, or `undefined` if the name is unknown. */
     getProviderInfo(name: string): IBrokerProviderInfo | undefined;
+    /**
+     * Membership of the reserved `_all` aggregate slot, or `undefined` when the
+     * host cannot report it. Lets a diagnosis distinguish "the aggregate is
+     * empty because nobody opted in" from "the aggregate is disabled".
+     */
+    getAggregateInfo?(): IBrokerAggregateInfo | undefined;
+    /**
+     * Security posture of the listening surface, or `undefined` when the host
+     * cannot report it. Lets a diagnosis catch the combination that produces a
+     * `403 invalid_origin` on a page the broker itself serves.
+     */
+    getSecurityInfo?(): IBrokerSecurityInfo | undefined;
+    /**
+     * Slot the stdio bridge is pinned to (`MCP_BROKER_STDIO_PROVIDER` /
+     * `withStdioClient`), `null` when no bridge is configured, or `undefined`
+     * when the host cannot report it. Lets a diagnosis catch a bridge pinned to
+     * a slot that cannot exist at host start.
+     */
+    getStdioBridgeTarget?(): string | null | undefined;
+}
+/**
+ * Membership snapshot of the reserved `_all` aggregate slot.
+ *
+ * `providers` lists the slot names currently contributing tools and prompts,
+ * which normally includes `_broker`. It is not the same set as "connected
+ * slots": a provider is in `_all` only if it opted in.
+ */
+interface IBrokerAggregateInfo {
+    /** `false` when the aggregate slot was disabled at construction. */
+    enabled: boolean;
+    /** Slot names currently contributing to the aggregate. */
+    providers: readonly string[];
+}
+/** What the broker enforces on its listening surface right now. */
+interface IBrokerSecurityInfo {
+    /** `true` when at least one browser origin is allowed on `/<slot>/mcp`. */
+    allowedOriginsConfigured: boolean;
+    /** `true` when clients must present an OAuth 2.1 bearer token. */
+    clientAuthEnabled: boolean;
+    /** `true` when providers must authenticate at the WebSocket upgrade. */
+    providerAuthEnabled: boolean;
+    /** URL prefixes served as static files, e.g. `["/bundle", "/"]`. */
+    staticMountPrefixes: readonly string[];
 }
 /**
  * Transport kind currently feeding a provider slot.
@@ -97,14 +140,37 @@ declare class BrokerProvidersBehavior extends McpBehavior {
     protected _buildTools(): McpTool[];
 }
 
+/**
+ * The broker's reserved slot names, in one dependency-free module.
+ *
+ * They live here rather than next to the code that registers them because
+ * three unrelated layers need them: `broker.server.ts` registers `_broker`,
+ * `AggregateServer` owns `_all`, and the diagnostics engine has to tell a
+ * reserved slot from a user slot without importing either. Importing the
+ * registrars would close a module cycle; importing this does not.
+ */
 /**
  * Reserved provider slot name under which the broker exposes itself as an MCP
- * server. Clients reach it via `<host>/_broker/mcp` (or any other client transport).
+ * server. Clients reach it via `<host>/_broker/mcp` (or any other client
+ * transport).
  *
  * Prefixed with `_` to make it unambiguously a system slot, and to reduce the
  * chance of collision with user-supplied provider names.
  */
 declare const BROKER_PROVIDER_NAME = "_broker";
+/**
+ * Reserved provider slot name under which the broker exposes the aggregate of
+ * every opted-in provider. Mirrors `AggregateServer.SLOT`.
+ */
+declare const BROKER_AGGREGATE_NAME = "_all";
+/** Every slot name the broker reserves for itself. */
+declare const BROKER_RESERVED_SLOTS: readonly string[];
+/**
+ * `true` when `name` is one of the broker's own slots rather than a slot a
+ * provider may claim. A provider connecting to a reserved name is refused.
+ */
+declare function isReservedBrokerSlot(name: string): boolean;
+
 /**
  * Optional knobs passed to {@link startBrokerServer}. Lets the embedder
  * replace either resolver with custom logic without touching mcp-broker
@@ -142,9 +208,20 @@ interface IStartBrokerServerOptions {
     localGrammarsDir?: string;
 }
 /**
- * Constructs the broker's own MCP server (the Tier-1 introspection behaviors)
- * and returns the running server plus the loopback transport that must be
- * registered against the {@link WsTunnel} as the `_broker` provider slot.
+ * Constructs the broker's own MCP server and returns the running server plus
+ * the loopback transport that must be registered against the {@link WsTunnel}
+ * as the `_broker` provider slot.
+ *
+ * Four behaviors are registered, in the order an agent meets them:
+ *
+ * - {@link BrokerInfoBehavior}: `broker_info`, `broker://info`.
+ * - {@link BrokerProvidersBehavior}: `providers_list`, `provider_status`,
+ *   `broker://providers`, `broker://providers/{name}`.
+ * - {@link BrokerGuideBehavior}: `broker_guide`, `broker://guide/*`. The
+ *   broker's own integration documentation, so an agent wiring something to
+ *   this broker never has to go find a README.
+ * - {@link BrokerDiagnoseBehavior}: `broker_diagnose`. Live state plus the
+ *   problems the broker can prove about its own wiring, each with a fix.
  *
  * Usage from {@link WsTunnel.start}:
  * ```ts
@@ -434,7 +511,24 @@ interface IAuthorizationRequest {
     readonly provider?: string;
     readonly tool?: string;
 }
-type AuthorizationDecisionReason = "explicit-deny" | "role-grant" | "no-matching-grant" | "invalid-resource" | "unknown-resource";
+/**
+ * Why a decision came out the way it did, as written to the audit log.
+ *
+ * The distinction between a policy outcome and a fault is load-bearing: the
+ * audit log is what an operator actually reads, and reporting a fault as
+ * `"no-matching-grant"` sends them off writing grants that can never help.
+ *
+ * - `explicit-deny`      a deny policy matched.
+ * - `role-grant`         an assignment matched; the only allowing reason.
+ * - `no-matching-grant`  no policy matched. A genuine policy outcome.
+ * - `invalid-resource`   the request carried no resource at all.
+ * - `unknown-resource`   the slot maps to no configured resource path.
+ * - `invalid-capability` the requested capability string is malformed, so no
+ *                        grant could ever match it. A configuration fault.
+ * - `evaluation-error`   evaluation threw. Nothing was decided; the request is
+ *                        denied because that is the safe answer. A fault.
+ */
+type AuthorizationDecisionReason = "explicit-deny" | "role-grant" | "no-matching-grant" | "invalid-resource" | "unknown-resource" | "invalid-capability" | "evaluation-error";
 interface IAuthorizationDecision {
     readonly allowed: boolean;
     readonly reason: AuthorizationDecisionReason;
@@ -853,6 +947,44 @@ interface IProviderAuthenticator {
     authenticate(req: IncomingMessage, slot: string | undefined): ProviderAuthenticatorReturn | Promise<ProviderAuthenticatorReturn>;
 }
 declare function normalizeProviderAuthentication(result: ProviderAuthenticatorReturn, fallbackId?: string): ProviderAuthenticationResult;
+/** Why a provider was refused a slot. `undefined` when it was allowed. */
+type ProviderPublishDenialReason = "no-allowed-resources" | "out-of-namespace" | "malformed-pattern";
+/** The outcome of a provider namespace check, with the cause when it denies. */
+interface IProviderPublishDecision {
+    readonly allowed: boolean;
+    /** Machine-readable cause, present only when `allowed` is `false`. */
+    readonly reason?: ProviderPublishDenialReason;
+    /** Operator-facing explanation that already names the fix. */
+    readonly detail?: string;
+}
+/**
+ * Compiles a principal's `allowedResources`, throwing on the first malformed
+ * pattern with the offending pattern quoted in the message.
+ *
+ * Call this wherever a provider principal is *built* (config load, a custom
+ * authenticator's constructor) so a typo fails the broker at startup instead of
+ * silently 403-ing every provider on that principal forever.
+ * {@link providerPublishDecision} deliberately does not throw: it runs inside the
+ * WebSocket upgrade, where the only safe answer to "is this pattern valid?" is
+ * to deny loudly.
+ */
+declare function compileProviderAllowedResources(allowed: readonly string[], label?: string): readonly ResourcePathPattern[];
+/**
+ * Decides whether a provider principal may claim `resource`, and says why when
+ * it may not.
+ *
+ * Every denial here surfaces to the provider as a bare 403 at the WebSocket
+ * handshake, which a browser reports as a contentless error event. The reason is
+ * therefore the only thing an operator (or an agent wiring this up) has to work
+ * from, so it is returned to the caller for the registration log and, for the
+ * configuration-fault case, logged here as well.
+ */
+declare function providerPublishDecision(principal: IProviderPrincipal, resource: ResourcePath): IProviderPublishDecision;
+/**
+ * Boolean form of {@link providerPublishDecision}, kept for callers that only
+ * need the verdict. Prefer the decision form so the refusal can be logged with
+ * its cause.
+ */
 declare function providerMayPublish(principal: IProviderPrincipal, resource: ResourcePath): boolean;
 /**
  * The default {@link IProviderAuthenticator}: every provider connection must
@@ -871,6 +1003,24 @@ type ProviderPrincipal = IProviderPrincipal;
 /** @deprecated Use {@link IProviderAuthenticator}. */
 type ProviderAuthenticator = IProviderAuthenticator;
 
+/**
+ * What the broker does when a provider connects to a slot another socket
+ * already holds.
+ *
+ * - `reject`: refuse the newcomer whenever the incumbent socket is OPEN. The
+ *   pre-1.3 behavior, and the only mode that never disconnects a live provider,
+ *   at the cost of a slot wedged by a half-open socket until the OS gives up on
+ *   it (roughly two hours).
+ * - `liveness` (default): refuse only while the incumbent still answers the
+ *   heartbeat. A socket that missed its last ping is terminated and the
+ *   newcomer takes the slot.
+ * - `always`: the newcomer always wins. Honored **only** when
+ *   {@link IWsTunnelOptions.providerAuth} is configured and the newcomer
+ *   authenticated as the same principal as the incumbent; otherwise the broker
+ *   falls back to `liveness` and says so, because with provider auth off anyone
+ *   who can reach the URL could evict the real provider at will.
+ */
+type ProviderTakeoverMode = "reject" | "liveness" | "always";
 /**
  * How `/<slot>/mcp` decides whether a browser origin may reach it.
  *
@@ -968,7 +1118,8 @@ interface IWsTunnelOptions {
      */
     samplesIndexPath?: string;
     /**
-     * Browser origins allowed to reach `/<slot>/mcp`.
+     * Browser origins allowed to reach a slot's client endpoints: `/<slot>/mcp`
+     * (Streamable HTTP) and the legacy SSE pair `/<slot>/sse` + `/<slot>/messages`.
      *
      * The MCP specification requires the `Origin` header to be validated,
      * because without it any web page the operator's browser happens to load
@@ -982,6 +1133,53 @@ interface IWsTunnelOptions {
      * @default undefined, no browser origin is allowed
      */
     allowedOrigins?: AllowedOrigins;
+    /**
+     * How often, in milliseconds, the broker pings every connected provider
+     * socket to check it is still there. `0` disables the heartbeat entirely.
+     *
+     * A provider that does not answer within one full interval is terminated,
+     * which frees its slot for the reconnect that is usually already being
+     * refused. Without this the only evidence of occupancy is the socket's
+     * `readyState`, and a half-open socket (a killed browser tab, a laptop that
+     * slept, a severed VPN) stays `OPEN` until the OS gives up on the TCP
+     * connection, roughly two hours, during which the broker cheerfully reports
+     * the zombie as connected, routes client frames into it, and refuses every
+     * reconnect attempt with a `1008`.
+     *
+     * **What a pong actually proves.** An RFC 6455 pong is answered by the
+     * peer's network stack, which in a browser is not the page's JavaScript
+     * thread. So this detects a dead process, a dead machine and a dead network
+     * path; it does **not** detect a page whose event loop is blocked or whose
+     * MCP server stopped serving. For that failure use
+     * {@link providerRequestTimeoutMs}, which measures the answer rather than
+     * the socket.
+     *
+     * @default 30000
+     */
+    providerHeartbeatIntervalMs?: number;
+    /**
+     * What happens when a provider connects to a slot another socket holds.
+     *
+     * @default "liveness", the incumbent keeps the slot only while it still
+     *          answers the heartbeat
+     */
+    providerTakeover?: ProviderTakeoverMode;
+    /**
+     * How long, in milliseconds, the broker waits for a provider to answer one
+     * request before failing it. `0` disables the timeout.
+     *
+     * On expiry the waiting client receives a JSON-RPC error naming the slot and
+     * the elapsed time, addressed to the id it used. Without it, a provider that
+     * simply never answers (a browser tab throttled in the background is the
+     * normal case, not the exotic one) leaves the client's request open forever
+     * with nothing to release it and no diagnostic anywhere.
+     *
+     * Raise it if you host genuinely long-running tools; a slow answer is worth
+     * waiting for, but a hang with no error is not.
+     *
+     * @default 60000
+     */
+    providerRequestTimeoutMs?: number;
     /**
      * Optional static-file mounts served over plain HTTP.
      * Matched by longest URL prefix; directory requests fall back to `index.html`.
@@ -1145,6 +1343,46 @@ declare class WsTunnel implements IBrokerContext {
     private readonly _providers;
     /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
     private readonly _multiplexSockets;
+    /**
+     * Every inbound provider socket the heartbeat watches, dedicated and
+     * multiplexed alike.
+     *
+     * An explicit collection is needed because there was none: `_providers`
+     * holds only the socket that currently owns a slot (so it misses a
+     * multiplex socket that has not announced a name yet), and
+     * `_providerPrincipals` only has entries when provider auth is configured.
+     */
+    private readonly _providerSockets;
+    /**
+     * Liveness of each provider socket: `true` when it answered the last ping,
+     * `false` while a ping is outstanding.
+     *
+     * A `WeakMap` so a terminated socket needs no cleanup here, and so a socket
+     * the heartbeat never saw (heartbeat disabled) reads back `undefined`,
+     * which the admission check treats as "no evidence either way" and refuses
+     * the takeover.
+     */
+    private readonly _alive;
+    /** Heartbeat sweep timer; `null` while stopped or disabled. */
+    private _heartbeatTimer;
+    /** Pending-request deadline sweep timer; `null` while stopped or disabled. */
+    private _requestTimeoutTimer;
+    /**
+     * Counter behind every broker-assigned request id. Monotonic per process,
+     * which is all the uniqueness the pending maps need.
+     */
+    private _nextRequestId;
+    /**
+     * Slots already warned about for answering with an id the broker never
+     * issued, so a provider that does this on every frame warns once.
+     */
+    private readonly _unmatchedIdWarnedProviders;
+    /**
+     * Slots already warned about for emitting a frame that is not JSON-RPC.
+     * A provider that speaks a non-JSON dialect emits one on every message, so
+     * the warning fires once per slot instead of flooding the log.
+     */
+    private readonly _nonJsonWarnedProviders;
     /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
     private readonly _upstreams;
     /**
@@ -1191,6 +1429,18 @@ declare class WsTunnel implements IBrokerContext {
     get port(): number;
     get tls(): boolean;
     get paths(): IBrokerContext["paths"];
+    /**
+     * What the broker enforces on its listening surface right now, for
+     * `broker_diagnose`.
+     *
+     * The rule it feeds is the one that catches a page the broker serves itself
+     * being refused by its own origin check: static files mounted, no browser
+     * origin allowed. That combination now costs more than it did, because the
+     * check reaches the legacy SSE endpoints too.
+     */
+    getSecurityInfo(): IBrokerSecurityInfo;
+    /** Slot the stdio bridge is pinned to, or `null` when there is no bridge. */
+    getStdioBridgeTarget(): string | null;
     getProvidersInfo(): IBrokerProviderInfo[];
     getProviderInfo(name: string): IBrokerProviderInfo | undefined;
     private _buildProviderInfo;
@@ -1220,14 +1470,32 @@ declare class WsTunnel implements IBrokerContext {
     /** @deprecated Check `providerNames.length > 0` instead. */
     get hasProvider(): boolean;
     /**
-     * Starts the broker. Resolves once the HTTP server is listening.
+     * Starts the broker. Resolves once the HTTP server is listening, and
+     * **rejects** when the listen fails.
+     *
+     * The rejection is the point: until the port is bound, a listen failure has
+     * nowhere else to go. `ws` mirrors the HTTP server's `'error'` onto the
+     * `WebSocketServer` from a listener it installs inside its own constructor,
+     * so an unhandled one is rethrown by Node as an uncaught exception, outside
+     * any caller's `await` and outside any `catch` the caller wrote.
      */
     start(): Promise<void>;
+    /**
+     * Turns a listen failure into an error whose message says what to do next.
+     *
+     * `EADDRINUSE` is the one that happens in practice, and the reflex it
+     * triggers is usually the wrong one: another broker gets spawned on another
+     * port. Two brokers do not share anything, a slot is held by exactly one
+     * process, so the second instance's providers are invisible to the first
+     * instance's clients. Hence the message points at attaching to the running
+     * broker first, and only then at changing the port.
+     */
+    private _listenError;
     /**
      * Starts the in-process MCP server that exposes the broker's own behaviors
-     * (`broker_info`, `providers_list`, `provider_status`) under the reserved
-     * provider slot `_broker`. No-op when {@link IWsTunnelOptions.enableBrokerProvider}
-     * is `false`.
+     * (`broker_info`, `providers_list`, `provider_status`, `broker_guide`,
+     * `broker_diagnose`) under the reserved provider slot `_broker`. No-op when
+     * {@link IWsTunnelOptions.enableBrokerProvider} is `false`.
      */
     private _maybeStartBrokerServer;
     /**
@@ -1239,6 +1507,112 @@ declare class WsTunnel implements IBrokerContext {
      * Gracefully closes all connections and stops the HTTP server.
      */
     stop(): Promise<void>;
+    /** Effective heartbeat period in ms; `0` means the heartbeat is off. */
+    private _heartbeatIntervalMs;
+    /** Effective per-request deadline in ms; `0` means requests never expire. */
+    private _requestTimeoutMs;
+    /**
+     * Starts watching every provider socket for a missed pong.
+     *
+     * `unref()` is not cosmetic: without it this interval alone keeps the Node
+     * event loop alive, so every test file that starts a tunnel would hang on
+     * teardown, and an embedder's process would refuse to exit.
+     */
+    private _startHeartbeat;
+    private _stopHeartbeat;
+    /**
+     * One heartbeat round: terminate whoever did not answer the previous ping,
+     * then ping everybody still standing.
+     *
+     * The two-phase shape is what gives a provider a full interval to reply,
+     * and it is why {@link _alive} means "answered since the last sweep" rather
+     * than "is connected".
+     */
+    private _sweepHeartbeats;
+    /**
+     * Puts one accepted provider socket under the heartbeat.
+     *
+     * No-op when the heartbeat is disabled, which is what keeps
+     * {@link _alive} empty and makes the admission check fall back to refusing
+     * every takeover: with no liveness evidence, evicting the incumbent would
+     * be a guess.
+     */
+    private _watchProviderSocket;
+    /** Human-readable list of the slots one provider socket currently serves. */
+    private _slotsOfSocket;
+    /**
+     * Decides whether a newly connected provider socket may take the slot
+     * `name`, evicting the incumbent when it is allowed to.
+     *
+     * Returns `null` when the newcomer is admitted, or the refusal otherwise:
+     * `detail` is the full diagnosis for the log and for the envelope the
+     * multiplexed path can carry, `closeReason` the same thing squeezed into the
+     * 123 bytes RFC 6455 allows on a close frame, with the actionable part
+     * first so truncation eats the slot name (which the peer already knows)
+     * rather than the instruction.
+     *
+     * See {@link ProviderTakeoverMode} for what each mode means and why
+     * `"always"` is gated on provider authentication.
+     */
+    private _claimSlot;
+    /**
+     * `true` when two provider sockets authenticated as the same principal.
+     *
+     * Deliberately `false` when provider auth is off: with no authenticator
+     * there are no principals to compare, and treating "both anonymous" as
+     * "the same provider" is exactly the spoofing primitive the gate exists to
+     * prevent.
+     */
+    private _sameProviderPrincipal;
+    /** Closes a socket with a reason RFC 6455 actually allows on the wire. */
+    private _closeWs;
+    /**
+     * Registers one outbound request against a slot and returns the frame to
+     * put on the wire, with the client's JSON-RPC id replaced by a
+     * broker-assigned one.
+     *
+     * The rewrite is the fix for a cross-client response leak. `state.pending`
+     * is one map per **slot**, written from five different ingresses (raw WS,
+     * legacy SSE, Streamable HTTP, the stdio bridge, in-process clients), and
+     * it used to be keyed by the id the client chose. Two clients on one slot
+     * that both start numbering at 1 (MCP Inspector plus Claude, the pairing
+     * the architecture doc explicitly advertises) therefore shared one entry:
+     * the second write replaced the first, one client received the other's
+     * result, and the overwritten request hung forever with no error. Rewriting
+     * also stops the provider from seeing two concurrent requests with the same
+     * id, which it has no way to answer correctly either.
+     *
+     * Invisible to conforming clients: {@link _routeFromProvider} restores the
+     * original id before the answer is delivered.
+     *
+     * Frames with no usable id (notifications) and JSON-RPC batches (an array,
+     * which has no top-level id) are returned untouched and untracked, exactly
+     * as before.
+     */
+    private _trackRequest;
+    /** Delivers one already-addressed frame to the sink that is waiting for it. */
+    private _deliverToSink;
+    /**
+     * Starts the sweep that fails requests a provider never answered.
+     *
+     * Same `unref()` requirement as the heartbeat. The period is derived from
+     * the deadline rather than fixed, so a short timeout (a test, or a
+     * latency-sensitive deployment) is still honored roughly on time instead of
+     * being rounded up to the next sweep minutes later.
+     */
+    private _startRequestTimeoutSweep;
+    private _stopRequestTimeoutSweep;
+    /**
+     * Fails every request whose deadline has passed.
+     *
+     * Until this existed a pending entry was released only by a matching
+     * response, a provider disconnect, or the client's own close, so a provider
+     * that stayed connected and simply never answered (a browser tab throttled
+     * in the background is the ordinary case) left the caller waiting with
+     * nothing to release it and no trace anywhere. A named error is strictly
+     * better than a hang.
+     */
+    private _sweepPendingTimeouts;
     private _authorizationSubject;
     private _auditDecision;
     /**
@@ -1250,6 +1624,26 @@ declare class WsTunnel implements IBrokerContext {
     /** The JSON-RPC error returned when the slot has nobody behind it. */
     private _notConnectedPayload;
     private _handleHttp;
+    /**
+     * Applies the browser-origin check to the legacy SSE pair, answering `403`
+     * and returning `false` when the origin is refused.
+     *
+     * This closes a hole, and it is the one behavior change in this release a
+     * browser page can notice. `allowedOrigins` reached exactly one place, the
+     * Streamable HTTP endpoint, so `/<slot>/sse` and `/<slot>/messages` were
+     * open to every page on the machine: `Access-Control-Allow-Origin: *` is
+     * set unconditionally a few lines above, and a POST of JSON to
+     * `/<slot>/messages` is a CORS *simple* request, so any page could open an
+     * `EventSource`, read the session id off the `endpoint` event, and drive the
+     * broker. That is verbatim the attack the origin check exists to stop.
+     *
+     * The contract of the check is preserved exactly: a request carrying **no**
+     * `Origin` always passes, which is every non-browser client (Claude Desktop,
+     * Inspector, the server-side SDKs), and an `Origin` passes only if
+     * `allowedOrigins` names it. The same predicate object is used as for
+     * `/<slot>/mcp`, so the two endpoints cannot drift apart.
+     */
+    private _sseOriginAllowed;
     /**
      * Parses `/<providerName>/<endpoint>` from a URL path.
      * Returns `null` if the URL does not match this two-segment pattern.
@@ -1266,17 +1660,40 @@ declare class WsTunnel implements IBrokerContext {
     /** Turns a rejected {@link HttpAuthGuard.authorize} into an HTTP response. */
     private _handleAuthFailure;
     /**
-     * Builds the `ws` verifyClient hook that authenticates every WebSocket
-     * upgrade before the connection is accepted, returning a real `401`/`403`
-     * during the handshake rather than a post-handshake close:
+     * Decides, from the URL alone, what one WebSocket upgrade is asking for.
      *
+     * One function rather than the two `startsWith` chains this used to be, one
+     * in the connection handler and one in `verifyClient`. They agreed by
+     * coincidence, and a disagreement would mean a socket authenticated as one
+     * role and then served as another.
+     *
+     * The three refusals are paths that cannot work whatever is behind them:
+     * a provider URL with no slot name (which used to mint a slot literally
+     * named `(unnamed)` that nothing could ever address) and a slot-scoped
+     * provider URL with more than one segment (`/provider/a/b`, which aliases
+     * the `%2F`-encoded spelling of the same slot, so refusing it removes
+     * nothing and forces one spelling).
+     *
+     * What is deliberately **not** refused: a slot name that matches nothing
+     * configured. Claiming a free slot by connecting to it is how a provider
+     * registers, so an unknown name is the normal case, not an error.
+     */
+    private _classifyWsRoute;
+    /**
+     * Builds the `ws` verifyClient hook, which decides every WebSocket upgrade
+     * before the connection is accepted, returning a real HTTP status during
+     * the handshake rather than a post-handshake close:
+     *
+     * - Paths that cannot work are refused with `400` and the full reason as the
+     *   response body (see {@link _classifyWsRoute}).
      * - **Raw MCP clients** (`/<slot>`) are gated by the OAuth 2.1 resource
      *   server ({@link _authGuard}) with the RFC 9728 `WWW-Authenticate` challenge.
      * - **Providers** (`/provider/<slot>`, `/providers`) are gated by the
      *   {@link _providerAuth} shared-secret / custom authenticator.
      *
-     * Each side is independent: a branch with no authenticator configured is let
-     * through unchanged. Returns `undefined` (no hook) when neither is set.
+     * Each authentication side is independent: a branch with no authenticator
+     * configured is let through unchanged. The hook is always installed now,
+     * because the path check applies whether or not anything is authenticated.
      */
     private _makeVerifyClient;
     /**
@@ -1315,16 +1732,88 @@ declare class WsTunnel implements IBrokerContext {
     private _fromHttpSession;
     /** Writes one JSON-RPC message as an SSE `message` event. */
     private _sendSseEvent;
+    /**
+     * Prints one line for every accepted WebSocket upgrade: the path asked for,
+     * the role the router gave it, and the slot it landed on.
+     *
+     * Without it a successful connect produces no output whatsoever, so a
+     * mistyped provider URL looks exactly like a working one until nothing ever
+     * answers. The last router branch accepts **any** unmatched path as a client
+     * slot, so `/providers/foo` (neither the multiplex endpoint `/providers` nor
+     * a dedicated `/provider/foo`) becomes a client on a slot literally named
+     * `providers/foo`; that case gets the fix spelled out in the same line.
+     *
+     * `console.log` is safe here: in stdio mode `bin.ts` rebinds the console to
+     * stderr before the tunnel starts, so this never reaches the JSON-RPC stream.
+     */
+    private _logWsConnection;
     private _logProviderRegistration;
     private _onProviderConnect;
     /**
-     * Inspects a provider's first WebSocket message for an optional registration
-     * control frame `{ "type": "register", "aggregate": boolean }`. Returns
-     * `true` when the message was a registration frame: and thus consumed, not
-     * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
+     * Inspects a provider's first WebSocket message for a registration frame,
+     * and consumes it when that is what it is. Returns `true` when the message
+     * was a registration, and thus must not be routed as MCP traffic.
+     *
+     * Two shapes are accepted, both notifications a peer that does not know them
+     * ignores:
+     *
+     * - `{"jsonrpc":"2.0","method":"notifications/register","params":{"aggregate":true}}`,
+     *   what `@cyanmycelium/mcp-broker-provider` sends on **both** paths. This
+     *   is the shape to write new providers against: the multiplexed socket has
+     *   always used it (wrapped in an envelope), so there is now one
+     *   registration to learn instead of one per path.
+     * - `{"type":"register","aggregate":true}`, the legacy control frame, kept
+     *   working indefinitely for hand-written providers already sending it.
+     *
+     * `aggregate` is opt-in and stays that way. Joining `_all` publishes a
+     * provider's tools and prompts to every client of the aggregate slot, which
+     * is a confidentiality boundary: a provider that never asks is reachable
+     * only on its own slot.
+     *
+     * A normal MCP frame carries `jsonrpc` with some other `method`, so it
      * returns `false` and the provider stays non-aggregated.
      */
     private _tryHandleRegistration;
+    /**
+     * Detects a `MultiplexTransport` connected to a slot-scoped provider URL,
+     * the single most reported way to wire this broker up wrong, and refuses it
+     * instead of letting it look like it worked.
+     *
+     * What the mistake looks like without this check: the socket connects, the
+     * broker registers the slot from the URL before any frame exists, so
+     * `provider_status` reports the provider connected; then every frame the
+     * broker sends is a plain JSON-RPC one that the peer's envelope decoder
+     * drops on the floor, and every frame the peer sends is an envelope with no
+     * top-level `id`, so it matches no pending request. Both sides believe they
+     * are connected and no request is ever answered. Nothing is logged anywhere.
+     *
+     * Only an **unambiguous** envelope closes the socket: a JSON object with no
+     * `jsonrpc` member that decodes as `{provider, payload}`. A malformed frame
+     * is left alone and routed as before, since a provider is entitled to speak
+     * a dialect the broker does not recognize. The legacy
+     * `{"type":"register","aggregate":true}` frame has no `provider`/`payload`
+     * pair and so is never mistaken for one.
+     *
+     * The diagnosis goes out three ways because each reaches a different reader:
+     * the broker log, an error **envelope** (the only framing this particular
+     * peer can decode), and the close reason, which the provider SDK surfaces
+     * through `onError` and prints to the browser console.
+     */
+    private _refuseEnvelopeOnSlotPath;
+    /**
+     * The mirror image: a `DirectTransport` connected to the shared multiplexed
+     * base. Refuses it instead of dropping its frames one by one in silence.
+     *
+     * Signature of the mistake: the socket opens, the broker never learns a slot
+     * name (they only arrive inside envelopes), so no slot is ever claimed and
+     * every client is told the provider is not connected, while the provider
+     * believes it published successfully.
+     *
+     * Only a frame that is unambiguously plain JSON-RPC (a JSON object carrying
+     * `jsonrpc`, that did not decode as an envelope) closes the socket. Anything
+     * else keeps the old behavior of dropping the frame, now with one warning.
+     */
+    private _refusePlainFrameOnMultiplexPath;
     private _onClientConnect;
     /**
      * Handles a multiplexed provider WebSocket (`/providers`).
@@ -1341,6 +1830,21 @@ declare class WsTunnel implements IBrokerContext {
     private _routeFromStdioClient;
     private _routeFromClient;
     private _routeFromProvider;
+    /**
+     * Reports a frame carrying an id nothing is waiting for.
+     *
+     * Two very different causes, so the message names both. Either the provider
+     * did not echo the id it was given (the frame is then unroutable and the
+     * real client hangs until the request deadline), or the provider is opening
+     * a **server-to-client** request of its own (`sampling/createMessage`,
+     * `roots/list`, `elicitation/create`), which this broker does not relay: the
+     * frame is dropped and the provider waits for an answer that never comes.
+     * Both used to be silent, which is what made the second one impossible to
+     * diagnose from either end.
+     *
+     * Once per slot: a provider doing this does it on every frame.
+     */
+    private _warnUnmatchedResponseId;
     /** Sends a message to all clients connected to one provider. */
     private _broadcast;
     /**
@@ -1388,6 +1892,9 @@ declare class WsTunnelBuilder {
     private _mcpPath;
     private _samplesIndexPath;
     private _allowedOrigins;
+    private _providerHeartbeatIntervalMs;
+    private _providerTakeover;
+    private _providerRequestTimeoutMs;
     private _staticMounts;
     private _stdioUpstreams;
     private _remoteUpstreams;
@@ -1459,6 +1966,50 @@ declare class WsTunnelBuilder {
      * ```
      */
     withAllowedOrigins(allowed: AllowedOrigins): this;
+    /**
+     * Sets how often the broker pings each connected provider socket to check
+     * it is still there. Pass `0` to disable the heartbeat.
+     *
+     * A provider that misses a full interval is terminated and its slot freed,
+     * which is what stops a half-open socket (a killed tab, a slept laptop, a
+     * dropped VPN) from holding a slot for the ~2 hours it takes the OS to give
+     * up on the TCP connection, refusing every reconnect in the meantime.
+     *
+     * Honest about what it proves: a pong is answered by the peer's network
+     * stack, not by the page's JavaScript. It detects a dead process, machine or
+     * network path, not a provider that is connected and simply not serving.
+     * For that, see {@link withProviderRequestTimeout}.
+     *
+     * @default 30000
+     */
+    withProviderHeartbeat(intervalMs: number): this;
+    /**
+     * Sets what happens when a provider connects to a slot another socket
+     * already holds.
+     *
+     * - `"reject"`: the incumbent always keeps the slot.
+     * - `"liveness"` (default): the incumbent keeps it only while it answers the
+     *   heartbeat; a socket that missed its last ping is terminated.
+     * - `"always"`: the newcomer wins, but **only** when
+     *   {@link withProviderSecret} / {@link withProviderAuth} is configured and
+     *   it authenticated as the same principal as the incumbent. Without that,
+     *   the broker falls back to `"liveness"` and logs why: with provider auth
+     *   off, unconditional takeover would let anyone who can reach the URL evict
+     *   the real provider.
+     */
+    withProviderTakeover(mode: ProviderTakeoverMode): this;
+    /**
+     * Sets how long the broker waits for a provider to answer one request before
+     * failing it with a JSON-RPC error naming the slot. Pass `0` to disable.
+     *
+     * Without a deadline, a provider that stays connected and never answers (a
+     * browser tab throttled in the background is the ordinary case) leaves the
+     * caller waiting forever with nothing to release it. Raise it if you host
+     * genuinely long-running tools.
+     *
+     * @default 60000
+     */
+    withProviderRequestTimeout(timeoutMs: number): this;
     /**
      * Adds a static-file mount served over plain HTTP.
      * Can be called multiple times; longest-prefix match wins at runtime.
@@ -1582,6 +2133,290 @@ type McpbBundleConfig = IMcpbBundleConfig;
  */
 declare function unzipMcpb(mcpbPath: string, destDir: string): void;
 
+/**
+ * Teaches an agent how to integrate with this broker, from inside the broker.
+ *
+ * Every page is exposed twice: as a resource (`broker://guide/<topic>`, plus
+ * the `broker://guide/{topic}` template) and through the `broker_guide` tool,
+ * because a fair number of MCP clients implement tools and ignore resources
+ * entirely. Both return the same text.
+ *
+ * This is the answer to "an agent asked to embed mcp-broker has to find and
+ * read several READMEs across two packages": it does not, it reads this.
+ */
+declare class BrokerGuideBehavior extends McpBehavior {
+    static readonly NAMESPACE = "broker_guide";
+    constructor(context: IBrokerContext);
+    protected _buildResources(): McpResource[];
+    protected _buildTemplate(): McpResourceTemplate[];
+    protected _buildTools(): McpTool[];
+}
+
+/**
+ * Exposes `broker_diagnose({ slot? })`: the live state of the broker plus the
+ * problems it can prove about its own wiring, each with a symptom, the
+ * evidence, and a fix.
+ *
+ * It exists because the raw counters were not enough. `provider_status`
+ * already reported `pendingCount`, and that number is what located a
+ * transport/path mismatch in the field, but only after someone thought to
+ * correlate it with the transport kind. That correlation is mechanical, so
+ * the broker does it here instead of leaving it to the reader.
+ *
+ * Tool-only, no resource: a diagnosis must never be served from a cache.
+ */
+declare class BrokerDiagnoseBehavior extends McpBehavior {
+    static readonly NAMESPACE = "broker_diagnostics";
+    constructor(context: IBrokerContext);
+    protected _buildTools(): McpTool[];
+}
+
+/**
+ * The broker's self-documentation, as plain Markdown constants.
+ *
+ * This module is the **source of truth** for how to integrate with an
+ * mcp-broker instance. It is served live over MCP by
+ * {@link BrokerGuideBehavior} (resources `broker://guide/*` and the
+ * `broker_guide` tool), so an agent that can reach the reserved `_broker`
+ * slot, or `_all` which aggregates it, learns the integration rules without
+ * ever opening a README.
+ *
+ * Every statement here is derived from the broker's own source, not from the
+ * repository's prose documentation. When the two disagree, this file is right
+ * and the prose is stale. The markdown docs and the samples import these
+ * constants rather than restating them, so there is exactly one copy of the
+ * rules to keep correct.
+ *
+ * Content is written for a machine reader with no prior knowledge of this
+ * project: rules are stated as rules, failure modes name their observable
+ * signature, and every diagnosis ends in an action.
+ */
+/**
+ * Identifier of one guide page. Also the last URI segment of the matching
+ * `broker://guide/<topic>` resource, and the value accepted by the
+ * `broker_guide` tool's `topic` argument.
+ */
+type BrokerGuideTopic = "index" | "publish-provider" | "connect-client" | "host-config" | "deploy" | "troubleshooting";
+/** Scheme + path prefix shared by every guide resource URI. */
+declare const BROKER_GUIDE_URI_PREFIX = "broker://guide/";
+/** RFC 6570 URI template covering every guide page. */
+declare const BROKER_GUIDE_URI_TEMPLATE = "broker://guide/{topic}";
+/** One guide page: its identity, its one-line pitch, and its Markdown body. */
+interface IBrokerGuide {
+    /** Stable topic id, used by the tool argument and the resource URI. */
+    topic: BrokerGuideTopic;
+    /** Canonical resource URI, `broker://guide/<topic>`. */
+    uri: string;
+    /** Short human title, e.g. "Publish a provider". */
+    title: string;
+    /** One line describing when to read this page. Shown in the index. */
+    summary: string;
+    /** The page body, Markdown, self-contained. */
+    content: string;
+}
+/**
+ * Every guide page, in the order an agent should meet them: the index first,
+ * then the two integration directions, then deployment, then the failure
+ * reference.
+ */
+declare const BROKER_GUIDES: readonly IBrokerGuide[];
+/** Every topic id, in catalog order. */
+declare const BROKER_GUIDE_TOPICS: readonly BrokerGuideTopic[];
+/** MIME type every guide page is served with. */
+declare const BROKER_GUIDE_MIME_TYPE = "text/markdown";
+/** Builds the canonical resource URI for a topic. */
+declare function brokerGuideUri(topic: BrokerGuideTopic): string;
+/** Looks a guide page up by topic id. `undefined` when the topic is unknown. */
+declare function brokerGuide(topic: string): IBrokerGuide | undefined;
+/**
+ * Extracts the topic from a `broker://guide/<topic>` URI, or `undefined` when
+ * the URI is not a guide URI or names a topic that does not exist.
+ *
+ * Percent-encoding is decoded so `broker://guide/publish%2Dprovider` resolves,
+ * and a decode failure is treated as "not a guide URI" rather than throwing:
+ * the URI comes off the wire.
+ */
+declare function brokerGuideTopicFromUri(uri: string): BrokerGuideTopic | undefined;
+/**
+ * The index rendered as data rather than prose: one entry per page, for a
+ * client that would rather plan its reads than parse a Markdown table.
+ */
+declare function brokerGuideIndex(): Array<{
+    topic: BrokerGuideTopic;
+    uri: string;
+    title: string;
+    summary: string;
+}>;
+
+/**
+ * Serves the broker's own integration documentation, so an agent that can
+ * reach this slot never has to find a README.
+ *
+ * The prose lives in `broker.guides.ts` and is static, which is what makes it
+ * safe to cache and to re-export to the markdown docs. What is NOT static is
+ * the deployment it describes: port, scheme and URL paths are per-instance.
+ * Rather than templating the guides, the adapter appends one short block of
+ * effective values to every page, so a reader never has to guess whether the
+ * defaults in the prose are the values in force here.
+ */
+declare class BrokerGuideAdapter extends McpAdapterBase {
+    private readonly _context;
+    constructor(_context: IBrokerContext);
+    readResourceAsync(uri: string): Promise<McpResourceContent | undefined>;
+    executeToolAsync(_uri: string, toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
+    /**
+     * Machine-readable form of the index, for a caller that wants to plan its
+     * reads without parsing a Markdown table. Exposed for the behavior's tool
+     * schema documentation and for tests.
+     */
+    index(): ReturnType<typeof brokerGuideIndex>;
+    /**
+     * Appends the effective configuration of THIS broker to a guide page.
+     *
+     * Everything in the block is read live from the context, so a deployment
+     * that moved a path or enabled TLS does not silently contradict the prose
+     * above it.
+     */
+    private _render;
+}
+
+/**
+ * Runs the broker's self-diagnosis on demand.
+ *
+ * Deliberately tool-only, with no backing resource: the answer is a snapshot
+ * of live state, and a resource read can be served from the behavior's content
+ * cache, which would hand a caller a stale diagnosis at exactly the moment it
+ * matters. `broker://providers` is the resource for state you want cached;
+ * this is the one you want fresh.
+ */
+declare class BrokerDiagnoseAdapter extends McpAdapterBase {
+    private readonly _context;
+    constructor(_context: IBrokerContext);
+    readResourceAsync(_uri: string): Promise<McpResourceContent | undefined>;
+    executeToolAsync(_uri: string, toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
+}
+
+/**
+ * The broker's self-diagnosis: live state plus the problems the broker can
+ * *prove* about its own wiring, each carrying the fix.
+ *
+ * The point is to do the correlation an integrator would otherwise have to do
+ * by hand. `provider_status` already exposes the raw counters, and the field
+ * evidence is that `pendingCount` is what finally located a transport/path
+ * mismatch. That inference is mechanical, so the broker should make it instead
+ * of making a caller notice a number.
+ *
+ * Two rules govern what lands in {@link IBrokerDiagnosisProblem}:
+ *
+ * 1. **Evidence or nothing.** A problem is reported only when the state
+ *    actually observed implies it. A check whose input is not reachable on this
+ *    host is reported as skipped (see {@link IBrokerDiagnosisSkippedCheck}),
+ *    never guessed at.
+ * 2. **Every problem ends in an action.** `fix` must be executable by a reader
+ *    that has read nothing else, so it names paths, slots and settings in full
+ *    rather than pointing at a document.
+ *
+ * The engine is a pure function of {@link IBrokerContext}, so it is testable
+ * without a socket and reusable by anything holding a context.
+ */
+
+/**
+ * How much a problem matters.
+ *
+ * - `error`: something is broken right now and a caller is being hurt by it.
+ * - `warning`: a configuration that will break under a foreseeable condition.
+ * - `info`: worth knowing, nothing is wrong.
+ */
+type BrokerDiagnosisSeverity = "error" | "warning" | "info";
+/** Stable identifier of a diagnostic rule. Safe to branch on programmatically. */
+type BrokerDiagnosisRuleId = "broker-not-started" | "transport-path-mismatch" | "provider-not-responding" | "upstream-not-responding" | "sessions-without-clients" | "no-providers" | "slot-never-connected" | "aggregate-disabled" | "aggregate-empty" | "aggregate-missing-live-slots" | "stdio-bridge-target-unreachable" | "self-served-page-blocked";
+/** One detected problem: what is wrong, what proves it, and what to do. */
+interface IBrokerDiagnosisProblem {
+    /** Stable rule id. */
+    id: BrokerDiagnosisRuleId;
+    severity: BrokerDiagnosisSeverity;
+    /** Slot the problem is about, when it is about one. */
+    slot?: string;
+    /** What a caller of this broker actually observes. */
+    symptom: string;
+    /** The state that proves the symptom, verbatim from the live snapshot. */
+    evidence: Record<string, unknown>;
+    /** A concrete action, executable without reading anything else. */
+    fix: string;
+}
+/** A rule that could not run, and why. Never a silent omission. */
+interface IBrokerDiagnosisSkippedCheck {
+    id: BrokerDiagnosisRuleId;
+    reason: string;
+}
+/** One slot as the diagnosis sees it: the live counters plus its role. */
+interface IBrokerDiagnosisSlot extends IBrokerProviderInfo {
+    /** `true` for `_broker` and `_all`, which no provider may claim. */
+    reserved: boolean;
+    /** `true` when this slot currently contributes to `_all`. `undefined` when unknown. */
+    aggregated?: boolean;
+}
+/** The whole answer of `broker_diagnose`. */
+interface IBrokerDiagnosis {
+    /** Identity and listening configuration, enough to build a URL. */
+    broker: {
+        name: string;
+        version: string;
+        startedAt: string | null;
+        uptimeSeconds: number;
+        listening: string;
+        tls: boolean;
+        paths: IBrokerContext["paths"];
+        endpoints: {
+            provider: string;
+            providers: string;
+            client: string;
+            streamableHttp: string;
+        };
+    };
+    /** Slots in scope: every slot, or just the one the caller asked about. */
+    slots: IBrokerDiagnosisSlot[];
+    /** Counts, so a caller does not have to reduce the array itself. */
+    summary: {
+        slots: number;
+        connected: number;
+        providerSlots: number;
+        connectedProviderSlots: number;
+        pendingRequests: number;
+        clients: number;
+        sessions: number;
+    };
+    /** Membership of `_all`, when the host can report it. */
+    aggregate?: {
+        enabled: boolean;
+        providers: readonly string[];
+    };
+    /** Detected problems, most severe first. Empty means nothing was provable. */
+    problems: IBrokerDiagnosisProblem[];
+    /** Rules that could not run here. */
+    checksSkipped: IBrokerDiagnosisSkippedCheck[];
+    /**
+     * Statements that are true and worth acting on but are not faults, e.g. a
+     * configuration that only breaks a topology this broker cannot see.
+     */
+    notes: string[];
+    /** Where to read the rule behind a problem. */
+    seeAlso: string[];
+}
+/**
+ * Runs every rule that has the evidence to run, against a live broker context.
+ *
+ * @param context Read-only view of the broker.
+ * @param slot    Narrows the report to one slot. Problems that are not about a
+ *                slot (no providers at all, a blocked self-served page) are
+ *                dropped in that mode, because they are not answers to the
+ *                question that was asked.
+ * @returns The full diagnosis. `undefined` only when `slot` names a slot the
+ *          broker has never heard of, which the caller should report as an
+ *          error naming `providers_list`.
+ */
+declare function diagnoseBroker(context: IBrokerContext, slot?: string): IBrokerDiagnosis | undefined;
+
 declare const VERSION: string;
 declare const PACKAGE_NAME: string;
 
@@ -1641,8 +2476,57 @@ interface IBrokerConfig {
     locale?: string;
     /** Bridge stdin/stdout for a Claude-Desktop-style client. Maps to `MCP_BROKER_STDIO_PROVIDER`. */
     stdioProvider?: string;
-    /** Logical broker name reported by `broker_info`. */
+    /**
+     * Logical broker name reported by `broker_info`.
+     *
+     * **Library-only today.** `WsTunnel` honors it
+     * (`IWsTunnelOptions.brokerName`), but `WsTunnelBuilder` has no
+     * `withBrokerName()`, so the CLI cannot forward it and setting it in
+     * `config.json` has no effect. Set it through the programmatic API until
+     * the setter exists.
+     */
     brokerName?: string;
+    /**
+     * How often (ms) the broker pings each connected provider socket to check
+     * it is still there. `0` disables the heartbeat. Maps to
+     * `MCP_BROKER_PROVIDER_HEARTBEAT_MS`.
+     *
+     * A provider that misses a full interval is terminated and its slot freed,
+     * which is what stops a half-open socket (a killed browser tab, a slept
+     * laptop, a dropped VPN) from holding a slot for the ~2 hours the OS takes
+     * to give up on the TCP connection, refusing every reconnect meanwhile.
+     *
+     * @default 30000
+     */
+    providerHeartbeatIntervalMs?: number;
+    /**
+     * How long (ms) the broker waits for a provider to answer one request
+     * before failing it with a JSON-RPC error naming the slot. `0` disables the
+     * deadline. Maps to `MCP_BROKER_PROVIDER_REQUEST_TIMEOUT_MS`.
+     *
+     * Raise it if you host genuinely long-running tools; without it a provider
+     * that stays connected and never answers (a throttled background browser
+     * tab is the ordinary case) leaves the caller waiting forever.
+     *
+     * @default 60000
+     */
+    providerRequestTimeoutMs?: number;
+    /**
+     * What happens when a provider connects to a slot another socket already
+     * holds. Maps to `MCP_BROKER_PROVIDER_TAKEOVER`.
+     *
+     * - `"reject"`: the incumbent always keeps the slot.
+     * - `"liveness"` (default): the incumbent keeps it only while it answers
+     *   the heartbeat.
+     * - `"always"`: the newcomer wins, but only when provider authentication is
+     *   configured and it authenticated as the same principal as the incumbent.
+     *   Without provider auth the broker falls back to `"liveness"` and says so,
+     *   because unconditional takeover would let anyone who can reach the URL
+     *   evict the real provider.
+     *
+     * @default "liveness"
+     */
+    providerTakeover?: "reject" | "liveness" | "always";
     /**
      * Browser origins allowed to reach `/<slot>/mcp`.
      *
@@ -1678,13 +2562,29 @@ interface IBrokerConfig {
      * `MCP_BROKER_PUBLIC_BASE_URL`, `MCP_BROKER_JWKS`, `MCP_BROKER_ISSUER`.
      */
     auth?: IBrokerAuthConfig;
-    /** URL paths (override the defaults). */
+    /**
+     * URL paths (override the defaults). Every key is also settable through an
+     * environment variable, which wins.
+     *
+     * Changing one moves an endpoint for **every** peer: a provider SDK, a
+     * client, and the startup banner all have to agree. The two provider paths
+     * are not interchangeable, they carry different framing:
+     * `provider` is a prefix (`<provider>/<slot>`) speaking plain JSON-RPC
+     * frames (`DirectTransport`), `providers` is matched exactly and speaks
+     * multiplex envelopes (`MultiplexTransport`).
+     */
     paths?: {
+        /** Prefix for one-slot-per-socket provider connections. Maps to `MCP_BROKER_PROVIDER_PATH`. @default "/provider" */
         provider?: string;
+        /** Exact path for multiplexed provider connections. Maps to `MCP_BROKER_PROVIDERS_PATH`. @default "/providers" */
         providers?: string;
+        /** Prefix raw-WebSocket clients connect to. Maps to `MCP_BROKER_CLIENT_PATH`. @default "/" */
         client?: string;
+        /** Per-slot suffix for the Streamable HTTP transport. Maps to `MCP_BROKER_MCP_PATH`. @default "/mcp" */
         mcp?: string;
+        /** Per-slot suffix for the legacy SSE stream (GET). Maps to `MCP_BROKER_SSE_PATH`. @default "/sse" */
         sse?: string;
+        /** Per-slot suffix for legacy SSE JSON-RPC posts. Maps to `MCP_BROKER_MESSAGES_PATH`. @default "/messages" */
         messages?: string;
     };
     /** TLS material as paths on disk. Resolved against the config file's directory. */
@@ -1697,8 +2597,22 @@ interface IBrokerConfig {
      * always take precedence.
      */
     www?: {
-        /** Auto-launch the default browser at the root URL on startup. */
-        open?: boolean;
+        /**
+         * Auto-launch the default browser on startup. Maps to `MCP_BROKER_OPEN`.
+         *
+         * - `false` / absent / `""` / `"0"`: do not open anything.
+         * - `true` / `"1"`: open the broker root, `<scheme>://localhost:<port>/`.
+         * - a path (`"/app/index.html"`): open that page on this broker.
+         * - an absolute URL on this broker's own origin: opened as given.
+         *
+         * A URL on any other origin is refused with a message, and so is any
+         * other string. See {@link resolveOpenTarget} for why.
+         *
+         * The browser opens only when a static mount actually covers the
+         * resolved path; otherwise the broker says which mounts exist instead of
+         * launching a browser onto a 404.
+         */
+        open?: boolean | string;
         /** URL-prefix → directory mappings. Longest-prefix match wins. */
         mounts?: Array<{
             urlPrefix: string;
@@ -1780,6 +2694,58 @@ declare const DEFAULT_CONFIG_FILENAME = "config.json";
  * {@link ILoadedBrokerConfig.baseDir} by the consumer.
  */
 declare function loadBrokerConfig(path?: string): ILoadedBrokerConfig;
+/**
+ * Outcome of {@link resolveOpenTarget}. Exactly one of the three states holds:
+ *
+ * - `{ url: null, path: null }` and no `error`: nothing should be opened.
+ * - `{ url, path }`: open `url`; `path` is what a static mount has to cover.
+ * - `{ url: null, path: null, error }`: the value was refused, `error` is a
+ *   sentence to print verbatim that names both the fault and the fix.
+ */
+interface IOpenTargetResolution {
+    /** Absolute URL to hand to the platform opener, or `null` to open nothing. */
+    url: string | null;
+    /** Path portion of {@link url} (always starts with `/`), or `null`. */
+    path: string | null;
+    /** Set when the raw value was refused. Human-readable, names the fix. */
+    error?: string;
+}
+/**
+ * Resolves `www.open` / `MCP_BROKER_OPEN` into an absolute URL to launch.
+ *
+ * Lives here rather than in `bin.ts` because `bin.ts` starts a server the
+ * moment it is imported, so nothing in it can be unit-tested.
+ *
+ * Accepted forms (leading/trailing whitespace is trimmed):
+ *
+ * | `raw`                      | result                                    |
+ * |----------------------------|-------------------------------------------|
+ * | `undefined`, `false`, `""`, `"0"`, `"false"` | open nothing            |
+ * | `true`, `"1"`, `"true"`    | `<baseUrl>/`                              |
+ * | `"/app/"`, `"/index.html"` | resolved against `baseUrl`                |
+ * | `"http://localhost:3000/x"`| passed through when the origin is `baseUrl`'s |
+ * | anything else              | refused, with `error` explaining why       |
+ *
+ * Two refusals are security-load-bearing rather than pedantic:
+ *
+ * - **A foreign origin is refused.** Auto-opening is a startup convenience, and
+ *   a config file (or an env var inherited from a parent process) that can make
+ *   the broker launch a browser at an arbitrary site is a phishing primitive
+ *   with no upside: nothing about starting a broker requires visiting another
+ *   host. Open it yourself, or point `open` at a page this broker serves.
+ * - **`//host/path` is refused** even though it starts with `/`: it is a
+ *   protocol-relative URL, so `new URL("//evil.example/x", base)` resolves to
+ *   `evil.example` and a naive "starts with a slash so it is local" test lets
+ *   it through.
+ *
+ * Anything that is neither is refused rather than forwarded, because the
+ * platform opener performs no validation of its own: a typo'd relative path is
+ * handed to the shell and can launch a local file or a registered application.
+ *
+ * @param raw     The configured value (`config.www.open`) or the raw env string.
+ * @param baseUrl Origin this broker is reachable at, e.g. `http://localhost:3000`.
+ */
+declare function resolveOpenTarget(raw: boolean | string | undefined | null, baseUrl: string): IOpenTargetResolution;
 /** @deprecated Use {@link IBrokerAuthConfig}. */
 type BrokerAuthConfig = IBrokerAuthConfig;
 /** @deprecated Use {@link IBrokerConfig}. */
@@ -1787,4 +2753,4 @@ type BrokerConfig = IBrokerConfig;
 /** @deprecated Use {@link ILoadedBrokerConfig}. */
 type LoadedBrokerConfig = ILoadedBrokerConfig;
 
-export { type AccessTokenClaims, type AggregateScopeFilter, type AllowedOrigins, type AuditContext, AuthError, type AuthErrorCode, type AuthorizationAuditConfig, type AuthorizationAuditEvent, type AuthorizationDecision, type AuthorizationDecisionReason, type AuthorizationPolicyConfig, type AuthorizationRequest, type AuthorizationSubject, BROKER_PROVIDER_NAME, type BrokerAuthConfig, type BrokerConfig, type BrokerContext, type BrokerGrammarEntry, BrokerInfoBehavior, type BrokerLocale, type BrokerProviderInfo, type BrokerProviderTransport, BrokerProvidersBehavior, type BrokerUserAgent, type CapabilityClassifier, type ClassifiedCapability, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, type DenyPolicy, HttpAuthGuard, type IAuditContext, type IAuthorizationAuditConfig, type IAuthorizationAuditEvent, type IAuthorizationDecision, type IAuthorizationPolicyConfig, type IAuthorizationRequest, type IAuthorizationSubject, type IBrokerAuthConfig, type IBrokerConfig, type IBrokerContext, type IBrokerGrammarEntry, type IBrokerProviderInfo, type ICapabilityClassifier, type IClassifiedCapability, type IDenyPolicy, type IInternalClient, type IJwtAuthOptions, type IJwtValidatorOptions, type ILoadedBrokerConfig, type IMcpOperation, type IMcpbBundleConfig, type IPolicyAssignment, type IPolicyAuthorization, type IPolicyEngine, type IPrincipal, type IProviderAuthenticator, type IProviderPrincipal, type IRemoteUpstreamConfig, type IResolvedAuth, type IRoleDefinition, type ISlotResourceResolver, type IStartBrokerServerOptions, type IStaticMount, type IStdioUpstreamConfig, type ISubjectMapper, type ISubjectMappingConfig, type IUpstream, type IWsTunnelOptions, type InternalClient, type JwtAuthOptions, JwtSubjectMapper, JwtTokenValidator, type JwtValidatorOptions, type LoadedBrokerConfig, type McpOperation, type McpbBundleConfig, PACKAGE_NAME, type PolicyAssignment, type PolicyAuthorization, type PolicyEngine, type Principal, type ProtectedResourceMetadata, type ProviderAuthenticationResult, type ProviderAuthenticator, type ProviderAuthenticatorReturn, type ProviderPrincipal, RemoteUpstream, type RemoteUpstreamConfig, type ResolvedAuth, ResourcePath, ResourcePathPattern, type RoleDefinition, SharedSecretProviderAuthenticator, type SlotResourceResolver, type StartBrokerServerOptions, type StaticMount, StdioUpstream, type StdioUpstreamConfig, type SubjectMapper, type SubjectMappingConfig, SubjectMappingError, type TokenValidator, type Upstream, VERSION, WsTunnel, WsTunnelBuilder, type WsTunnelOptions, authorizationWithEngine, brokerGrammarKey, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, hasAuthorizationPolicies, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, scopesOf, startBrokerServer, unzipMcpb, validateCapability };
+export { type AccessTokenClaims, type AggregateScopeFilter, type AllowedOrigins, type AuditContext, AuthError, type AuthErrorCode, type AuthorizationAuditConfig, type AuthorizationAuditEvent, type AuthorizationDecision, type AuthorizationDecisionReason, type AuthorizationPolicyConfig, type AuthorizationRequest, type AuthorizationSubject, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, type BrokerAuthConfig, type BrokerConfig, type BrokerContext, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, type BrokerDiagnosisRuleId, type BrokerDiagnosisSeverity, type BrokerGrammarEntry, BrokerGuideAdapter, BrokerGuideBehavior, type BrokerGuideTopic, BrokerInfoBehavior, type BrokerLocale, type BrokerProviderInfo, type BrokerProviderTransport, BrokerProvidersBehavior, type BrokerUserAgent, type CapabilityClassifier, type ClassifiedCapability, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, type DenyPolicy, HttpAuthGuard, type IAuditContext, type IAuthorizationAuditConfig, type IAuthorizationAuditEvent, type IAuthorizationDecision, type IAuthorizationPolicyConfig, type IAuthorizationRequest, type IAuthorizationSubject, type IBrokerAggregateInfo, type IBrokerAuthConfig, type IBrokerConfig, type IBrokerContext, type IBrokerDiagnosis, type IBrokerDiagnosisProblem, type IBrokerDiagnosisSkippedCheck, type IBrokerDiagnosisSlot, type IBrokerGrammarEntry, type IBrokerGuide, type IBrokerProviderInfo, type IBrokerSecurityInfo, type ICapabilityClassifier, type IClassifiedCapability, type IDenyPolicy, type IInternalClient, type IJwtAuthOptions, type IJwtValidatorOptions, type ILoadedBrokerConfig, type IMcpOperation, type IMcpbBundleConfig, type IOpenTargetResolution, type IPolicyAssignment, type IPolicyAuthorization, type IPolicyEngine, type IPrincipal, type IProviderAuthenticator, type IProviderPrincipal, type IProviderPublishDecision, type IRemoteUpstreamConfig, type IResolvedAuth, type IRoleDefinition, type ISlotResourceResolver, type IStartBrokerServerOptions, type IStaticMount, type IStdioUpstreamConfig, type ISubjectMapper, type ISubjectMappingConfig, type IUpstream, type IWsTunnelOptions, type InternalClient, type JwtAuthOptions, JwtSubjectMapper, JwtTokenValidator, type JwtValidatorOptions, type LoadedBrokerConfig, type McpOperation, type McpbBundleConfig, PACKAGE_NAME, type PolicyAssignment, type PolicyAuthorization, type PolicyEngine, type Principal, type ProtectedResourceMetadata, type ProviderAuthenticationResult, type ProviderAuthenticator, type ProviderAuthenticatorReturn, type ProviderPrincipal, type ProviderPublishDenialReason, type ProviderTakeoverMode, RemoteUpstream, type RemoteUpstreamConfig, type ResolvedAuth, ResourcePath, ResourcePathPattern, type RoleDefinition, SharedSecretProviderAuthenticator, type SlotResourceResolver, type StartBrokerServerOptions, type StaticMount, StdioUpstream, type StdioUpstreamConfig, type SubjectMapper, type SubjectMappingConfig, SubjectMappingError, type TokenValidator, type Upstream, VERSION, WsTunnel, WsTunnelBuilder, type WsTunnelOptions, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability };