@thotischner/observability-mcp 3.0.0 → 3.0.1

package/dist/sdk/hook-wrappers.d.ts

@@ -0,0 +1,39 @@
+import type { HookRegistry } from "./hooks.js";
+export interface HookCtxBase {
+    /** Principal sub identifier from the caller's RequestContext. */
+    principal: string;
+    /** Tenant the caller is acting under. */
+    tenant: string;
+    /** Tool / resource / prompt target identifier. */
+    target: string;
+}
+type ToolHandler = (args: unknown, extra: unknown) => Promise<unknown> | unknown;
+type ResourceHandler = (uri: URL | string, extra?: unknown) => Promise<unknown> | unknown;
+type PromptHandler = (args: unknown, extra?: unknown) => Promise<unknown> | unknown;
+/**
+ * Wrap a tool handler with `tool_pre_invoke` + `tool_post_invoke`
+ * hooks. Existing wire-up in index.ts is inlined; extracting it here
+ * for parity with the new resource + prompt wrappers and so tests
+ * can exercise the path without spinning up the full server.
+ */
+export declare function wrapToolHandler(registry: HookRegistry, ctx: HookCtxBase, handler: ToolHandler): ToolHandler;
+/**
+ * Wrap a resource readCallback with `resource_pre_fetch` +
+ * `resource_post_fetch` hooks.
+ *
+ * Pre-fetch sees `{uri}`; the payload's `uri` can be mutated (e.g. a
+ * canonicalising plugin) and the override flows into the original
+ * handler. Post-fetch sees `{uri, contents}`; the post-payload's
+ * `contents` (if set) replaces the response.
+ */
+export declare function wrapResourceHandler(registry: HookRegistry, ctx: HookCtxBase, handler: ResourceHandler): ResourceHandler;
+/**
+ * Wrap a prompt callback with `prompt_pre_fetch` + `prompt_post_fetch`
+ * hooks.
+ *
+ * Pre-fetch sees `{name, arguments}`; the override flows in. Post-fetch
+ * sees `{name, arguments, messages}`; the post-payload's `messages`
+ * (if set) replaces the response messages.
+ */
+export declare function wrapPromptHandler(registry: HookRegistry, ctx: HookCtxBase, handler: PromptHandler): PromptHandler;
+export {};

package/dist/sdk/hook-wrappers.js

@@ -0,0 +1,113 @@
+// Reusable hook-fire wrappers around the MCP SDK's tool / resource /
+// prompt callbacks.
+//
+// Each wrapper fires the matching `*_pre_*` hook before the original
+// handler runs and `*_post_*` after it returns. Hooks can:
+//   - deny the call (allow:false → caller sees a structured error)
+//   - mutate the payload before dispatch (args / uri / arguments)
+//   - mutate the result before it reaches the caller (contents /
+//     messages / tool result)
+//
+// When no hooks are registered (the default in the OSS demo) the
+// wrappers are thin pass-throughs.
+//
+// The wrappers are pure — they take the HookRegistry + a ctx object
+// and a handler, and return the wrapped handler. They never touch
+// the McpServer SDK directly, so they're trivially unit-testable.
+/** Shape an MCP tool dispatch returns on a hook denial. */
+function deniedToolResult(reason) {
+    return {
+        content: [{ type: "text", text: reason ?? "denied by plugin hook" }],
+        isError: true,
+    };
+}
+/** Shape an MCP resource read returns on a hook denial. */
+function deniedResourceResult(uri, reason) {
+    return {
+        contents: [
+            { uri, mimeType: "text/plain", text: reason ?? "denied by plugin hook" },
+        ],
+        isError: true,
+    };
+}
+/** Shape an MCP prompt fetch returns on a hook denial. */
+function deniedPromptResult(reason) {
+    return {
+        description: reason ?? "denied by plugin hook",
+        messages: [],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler with `tool_pre_invoke` + `tool_post_invoke`
+ * hooks. Existing wire-up in index.ts is inlined; extracting it here
+ * for parity with the new resource + prompt wrappers and so tests
+ * can exercise the path without spinning up the full server.
+ */
+export function wrapToolHandler(registry, ctx, handler) {
+    return async (args, extra) => {
+        const pre = await registry.fire("tool_pre_invoke", { ...ctx, kind: "tool_pre_invoke" }, { args });
+        if (!pre.allow)
+            return deniedToolResult(pre.reason);
+        const effectiveArgs = pre.payload?.args ?? args;
+        const result = await handler(effectiveArgs, extra);
+        const post = await registry.fire("tool_post_invoke", { ...ctx, kind: "tool_post_invoke" }, { args: effectiveArgs, result });
+        if (!post.allow)
+            return deniedToolResult(post.reason);
+        return post.payload?.result ?? result;
+    };
+}
+/**
+ * Wrap a resource readCallback with `resource_pre_fetch` +
+ * `resource_post_fetch` hooks.
+ *
+ * Pre-fetch sees `{uri}`; the payload's `uri` can be mutated (e.g. a
+ * canonicalising plugin) and the override flows into the original
+ * handler. Post-fetch sees `{uri, contents}`; the post-payload's
+ * `contents` (if set) replaces the response.
+ */
+export function wrapResourceHandler(registry, ctx, handler) {
+    return async (uri, extra) => {
+        const uriStr = uri instanceof URL ? uri.toString() : String(uri);
+        const pre = await registry.fire("resource_pre_fetch", { ...ctx, kind: "resource_pre_fetch" }, { uri: uriStr });
+        if (!pre.allow)
+            return deniedResourceResult(uriStr, pre.reason);
+        const effectiveUri = pre.payload?.uri ?? uriStr;
+        // Preserve URL vs string typing the SDK expects.
+        const forwardedUri = uri instanceof URL && effectiveUri !== uriStr ? new URL(effectiveUri) : (uri instanceof URL ? uri : effectiveUri);
+        const result = await handler(forwardedUri, extra);
+        const post = await registry.fire("resource_post_fetch", { ...ctx, kind: "resource_post_fetch" }, { uri: effectiveUri, contents: result?.contents });
+        if (!post.allow)
+            return deniedResourceResult(effectiveUri, post.reason);
+        const overrideContents = post.payload?.contents;
+        if (overrideContents !== undefined && result && typeof result === "object") {
+            return { ...result, contents: overrideContents };
+        }
+        return result;
+    };
+}
+/**
+ * Wrap a prompt callback with `prompt_pre_fetch` + `prompt_post_fetch`
+ * hooks.
+ *
+ * Pre-fetch sees `{name, arguments}`; the override flows in. Post-fetch
+ * sees `{name, arguments, messages}`; the post-payload's `messages`
+ * (if set) replaces the response messages.
+ */
+export function wrapPromptHandler(registry, ctx, handler) {
+    return async (args, extra) => {
+        const pre = await registry.fire("prompt_pre_fetch", { ...ctx, kind: "prompt_pre_fetch" }, { name: ctx.target, arguments: args });
+        if (!pre.allow)
+            return deniedPromptResult(pre.reason);
+        const effectiveArgs = pre.payload?.arguments ?? args;
+        const result = await handler(effectiveArgs, extra);
+        const post = await registry.fire("prompt_post_fetch", { ...ctx, kind: "prompt_post_fetch" }, { name: ctx.target, arguments: effectiveArgs, messages: result?.messages });
+        if (!post.allow)
+            return deniedPromptResult(post.reason);
+        const overrideMessages = post.payload?.messages;
+        if (overrideMessages !== undefined && result && typeof result === "object") {
+            return { ...result, messages: overrideMessages };
+        }
+        return result;
+    };
+}

package/dist/sdk/hook-wrappers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/hook-wrappers.test.js

@@ -0,0 +1,204 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { HookRegistry } from "./hooks.js";
+import { wrapToolHandler, wrapResourceHandler, wrapPromptHandler, } from "./hook-wrappers.js";
+const CTX = { principal: "alice", tenant: "default", target: "x" };
+// --- tool ------------------------------------------------------------
+test("wrapToolHandler: no hooks → pass-through", async () => {
+    const reg = new HookRegistry();
+    const wrapped = wrapToolHandler(reg, CTX, async (args) => ({ content: [{ type: "text", text: `got ${JSON.stringify(args)}` }] }));
+    const r = await wrapped({ q: 1 }, undefined);
+    assert.deepEqual(r, { content: [{ type: "text", text: 'got {"q":1}' }] });
+});
+test("wrapToolHandler: pre-invoke denial → isError + reason; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "tool_pre_invoke",
+        handler: () => ({ allow: false, reason: "blocked" }),
+    });
+    const wrapped = wrapToolHandler(reg, CTX, async () => {
+        called = true;
+        return { content: [] };
+    });
+    const r = await wrapped({}, undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, { content: [{ type: "text", text: "blocked" }], isError: true });
+});
+test("wrapToolHandler: pre-invoke args mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "enrich",
+        kind: "tool_pre_invoke",
+        handler: (_ctx, payload) => ({
+            allow: true,
+            payload: { args: { ...payload.args, injected: true } },
+        }),
+    });
+    let observedArgs;
+    const wrapped = wrapToolHandler(reg, CTX, async (args) => {
+        observedArgs = args;
+        return { content: [] };
+    });
+    await wrapped({ original: 1 }, undefined);
+    assert.deepEqual(observedArgs, { original: 1, injected: true });
+});
+test("wrapToolHandler: post-invoke result mutation flows back to caller", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "redact",
+        kind: "tool_post_invoke",
+        handler: () => ({ allow: true, payload: { result: { content: [{ type: "text", text: "REDACTED" }] } } }),
+    });
+    const wrapped = wrapToolHandler(reg, CTX, async () => ({
+        content: [{ type: "text", text: "secret-value" }],
+    }));
+    const r = await wrapped({}, undefined);
+    assert.deepEqual(r, { content: [{ type: "text", text: "REDACTED" }] });
+});
+// --- resource --------------------------------------------------------
+test("wrapResourceHandler: no hooks → pass-through with original URI", async () => {
+    const reg = new HookRegistry();
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "hi" }] };
+    });
+    const r = await wrapped("file:///a", undefined);
+    assert.equal(observed, "file:///a");
+    assert.deepEqual(r, { contents: [{ uri: "file:///a", text: "hi" }] });
+});
+test("wrapResourceHandler: pre-fetch denial returns structured error; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: false, reason: "forbidden uri" }),
+    });
+    const wrapped = wrapResourceHandler(reg, CTX, async () => {
+        called = true;
+        return { contents: [] };
+    });
+    const r = await wrapped("file:///secret", undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, {
+        contents: [{ uri: "file:///secret", mimeType: "text/plain", text: "forbidden uri" }],
+        isError: true,
+    });
+});
+test("wrapResourceHandler: pre-fetch URI mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "canon",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: true, payload: { uri: "file:///canonical" } }),
+    });
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "ok" }] };
+    });
+    await wrapped("file:///raw", undefined);
+    assert.equal(observed, "file:///canonical");
+});
+test("wrapResourceHandler: URL instance preserved across mutation", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "canon",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: true, payload: { uri: "https://new.example/path" } }),
+    });
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "ok" }] };
+    });
+    await wrapped(new URL("https://old.example/path"), undefined);
+    assert.ok(observed instanceof URL, "mutated URI should still be a URL when caller passed one");
+    assert.equal(String(observed), "https://new.example/path");
+});
+test("wrapResourceHandler: post-fetch contents replacement", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "censor",
+        kind: "resource_post_fetch",
+        handler: () => ({ allow: true, payload: { contents: [{ uri: "file:///x", text: "[censored]" }] } }),
+    });
+    const wrapped = wrapResourceHandler(reg, CTX, async () => ({
+        contents: [{ uri: "file:///x", text: "raw" }],
+        _meta: { kept: true },
+    }));
+    const r = (await wrapped("file:///x", undefined));
+    assert.deepEqual(r.contents, [{ uri: "file:///x", text: "[censored]" }]);
+    // Other top-level keys survive the mutation
+    assert.deepEqual(r._meta, { kept: true });
+});
+// --- prompt ----------------------------------------------------------
+test("wrapPromptHandler: no hooks → pass-through", async () => {
+    const reg = new HookRegistry();
+    const wrapped = wrapPromptHandler(reg, { ...CTX, target: "greet" }, async (args) => ({
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: `hi ${JSON.stringify(args)}` } }],
+    }));
+    const r = await wrapped({ who: "world" }, undefined);
+    assert.deepEqual(r, {
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: 'hi {"who":"world"}' } }],
+    });
+});
+test("wrapPromptHandler: pre-fetch denial returns structured error; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "prompt_pre_fetch",
+        handler: () => ({ allow: false, reason: "denied" }),
+    });
+    const wrapped = wrapPromptHandler(reg, CTX, async () => {
+        called = true;
+        return { description: "x", messages: [] };
+    });
+    const r = await wrapped({}, undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, { description: "denied", messages: [], isError: true });
+});
+test("wrapPromptHandler: pre-fetch arguments mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "augment",
+        kind: "prompt_pre_fetch",
+        handler: (_ctx, payload) => ({
+            allow: true,
+            payload: { name: payload.name, arguments: { ...payload.arguments, extra: 1 } },
+        }),
+    });
+    let observed;
+    const wrapped = wrapPromptHandler(reg, CTX, async (args) => {
+        observed = args;
+        return { description: "", messages: [] };
+    });
+    await wrapped({ original: true }, undefined);
+    assert.deepEqual(observed, { original: true, extra: 1 });
+});
+test("wrapPromptHandler: post-fetch messages replacement", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "rewrite",
+        kind: "prompt_post_fetch",
+        handler: () => ({
+            allow: true,
+            payload: {
+                messages: [{ role: "system", content: { type: "text", text: "rewritten" } }],
+            },
+        }),
+    });
+    const wrapped = wrapPromptHandler(reg, CTX, async () => ({
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: "raw" } }],
+    }));
+    const r = (await wrapped({}, undefined));
+    assert.equal(r.description, "ok");
+    assert.deepEqual(r.messages, [{ role: "system", content: { type: "text", text: "rewritten" } }]);
+});

package/dist/sdk/index.d.ts

@@ -42,6 +42,19 @@ export interface ConnectorManifest {
      * server runs with VERIFY_PLUGINS=true. See docs/plugin-architecture.md.
      */
     integrity?: string;
+    /**
+     * Lifecycle hooks the plugin wants auto-registered on load. Each
+     * entry points to a module path INSIDE the plugin's bundled files;
+     * the loader imports its default export and registers it on the
+     * gateway's HookRegistry. Mirrors the Zod manifestSchema in
+     * mcp-server/src/sdk/manifest-schema.ts. See Q10 / phase-q-sprint.md.
+     */
+    hooks?: Array<{
+        kind: "tool_pre_invoke" | "tool_post_invoke" | "resource_pre_fetch" | "resource_post_fetch" | "prompt_pre_fetch" | "prompt_post_fetch";
+        module: string;
+        priority?: number;
+        mode?: "enforce" | "permissive" | "disabled";
+    }>;
 }
 /**
  * The default export shape a connector plugin module must provide.

package/dist/tools/detect-anomalies.d.ts

@@ -22,11 +22,22 @@ export declare const detectAnomaliesDefinition: {
         };
     };
 };
+export interface AnomalyHistorySink {
+    record(entry: {
+        ts: string;
+        service: string;
+        tenant: string;
+        score: number;
+        method: string;
+        severity: string;
+        signal?: string;
+    }): Promise<void> | void;
+}
 export declare function detectAnomaliesHandler(registry: ConnectorRegistry, args: {
     service?: string;
     duration?: string;
     sensitivity?: string;
-}, ctx?: RequestContext): Promise<{
+}, ctx?: RequestContext, history?: AnomalyHistorySink): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/detect-anomalies.js

@@ -33,7 +33,7 @@ const KEY_METRICS = ["cpu", "memory", "error_rate", "latency_p99", "request_rate
 // the overall error ratio is low (e.g. a memory leak emits a handful of
 // "OutOfMemoryWarning" lines long before it turns into 5xx errors).
 const CRITICAL_LOG_PATTERN = /\b(out\s?of\s?memory|oom|outofmemory|heap (usage|exhaust)|memory leak|panic|fatal|deadlock|segfault|stack overflow|cannot allocate)\b/i;
-export async function detectAnomaliesHandler(registry, args, ctx = defaultContext()) {
+export async function detectAnomaliesHandler(registry, args, ctx = defaultContext(), history) {
     const duration = args.duration || "10m";
     const threshold = SENSITIVITY_THRESHOLDS[args.sensitivity || "medium"] || 2.0;
     // Discover services to scan — tenant-scoped.
@@ -72,9 +72,10 @@ export async function detectAnomaliesHandler(registry, args, ctx = defaultContex
                         const deviationPercent = anomaly.baselineValue === 0
                             ? 100
                             : Math.round(((anomaly.recentValue - anomaly.baselineValue) / anomaly.baselineValue) * 100);
+                        const severityLabel = Math.abs(anomaly.score) >= 6 ? "high" : Math.abs(anomaly.score) >= 4 ? "medium" : "low";
                         allAnomalies.push({
                             metric,
-                            severity: Math.abs(anomaly.score) >= 6 ? "high" : Math.abs(anomaly.score) >= 4 ? "medium" : "low",
+                            severity: severityLabel,
                             description: `${metric}: ${anomaly.reason}`,
                             currentValue: anomaly.recentValue,
                             baselineValue: anomaly.baselineValue,
@@ -82,6 +83,25 @@ export async function detectAnomaliesHandler(registry, args, ctx = defaultContex
                             source: connector.name,
                             service: serviceName,
                         });
+                        // Phase P1: mirror the score to the TSDB sink (no-op if no
+                        // sink wired). Best-effort — a slow / down sink must never
+                        // block the detector loop, which is why we don't await.
+                        if (history) {
+                            try {
+                                void history.record({
+                                    ts: new Date().toISOString(),
+                                    service: serviceName,
+                                    tenant: ctx.tenant || "default",
+                                    score: Math.abs(anomaly.score),
+                                    method: anomaly.method === "seasonal" ? "seasonality"
+                                        : anomaly.method === "robust-z" ? "mad"
+                                            : anomaly.method,
+                                    severity: severityLabel === "high" ? "critical" : severityLabel === "medium" ? "warn" : "info",
+                                    signal: metric,
+                                });
+                            }
+                            catch { /* swallow — best-effort */ }
+                        }
                     }
                 }
                 catch {

package/dist/tools/topology.js

@@ -14,10 +14,10 @@
 // connector later requires zero changes here.
 import { isTopologyProvider } from "../connectors/interface.js";
 import { defaultContext } from "../context.js";
+import { mergeTopologies } from "../topology/merge.js";
 export async function aggregateTopology(registry, tenant) {
     const sources = [];
-    const resources = [];
-    const edges = [];
+    const snapshots = [];
     // Tenant-scoped when a tenant is supplied (call sites at the MCP
     // tool layer pass ctx.tenant); undefined preserves the original
     // global behaviour for internal / non-request callers.
@@ -34,14 +34,32 @@ export async function aggregateTopology(registry, tenant) {
                 resources: snap.resources.length,
                 edges: snap.edges.length,
             });
-            resources.push(...snap.resources);
-            edges.push(...snap.edges);
+            snapshots.push(snap);
         }
         catch {
             // A misbehaving connector must not poison the agent's view of the graph.
         }
     }
-    return { sources, resources, edges };
+    // P1: run the snapshots through mergeTopologies so workloads
+    // surfaced by more than one provider (e.g. the same Deployment
+    // observed by both Kubernetes + a service-mesh connector) collapse
+    // into a single canonical node and edges are rewritten to match.
+    //
+    // ONLY engages for multi-source topologies — with a single snapshot
+    // the merger would mis-group intra-source siblings that happen to
+    // share a canonical label (e.g. two pod replicas with
+    // `app.kubernetes.io/name=api`). The merger is designed for
+    // cross-provider de-duplication, not intra-provider.
+    if (snapshots.length <= 1) {
+        const only = snapshots[0];
+        return {
+            sources,
+            resources: only?.resources ?? [],
+            edges: only?.edges ?? [],
+        };
+    }
+    const merged = mergeTopologies(snapshots);
+    return { sources, resources: merged.resources, edges: merged.edges };
 }
 /**
  * Resolve a caller-supplied identifier to a Resource. Accepts:

package/dist/tools/topology.test.js

@@ -208,3 +208,48 @@ describe("get_blast_radius tool", () => {
         assert.equal(apiBucket.ownershipRootKind, "deployment");
     });
 });
+// --- Multi-source merge (Phase P1 wiring) ----------------------------
+// `aggregateTopology` now delegates to `mergeTopologies` when 2+
+// snapshots are present so the same logical workload reported by
+// e.g. Kubernetes + a cloud connector collapses into one node.
+// Single-snapshot calls pass through unchanged (guarded so we don't
+// mis-merge intra-source siblings that share an `app:` label).
+describe("aggregateTopology — multi-source merger (P1 wire)", () => {
+    it("collapses cross-source duplicates that share a canonical label", async () => {
+        // Source A (k8s): one Deployment "checkout" in prod
+        const aRes = [
+            { id: "k8s:deployment:prod/checkout", kind: "deployment", name: "checkout", source: "k8s",
+                labels: { "app.kubernetes.io/name": "checkout" } },
+        ];
+        // Source B (trace provider): the same logical service
+        const bRes = [
+            { id: "tempo:service:checkout", kind: "trace_service", name: "checkout", source: "tempo",
+                labels: { "service.name": "checkout" } },
+        ];
+        const loader = new PluginLoader();
+        const reg = new ConnectorRegistry(loader);
+        const connA = new FakeTopologyConnector(aRes, []);
+        const connB = new FakeTopologyConnector(bRes, []);
+        await connA.connect({ name: "k8s", type: "fake", url: "", enabled: true });
+        await connB.connect({ name: "tempo", type: "fake", url: "", enabled: true });
+        const loaderInternal = loader;
+        loaderInternal.connectors.set("fake-a", { name: "fake-a", source: "builtin", factory: () => connA });
+        loaderInternal.connectors.set("fake-b", { name: "fake-b", source: "builtin", factory: () => connB });
+        await reg.addSource({ name: "k8s", type: "fake-a", url: "", enabled: true });
+        await reg.addSource({ name: "tempo", type: "fake-b", url: "", enabled: true });
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        // 2 sources reported in summary
+        assert.equal(out.sources.length, 2);
+        // But ONE resource after merge (deployment + trace_service of the
+        // same canonical name collapse via MERGEABLE_KIND_PAIRS).
+        assert.equal(out.resources.length, 1);
+        assert.equal(out.resources[0].name, "checkout");
+    });
+    it("single-source passes through unchanged (no intra-source merging)", async () => {
+        // The existing 4-pod fixture has two pods sharing `app: api`.
+        // With a single snapshot the merger must NOT collapse them.
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.equal(out.resources.length, fixture().resources.length);
+    });
+});

package/dist/transport/transportSessionMap.d.ts

@@ -0,0 +1,70 @@
+import type { SessionStore } from "./sessionStore.js";
+export interface TransportSessionMeta {
+    /** Stable id of the replica that owns the underlying SDK
+     *  Transport object. Set on creation. */
+    ownerReplica: string;
+    /** Optional virtual-server product slug. Undefined for the
+     *  root /mcp surface. */
+    product?: string;
+    /** Epoch ms — bumped on every successful request. */
+    lastActive: number;
+}
+export interface TransportSessionMap {
+    /** Stable backend identifier (used in /api/info diagnostics). */
+    readonly backend: string;
+    /** True iff there's a metadata entry — does NOT imply a local
+     *  Transport exists. */
+    has(sessionId: string): Promise<boolean>;
+    get(sessionId: string): Promise<TransportSessionMeta | undefined>;
+    set(sessionId: string, meta: TransportSessionMeta, ttlSeconds?: number): Promise<void>;
+    /** Convenience: bump lastActive while preserving the rest. */
+    touch(sessionId: string, ttlSeconds?: number): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    /** Return every session id this map knows about. Used for the
+     *  cleanup tick. Implementations MAY cap; in-memory returns the
+     *  full set, Redis pages via SCAN under the prefix. */
+    keys(): Promise<string[]>;
+    /** Evict entries with lastActive older than `maxIdleMs`. Returns
+     *  the evicted ids (caller logs / records metrics). */
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+export declare class InMemoryTransportSessionMap implements TransportSessionMap {
+    readonly backend = "memory";
+    private readonly map;
+    has(id: string): Promise<boolean>;
+    get(id: string): Promise<TransportSessionMeta | undefined>;
+    set(id: string, meta: TransportSessionMeta): Promise<void>;
+    touch(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    keys(): Promise<string[]>;
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+/**
+ * Wraps an existing SessionStore so the per-session metadata lives
+ * wherever the SessionStore decided — InMemorySessionStore (no
+ * cross-replica visibility, identical to InMemoryTransportSessionMap
+ * but useful for tests / when a future backend is plugged in) or
+ * RedisSessionStore (cross-replica safe).
+ *
+ * Each entry stored at `<KEY_PREFIX><sessionId>` as JSON.
+ */
+export declare class SessionStoreBackedTransportSessionMap implements TransportSessionMap {
+    readonly backend: string;
+    private readonly store;
+    private readonly defaultTtlSeconds;
+    constructor(store: SessionStore, defaultTtlSeconds?: number);
+    has(id: string): Promise<boolean>;
+    get(id: string): Promise<TransportSessionMeta | undefined>;
+    set(id: string, meta: TransportSessionMeta, ttlSeconds?: number): Promise<void>;
+    touch(id: string, ttlSeconds?: number): Promise<void>;
+    delete(id: string): Promise<void>;
+    keys(): Promise<string[]>;
+    cleanup(maxIdleMs: number): Promise<string[]>;
+}
+/**
+ * Pick the right implementation. When `sessionStore` is the
+ * in-memory default, return InMemoryTransportSessionMap so we
+ * avoid the (synchronous → async) layering tax. Otherwise wrap
+ * the supplied store.
+ */
+export declare function createTransportSessionMap(sessionStore?: SessionStore): TransportSessionMap;