@thotischner/observability-mcp 1.6.0 → 1.7.0

package/dist/tools/topology.d.ts

@@ -0,0 +1,64 @@
+import type { ConnectorRegistry } from "../connectors/registry.js";
+import type { Resource, Edge } from "../types.js";
+import { type RequestContext } from "../context.js";
+interface AggregatedTopology {
+    sources: Array<{
+        source: string;
+        type: string;
+        revision: number;
+        resources: number;
+        edges: number;
+    }>;
+    resources: Resource[];
+    edges: Edge[];
+}
+export declare function aggregateTopology(registry: ConnectorRegistry): Promise<AggregatedTopology>;
+/**
+ * Resolve a caller-supplied identifier to a Resource. Accepts:
+ *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
+ *   - exact resource name (e.g. "checkout-7f89d")
+ *   - case-insensitive substring of name (only used if uniquely matching)
+ *
+ * Stays generic — no knowledge of kind-specific id grammars.
+ */
+export declare function resolveResource(query: string, resources: Resource[]): Resource | {
+    error: string;
+    candidates?: string[];
+};
+export declare const getTopologyDefinition: {
+    name: "get_topology";
+    description: string;
+};
+export interface GetTopologyArgs {
+    source?: string;
+    kind?: string;
+    scope?: string;
+    limit?: number;
+}
+export declare function getTopologyHandler(registry: ConnectorRegistry, args?: GetTopologyArgs, _ctx?: RequestContext): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare const getBlastRadiusDefinition: {
+    name: "get_blast_radius";
+    description: string;
+};
+export interface GetBlastRadiusArgs {
+    resource: string;
+}
+export declare function getBlastRadiusHandler(registry: ConnectorRegistry, args: GetBlastRadiusArgs, _ctx?: RequestContext): Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+export {};

package/dist/tools/topology.js

@@ -0,0 +1,233 @@
+// MCP tools that expose the infrastructure topology graph to agents.
+//
+// Two tools live here:
+//   - `get_topology`     — returns the merged resource/edge graph across
+//                          every topology-capable connector, optionally
+//                          filtered by source/kind/scope. Useful as a
+//                          starting point for any cross-cutting question.
+//   - `get_blast_radius` — given a resource, returns who else is co-tenant
+//                          on the same host(s). The canonical "if this
+//                          host fails, who else fails?" question.
+//
+// Both stay generic — they pivot on the `RUNS_ON` and `OWNED_BY` relations
+// rather than any specific kind. Adding a vCenter/NetBox/AWS topology
+// connector later requires zero changes here.
+import { isTopologyProvider } from "../connectors/interface.js";
+import { defaultContext } from "../context.js";
+export async function aggregateTopology(registry) {
+    const sources = [];
+    const resources = [];
+    const edges = [];
+    for (const c of registry.getAll()) {
+        if (!isTopologyProvider(c))
+            continue;
+        try {
+            const snap = await c.getTopologySnapshot();
+            sources.push({
+                source: snap.source,
+                type: c.type,
+                revision: snap.revision,
+                resources: snap.resources.length,
+                edges: snap.edges.length,
+            });
+            resources.push(...snap.resources);
+            edges.push(...snap.edges);
+        }
+        catch {
+            // A misbehaving connector must not poison the agent's view of the graph.
+        }
+    }
+    return { sources, resources, edges };
+}
+/**
+ * Resolve a caller-supplied identifier to a Resource. Accepts:
+ *   - exact canonical id (e.g. "k8s:pod:default/checkout-7f89d")
+ *   - exact resource name (e.g. "checkout-7f89d")
+ *   - case-insensitive substring of name (only used if uniquely matching)
+ *
+ * Stays generic — no knowledge of kind-specific id grammars.
+ */
+export function resolveResource(query, resources) {
+    if (!query)
+        return { error: "Missing resource query" };
+    const exactId = resources.find((r) => r.id === query);
+    if (exactId)
+        return exactId;
+    const exactName = resources.filter((r) => r.name === query);
+    if (exactName.length === 1)
+        return exactName[0];
+    if (exactName.length > 1) {
+        return {
+            error: `Name '${query}' is ambiguous across ${exactName.length} resources; pass the full id`,
+            candidates: exactName.map((r) => r.id),
+        };
+    }
+    const q = query.toLowerCase();
+    const fuzzy = resources.filter((r) => r.name.toLowerCase().includes(q) || r.id.toLowerCase().includes(q));
+    if (fuzzy.length === 1)
+        return fuzzy[0];
+    if (fuzzy.length > 1) {
+        return {
+            error: `Query '${query}' matched ${fuzzy.length} resources; pass the full id`,
+            candidates: fuzzy.slice(0, 25).map((r) => r.id),
+        };
+    }
+    return { error: `No resource found matching '${query}'` };
+}
+// --- get_topology ------------------------------------------------------
+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);
+    // Filtering — all optional. Filters compose conjunctively.
+    let resources = agg.resources;
+    let edges = agg.edges;
+    if (args.source) {
+        resources = resources.filter((r) => r.source === args.source);
+        edges = edges.filter((e) => e.source === args.source);
+    }
+    if (args.kind) {
+        resources = resources.filter((r) => r.kind === args.kind);
+    }
+    if (args.scope) {
+        // Match either by scope resource id (e.g. "k8s:namespace:default") or by name (e.g. "default").
+        const inScope = new Set();
+        for (const e of agg.edges) {
+            if (e.relation !== "IN_NAMESPACE")
+                continue;
+            const target = agg.resources.find((r) => r.id === e.to);
+            if (!target)
+                continue;
+            if (target.id === args.scope || target.name === args.scope)
+                inScope.add(e.from);
+        }
+        resources = resources.filter((r) => inScope.has(r.id));
+    }
+    // Edges must still reference resources that survived filtering.
+    const keepIds = new Set(resources.map((r) => r.id));
+    edges = edges.filter((e) => keepIds.has(e.from) && keepIds.has(e.to));
+    // Soft truncation so an agent can't accidentally pull a 10k-node graph
+    // into context — defaults are generous but capped.
+    const limit = Math.min(Math.max(args.limit ?? 500, 1), 5000);
+    const truncated = resources.length > limit;
+    if (truncated) {
+        resources = resources.slice(0, limit);
+        const keep2 = new Set(resources.map((r) => r.id));
+        edges = edges.filter((e) => keep2.has(e.from) && keep2.has(e.to));
+    }
+    const payload = {
+        sources: agg.sources,
+        resources,
+        edges,
+        total: { resources: agg.resources.length, edges: agg.edges.length },
+        truncated,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+// --- get_blast_radius --------------------------------------------------
+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);
+    const found = resolveResource(args.resource, agg.resources);
+    if ("error" in found) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(found, null, 2) }],
+        };
+    }
+    // Index edges once.
+    const byId = new Map(agg.resources.map((r) => [r.id, r]));
+    const runsOnOut = new Map(); // child → host
+    const runsOnIn = new Map(); // host → children
+    const ownedByOut = new Map(); // child → owner
+    for (const e of agg.edges) {
+        if (e.relation === "RUNS_ON") {
+            runsOnOut.set(e.from, e.to);
+            const s = runsOnIn.get(e.to) || new Set();
+            s.add(e.from);
+            runsOnIn.set(e.to, s);
+        }
+        else if (e.relation === "OWNED_BY") {
+            if (!ownedByOut.has(e.from))
+                ownedByOut.set(e.from, e.to);
+        }
+    }
+    function ownershipRoot(id) {
+        let cur = id;
+        for (let i = 0; i < 16; i++) {
+            const next = ownedByOut.get(cur);
+            if (!next || next === cur)
+                return cur;
+            cur = next;
+        }
+        return cur;
+    }
+    // Determine which hosts the target depends on. If the resource is itself
+    // a host (incoming RUNS_ON exists), the host is the resource itself.
+    const hosts = [];
+    if (runsOnIn.has(found.id)) {
+        hosts.push(found.id);
+    }
+    else if (runsOnOut.has(found.id)) {
+        hosts.push(runsOnOut.get(found.id));
+    }
+    if (hosts.length === 0) {
+        const payload = {
+            target: { id: found.id, name: found.name, kind: found.kind },
+            hosts: [],
+            note: "This resource has no RUNS_ON edges in the current topology — either it is itself a top-level host with no tenants yet, or its connector does not emit RUNS_ON.",
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    }
+    const perHost = [];
+    for (const hostId of hosts) {
+        const host = byId.get(hostId);
+        if (!host)
+            continue;
+        const childIds = Array.from(runsOnIn.get(hostId) || []);
+        // Bucket children by their ownership root.
+        const buckets = new Map();
+        for (const cid of childIds) {
+            const child = byId.get(cid);
+            if (!child)
+                continue;
+            const rootId = ownershipRoot(cid);
+            const root = byId.get(rootId);
+            const bucket = buckets.get(rootId) || {
+                ownershipRoot: rootId,
+                ownershipRootName: root ? root.name : rootId,
+                ownershipRootKind: root ? root.kind : "?",
+                members: [],
+            };
+            bucket.members.push({ id: child.id, name: child.name, kind: child.kind });
+            buckets.set(rootId, bucket);
+        }
+        const coTenants = Array.from(buckets.values()).sort((a, b) => b.members.length - a.members.length);
+        perHost.push({
+            host: { id: host.id, name: host.name, kind: host.kind },
+            ownershipRoots: coTenants.length,
+            coTenants,
+        });
+    }
+    // Surface a one-line recommendation when ≥2 services share a host —
+    // exactly the "blast radius if it fails" case that justifies this tool.
+    const sharedHosts = perHost.filter((h) => h.ownershipRoots > 1);
+    const summary = sharedHosts.length > 0
+        ? `${sharedHosts.length} of ${perHost.length} host(s) carry ≥2 services — those hosts are blast-radius candidates if they fail.`
+        : `No host carries more than one service besides the target — limited shared-host blast radius.`;
+    const payload = {
+        target: { id: found.id, name: found.name, kind: found.kind },
+        hosts: perHost,
+        summary,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}

package/dist/tools/topology.test.d.ts

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

package/dist/tools/topology.test.js

@@ -0,0 +1,210 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { PluginLoader } from "../connectors/loader.js";
+import { getTopologyHandler, getBlastRadiusHandler, resolveResource, } from "./topology.js";
+// --- A minimal stand-alone topology connector used as test fixture -----
+// Lets the suite drive the tool handlers without a real K8s cluster.
+class FakeTopologyConnector {
+    type = "fake";
+    signalType = "topology";
+    name = "fake-cluster";
+    resources;
+    edges;
+    constructor(resources, edges) {
+        this.resources = resources;
+        this.edges = edges;
+    }
+    async connect(c) { this.name = c.name; }
+    async healthCheck() { return { status: "up", latencyMs: 1 }; }
+    async disconnect() { }
+    getDefaultMetrics() { return []; }
+    getMetrics() { return []; }
+    async listServices() { return []; }
+    async listResources() { return this.resources; }
+    async listEdges() { return this.edges; }
+    async getTopologySnapshot() {
+        return { source: this.name, resources: this.resources, edges: this.edges, revision: 1 };
+    }
+    watchTopology(_l) { return () => { }; }
+}
+// Build a small but realistic topology covering both happy and edge cases:
+// two services, two hosts, ownership chain, one orphan, one cross-kind link.
+function fixture() {
+    const r = [
+        // Hosts
+        { id: "k8s:node:n1", kind: "node", name: "n1", source: "fake", labels: {} },
+        { id: "k8s:node:n2", kind: "node", name: "n2", source: "fake", labels: {} },
+        // Scope
+        { id: "k8s:namespace:prod", kind: "namespace", name: "prod", source: "fake", labels: {} },
+        { id: "k8s:namespace:staging", kind: "namespace", name: "staging", source: "fake", labels: {} },
+        // Ownership roots (deployments)
+        { id: "k8s:deployment:prod/api", kind: "deployment", name: "api", source: "fake", labels: {} },
+        { id: "k8s:deployment:prod/db", kind: "deployment", name: "db", source: "fake", labels: {} },
+        // Intermediate
+        { id: "k8s:replicaset:prod/api-1", kind: "replicaset", name: "api-1", source: "fake", labels: {} },
+        // Workloads
+        { id: "k8s:pod:prod/api-aaa", kind: "pod", name: "api-aaa", source: "fake", labels: { app: "api" } },
+        { id: "k8s:pod:prod/api-bbb", kind: "pod", name: "api-bbb", source: "fake", labels: { app: "api" } },
+        { id: "k8s:pod:prod/db-aaa", kind: "pod", name: "db-aaa", source: "fake", labels: { app: "db" } },
+        // Orphan with no RUNS_ON (e.g. pending)
+        { id: "k8s:pod:staging/pending-1", kind: "pod", name: "pending-1", source: "fake", labels: {} },
+    ];
+    const e = [
+        // ownership chain
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:replicaset:prod/api-1", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:replicaset:prod/api-1", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:replicaset:prod/api-1", to: "k8s:deployment:prod/api", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:deployment:prod/db", relation: "OWNED_BY", source: "fake", confidence: 1 },
+        // RUNS_ON — api-aaa shares n1 with db-aaa (blast-radius case);
+        // api-bbb alone on n2 (no shared-host case)
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:node:n1", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:node:n1", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:node:n2", relation: "RUNS_ON", source: "fake", confidence: 1 },
+        // IN_NAMESPACE
+        { from: "k8s:pod:prod/api-aaa", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/api-bbb", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:prod/db-aaa", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:deployment:prod/api", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:deployment:prod/db", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:replicaset:prod/api-1", to: "k8s:namespace:prod", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+        { from: "k8s:pod:staging/pending-1", to: "k8s:namespace:staging", relation: "IN_NAMESPACE", source: "fake", confidence: 1 },
+    ];
+    return { resources: r, edges: e };
+}
+async function makeRegistry() {
+    const { resources, edges } = fixture();
+    const loader = new PluginLoader();
+    // Don't load builtins/filesystem — we plug a single fake connector in
+    // directly so the suite is hermetic and fast.
+    const reg = new ConnectorRegistry(loader);
+    const conn = new FakeTopologyConnector(resources, edges);
+    await conn.connect({ name: "fake-cluster", type: "fake", url: "", enabled: true });
+    // ConnectorRegistry has no public "register a live instance" method,
+    // so we install via the documented addSource path with a fake loader.
+    loader.connectors.set("fake", {
+        name: "fake",
+        source: "builtin",
+        factory: () => conn,
+    });
+    await reg.addSource({ name: "fake-cluster", type: "fake", url: "", enabled: true });
+    return reg;
+}
+function parseTool(result) {
+    return JSON.parse(result.content[0].text);
+}
+describe("resolveResource", () => {
+    const { resources } = fixture();
+    it("matches an exact id", () => {
+        const r = resolveResource("k8s:node:n1", resources);
+        assert.ok(!("error" in r));
+        if (!("error" in r))
+            assert.equal(r.kind, "node");
+    });
+    it("matches a unique exact name", () => {
+        const r = resolveResource("api-aaa", resources);
+        assert.ok(!("error" in r));
+    });
+    it("returns candidates for an ambiguous fuzzy match", () => {
+        // "aaa" doesn't exactly match any name, but fuzzy-matches api-aaa and db-aaa
+        const r = resolveResource("aaa", resources);
+        assert.ok("error" in r);
+        if ("error" in r) {
+            assert.ok((r.candidates?.length ?? 0) >= 2);
+        }
+    });
+    it("returns a clean error for no match", () => {
+        const r = resolveResource("does-not-exist", resources);
+        assert.ok("error" in r);
+    });
+});
+describe("get_topology tool", () => {
+    it("returns the full graph by default", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, {}));
+        assert.equal(out.sources.length, 1);
+        assert.equal(out.resources.length, fixture().resources.length);
+        assert.equal(out.edges.length, fixture().edges.length);
+        assert.equal(out.truncated, false);
+    });
+    it("filters by kind", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, { kind: "pod" }));
+        for (const r of out.resources)
+            assert.equal(r.kind, "pod");
+        // edges must reference only the kept resources
+        const ids = new Set(out.resources.map((r) => r.id));
+        for (const e of out.edges) {
+            assert.ok(ids.has(e.from) && ids.has(e.to));
+        }
+    });
+    it("filters by scope name or id", async () => {
+        const reg = await makeRegistry();
+        const byName = parseTool(await getTopologyHandler(reg, { scope: "prod" }));
+        const byId = parseTool(await getTopologyHandler(reg, { scope: "k8s:namespace:prod" }));
+        assert.equal(byName.resources.length, byId.resources.length);
+        // staging pod must not appear
+        assert.ok(!byName.resources.some((r) => r.name === "pending-1"));
+    });
+    it("respects the limit and reports truncation", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getTopologyHandler(reg, { limit: 3 }));
+        assert.equal(out.resources.length, 3);
+        assert.equal(out.truncated, true);
+        assert.equal(out.total.resources, fixture().resources.length);
+    });
+});
+describe("get_blast_radius tool", () => {
+    it("reports shared-host blast radius for a co-located pod", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-aaa" }));
+        assert.equal(out.target.name, "api-aaa");
+        assert.equal(out.hosts.length, 1);
+        const host = out.hosts[0];
+        assert.equal(host.host.name, "n1");
+        // Two ownership roots on n1: deployment/api and deployment/db
+        assert.equal(host.ownershipRoots, 2);
+        const rootNames = new Set(host.coTenants.map((c) => c.ownershipRootName));
+        assert.ok(rootNames.has("api"));
+        assert.ok(rootNames.has("db"));
+        assert.match(out.summary, /blast-radius candidate/i);
+    });
+    it("reports no shared-host for a pod alone on its node", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-bbb" }));
+        assert.equal(out.hosts.length, 1);
+        assert.equal(out.hosts[0].host.name, "n2");
+        assert.equal(out.hosts[0].ownershipRoots, 1);
+        assert.match(out.summary, /limited shared-host/i);
+    });
+    it("treats a host resource as its own host (incoming RUNS_ON pivot)", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "k8s:node:n1" }));
+        assert.equal(out.target.kind, "node");
+        assert.equal(out.hosts.length, 1);
+        assert.equal(out.hosts[0].host.id, "k8s:node:n1");
+    });
+    it("returns a note when a resource has no RUNS_ON edges", async () => {
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "pending-1" }));
+        assert.equal(out.hosts.length, 0);
+        assert.match(out.note, /no RUNS_ON/i);
+    });
+    it("surfaces a structured error for unknown resources", async () => {
+        const reg = await makeRegistry();
+        const result = await getBlastRadiusHandler(reg, { resource: "totally-not-here" });
+        assert.equal(result.isError, true);
+        const out = parseTool(result);
+        assert.match(out.error, /No resource found/);
+    });
+    it("uses ownership root, not direct owner, when grouping co-tenants", async () => {
+        // api-aaa is OWNED_BY a ReplicaSet which is OWNED_BY a Deployment.
+        // The blast-radius should bucket api-aaa under the Deployment, not the RS.
+        const reg = await makeRegistry();
+        const out = parseTool(await getBlastRadiusHandler(reg, { resource: "api-aaa" }));
+        const onN1 = out.hosts[0];
+        const apiBucket = onN1.coTenants.find((c) => c.ownershipRootName === "api");
+        assert.ok(apiBucket, "expected an 'api' deployment bucket on n1");
+        assert.equal(apiBucket.ownershipRootKind, "deployment");
+    });
+});

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type SignalType = "metrics" | "logs" | "traces";
+export type SignalType = "metrics" | "logs" | "traces" | "topology";
 export type HealthStatus = "healthy" | "degraded" | "critical";
 export type Trend = "rising" | "falling" | "stable";
 export type AnomalySeverity = "low" | "medium" | "high";
@@ -151,6 +151,72 @@ export interface LogResult {
     entries: LogEntry[];
     summary: LogSummary;
 }
+/**
+ * A discrete infrastructure entity discovered by a topology-aware connector.
+ *
+ * `kind` and the relation strings on Edge are intentionally open (not unions):
+ * future connectors (vCenter, NetBox, SNMP, ...) will introduce new kinds and
+ * relations. Document common values here, but do not hard-restrict the type.
+ *
+ * `id` is a stable, human-readable canonical key. For Kubernetes we use
+ *   `k8s:<kind>:<namespace>/<name>` for namespaced kinds, `k8s:<kind>:<name>`
+ *   for cluster-scoped kinds. Pod names are ephemeral by design — that's
+ *   acceptable since pods are short-lived; deployments/nodes/services are
+ *   stable. Backend identifiers (e.g. K8s metadata.uid) belong in `attributes`.
+ *
+ * `source` is mandatory so a future entity-resolution layer can merge views
+ * from multiple connectors without ambiguity.
+ *
+ * Common kinds (Kubernetes): "pod", "node", "deployment", "service", "namespace".
+ */
+export interface Resource {
+    id: string;
+    kind: string;
+    name: string;
+    source: string;
+    labels: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * A directed relationship between two Resources.
+ *
+ * Common relations (Kubernetes):
+ *   - "RUNS_ON"      pod -> node, container -> host, vm -> hypervisor
+ *   - "OWNED_BY"     pod -> replicaset/deployment
+ *   - "ROUTES_TO"    service -> pod
+ *   - "IN_NAMESPACE" pod/service/deployment -> namespace
+ *
+ * `confidence` is 0..1. For data that comes straight from an authoritative
+ * source (K8s API), use 1.0. Inferred relations (e.g. label-based matching)
+ * should report lower values.
+ */
+export interface Edge {
+    from: string;
+    to: string;
+    relation: string;
+    source: string;
+    confidence: number;
+}
+/** Snapshot of the topology graph as known by a single connector. */
+export interface TopologySnapshot {
+    source: string;
+    resources: Resource[];
+    edges: Edge[];
+    /** Monotonic counter; bumped on each successful watch event apply. */
+    revision: number;
+}
+/** Event emitted by a watching connector when its in-memory graph changes. */
+export type TopologyChangeEvent = {
+    type: "resource_added" | "resource_updated" | "resource_removed";
+    resource: Resource;
+} | {
+    type: "edge_added" | "edge_removed";
+    edge: Edge;
+} | {
+    type: "resync";
+    snapshot: TopologySnapshot;
+};
+export type TopologyChangeListener = (event: TopologyChangeEvent) => void;
 export interface AnomalyReport {
     metric: string;
     severity: AnomalySeverity;