@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/tools/query-metrics.js

@@ -30,12 +30,12 @@ export const queryMetricsDefinition = {
         required: ["service", "metric"],
     },
 };
-export async function queryMetricsHandler(registry, args, _ctx = defaultContext()) {
+export async function queryMetricsHandler(registry, args, ctx = defaultContext()) {
     // Coarse single-tenant source scoping: if the principal is restricted to a
     // source allow-list, deny an explicit out-of-scope source.
-    if (_ctx.allowedSources &&
+    if (ctx.allowedSources &&
         args.source &&
-        !_ctx.allowedSources.includes(args.source)) {
+        !ctx.allowedSources.includes(args.source)) {
         return errorResponse(`forbidden: source "${args.source}" is not in your allowed sources`);
     }
     const svcErr = validateServiceName(args.service);
@@ -51,12 +51,25 @@ export async function queryMetricsHandler(registry, args, _ctx = defaultContext(
     if (args.groupBy && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(args.groupBy)) {
         return errorResponse(`Invalid groupBy "${args.groupBy}". Must be a valid Prometheus label name (alphanumeric + underscore, starting with letter/underscore).`);
     }
+    // Tenant-scoped resolution: an explicit `source` from the agent
+    // must belong to the caller's tenant (or be a global / untagged
+    // source) — cross-tenant sources resolve to undefined exactly like
+    // a missing source, preserving the no-existence-leak posture used
+    // elsewhere in the tenancy layer.
     const connectors = args.source
-        ? [registry.getByName(args.source)].filter(Boolean)
-        : registry.getBySignal("metrics");
+        ? [registry.getByNameForTenant(args.source, ctx.tenant)].filter(Boolean)
+        : registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "metrics");
     if (connectors.length === 0) {
+        // Distinct messages but identical posture: the source-named branch
+        // could land here either because the source doesn't exist OR
+        // belongs to another tenant — both surface as "not found", same
+        // shape, no existence leak. The fan-out branch lands here only on
+        // an empty registry.
+        const msg = args.source
+            ? `Source "${args.source}" not found`
+            : "No metrics backends configured";
         return {
-            content: [{ type: "text", text: JSON.stringify({ error: "No metrics backends configured" }) }],
+            content: [{ type: "text", text: JSON.stringify({ error: msg }) }],
             isError: true,
         };
     }

package/dist/tools/query-traces.d.ts

@@ -0,0 +1,47 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+import { type RequestContext } from "../context.js";
+export declare const queryTracesDefinition: {
+    name: "query_traces";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            service: {
+                type: string;
+                description: string;
+            };
+            duration: {
+                type: string;
+                description: string;
+            };
+            filter: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            errorsOnly: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function queryTracesHandler(registry: ConnectorRegistry, args: {
+    service: string;
+    duration?: string;
+    filter?: string;
+    limit?: number;
+    errorsOnly?: boolean;
+}, ctx?: RequestContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}>;
+/** Pure percentile over a numeric array. Returns 0 for empty input. */
+export declare function percentile(values: number[], p: number): number;

package/dist/tools/query-traces.js

@@ -0,0 +1,145 @@
+// query_traces — Phase F13.
+//
+// Surfaces distributed traces from any connector that implements the
+// queryTraces capability. Fans out across every traces-signal
+// connector in the caller's tenant, merges the returned trace
+// summaries, and recomputes a global p50/p95 over the merged set
+// (rather than blindly averaging per-source summaries).
+//
+// Backend support today: a Tempo connector + a Jaeger shim ship as
+// filesystem plugins. Any connector that implements queryTraces
+// participates automatically — no changes needed in the tool layer
+// when a new backend lands.
+import { defaultContext } from "../context.js";
+import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+export const queryTracesDefinition = {
+    name: "query_traces",
+    description: [
+        "Query distributed traces for a service over a given timeframe.",
+        "Returns ranked trace summaries with duration, error status, and span count, plus a p50/p95 duration aggregate across the returned set.",
+        "When to use: investigating tail-latency outliers, walking call chains across services for a known time window, or pulling related traces for an anomaly the metric/log tools surfaced first.",
+        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned.",
+        "Related: `query_metrics` for the per-service latency series; `get_blast_radius` for the topology a trace traverses.",
+    ].join(" "),
+    inputSchema: {
+        type: "object",
+        properties: {
+            service: { type: "string", description: "Service name (e.g. 'payment-service')" },
+            duration: { type: "string", description: "Rolling time window (e.g. '5m', '1h'). Default '15m'." },
+            filter: { type: "string", description: "Backend-native filter (TraceQL on Tempo, tag query on Jaeger). Optional." },
+            limit: { type: "number", description: "Soft cap on returned trace summaries. Default 50." },
+            errorsOnly: { type: "boolean", description: "If true, only traces with at least one error span." },
+        },
+        required: ["service"],
+    },
+};
+export async function queryTracesHandler(registry, args, ctx = defaultContext()) {
+    const svcErr = validateServiceName(args.service);
+    if (svcErr)
+        return errorResponse(svcErr);
+    const duration = args.duration || "15m";
+    const durationErr = validateDuration(duration);
+    if (durationErr)
+        return errorResponse(durationErr);
+    // signalType filter: traces-aware connectors should report "traces"
+    // (the new signal type) but we also accept any connector that
+    // declares queryTraces — back-compat for connectors that haven't
+    // updated their signalType yet.
+    const candidates = registry
+        .getByTenant(ctx.tenant)
+        .filter((c) => typeof c.queryTraces === "function");
+    if (candidates.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "No trace backends configured" }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const results = [];
+    const errors = [];
+    for (const connector of candidates) {
+        if (!connector.queryTraces)
+            continue;
+        try {
+            const r = await connector.queryTraces({
+                service: args.service,
+                duration,
+                filter: args.filter,
+                limit: args.limit,
+                errorsOnly: args.errorsOnly,
+            });
+            results.push(r);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Trace query failed on ${connector.name}:`, msg);
+            errors.push(`${connector.name}: ${msg}`);
+        }
+    }
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: errors.length > 0 ? `Query failed: ${errors.join("; ")}` : "No traces returned",
+                        service: args.service,
+                        duration,
+                    }),
+                },
+            ],
+            isError: errors.length > 0,
+        };
+    }
+    // Merge: every source returns its own ranked set; we keep the union
+    // and recompute a global p50/p95 over the merged set so the summary
+    // reflects what the tool actually returned to the caller.
+    const merged = [];
+    for (const r of results)
+        merged.push(...r.traces);
+    // Sort hottest-first by duration, then truncate to the requested limit.
+    merged.sort((a, b) => b.durationMs - a.durationMs);
+    const limit = args.limit ?? 50;
+    const capped = merged.slice(0, limit);
+    const errorCount = capped.filter((t) => t.hasError).length;
+    const summary = {
+        total: capped.length,
+        errorCount,
+        p50DurationMs: percentile(capped.map((t) => t.durationMs), 0.5),
+        p95DurationMs: percentile(capped.map((t) => t.durationMs), 0.95),
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    service: args.service,
+                    duration,
+                    sources: results.map((r) => r.source),
+                    summary,
+                    traces: capped,
+                    errors: errors.length > 0 ? errors : undefined,
+                }),
+            },
+        ],
+        isError: false,
+    };
+}
+/** Pure percentile over a numeric array. Returns 0 for empty input. */
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    // Linear interpolation between the two surrounding samples.
+    const rank = p * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo] ?? 0;
+    const frac = rank - lo;
+    return Math.round((sorted[lo] ?? 0) * (1 - frac) + (sorted[hi] ?? 0) * frac);
+}

package/dist/tools/query-traces.test.d.ts

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

package/dist/tools/query-traces.test.js

@@ -0,0 +1,110 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { queryTracesHandler, percentile } from "./query-traces.js";
+function span(traceId, durationMs, opts = {}) {
+    return {
+        traceId,
+        rootName: "GET /pay",
+        rootService: opts.service ?? "payment-service",
+        durationMs,
+        spanCount: 4,
+        hasError: opts.hasError ?? false,
+        startTs: "2026-06-06T00:00:00.000Z",
+    };
+}
+function fakeRegistry(connectors) {
+    return {
+        getByTenant: (_tenant) => connectors,
+    };
+}
+function parseResponse(r) {
+    return JSON.parse(r.content[0].text);
+}
+test("percentile: empty → 0; single value → that value; linear interpolation otherwise", () => {
+    assert.equal(percentile([], 0.5), 0);
+    assert.equal(percentile([10], 0.5), 10);
+    assert.equal(percentile([1, 2, 3, 4, 5], 0.5), 3);
+    // 95th of [1..20] sits between index 18 (19) and 19 (20)
+    const vs = Array.from({ length: 20 }, (_, i) => i + 1);
+    assert.ok(percentile(vs, 0.95) >= 19 && percentile(vs, 0.95) <= 20);
+});
+test("query_traces: rejects invalid service name", async () => {
+    const r = await queryTracesHandler(fakeRegistry([]), { service: "bad name with space" });
+    assert.equal(r.isError, true);
+});
+test("query_traces: rejects invalid duration", async () => {
+    const r = await queryTracesHandler(fakeRegistry([]), { service: "ok", duration: "bogus" });
+    assert.equal(r.isError, true);
+});
+test("query_traces: no trace backends configured → isError + clear message", async () => {
+    // Connectors without queryTraces are skipped.
+    const conn = { name: "prom", signalType: "metrics" };
+    const r = await queryTracesHandler(fakeRegistry([conn]), { service: "ok" });
+    assert.equal(r.isError, true);
+    assert.match(parseResponse(r).error, /No trace backends/);
+});
+test("query_traces: merges spans from every connector that returned, caps to limit, ranks by duration", async () => {
+    const tempo = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "tempo",
+            service: "payment",
+            traces: [span("aaa", 100), span("bbb", 800), span("ccc", 300)],
+            summary: { total: 3, errorCount: 0, p50DurationMs: 300, p95DurationMs: 800 },
+        }),
+    };
+    const jaeger = {
+        name: "jaeger",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "jaeger",
+            service: "payment",
+            traces: [span("ddd", 500, { hasError: true }), span("eee", 200)],
+            summary: { total: 2, errorCount: 1, p50DurationMs: 350, p95DurationMs: 500 },
+        }),
+    };
+    const r = await queryTracesHandler(fakeRegistry([tempo, jaeger]), { service: "payment", limit: 4 });
+    const body = parseResponse(r);
+    assert.deepEqual(body.sources.sort(), ["jaeger", "tempo"]);
+    assert.equal(body.traces.length, 4, "limit honoured");
+    // Sorted hottest-first
+    assert.equal(body.traces[0].durationMs, 800);
+    assert.equal(body.traces[1].durationMs, 500);
+    assert.equal(body.summary.errorCount, 1);
+});
+test("query_traces: surfaces per-connector errors but still returns successful results", async () => {
+    const ok = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => ({
+            source: "tempo",
+            service: "payment",
+            traces: [span("aaa", 50)],
+            summary: { total: 1, errorCount: 0, p50DurationMs: 50, p95DurationMs: 50 },
+        }),
+    };
+    const broken = {
+        name: "jaeger",
+        signalType: "metrics",
+        queryTraces: async () => {
+            throw new Error("upstream 503");
+        },
+    };
+    const r = await queryTracesHandler(fakeRegistry([ok, broken]), { service: "payment" });
+    const body = parseResponse(r);
+    assert.equal(body.errors.length, 1);
+    assert.equal(body.traces.length, 1);
+});
+test("query_traces: all backends fail → isError true + errors surfaced", async () => {
+    const broken = {
+        name: "tempo",
+        signalType: "metrics",
+        queryTraces: async () => {
+            throw new Error("upstream gone");
+        },
+    };
+    const r = await queryTracesHandler(fakeRegistry([broken]), { service: "payment" });
+    assert.equal(r.isError, true);
+    assert.match(parseResponse(r).error, /upstream gone/);
+});

package/dist/tools/registry-names.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical list of MCP tool names exposed by createMcpServer().
+ *
+ * Used by:
+ *   - the Product validator (typo guard): a Product's `tools` allow-
+ *     list must reference names that actually register, otherwise a
+ *     bound credential opens an /mcp session with an empty tool set
+ *     and the agent silently fails.
+ *   - the keystone integration test in registry-names.test.ts that
+ *     reads index.ts and asserts the registerTool() call sites match
+ *     this list 1:1 — a missing entry or an extra one trips the test.
+ *
+ * Keep this list and the registerTool("name", ...) calls in
+ * createMcpServer in sync. The test enforces it.
+ */
+export declare const REGISTERED_TOOL_NAMES: readonly ["list_sources", "list_services", "query_metrics", "query_logs", "query_traces", "get_service_health", "detect_anomalies", "get_anomaly_history", "generate_postmortem", "get_topology", "get_blast_radius"];
+export type RegisteredToolName = typeof REGISTERED_TOOL_NAMES[number];
+/** Functional category of a tool, surfaced in /api/tools/registry and
+ *  used by the Products UI to group the multi-select picker. Keeps
+ *  operator-facing taxonomy stable even when tool descriptions evolve. */
+export type ToolCategory = "discovery" | "query" | "diagnose" | "topology";
+export interface ToolRegistryEntry {
+    name: RegisteredToolName;
+    category: ToolCategory;
+    /** One-liner — what the tool does, no fluff. The full multi-paragraph
+     *  description lives in createMcpServer's registerTool() call; this
+     *  is the catalogue summary the picker shows alongside the name. */
+    summary: string;
+}
+export declare const REGISTERED_TOOLS: readonly ToolRegistryEntry[];
+/** Validate a candidate Product tools[] array. Returns the unknown
+ *  names (empty array = all OK). Pure helper — the caller decides
+ *  how to surface the rejection (the API handler emits a 422 with a
+ *  hint of valid names; the YAML loader could decide to warn). */
+export declare function unknownToolNames(tools: readonly string[]): string[];

package/dist/tools/registry-names.js

@@ -0,0 +1,54 @@
+/**
+ * Canonical list of MCP tool names exposed by createMcpServer().
+ *
+ * Used by:
+ *   - the Product validator (typo guard): a Product's `tools` allow-
+ *     list must reference names that actually register, otherwise a
+ *     bound credential opens an /mcp session with an empty tool set
+ *     and the agent silently fails.
+ *   - the keystone integration test in registry-names.test.ts that
+ *     reads index.ts and asserts the registerTool() call sites match
+ *     this list 1:1 — a missing entry or an extra one trips the test.
+ *
+ * Keep this list and the registerTool("name", ...) calls in
+ * createMcpServer in sync. The test enforces it.
+ */
+export const REGISTERED_TOOL_NAMES = [
+    "list_sources",
+    "list_services",
+    "query_metrics",
+    "query_logs",
+    "query_traces",
+    "get_service_health",
+    "detect_anomalies",
+    "get_anomaly_history",
+    "generate_postmortem",
+    "get_topology",
+    "get_blast_radius",
+];
+export const REGISTERED_TOOLS = [
+    { name: "list_sources", category: "discovery", summary: "List configured observability backends + reachability." },
+    { name: "list_services", category: "discovery", summary: "Discover service names across every connected backend." },
+    { name: "query_metrics", category: "query", summary: "Fetch the raw time-series for one metric of one service over a window." },
+    { name: "query_logs", category: "query", summary: "Fetch matching log lines for one service over a window." },
+    { name: "query_traces", category: "query", summary: "Fetch ranked trace summaries for one service over a window." },
+    { name: "get_service_health", category: "diagnose", summary: "Aggregated health verdict for one service (metrics + logs)." },
+    { name: "detect_anomalies", category: "diagnose", summary: "Scan for anomalous services using z-score / heuristics." },
+    { name: "get_anomaly_history", category: "diagnose", summary: "Replay historical anomaly scores for a service (post-mortem context)." },
+    { name: "generate_postmortem", category: "diagnose", summary: "One-shot markdown post-mortem stitching anomaly history + traces + blast-radius + logs for a service." },
+    { name: "get_topology", category: "topology", summary: "Return the infrastructure topology graph (resources + edges)." },
+    { name: "get_blast_radius", category: "topology", summary: "Given a resource, return the impact set if its host(s) fail." },
+];
+/** Validate a candidate Product tools[] array. Returns the unknown
+ *  names (empty array = all OK). Pure helper — the caller decides
+ *  how to surface the rejection (the API handler emits a 422 with a
+ *  hint of valid names; the YAML loader could decide to warn). */
+export function unknownToolNames(tools) {
+    const known = new Set(REGISTERED_TOOL_NAMES);
+    const out = [];
+    for (const t of tools) {
+        if (!known.has(t))
+            out.push(t);
+    }
+    return out;
+}

package/dist/tools/registry-names.test.d.ts

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

package/dist/tools/registry-names.test.js

@@ -0,0 +1,61 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { REGISTERED_TOOL_NAMES, REGISTERED_TOOLS, unknownToolNames } from "./registry-names.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = join(here, "..", "index.ts");
+test("REGISTERED_TOOL_NAMES — 1:1 with createMcpServer's registerTool() calls", () => {
+    // This is the integration-test-shaped guard: if a future PR adds
+    // or removes a tool registration in index.ts without updating
+    // REGISTERED_TOOL_NAMES, the Product validator will silently
+    // accept or reject the wrong names. We parse index.ts as text and
+    // assert the registered set matches the constant exactly.
+    const src = readFileSync(INDEX_TS, "utf8");
+    // registerTool("name", → captures the first argument of every call site.
+    const re = /\bregisterTool\(\s*"([a-z_][a-z0-9_]*)"/g;
+    const found = [];
+    for (const m of src.matchAll(re))
+        found.push(m[1]);
+    found.sort();
+    const expected = [...REGISTERED_TOOL_NAMES].sort();
+    assert.deepEqual(found, expected, `registerTool() call sites in index.ts don't match REGISTERED_TOOL_NAMES. ` +
+        `Add or remove names in src/tools/registry-names.ts to match the actual ` +
+        `registrations.\n  found: ${JSON.stringify(found)}\n  expected: ${JSON.stringify(expected)}`);
+});
+test("unknownToolNames — empty input → no unknowns", () => {
+    assert.deepEqual(unknownToolNames([]), []);
+});
+test("unknownToolNames — every registered name is accepted", () => {
+    assert.deepEqual(unknownToolNames([...REGISTERED_TOOL_NAMES]), []);
+});
+test("unknownToolNames — surfaces typos and unknown names verbatim", () => {
+    const r = unknownToolNames(["list_sources", "query_logz", "get_topologyy"]);
+    assert.deepEqual(r, ["query_logz", "get_topologyy"]);
+});
+test("unknownToolNames — case-sensitive (MCP spec)", () => {
+    // The spec requires exact name match; "List_Sources" is not the
+    // same tool as "list_sources" and silently accepting it would be a
+    // worse failure mode than rejecting (mismatched casing wouldn't
+    // route to a real tool).
+    assert.deepEqual(unknownToolNames(["List_Sources"]), ["List_Sources"]);
+});
+test("REGISTERED_TOOLS — every name has a category + summary", () => {
+    for (const t of REGISTERED_TOOLS) {
+        assert.ok(t.name, "name required");
+        assert.ok(t.category, `category required on ${t.name}`);
+        assert.ok(t.summary && t.summary.length > 10, `summary required on ${t.name}`);
+    }
+});
+test("REGISTERED_TOOLS — matches REGISTERED_TOOL_NAMES 1:1 (no drift)", () => {
+    const a = REGISTERED_TOOLS.map((t) => t.name).sort();
+    const b = [...REGISTERED_TOOL_NAMES].sort();
+    assert.deepEqual(a, b, "REGISTERED_TOOLS and REGISTERED_TOOL_NAMES must agree");
+});
+test("REGISTERED_TOOLS — every category is one of the four valid values", () => {
+    const valid = new Set(["discovery", "query", "diagnose", "topology"]);
+    for (const t of REGISTERED_TOOLS) {
+        assert.ok(valid.has(t.category), `unknown category '${t.category}' on ${t.name}`);
+    }
+});

package/dist/tools/topology.d.ts

@@ -12,7 +12,7 @@ interface AggregatedTopology {
     resources: Resource[];
     edges: Edge[];
 }
-export declare function aggregateTopology(registry: ConnectorRegistry): Promise<AggregatedTopology>;
+export declare function aggregateTopology(registry: ConnectorRegistry, tenant?: string): Promise<AggregatedTopology>;
 /**
  * Resolve a caller-supplied identifier to a Resource. Accepts:
  *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
@@ -35,7 +35,7 @@ export interface GetTopologyArgs {
     scope?: string;
     limit?: number;
 }
-export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, _ctx?: RequestContext): Promise<{
+export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;
@@ -48,7 +48,7 @@ export declare const getBlastRadiusDefinition: {
 export interface GetBlastRadiusArgs {
     resource: string;
 }
-export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, _ctx?: RequestContext): Promise<{
+export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, ctx?: RequestContext): Promise<{
     isError: boolean;
     content: {
         type: "text";

package/dist/tools/topology.js

@@ -14,11 +14,15 @@
 // connector later requires zero changes here.
 import { isTopologyProvider } from "../connectors/interface.js";
 import { defaultContext } from "../context.js";
-export async function aggregateTopology(registry) {
+export async function aggregateTopology(registry, tenant) {
     const sources = [];
     const resources = [];
     const edges = [];
-    for (const c of registry.getAll()) {
+    // 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.
+    const connectors = tenant ? registry.getByTenant(tenant) : registry.getAll();
+    for (const c of connectors) {
         if (!isTopologyProvider(c))
             continue;
         try {
@@ -79,8 +83,8 @@ export const getTopologyDefinition = {
     name: "get_topology",
     description: "Return the infrastructure topology graph as Resources and Edges. Use this when an agent needs to reason about which workload runs where, who owns whom, or which scope (namespace/project/folder) a resource belongs to.",
 };
-export async function getTopologyHandler(registry, args = {}, _ctx = defaultContext()) {
-    const agg = await aggregateTopology(registry);
+export async function getTopologyHandler(registry, args = {}, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     // Filtering — all optional. Filters compose conjunctively.
     let resources = agg.resources;
     let edges = agg.edges;
@@ -133,8 +137,8 @@ export const getBlastRadiusDefinition = {
     name: "get_blast_radius",
     description: "Given a resource, return the impact set if its underlying host(s) fail. Pivots on the generic RUNS_ON relation, so it works for pod→node, vm→hypervisor, container→host alike. Use this for cross-cutting RCA when several services degrade together.",
 };
-export async function getBlastRadiusHandler(registry, args, _ctx = defaultContext()) {
-    const agg = await aggregateTopology(registry);
+export async function getBlastRadiusHandler(registry, args, ctx = defaultContext()) {
+    const agg = await aggregateTopology(registry, ctx.tenant);
     const found = resolveResource(args.resource, agg.resources);
     if ("error" in found) {
         return {

package/dist/topology/merge.d.ts

@@ -0,0 +1,22 @@
+import type { Resource, Edge, TopologySnapshot } from "../types.js";
+/** Labels we treat as canonical-name carriers. First-match wins. */
+export declare const CANONICAL_LABEL_KEYS: readonly ["app.kubernetes.io/name", "app.kubernetes.io/instance", "app", "service", "service.name", "k8s-app"];
+/** Lower-cased label-key lookup; first match in CANONICAL_LABEL_KEYS
+ *  ordering wins so two providers with different label conventions
+ *  still converge if they both ship a known label. */
+export declare function canonicalNameFor(r: Resource): string | undefined;
+export interface MergeResult {
+    resources: Resource[];
+    edges: Edge[];
+    /** Map from original (source-scoped) id → merged canonical id. Used
+     *  to rewrite edges that referenced one of the collapsed nodes. */
+    idMap: Map<string, string>;
+}
+/**
+ * Merge a set of provider snapshots into one unified graph. The
+ * input is the flat union of every provider's resources+edges; the
+ * output collapses every group of nodes that share a canonical name
+ * (and a compatible kind) into a single node, then rewrites the
+ * edge endpoints accordingly.
+ */
+export declare function mergeTopologies(snapshots: TopologySnapshot[]): MergeResult;