@cyanmycelium/mcp-broker-provider 0.1.1 → 0.3.0

package/README.md

@@ -36,7 +36,7 @@ A multiplexed tunnel socket carries traffic for several providers at once, so ev
 
 Beyond the envelope it also covers:
 
-- `notifications/register`, sent as soon as the tunnel opens to claim a provider slot. Without it the broker only learns a provider name on its first real message, and an MCP client connecting in between is told the provider is not connected.
+- `notifications/register`, sent as soon as the tunnel opens to claim a provider slot. Without it the broker only learns a provider name on its first real message, and an MCP client connecting in between is told the provider is not connected. It optionally carries `params: { aggregate: true }`, which also joins the broker's `_all` slot, see [Joining the `_all` aggregate slot](#joining-the-_all-aggregate-slot).
 - The tunnel error codes: `-32001` when the provider's credentials do not allow publishing on the requested slot, `-32000` when the slot is unavailable.
 
 When the broker refuses a slot, the transport surfaces it through `onError` rather than forwarding it. An id-less error frame handed to an MCP server would be classified as an unknown notification and dropped without a word, so the publisher would never learn it was refused.
@@ -45,10 +45,12 @@ Malformed frames decode to `undefined` rather than throwing: a tunnel socket is
 
 ## Transports
 
-| Transport | Use case |
-|---|---|
-| `MultiplexTransport` | Several servers published by one application. A single socket carries them all, keyed by slot name |
-| `DirectTransport` | One server, one socket, on `ws://<broker>/provider/<name>` |
+| Transport | Endpoint it speaks to | Framing | Reconnects | Use case |
+|---|---|---|---|---|
+| `MultiplexTransport` | the shared multiplex base, `ws://<broker>/providers` | envelopes `{ provider, payload }` | yes, on the shared socket | Several servers published by one application. A single socket carries them all, keyed by slot name |
+| `DirectTransport` | a slot-scoped path, `ws://<broker>/provider/<name>` | plain JSON-RPC frames | **no** | One server, one socket |
+
+**The transport and the path are a pair, not a preference.** The broker decides framing from the endpoint the socket landed on, so a mismatch does not fail the handshake: the socket opens, looks healthy, and every frame is dropped on one side or the other with nothing logged by the broker. Both transports warn on the console when they spot the mismatch at connect time. And `ws://<broker>/providers/<name>`, the natural-looking blend of the two, is neither: the broker accepts it as a *client* connection on a slot of that name.
 
 ```ts
 import { McpServerBuilder } from "@cyanmycelium/mcp-core/server";
@@ -63,13 +65,157 @@ const server = new McpServerBuilder()
 await server.start();
 ```
 
-Transports created for the same tunnel URL share one WebSocket, whichever order they are opened in. Reconnection is handled by that shared socket, with exponential back-off and jitter; individual transports never reconnect on their own.
+Transports created for the same tunnel URL share one WebSocket, whichever order they are opened in. Reconnection is handled by that shared socket, with exponential back-off and jitter, and individual transports never reconnect on their own. `DirectTransport` does not reconnect at all: when its socket closes it stays closed, and the application decides whether to call `connect()` again.
+
+`server.start()` resolving means the transport reported itself open, not that the broker accepted the slot. A refusal arrives afterwards, and reaches you as an `onError` on the transport and a line on the console.
 
 `@cyanmycelium/mcp-core` is a peer dependency: the transports import its `IMessageTransport` type and nothing else at runtime, so your application keeps a single copy of it.
 
+## Joining the `_all` aggregate slot
+
+The broker publishes an aggregate slot, `_all`, which exposes every opted-in provider's tools and prompts through one MCP connection. Membership is opt-in, because `_all` is a confidentiality boundary: a provider that does not ask for it stays reachable only on its own slot.
+
+```ts
+import { DirectTransport, MultiplexTransport } from "@cyanmycelium/mcp-broker-provider";
+
+// One socket per server
+const direct = new DirectTransport("ws://localhost:3000/provider/scene-1", { aggregate: true });
+
+// Or on the shared tunnel
+const shared = MultiplexTransport.create("scene-1", "ws://localhost:3000/providers", { aggregate: true });
+```
+
+Either form sends the registration notification with `params: { aggregate: true }` as its first frame:
+
+```json
+{ "jsonrpc": "2.0", "method": "notifications/register", "params": { "aggregate": true } }
+```
+
+`DirectTransport` sends it verbatim, since the slot-scoped path carries plain JSON-RPC and the broker already knows the slot name from the URL. `MultiplexTransport` sends it inside the usual envelope, as `{ "provider": "scene-1", "payload": { ... } }`.
+
+**Wire the message handler before you connect.** The broker runs `initialize` against a newly aggregated provider immediately, and a provider that does not answer is dropped from `_all` silently. Handing the transport to an MCP server does this for you, since the server assigns `onMessage` before calling `connect()`. Assigning it yourself, after connecting, loses the handshake and the provider never appears in the aggregate.
+
+## Letting the broker decide (broker 1.5.0)
+
+A provider that serves its own kind of resource can declare an authorization
+domain and ask the broker for decisions, instead of carrying a policy of its
+own. Both transports expose the broker's methods as `transport.broker`:
+
+```ts
+import { DirectTransport, callerReferenceOf } from "@cyanmycelium/mcp-broker-provider";
+
+const transport = new DirectTransport("ws://broker:3000/provider/scada");
+// ... start the MCP server on it, then:
+await transport.broker.declare({
+    version: "2026-10-01.1",
+    domain: "scada",
+    namespace: { resource: "/production/site1" },
+    capabilities: ["scada.observe", "scada.control"],
+    resources: [
+        {
+            resource: "uns://production/site1/line1/motor01/speed_sp",
+            resourcePath: "/production/site1/line1/motor01/speed_sp",
+            limits: { minValue: 0, maxValue: 1500 },
+        },
+    ],
+    resultsRequired: ["scada.control"],
+});
+
+// In a tool handler (mcp-core 1.4.0 hands the adapter the request's _meta):
+const caller = callerReferenceOf(request?.meta);
+const { decisions } = await transport.broker.authorize({
+    principal: { type: "caller-ref", ref: caller!.ref },
+    checks: [{ capability: "scada.control", resource: "uns://production/site1/line1/motor01/speed_sp", resourcePath: "/production/site1/line1/motor01/speed_sp" }],
+});
+// decisions[0]: { effect: "allow-with-constraints", allowed: false, obligations: { constraints: { minValue: 0, maxValue: 1500 } }, ... }
+
+// Once the write is done, or refused by a constraint:
+transport.broker.reportResult({ decisionId: decisions[0].decisionId, result: "success", nativeStatus: "Good" });
+```
+
+- `effect` is `allow`, `deny` or `allow-with-constraints`. The last one comes
+  with the resource's declared limits in `obligations.constraints`; apply them
+  right before executing. `allowed` is `true` only for a plain `allow`, so code
+  that reads `allowed` alone refuses a constrained allow instead of ignoring
+  its limits.
+- `reportResult()` is a notification: nothing comes back. The broker writes the
+  outcome next to the decision in its audit, and `broker_diagnose` reports
+  decisions of `resultsRequired` capabilities still unreported.
+
+- The provider needs its own identity on the broker (an entry in the security
+  file's `providers` table), which means presenting a secret:
+  `new DirectTransport(url, { secret })`, sent as `X-Provider-Token`. Node 22
+  and later can; a browser cannot, so this is for Node and native providers.
+- To test all of this without an authorization server, start the broker with
+  `startTestBroker()` from `@cyanmycelium/mcp-broker/testing`
+  ([guide](../broker/docs/testing.md)).
+- The broker's answers are taken off the socket before the MCP server sees
+  them. A refused request rejects with `BrokerRequestError` (`code`, `data`).
+- There is no timeout by default: a broker from 1.4.1 on answers at once. Set
+  `brokerRequestTimeoutMs` only to talk to an older one, which drops methods it
+  does not know.
+
+## Distributed traces (broker 1.5.0)
+
+Every addressed request arriving from broker 1.5 carries W3C Trace Context in
+`params._meta.traceparent`. Read it from the request metadata, create a SERVER
+span, then propagate a child context when this provider calls another slot:
+
+```ts
+import {
+    childTraceparent,
+    traceparentOf,
+    withTraceparent,
+} from "@cyanmycelium/mcp-broker-provider";
+
+const incoming = traceparentOf(request?.meta);
+const downstreamMeta = incoming
+    ? withTraceparent(undefined, childTraceparent(incoming, clientSpanId))
+    : undefined;
+```
+
+Completed spans are validated before emission:
+
+```ts
+const emitted = transport.broker.span({
+    traceId,
+    spanId,
+    parentSpanId,
+    name: "modbus.read",
+    kind: 3,
+    startTimeUnixNano,
+    endTimeUnixNano,
+    attributes: { "modbus.unit_id": 1 },
+});
+```
+
+The call is a notification and never waits for an answer. The broker consumes
+`broker/telemetry`, sends it through its bounded exporter queue, and never
+broadcasts it to MCP clients. It returns `false` and drops the span when the
+provider link is down, so telemetry never occupies the transport queue ahead
+of MCP control traffic. See [the complete telemetry contract](../../../docs/telemetry.md).
+
+## Diagnostics
+
+This stack used to fail quietly. The transports now name what went wrong, on the console, because a browser-hosted provider has nowhere else to report:
+
+- A frame written before the socket is open is queued (64 frames, oldest dropped first with a warning) and flushed on open, rather than discarded. That window covers the whole reconnect back-off, up to 30 seconds.
+- A close with a code other than `1000` is reported through `onError` with the code and the broker's own reason, before `onClose`. A `1008` is a policy refusal: the slot is already connected, is reserved, or provider authentication rejected it.
+- An incoming frame that is not an envelope, or one for a slot this socket does not publish, is logged with the likely cause and the fix. Repeats are sampled (the first in full, then one in fifty) so a mismatched tunnel cannot flood the console.
+
+## In a browser
+
+The transports are written for the browser, but the npm path needs a bundler: neither this package nor `@cyanmycelium/mcp-core` ships a UMD build or declares a `browser` field, so a bare `<script>` tag will not load them. Any bundler works; there is nothing to configure beyond resolving the two packages.
+
+Import only the isomorphic entry points. `@cyanmycelium/mcp-core/server` and `@cyanmycelium/mcp-core/client` run in a browser; `@cyanmycelium/mcp-core/node` does not, and pulling it in is the usual cause of a build that fails on Node built-ins.
+
+If you would rather not add a build step, the broker ships a dependency-free ES module that speaks the same tunnel, `web/js/lib/broker-tunnel.js` (inside the `@cyanmycelium/mcp-broker` package, at `node/packages/broker/web` in the repository). It is the zero-build alternative, not a replacement: it carries no MCP server implementation.
+
+One limitation worth knowing before you deploy: if the broker is configured with provider authentication, a browser-hosted provider cannot connect. The broker reads its credential from the `X-Provider-Token` or `Authorization` header of the upgrade request, and the browser `WebSocket` constructor cannot set headers, so the handshake is refused with a 401 the page sees only as a generic error. A browser provider needs provider auth off, or an authenticating reverse proxy in front of the broker.
+
 ## Status
 
-`0.1.0` ships the protocol module and both transports. They still exist in `@cyanmycelium/mcp-core@0.4.x` as well, and are removed there in `0.5.0`, migrate your imports before upgrading.
+This package is the only home of the tunnel transports. They also shipped in `@cyanmycelium/mcp-core@0.4.x`, were removed there in `0.5.0`, and are absent from `0.7.x` and `1.x`, so migrate those imports here before upgrading `mcp-core`.
 
 The protocol is shared with the broker, and later with the consumer side. Import it through the `./protocol` subpath rather than the package root, so it can move to a package of its own one day without touching your call sites.
 

package/dist/index.d.ts

@@ -1,6 +1,279 @@
-export { TUNNEL_REGISTER_METHOD, TunnelEnvelope, TunnelError, TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf } from './protocol/index.js';
+export { ITunnelRegisterOptions, TUNNEL_REGISTER_METHOD, TunnelEnvelope, TunnelError, TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, encodeRegisterFrame, envelopeFrame, tunnelErrorOf } from './protocol/index.js';
 import { IMessageTransport } from '@cyanmycelium/mcp-core';
 
+/**
+ * Talks to the broker itself, over the provider's own socket: declaring an
+ * authorization domain, and asking for decisions.
+ *
+ * Requires broker 1.5.0 or later. An older broker does not know these methods:
+ * from 1.4.1 it refuses them at once with `-32601`; 1.4.0 and earlier drop
+ * them and never answer, which is why {@link IBrokerClientOptions.requestTimeoutMs}
+ * exists, off by default.
+ */
+/** The `params._meta` key under which the broker passes the caller reference with each request. */
+declare const CALLER_META_KEY = "io.cyanmycelium/caller";
+/** W3C Trace Context carrier used by MCP requests. */
+declare const TRACEPARENT_META_KEY = "traceparent";
+/** Provider-to-broker telemetry notification. */
+declare const TELEMETRY_NOTIFICATION_METHOD = "broker/telemetry";
+/** Provider-to-broker notification reporting what happened after a decision. */
+declare const AUDIT_RESULT_NOTIFICATION_METHOD = "broker/audit/result";
+interface ITraceParent {
+    readonly version: "00";
+    readonly traceId: string;
+    readonly parentId: string;
+    readonly traceFlags: string;
+}
+type TelemetryAttributeValue = string | number | boolean;
+interface ITelemetryEvent {
+    readonly name: string;
+    readonly timeUnixNano: string;
+    readonly attributes?: Readonly<Record<string, TelemetryAttributeValue>>;
+}
+interface ITelemetrySpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly name: string;
+    readonly kind?: number;
+    readonly startTimeUnixNano: string;
+    readonly endTimeUnixNano: string;
+    readonly attributes?: Readonly<Record<string, TelemetryAttributeValue>>;
+    readonly events?: readonly ITelemetryEvent[];
+    readonly status?: {
+        readonly code: number;
+        readonly message?: string;
+    };
+}
+/** Parses the W3C version 00 traceparent representation used in MCP metadata. */
+declare function parseTraceparent(value: unknown): ITraceParent | undefined;
+declare function formatTraceparent(context: ITraceParent): string;
+/** Reads `params._meta.traceparent`, returning `undefined` when it is malformed. */
+declare function traceparentOf(meta: Readonly<Record<string, unknown>> | undefined): ITraceParent | undefined;
+/** Returns a metadata copy carrying the supplied validated trace context. */
+declare function withTraceparent(meta: Readonly<Record<string, unknown>> | undefined, context: ITraceParent): Readonly<Record<string, unknown>>;
+/** Continues a trace using the caller's span as the new W3C parent id. */
+declare function childTraceparent(parent: ITraceParent, spanId: string): ITraceParent;
+/** What the broker hands a declaring provider with each request, under {@link CALLER_META_KEY}. */
+interface ICallerReference {
+    /** Opaque. Valid on this slot, while the request it came with is pending. */
+    readonly ref: string;
+    /** Ties the decisions and the eventual report to the client request. */
+    readonly correlationId: string;
+    /** W3C trace id carried by the MCP request. */
+    readonly traceId?: string;
+}
+/**
+ * Reads the caller reference out of a request's `params._meta`, or
+ * `undefined` when there is none (the broker only adds it once a declaration
+ * was accepted). With mcp-core 1.4.0, pass `request?.meta` from the context
+ * an adapter receives.
+ */
+declare function callerReferenceOf(meta: Readonly<Record<string, unknown>> | undefined): ICallerReference | undefined;
+/**
+ * Engineering limits of one resource. They hold for every caller, and the
+ * broker returns them with each allow on that resource as
+ * `obligations.constraints`, for the provider to apply.
+ */
+interface IResourceLimits {
+    readonly minValue?: number;
+    readonly maxValue?: number;
+    readonly allowedValues?: readonly (string | number | boolean | null)[];
+    readonly destinations?: readonly string[];
+}
+/** One resource of a declaration: the provider's own identifier, and the path the broker evaluates. */
+interface IDeclaredResource {
+    readonly resource: string;
+    readonly resourcePath: string;
+    readonly effect?: string;
+    readonly limits?: IResourceLimits;
+}
+/** `broker/authorization/declare` parameters. Describes; grants nothing. */
+interface IAuthorizationDeclaration {
+    readonly version: string;
+    readonly domain: string;
+    readonly namespace: {
+        readonly resource: string;
+    };
+    readonly capabilities: readonly string[];
+    readonly resources?: readonly IDeclaredResource[];
+    readonly protects?: readonly string[];
+    /**
+     * Declared capabilities whose allowed decisions this provider promises to
+     * report with {@link BrokerClient.reportResult}. One not reported in time
+     * shows up in `broker_diagnose`.
+     */
+    readonly resultsRequired?: readonly string[];
+}
+interface IDeclarationAccepted {
+    readonly accepted: true;
+    readonly version: string;
+    readonly policyVersion: string;
+}
+/** One question: may (the caller) do `capability` on this resource? */
+interface IAuthorizationCheck {
+    readonly capability: string;
+    readonly resource: string;
+    readonly resourcePath: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/** `broker/authorize` parameters. */
+interface IAuthorizationQuery {
+    /** On whose behalf: the caller of a pending request, or the provider itself. Never an identity. */
+    readonly principal: {
+        readonly type: "caller-ref";
+        readonly ref: string;
+    } | {
+        readonly type: "provider";
+    };
+    /** Only for `{ type: "provider" }`; a caller reference carries its own. */
+    readonly correlationId?: string;
+    /** Optional W3C trace id for provider-initiated work. */
+    readonly traceId?: string;
+    readonly checks: readonly IAuthorizationCheck[];
+}
+/** What an allow comes with. */
+interface IAuthorizationObligations {
+    /** The declared limits of the resource. Apply them right before executing. */
+    readonly constraints?: IResourceLimits;
+}
+interface IAuthorizationDecision {
+    readonly decisionId: string;
+    /** `allow-with-constraints`: allowed, within `obligations`. */
+    readonly effect: "allow" | "deny" | "allow-with-constraints";
+    /**
+     * `true` only for an unconditional `allow`. A provider that reads only
+     * this field therefore refuses a constrained allow rather than ignoring
+     * its constraints; read `effect` to apply them.
+     */
+    readonly allowed: boolean;
+    readonly reason: string;
+    readonly policies?: readonly string[];
+    readonly obligations?: IAuthorizationObligations;
+}
+/** `broker/audit/result` parameters: the outcome of what a decision allowed or refused. */
+interface IAuditResult {
+    /** The `decisionId` the broker returned. */
+    readonly decisionId: string;
+    readonly result: "success" | "failure" | "refused";
+    /** The protocol's own status (`Good`, an exception code, ...). */
+    readonly nativeStatus?: string;
+    /** The provider's error code, when it failed or refused. */
+    readonly errorCode?: string;
+}
+interface IAuthorizationAnswer {
+    readonly policyVersion: string;
+    /** One per check, in the same order. */
+    readonly decisions: readonly IAuthorizationDecision[];
+}
+/** The broker refused a request, or never answered it. */
+declare class BrokerRequestError extends Error {
+    /** JSON-RPC error code; `undefined` for a timeout or a closed socket. */
+    readonly code?: number | undefined;
+    /** The error's `data`, e.g. `{ errors: [...] }` for a refused declaration. */
+    readonly data?: unknown | undefined;
+    constructor(message: string, 
+    /** JSON-RPC error code; `undefined` for a timeout or a closed socket. */
+    code?: number | undefined, 
+    /** The error's `data`, e.g. `{ errors: [...] }` for a refused declaration. */
+    data?: unknown | undefined);
+}
+interface IBrokerClientOptions {
+    /**
+     * Rejects a request the broker did not answer within this many ms. Off by
+     * default: a broker from 1.4.1 on answers every request at once, refusals
+     * included, so waiting is never the normal path. Set it only to talk to an
+     * older broker, which drops what it does not know.
+     */
+    readonly requestTimeoutMs?: number;
+}
+/**
+ * The `broker/*` methods of one provider slot. Reached as `transport.broker`
+ * on {@link DirectTransport} and {@link MultiplexTransport}; the transport
+ * routes the broker's answers here before anything reaches the MCP server.
+ */
+declare class BrokerClient {
+    private readonly _write;
+    private readonly _writeTelemetry;
+    private readonly _timeoutMs;
+    private readonly _waiting;
+    private _next;
+    constructor(write: (frame: string) => void, options?: IBrokerClientOptions, writeTelemetry?: (frame: string) => boolean);
+    /**
+     * Declares this provider's authorization domain. Resolves when the broker
+     * accepted it; rejects with a {@link BrokerRequestError} whose `data.errors`
+     * lists every problem otherwise. Until it resolves, serve nothing that
+     * needs a decision.
+     */
+    declare(declaration: IAuthorizationDeclaration): Promise<IDeclarationAccepted>;
+    /** Asks for one decision per check. */
+    authorize(query: IAuthorizationQuery): Promise<IAuthorizationAnswer>;
+    /**
+     * Reports what happened after a decision, so the broker's audit shows the
+     * outcome next to the decision. A notification: nothing comes back, and a
+     * report the broker cannot match is counted on its side.
+     */
+    reportResult(report: IAuditResult): void;
+    /** Emits one complete provider span, or returns false when the link is down. */
+    span(span: ITelemetrySpan): boolean;
+    /** Number of requests still waiting for the broker. */
+    get pendingCount(): number;
+    /**
+     * Consumes a frame when it answers one of this client's requests. Returns
+     * `true` when it did, and the frame must not reach the MCP server.
+     * @internal Called by the transports.
+     */
+    handleIncoming(frame: string): boolean;
+    /**
+     * Fails every waiting request: the socket they went out on is gone, and a
+     * reconnected one will not carry their answers.
+     * @internal Called by the transports.
+     */
+    rejectAll(reason: string): void;
+    private _request;
+}
+
+/** Options accepted by {@link DirectTransport}. */
+interface IDirectTransportOptions {
+    /**
+     * Join the broker's `_all` aggregate slot as well as this provider's own
+     * slot, by sending the registration notification
+     * `{"jsonrpc":"2.0","method":"notifications/register","params":{"aggregate":true}}`
+     * as the first frame on the socket.
+     *
+     * Opt-in on purpose: `_all` exposes this provider's tools and prompts to
+     * every client of the aggregate slot, so a provider that does not ask for it
+     * stays reachable only on its own slot.
+     *
+     * ORDERING: the broker runs `initialize` against a newly aggregated provider
+     * immediately, and drops it from `_all` without a word if the handshake times
+     * out. The frame therefore goes out on `open`, never from the constructor, so
+     * assign `onMessage` (or hand this transport to an MCP server, which assigns
+     * it for you) *before* calling {@link DirectTransport.connect}. Connecting
+     * first and wiring the handler afterwards loses the broker's `initialize` and
+     * the provider silently never appears in `_all`.
+     */
+    aggregate?: boolean;
+    /**
+     * Rejects a `broker.declare()` / `broker.authorize()` the broker did not
+     * answer within this many ms. Off by default: a broker from 1.4.1 on answers
+     * at once. Only for an older broker, which drops methods it does not know.
+     */
+    brokerRequestTimeoutMs?: number;
+    /**
+     * The provider secret, sent as the `X-Provider-Token` header of the
+     * WebSocket handshake. Required by a broker that authenticates providers
+     * (`providerSecret`, or the security file's `providers` table, where it is
+     * what gives this provider its own identity).
+     *
+     * **Node only.** Node's `WebSocket` (22 and later) accepts handshake
+     * headers; a browser's does not, and a browser provider cannot
+     * authenticate (terminate provider auth in a reverse proxy instead).
+     */
+    secret?: string;
+    /** Extra handshake headers, Node only, like {@link secret}. */
+    headers?: Readonly<Record<string, string>>;
+}
 /**
  * 1:1 WebSocket transport, wraps a single `WebSocket` connection to a broker
  * provider slot, typically `ws://<broker>/provider/<name>`.
@@ -9,16 +282,32 @@ import { IMessageTransport } from '@cyanmycelium/mcp-core';
  * through the same broker, prefer {@link MultiplexTransport}, which shares a
  * single socket between them.
  *
+ * This transport does **not** reconnect: when the socket closes, it stays
+ * closed until the application calls {@link connect} again. Only
+ * {@link MultiplexTransport}'s shared socket reconnects on its own.
+ *
  * Call {@link connect} after setting the event callbacks to open the socket.
  */
 declare class DirectTransport implements IMessageTransport {
     private readonly _wsUrl;
+    private readonly _aggregate;
+    private readonly _headers;
+    private readonly _pending;
+    /** Throttles the "wrote to a closed transport" line, which repeats per frame. */
+    private readonly _afterCloseNotice;
     private _ws;
+    private _closed;
     onMessage: ((data: string) => void) | null;
     onOpen: (() => void) | null;
     onClose: (() => void) | null;
     onError: ((error: Error) => void) | null;
-    constructor(wsUrl: string);
+    /**
+     * The broker's own methods for this slot: declaring an authorization
+     * domain, asking for decisions. Its answers are taken off the socket
+     * before {@link onMessage} sees anything.
+     */
+    readonly broker: BrokerClient;
+    constructor(wsUrl: string, options?: IDirectTransportOptions);
     get isOpen(): boolean;
     /**
      * Opens the WebSocket connection and wires its events to the transport
@@ -27,6 +316,23 @@ declare class DirectTransport implements IMessageTransport {
     connect(): void;
     send(data: string): void;
     close(): void;
+    /**
+     * Sends the registration notification when the caller asked for a specific
+     * aggregate membership. The slot name is not in the frame: on the
+     * slot-scoped path the broker takes it from the URL at connect time.
+     */
+    private _sendRegistration;
+    /** Writes out everything queued while the socket was connecting. */
+    private _flush;
+    /**
+     * Builds the message for a close worth reporting, or `undefined` when there
+     * is nothing to say.
+     *
+     * A code of 1000 is a normal close and stays silent. An environment that
+     * calls `onclose` with no event at all leaves nothing to distinguish a
+     * refusal from a clean shutdown, so that stays silent too.
+     */
+    private _closeError;
 }
 
 /**
@@ -41,27 +347,100 @@ declare class MultiplexSocket {
     /** Per-URL cache so all transports targeting the same tunnel share one socket. */
     private static readonly _instances;
     private readonly _wsUrl;
+    /** Cache key: the URL, and the handshake headers, since two secrets are two identities and need two sockets. */
+    private readonly _key;
+    private readonly _headers;
     private readonly _transports;
+    /** Aggregate opt-in per slot, absent when the caller did not express one. */
+    private readonly _aggregates;
+    /** Frames written while the socket is connecting, reconnecting or backing off. */
+    private readonly _pending;
     private _ws;
     private _reconnectAttempts;
+    private _reconnectTimer;
     private _stopped;
+    /** Set once the last transport left and this instance gave up its URL. */
+    private _dead;
+    /** The URL guard is about the URL, not the socket, so it is said once. */
+    private _pathWarned;
+    /** Throttles the "wrote to a closed tunnel" line, which repeats per frame. */
+    private readonly _afterStopNotice;
     private constructor();
-    /** Returns (or creates) the singleton socket for a given tunnel URL. */
-    static getOrCreate(wsUrl: string): MultiplexSocket;
+    /** Returns (or creates) the singleton socket for a given tunnel URL and handshake headers. */
+    static getOrCreate(wsUrl: string, headers?: Record<string, string>): MultiplexSocket;
     get isOpen(): boolean;
-    register(name: string, transport: MultiplexTransport): void;
+    register(name: string, transport: MultiplexTransport, aggregate?: boolean): void;
     unregister(name: string): void;
+    /**
+     * Brings a torn-down instance back into service when a transport that
+     * captured it is reactivated.
+     *
+     * Reclaims the URL when nothing else holds it. When another instance already
+     * does, the two would race for the same slot names, so this says exactly that
+     * rather than letting the loser fail with a refusal nobody reads.
+     */
+    private _revive;
     /**
      * Claims the slot for `name` so the broker eagerly creates its provider
      * state before any MCP client connects. Without it the broker only learns
      * about a provider on its first real message, and a client connecting in
      * between is told the provider is not connected.
+     *
+     * Carries the aggregate opt-in when the caller expressed one, which is why
+     * it must go out before any traffic: the broker runs `initialize` against a
+     * newly aggregated provider straight away.
      */
     private _announceProvider;
     send(provider: string, data: string): void;
+    /** Sends low-priority telemetry only while the shared link is open. */
+    sendTelemetry(provider: string, data: string): boolean;
     private _connect;
+    /** Writes out everything queued while the socket was down. */
+    private _flush;
     private _routeIncoming;
     private _scheduleReconnect;
+    /** Disarms a pending reconnect, so nothing opens a socket behind our back. */
+    private _cancelReconnect;
+}
+/** Options accepted by {@link MultiplexTransport.create}. */
+interface IMultiplexTransportOptions {
+    /**
+     * Join the broker's `_all` aggregate slot as well as this provider's own
+     * slot, by carrying `params: { aggregate: true }` on the registration
+     * notification the shared socket sends when it claims the slot.
+     *
+     * Opt-in on purpose: `_all` exposes this provider's tools and prompts to
+     * every client of the aggregate slot, so a provider that does not ask for it
+     * stays reachable only on its own slot.
+     *
+     * ORDERING: the broker runs `initialize` against a newly aggregated provider
+     * immediately, and drops it from `_all` without a word if the handshake times
+     * out. The registration goes out from {@link MultiplexTransport.connect}, so
+     * assign `onMessage` (or hand this transport to an MCP server, which assigns
+     * it for you) *before* connecting. Connecting first and wiring the handler
+     * afterwards loses the broker's `initialize`, and the provider silently never
+     * appears in `_all`.
+     */
+    aggregate?: boolean;
+    /**
+     * Rejects a `broker.declare()` / `broker.authorize()` the broker did not
+     * answer within this many ms. Off by default: a broker from 1.4.1 on answers
+     * at once. Only for an older broker, which drops methods it does not know.
+     */
+    brokerRequestTimeoutMs?: number;
+    /**
+     * The provider secret, sent as the `X-Provider-Token` header of the
+     * WebSocket handshake. Required by a broker that authenticates providers
+     * (`providerSecret`, or the security file's `providers` table, where it is
+     * what gives this provider its own identity).
+     *
+     * **Node only.** Node's `WebSocket` (22 and later) accepts handshake
+     * headers; a browser's does not, and a browser provider cannot
+     * authenticate (terminate provider auth in a reverse proxy instead).
+     */
+    secret?: string;
+    /** Extra handshake headers, Node only, like {@link secret}. */
+    headers?: Readonly<Record<string, string>>;
 }
 /**
  * A transport that multiplexes multiple MCP servers over a single shared
@@ -77,19 +456,36 @@ declare class MultiplexSocket {
 declare class MultiplexTransport implements IMessageTransport {
     private readonly _name;
     private readonly _socket;
+    private readonly _aggregate;
     private _registered;
     onMessage: ((data: string) => void) | null;
     onOpen: (() => void) | null;
     onClose: (() => void) | null;
     onError: ((error: Error) => void) | null;
-    constructor(name: string, socket: MultiplexSocket);
+    /**
+     * The broker's own methods for this slot: declaring an authorization
+     * domain, asking for decisions. Its answers are taken off the socket
+     * before {@link onMessage} sees anything.
+     */
+    readonly broker: BrokerClient;
+    constructor(name: string, socket: MultiplexSocket, options?: IMultiplexTransportOptions);
+    /**
+     * One frame from the broker for this slot: the broker's answer to one of
+     * {@link broker}'s requests, or MCP traffic for the server.
+     * @internal Called by the shared socket.
+     */
+    _receive(frame: string): void;
     /**
      * Convenience factory: creates a {@link MultiplexTransport} backed by a
      * shared {@link MultiplexSocket} for the given tunnel URL.
      *
      * Transports targeting the same `wsUrl` automatically share one WebSocket.
+     *
+     * @param wsUrl The broker's shared multiplex base, `ws://<broker>/providers`.
+     *              A slot-scoped `/provider/<name>` URL belongs to
+     *              {@link DirectTransport} and is warned about on connect.
      */
-    static create(name: string, wsUrl: string): MultiplexTransport;
+    static create(name: string, wsUrl: string, options?: IMultiplexTransportOptions): MultiplexTransport;
     get isOpen(): boolean;
     /**
      * Registers this transport with the shared socket.
@@ -109,4 +505,4 @@ declare class MultiplexTransport implements IMessageTransport {
     close(): void;
 }
 
-export { DirectTransport, MultiplexTransport };
+export { AUDIT_RESULT_NOTIFICATION_METHOD, BrokerClient, BrokerRequestError, CALLER_META_KEY, DirectTransport, type IAuditResult, type IAuthorizationAnswer, type IAuthorizationCheck, type IAuthorizationDecision, type IAuthorizationDeclaration, type IAuthorizationObligations, type IAuthorizationQuery, type IBrokerClientOptions, type ICallerReference, type IDeclarationAccepted, type IDeclaredResource, type IDirectTransportOptions, type IMultiplexTransportOptions, type IResourceLimits, type ITelemetryEvent, type ITelemetrySpan, type ITraceParent, MultiplexTransport, TELEMETRY_NOTIFICATION_METHOD, TRACEPARENT_META_KEY, type TelemetryAttributeValue, callerReferenceOf, childTraceparent, formatTraceparent, parseTraceparent, traceparentOf, withTraceparent };