@cyanmycelium/mcp-broker 1.3.0 → 1.3.2

package/dist/grammars/claude/en.json

@@ -4,7 +4,7 @@
             "description": "Get the broker's identity: name, version, uptime, host, port, TLS, and URL paths. Call this first when you need to know what you are talking to."
         },
         "providers_list": {
-            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, current client count, and how many requests are in flight. Use this to discover what you can route to."
+            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, whether the provider is in `_all`, when it attached, the current client count, and how many requests are in flight. The counts are the slot's callers, not the provider: a connected provider nobody is calling reads all zeros. Use this to discover what you can route to."
         },
         "provider_status": {
             "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist, start with providers_list if you are not sure of the name.",

package/dist/grammars/claude/fr.json

@@ -4,7 +4,7 @@
             "description": "Récupère l'identité du broker : nom, version, uptime, hôte, port, TLS et chemins URL. À appeler en premier pour savoir à qui tu parles."
         },
         "providers_list": {
-            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, le nombre de clients actuels et le nombre de requêtes en cours. Utilise-le pour découvrir vers qui tu peux router."
+            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, l'appartenance à `_all`, la date de connexion du provider, le nombre de clients actuels et le nombre de requêtes en cours. Les compteurs sont ceux des appelants du slot, pas du provider : un provider connecté que personne n'appelle affiche des zéros. Utilise-le pour découvrir vers qui tu peux router."
         },
         "provider_status": {
             "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas, commence par providers_list si tu n'es pas sûr du nom.",

package/dist/grammars/default/en.json

@@ -4,7 +4,7 @@
             "description": "Returns the broker's name, version, uptime, host, port, TLS status, and configured URL paths."
         },
         "providers_list": {
-            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, client count, and pending request count."
+            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, `_all` membership, when the provider attached, client count, and pending request count. The counts are the slot's callers, not the provider: a connected provider nobody is calling reads all zeros."
         },
         "provider_status": {
             "description": "Returns the status of one provider slot identified by name. Errors if the slot does not exist.",

package/dist/grammars/default/fr.json

@@ -4,7 +4,7 @@
             "description": "Retourne le nom, la version, l'uptime, l'hôte, le port, l'état TLS et les chemins URL du broker."
         },
         "providers_list": {
-            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur nombre de clients et le nombre de requêtes en attente."
+            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur appartenance à `_all`, la date de connexion du provider, leur nombre de clients et le nombre de requêtes en attente. Les compteurs sont ceux des appelants du slot, pas du provider : un provider connecté que personne n'appelle affiche des zéros."
         },
         "provider_status": {
             "description": "Retourne l'état d'un emplacement de provider identifié par son nom. Échoue si le provider n'existe pas.",

package/dist/grammars/default/zh.json

@@ -4,7 +4,7 @@
             "description": "返回 broker 的名称、版本、运行时间、主机、端口、TLS 状态和已配置的 URL 路径。"
         },
         "providers_list": {
-            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、客户端数量和待处理请求数量。"
+            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、是否属于 `_all`、provider 的接入时间、客户端数量和待处理请求数量。计数针对槽位的调用方而非 provider：已连接但无人调用的 provider 显示全零。"
         },
         "provider_status": {
             "description": "返回由名称标识的某个 provider 槽位的状态。如果槽位不存在则返回错误。",

package/dist/index.d.ts

@@ -98,7 +98,26 @@ interface IBrokerProviderInfo {
     transport: BrokerProviderTransport;
     /** `true` iff the slot is reachable for routing right now. */
     connected: boolean;
-    /** Number of raw-WebSocket MCP clients on this slot. */
+    /**
+     * `true` when the provider is a member of the `_all` aggregate right now:
+     * it opted in and its `initialize` went through. The other side of
+     * {@link IBrokerAggregateInfo.providers}, per slot.
+     */
+    aggregate: boolean;
+    /**
+     * When the provider now serving the slot attached, ISO-8601; `null`
+     * while nothing serves it. Survives nothing: a reconnection is a new
+     * date, which is the point (a slot that says "since 3 s ago" every time
+     * you look is flapping).
+     */
+    connectedSince: string | null;
+    /** Milliseconds since `connectedSince`, computed at the time of the call; `null` when disconnected. */
+    connectedForMs: number | null;
+    /**
+     * Number of raw-WebSocket MCP clients on this slot. Clients, not the
+     * provider: a connected provider nobody is calling reads
+     * `clientCount: 0, sessionCount: 0, pendingCount: 0`.
+     */
     clientCount: number;
     /** Number of long-lived sessions (SSE + Streamable HTTP GET streams). */
     sessionCount: number;
@@ -1441,6 +1460,17 @@ declare class WsTunnel implements IBrokerContext {
     getSecurityInfo(): IBrokerSecurityInfo;
     /** Slot the stdio bridge is pinned to, or `null` when there is no bridge. */
     getStdioBridgeTarget(): string | null;
+    /**
+     * Membership of the `_all` aggregate, for `broker_diagnose`.
+     *
+     * Before `start()` the aggregate server does not exist yet, so an enabled
+     * aggregate reports no provider rather than `undefined`: "cannot be read"
+     * is for a host that has no aggregate at all, not for one that has not
+     * started. Without this accessor the CLI's own broker skipped the
+     * `aggregate-empty` check and told the operator to call tools/list on
+     * `_all` by hand.
+     */
+    getAggregateInfo(): IBrokerAggregateInfo;
     getProvidersInfo(): IBrokerProviderInfo[];
     getProviderInfo(name: string): IBrokerProviderInfo | undefined;
     private _buildProviderInfo;

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AuthError, 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, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, BrokerGuideAdapter, BrokerGuideBehavior, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, 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 } from './chunk-BZUZYXVA.js';
+export { AuthError, 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, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, BrokerGuideAdapter, BrokerGuideBehavior, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, 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 } from './chunk-J5TN5RYU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cyanmycelium/mcp-broker",
-    "version": "1.3.0",
+    "version": "1.3.2",
     "description": "WebSocket-based Model Context Protocol broker. Aggregates multiple MCP providers behind a single endpoint with stdio, SSE, and Streamable HTTP client transports.",
     "type": "module",
     "license": "Apache-2.0",
@@ -49,6 +49,7 @@
         }
     },
     "scripts": {
+        "leak-probe": "node --expose-gc scripts/leak-probe.mjs",
         "build": "tsup && npm run copy:assets",
         "clean": "rimraf dist",
         "copy:assets": "node scripts/copy-assets.mjs",

package/scripts/leak-probe.mjs

@@ -0,0 +1,156 @@
+/**
+ * Leak probe: the soak's round, in-process, with the garbage collector forced
+ * and the broker's own collections counted between batches.
+ *
+ * The soak reports RSS, which grows for reasons that are not leaks (V8 sizes
+ * its heap to the load and rarely gives pages back). This script asks the
+ * question the soak cannot: after a full GC, does the live heap keep growing
+ * with the number of rounds, and if so, which Map or Set inside the broker is
+ * growing with it.
+ *
+ *   node --expose-gc scripts/leak-probe.mjs [rounds=2000] [provider-binary]
+ *
+ * The provider is the C sample (c/build/samples/host-provider), aggregate, so
+ * the three surfaces the soak drives are exercised: the slot, `_all`, and
+ * `_broker`. Prints one line per batch; a leak reads as a heapUsed column that
+ * climbs batch after batch, and as the collection that climbs with it.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import * as url from "node:url";
+
+import { WsTunnelBuilder } from "../dist/index.js";
+import { connectMcp, toolText, waitForBroker } from "../../../../samples/lib/mcp-http-client.mjs";
+
+if (typeof globalThis.gc !== "function") {
+    console.error("run with: node --expose-gc scripts/leak-probe.mjs");
+    process.exit(2);
+}
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repo = path.resolve(here, "..", "..", "..", "..");
+const ROUNDS = Number(process.argv[2] ?? 2000);
+const BATCH = 250;
+const SLOT = "probe";
+
+function providerBinary() {
+    const given = process.argv[3];
+    const candidates = given
+        ? [given]
+        : ["host-provider", "host-provider.exe"].map((f) => path.join(repo, "c", "build", "samples", "host-provider", f));
+    const found = candidates.find((c) => existsSync(c));
+    if (!found) {
+        console.error(`host-provider not found (${candidates.join(", ")}); build c/ first`);
+        process.exit(2);
+    }
+    return found;
+}
+
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on("error", reject);
+    });
+}
+
+/** Every Map and Set reachable one level down from `obj`, with its size. */
+function collections(obj, prefix) {
+    const out = [];
+    if (!obj || typeof obj !== "object") return out;
+    for (const key of Object.getOwnPropertyNames(obj)) {
+        const v = obj[key];
+        if (v instanceof Map || v instanceof Set) out.push([`${prefix}.${key}`, v.size]);
+    }
+    return out;
+}
+
+function snapshot(tunnel) {
+    const rows = [...collections(tunnel, "tunnel"), ...collections(tunnel._brokerServer, "_broker"), ...collections(tunnel._aggregateServer, "_all")];
+    for (const [name, state] of tunnel._providers) {
+        rows.push(...collections(state, `slot(${name})`));
+        if (state.httpEndpoint) rows.push([`slot(${name}).endpoint.sessions`, state.httpEndpoint.sessionCount ?? state.httpEndpoint._sessions?.size ?? -1]);
+    }
+    return rows;
+}
+
+async function round(base, n) {
+    const text = `probe ${n}`;
+    const c = await connectMcp(base, SLOT);
+    await c.listTools();
+    const reply = toolText(await c.callTool("echo", { text }));
+    if (reply !== `${SLOT}: ${text}`) throw new Error(`echo mismatch: ${reply}`);
+    await c.close();
+
+    const a = await connectMcp(base, "_all");
+    const via = toolText(await a.callTool(`${SLOT}-echo`, { text }));
+    if (via !== `${SLOT}: ${text}`) throw new Error(`_all mismatch: ${via}`);
+    await a.close();
+
+    if (n % 50 === 0) {
+        const b = await connectMcp(base, "_broker");
+        await b.callTool("providers_list");
+        await b.callTool("broker_diagnose");
+        await b.close();
+    }
+}
+
+async function main() {
+    const port = await freePort();
+    const base = `http://127.0.0.1:${port}`;
+    const tunnel = new WsTunnelBuilder().withPort(port).withHost("127.0.0.1").withProviderHeartbeat(2000).build();
+    await tunnel.start();
+    await waitForBroker(base);
+
+    const provider = spawn(providerBinary(), ["--host", "127.0.0.1", "--port", String(port), "--name", SLOT, "--aggregate", "--retry-initial", "200"], {
+        stdio: ["ignore", "ignore", "inherit"],
+    });
+    await new Promise((r) => setTimeout(r, 800));
+
+    const mb = (b) => (b / 1048576).toFixed(1);
+    let previous = null;
+    const report = (label) => {
+        globalThis.gc();
+        globalThis.gc();
+        const m = process.memoryUsage();
+        const rows = snapshot(tunnel);
+        const grew = previous ? rows.filter(([k, v]) => v > (previous.get(k) ?? 0)) : [];
+        console.log(
+            `${label.padEnd(12)} heapUsed=${mb(m.heapUsed)}MB rss=${mb(m.rss)}MB external=${mb(m.external)}MB` +
+                (grew.length ? ` | growing: ${grew.map(([k, v]) => `${k}=${v}`).join(" ")}` : " | no collection grew")
+        );
+        previous = new Map(rows);
+        return m.heapUsed;
+    };
+
+    // Warm-up rounds first: JIT, caches, and the first sessions all allocate
+    // once; what matters is the slope after that.
+    for (let n = 1; n <= BATCH; n++) await round(base, n);
+    const baseline = report("warm-up");
+    const samples = [];
+    for (let n = BATCH + 1; n <= ROUNDS; n++) {
+        await round(base, n);
+        if (n % BATCH === 0) samples.push(report(`round ${n}`));
+    }
+
+    console.log("\ncollections after the last batch:");
+    for (const [k, v] of snapshot(tunnel)) if (v > 0) console.log(`  ${k} = ${v}`);
+
+    const last = samples[samples.length - 1] ?? baseline;
+    const perRound = (last - baseline) / Math.max(1, ROUNDS - BATCH);
+    console.log(`\nlive heap after GC: ${mb(baseline)}MB after warm-up -> ${mb(last)}MB after ${ROUNDS} rounds (${perRound.toFixed(0)} bytes per round)`);
+
+    provider.kill();
+    await tunnel.stop();
+    process.exit(0);
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/src/broker/aggregate/aggregate.server.ts

@@ -163,6 +163,16 @@ export class AggregateServer implements IMessageTransport {
         }
     }
 
+    /**
+     * Slot names currently contributing to the aggregate, in registration
+     * order. A provider whose handshake failed is not in it: `addProvider`
+     * removed it. This is what `broker_diagnose` reads through
+     * `IBrokerContext.getAggregateInfo()`.
+     */
+    get providerNames(): readonly string[] {
+        return [...this._sessions.keys()];
+    }
+
     /** Removes a provider from the aggregate. */
     removeProvider(name: string): void {
         const session = this._sessions.get(name);

package/src/broker/broker.context.ts

@@ -129,7 +129,29 @@ export interface IBrokerProviderInfo {
     /** `true` iff the slot is reachable for routing right now. */
     connected: boolean;
 
-    /** Number of raw-WebSocket MCP clients on this slot. */
+    /**
+     * `true` when the provider is a member of the `_all` aggregate right now:
+     * it opted in and its `initialize` went through. The other side of
+     * {@link IBrokerAggregateInfo.providers}, per slot.
+     */
+    aggregate: boolean;
+
+    /**
+     * When the provider now serving the slot attached, ISO-8601; `null`
+     * while nothing serves it. Survives nothing: a reconnection is a new
+     * date, which is the point (a slot that says "since 3 s ago" every time
+     * you look is flapping).
+     */
+    connectedSince: string | null;
+
+    /** Milliseconds since `connectedSince`, computed at the time of the call; `null` when disconnected. */
+    connectedForMs: number | null;
+
+    /**
+     * Number of raw-WebSocket MCP clients on this slot. Clients, not the
+     * provider: a connected provider nobody is calling reads
+     * `clientCount: 0, sessionCount: 0, pendingCount: 0`.
+     */
     clientCount: number;
 
     /** Number of long-lived sessions (SSE + Streamable HTTP GET streams). */

package/src/broker/grammars/claude/en.json

@@ -4,7 +4,7 @@
             "description": "Get the broker's identity: name, version, uptime, host, port, TLS, and URL paths. Call this first when you need to know what you are talking to."
         },
         "providers_list": {
-            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, current client count, and how many requests are in flight. Use this to discover what you can route to."
+            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, whether the provider is in `_all`, when it attached, the current client count, and how many requests are in flight. The counts are the slot's callers, not the provider: a connected provider nobody is calling reads all zeros. Use this to discover what you can route to."
         },
         "provider_status": {
             "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist, start with providers_list if you are not sure of the name.",

package/src/broker/grammars/claude/fr.json

@@ -4,7 +4,7 @@
             "description": "Récupère l'identité du broker : nom, version, uptime, hôte, port, TLS et chemins URL. À appeler en premier pour savoir à qui tu parles."
         },
         "providers_list": {
-            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, le nombre de clients actuels et le nombre de requêtes en cours. Utilise-le pour découvrir vers qui tu peux router."
+            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, l'appartenance à `_all`, la date de connexion du provider, le nombre de clients actuels et le nombre de requêtes en cours. Les compteurs sont ceux des appelants du slot, pas du provider : un provider connecté que personne n'appelle affiche des zéros. Utilise-le pour découvrir vers qui tu peux router."
         },
         "provider_status": {
             "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas, commence par providers_list si tu n'es pas sûr du nom.",

package/src/broker/grammars/default/en.json

@@ -4,7 +4,7 @@
             "description": "Returns the broker's name, version, uptime, host, port, TLS status, and configured URL paths."
         },
         "providers_list": {
-            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, client count, and pending request count."
+            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, `_all` membership, when the provider attached, client count, and pending request count. The counts are the slot's callers, not the provider: a connected provider nobody is calling reads all zeros."
         },
         "provider_status": {
             "description": "Returns the status of one provider slot identified by name. Errors if the slot does not exist.",

package/src/broker/grammars/default/fr.json

@@ -4,7 +4,7 @@
             "description": "Retourne le nom, la version, l'uptime, l'hôte, le port, l'état TLS et les chemins URL du broker."
         },
         "providers_list": {
-            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur nombre de clients et le nombre de requêtes en attente."
+            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur appartenance à `_all`, la date de connexion du provider, leur nombre de clients et le nombre de requêtes en attente. Les compteurs sont ceux des appelants du slot, pas du provider : un provider connecté que personne n'appelle affiche des zéros."
         },
         "provider_status": {
             "description": "Retourne l'état d'un emplacement de provider identifié par son nom. Échoue si le provider n'existe pas.",

package/src/broker/grammars/default/zh.json

@@ -4,7 +4,7 @@
             "description": "返回 broker 的名称、版本、运行时间、主机、端口、TLS 状态和已配置的 URL 路径。"
         },
         "providers_list": {
-            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、客户端数量和待处理请求数量。"
+            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、是否属于 `_all`、provider 的接入时间、客户端数量和待处理请求数量。计数针对槽位的调用方而非 provider：已连接但无人调用的 provider 显示全零。"
         },
         "provider_status": {
             "description": "返回由名称标识的某个 provider 槽位的状态。如果槽位不存在则返回错误。",

package/src/ws/ws.interfaces.ts

@@ -169,6 +169,12 @@ export interface IPendingRequest {
 export interface IProviderState {
     /** The active provider WebSocket, or `null` when the provider is not connected. */
     ws: WebSocket | null;
+    /**
+     * `Date.now()` when the provider currently serving the slot attached
+     * (socket, upstream or loopback), `null` while nothing serves it. What
+     * `providers_list` reports as `connectedSince`.
+     */
+    connectedSinceMs: number | null;
     /**
      * In-flight requests, keyed by the **broker-assigned** id that was written
      * into the frame sent to the provider. See {@link IPendingRequest.clientId}

package/src/ws/ws.tunnel.ts

@@ -19,7 +19,7 @@ import type { IBrokerContext, IBrokerProviderInfo, BrokerProviderTransport } fro
 // Imported from the defining module rather than the barrel: these two are the
 // optional `IBrokerContext` extensions `broker_diagnose` reads, and the barrel
 // does not re-export them yet.
-import type { IBrokerSecurityInfo } from "../broker/broker.context";
+import type { IBrokerAggregateInfo, IBrokerSecurityInfo } from "../broker/broker.context";
 import { AggregateServer } from "../broker/aggregate/aggregate.server";
 import {
     HttpAuthGuard,
@@ -433,6 +433,23 @@ export class WsTunnel implements IBrokerContext {
         return this._options.stdioClient?.providerName ?? null;
     }
 
+    /**
+     * Membership of the `_all` aggregate, for `broker_diagnose`.
+     *
+     * Before `start()` the aggregate server does not exist yet, so an enabled
+     * aggregate reports no provider rather than `undefined`: "cannot be read"
+     * is for a host that has no aggregate at all, not for one that has not
+     * started. Without this accessor the CLI's own broker skipped the
+     * `aggregate-empty` check and told the operator to call tools/list on
+     * `_all` by hand.
+     */
+    public getAggregateInfo(): IBrokerAggregateInfo {
+        return {
+            enabled: this._options.enableAggregateProvider !== false,
+            providers: this._aggregateServer?.providerNames ?? [],
+        };
+    }
+
     public getProvidersInfo(): IBrokerProviderInfo[] {
         const out: IBrokerProviderInfo[] = [];
         for (const [name, state] of this._providers) {
@@ -465,10 +482,17 @@ export class WsTunnel implements IBrokerContext {
             connected = false;
         }
 
+        // `connected` is decided above from what is actually open; the
+        // timestamp only says since when, and is withheld when they disagree
+        // (an upstream that opened once and is now closed keeps no date).
+        const since = connected ? state.connectedSinceMs : null;
         return {
             name,
             transport,
             connected,
+            aggregate: this._aggregateServer?.providerNames.includes(name) ?? false,
+            connectedSince: since !== null ? new Date(since).toISOString() : null,
+            connectedForMs: since !== null ? Math.max(0, Date.now() - since) : null,
             clientCount: state.wsClients.size,
             sessionCount: state.sseSessions.size + state.httpSessions.size,
             pendingCount: state.pending.size,
@@ -496,6 +520,7 @@ export class WsTunnel implements IBrokerContext {
 
         const state = this._getOrCreateProviderState(name);
         this._loopbackProviders.set(name, transport);
+        state.connectedSinceMs = Date.now();
 
         transport.onMessage = (data: string) => this._routeFromProvider(state, name, data);
         transport.onClose = () => {
@@ -681,9 +706,10 @@ export class WsTunnel implements IBrokerContext {
                         const state = this._providers.get(cfg.name);
                         if (state) this._failProviderDisconnected(state, cfg.name);
                     };
-                    if (cfg.aggregate) {
-                        upstream.onOpen = () => void this._aggregateServer?.addProvider(cfg.name);
-                    }
+                    upstream.onOpen = () => {
+                        this._getOrCreateProviderState(cfg.name).connectedSinceMs = Date.now();
+                        if (cfg.aggregate) void this._aggregateServer?.addProvider(cfg.name);
+                    };
                     this._upstreams.set(cfg.name, upstream);
                     upstream.connect();
                 };
@@ -1921,6 +1947,7 @@ export class WsTunnel implements IBrokerContext {
 
         const state = this._getOrCreateProviderState(name);
         state.ws = ws;
+        state.connectedSinceMs = Date.now();
         this._watchProviderSocket(ws);
         if (providerPrincipal) {
             this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
@@ -2208,6 +2235,7 @@ export class WsTunnel implements IBrokerContext {
                 providerNames.add(name);
                 const state = this._getOrCreateProviderState(name);
                 state.ws = ws;
+                state.connectedSinceMs = Date.now();
                 if (providerPrincipal) {
                     this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
                 }
@@ -2462,6 +2490,7 @@ export class WsTunnel implements IBrokerContext {
      * close handlers (dedicated WS, multiplexed WS, loopback).
      */
     private _failProviderDisconnected(state: IProviderState, name: string): void {
+        state.connectedSinceMs = null;
         // Echoing the **client's** id rather than `null` or the broker's: a
         // Streamable HTTP session matches the answer to its held-open POST by
         // the id it chose, so an unaddressed error would leave that request
@@ -2499,6 +2528,7 @@ export class WsTunnel implements IBrokerContext {
         if (!state) {
             state = {
                 ws: null,
+                connectedSinceMs: null,
                 pending: new Map(),
                 sseSessions: new Map(),
                 httpSessions: new Map(),