@thotischner/observability-mcp 3.0.0 → 3.1.0

package/dist/security/csp.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Content-Security-Policy for the management-plane Web UI.
+ *
+ * Two policies ship together, by design:
+ *
+ *  - **Enforced** (`Content-Security-Policy`): a real, non-breaking policy.
+ *    It locks down everything the UI doesn't need — no remote scripts
+ *    (`script-src 'self'`), no plugins (`object-src 'none'`), no `<base>`
+ *    hijack (`base-uri 'self'`), no framing (`frame-ancestors 'none'`),
+ *    and same-origin-only XHR via `connect-src 'self'`. It keeps
+ *    `'unsafe-inline'` for `script-src` because the single-file UI uses
+ *    ~200 inline event-handler attributes (`onclick=`, …) that a nonce
+ *    cannot cover — a nonce in `script-src` would *disable* `'unsafe-inline'`
+ *    in CSP3 and break every button. So the enforced policy is a genuine
+ *    improvement over no CSP without regressing the UI.
+ *
+ *  - **Report-Only** (`Content-Security-Policy-Report-Only`): the strict
+ *    target policy — `script-src 'self' 'nonce-…'`, no `'unsafe-inline'`.
+ *    The two legitimate inline `<script>` blocks carry the per-request
+ *    nonce, so this policy flags ONLY the inline event-handler debt. It
+ *    blocks nothing; it just reports, giving an actionable migration list
+ *    (move the handlers to addEventListener) before a future slice can
+ *    promote the strict policy to enforced.
+ *
+ *    It is **opt-in** (`OMCP_CSP_STRICT_REPORT=true`): with ~200 inline
+ *    handlers it would otherwise emit a `[Report Only]` console message
+ *    per handler on every page load — noise an operator with devtools
+ *    open shouldn't eat by default. Enable it when you're actively
+ *    working the migration. The enforced policy + reporting endpoint are
+ *    always on regardless.
+ *
+ * Both policies report to `/api/csp-violations` via the modern Reporting
+ * API (`Reporting-Endpoints` + `report-to`) and the legacy `report-uri`.
+ */
+/** Placeholder substituted with the per-request nonce when serving the UI HTML. */
+export declare const CSP_NONCE_PLACEHOLDER = "__CSP_NONCE__";
+/** The named reporting group used in the Report-To / Reporting-Endpoints headers. */
+export declare const CSP_REPORT_GROUP = "omcp-csp";
+/** Where violation reports are POSTed. */
+export declare const CSP_REPORT_PATH = "/api/csp-violations";
+/** Fresh base64 nonce (128 bits). */
+export declare function generateNonce(): string;
+/** The enforced policy — non-breaking, keeps the UI working. */
+export declare function enforcedCsp(): string;
+/** The strict target policy, run in report-only mode against the nonce. */
+export declare function reportOnlyCsp(nonce: string): string;
+/** Whether the strict Report-Only policy is enabled. Default off — see
+ *  the module header for why (console noise from ~200 inline handlers). */
+export declare function cspStrictReportFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/** Value for the modern `Reporting-Endpoints` header. */
+export declare function reportingEndpointsHeader(): string;
+/** Value for the legacy `Report-To` header (Reporting API v0). */
+export declare function reportToHeader(): string;
+/**
+ * Normalise a posted CSP violation (either the legacy
+ * `application/csp-report` `{ "csp-report": {...} }` envelope or a modern
+ * Reporting-API `application/reports+json` array element) into a compact,
+ * log-safe summary. Returns null when the body isn't a recognisable report.
+ */
+export declare function summariseViolation(body: unknown): {
+    directive: string;
+    blockedUri: string;
+    documentUri: string;
+} | null;

package/dist/security/csp.js

@@ -0,0 +1,135 @@
+/**
+ * Content-Security-Policy for the management-plane Web UI.
+ *
+ * Two policies ship together, by design:
+ *
+ *  - **Enforced** (`Content-Security-Policy`): a real, non-breaking policy.
+ *    It locks down everything the UI doesn't need — no remote scripts
+ *    (`script-src 'self'`), no plugins (`object-src 'none'`), no `<base>`
+ *    hijack (`base-uri 'self'`), no framing (`frame-ancestors 'none'`),
+ *    and same-origin-only XHR via `connect-src 'self'`. It keeps
+ *    `'unsafe-inline'` for `script-src` because the single-file UI uses
+ *    ~200 inline event-handler attributes (`onclick=`, …) that a nonce
+ *    cannot cover — a nonce in `script-src` would *disable* `'unsafe-inline'`
+ *    in CSP3 and break every button. So the enforced policy is a genuine
+ *    improvement over no CSP without regressing the UI.
+ *
+ *  - **Report-Only** (`Content-Security-Policy-Report-Only`): the strict
+ *    target policy — `script-src 'self' 'nonce-…'`, no `'unsafe-inline'`.
+ *    The two legitimate inline `<script>` blocks carry the per-request
+ *    nonce, so this policy flags ONLY the inline event-handler debt. It
+ *    blocks nothing; it just reports, giving an actionable migration list
+ *    (move the handlers to addEventListener) before a future slice can
+ *    promote the strict policy to enforced.
+ *
+ *    It is **opt-in** (`OMCP_CSP_STRICT_REPORT=true`): with ~200 inline
+ *    handlers it would otherwise emit a `[Report Only]` console message
+ *    per handler on every page load — noise an operator with devtools
+ *    open shouldn't eat by default. Enable it when you're actively
+ *    working the migration. The enforced policy + reporting endpoint are
+ *    always on regardless.
+ *
+ * Both policies report to `/api/csp-violations` via the modern Reporting
+ * API (`Reporting-Endpoints` + `report-to`) and the legacy `report-uri`.
+ */
+import { randomBytes } from "node:crypto";
+/** Placeholder substituted with the per-request nonce when serving the UI HTML. */
+export const CSP_NONCE_PLACEHOLDER = "__CSP_NONCE__";
+/** The named reporting group used in the Report-To / Reporting-Endpoints headers. */
+export const CSP_REPORT_GROUP = "omcp-csp";
+/** Where violation reports are POSTed. */
+export const CSP_REPORT_PATH = "/api/csp-violations";
+/** Fresh base64 nonce (128 bits). */
+export function generateNonce() {
+    return randomBytes(16).toString("base64");
+}
+/** The enforced policy — non-breaking, keeps the UI working. */
+export function enforcedCsp() {
+    return [
+        "default-src 'self'",
+        "base-uri 'self'",
+        "object-src 'none'",
+        "frame-ancestors 'none'",
+        "form-action 'self'",
+        "script-src 'self' 'unsafe-inline'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        `report-uri ${CSP_REPORT_PATH}`,
+        `report-to ${CSP_REPORT_GROUP}`,
+    ].join("; ");
+}
+/** The strict target policy, run in report-only mode against the nonce. */
+export function reportOnlyCsp(nonce) {
+    return [
+        "default-src 'self'",
+        "base-uri 'self'",
+        "object-src 'none'",
+        "frame-ancestors 'none'",
+        "form-action 'self'",
+        `script-src 'self' 'nonce-${nonce}'`,
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        `report-uri ${CSP_REPORT_PATH}`,
+        `report-to ${CSP_REPORT_GROUP}`,
+    ].join("; ");
+}
+/** Whether the strict Report-Only policy is enabled. Default off — see
+ *  the module header for why (console noise from ~200 inline handlers). */
+export function cspStrictReportFromEnv(env = process.env) {
+    const v = env.OMCP_CSP_STRICT_REPORT?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** Value for the modern `Reporting-Endpoints` header. */
+export function reportingEndpointsHeader() {
+    return `${CSP_REPORT_GROUP}="${CSP_REPORT_PATH}"`;
+}
+/** Value for the legacy `Report-To` header (Reporting API v0). */
+export function reportToHeader() {
+    return JSON.stringify({
+        group: CSP_REPORT_GROUP,
+        max_age: 10886400,
+        endpoints: [{ url: CSP_REPORT_PATH }],
+    });
+}
+/**
+ * Normalise a posted CSP violation (either the legacy
+ * `application/csp-report` `{ "csp-report": {...} }` envelope or a modern
+ * Reporting-API `application/reports+json` array element) into a compact,
+ * log-safe summary. Returns null when the body isn't a recognisable report.
+ */
+export function summariseViolation(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    // Reporting API delivers an array of { type, body: {...} }.
+    if (Array.isArray(body)) {
+        for (const item of body) {
+            const s = summariseViolation(item);
+            if (s)
+                return s;
+        }
+        return null;
+    }
+    const o = body;
+    // Reporting-API single report: { type: "csp-violation", body: {...} }.
+    const report = (o["csp-report"] ?? o.body ?? o);
+    if (!report || typeof report !== "object")
+        return null;
+    const pick = (...keys) => {
+        for (const k of keys) {
+            const v = report[k];
+            if (typeof v === "string" && v)
+                return v.slice(0, 256);
+        }
+        return "";
+    };
+    const directive = pick("effective-directive", "effectiveDirective", "violated-directive", "violatedDirective");
+    const blockedUri = pick("blocked-uri", "blockedURL", "blockedURI");
+    const documentUri = pick("document-uri", "documentURL", "documentURI");
+    if (!directive && !blockedUri && !documentUri)
+        return null;
+    return { directive, blockedUri, documentUri };
+}

package/dist/security/csp.test.d.ts

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

package/dist/security/csp.test.js

@@ -0,0 +1,97 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateNonce, enforcedCsp, reportOnlyCsp, reportingEndpointsHeader, reportToHeader, summariseViolation, cspStrictReportFromEnv, CSP_NONCE_PLACEHOLDER, CSP_REPORT_GROUP, CSP_REPORT_PATH, } from "./csp.js";
+test("generateNonce returns a fresh base64 value each call", () => {
+    const a = generateNonce();
+    const b = generateNonce();
+    assert.notEqual(a, b);
+    assert.match(a, /^[A-Za-z0-9+/]+=*$/);
+    // 16 bytes → 24 base64 chars (with padding).
+    assert.ok(a.length >= 22);
+});
+test("enforced policy keeps the UI working but locks the rest down", () => {
+    const csp = enforcedCsp();
+    // Inline handlers survive: unsafe-inline present, NO nonce (which would disable it).
+    assert.match(csp, /script-src 'self' 'unsafe-inline'/);
+    assert.ok(!csp.includes("nonce-"), "enforced policy must not carry a nonce");
+    // Hard locks.
+    assert.match(csp, /object-src 'none'/);
+    assert.match(csp, /base-uri 'self'/);
+    assert.match(csp, /frame-ancestors 'none'/);
+    assert.match(csp, /default-src 'self'/);
+    assert.match(csp, /connect-src 'self'/);
+    // Reporting wired both ways.
+    assert.match(csp, new RegExp(`report-uri ${CSP_REPORT_PATH}`));
+    assert.match(csp, new RegExp(`report-to ${CSP_REPORT_GROUP}`));
+});
+test("report-only policy is strict and nonce-bound, no unsafe-inline on scripts", () => {
+    const nonce = generateNonce();
+    const csp = reportOnlyCsp(nonce);
+    assert.match(csp, new RegExp(`script-src 'self' 'nonce-${nonce.replace(/[+/]/g, "\\$&")}'`));
+    // Strict: the script directive must NOT allow unsafe-inline.
+    const scriptDirective = csp.split(";").find((d) => d.trim().startsWith("script-src"));
+    assert.ok(!scriptDirective.includes("unsafe-inline"));
+    assert.match(csp, /object-src 'none'/);
+});
+test("reporting headers name the same group + endpoint", () => {
+    assert.equal(reportingEndpointsHeader(), `${CSP_REPORT_GROUP}="${CSP_REPORT_PATH}"`);
+    const parsed = JSON.parse(reportToHeader());
+    assert.equal(parsed.group, CSP_REPORT_GROUP);
+    assert.equal(parsed.endpoints[0].url, CSP_REPORT_PATH);
+    assert.ok(parsed.max_age > 0);
+});
+test("the nonce placeholder is a stable token", () => {
+    assert.equal(CSP_NONCE_PLACEHOLDER, "__CSP_NONCE__");
+});
+test("strict report-only is opt-in (default off)", () => {
+    assert.equal(cspStrictReportFromEnv({}), false);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "true" }), true);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "1" }), true);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "no" }), false);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "false" }), false);
+});
+test("summariseViolation parses the legacy csp-report envelope", () => {
+    const s = summariseViolation({
+        "csp-report": {
+            "effective-directive": "script-src-attr",
+            "blocked-uri": "inline",
+            "document-uri": "https://gw.example/",
+            "extra": "ignored",
+        },
+    });
+    assert.deepEqual(s, {
+        directive: "script-src-attr",
+        blockedUri: "inline",
+        documentUri: "https://gw.example/",
+    });
+});
+test("summariseViolation parses a modern Reporting-API array", () => {
+    const s = summariseViolation([
+        {
+            type: "csp-violation",
+            body: {
+                effectiveDirective: "script-src-elem",
+                blockedURL: "https://evil.example/x.js",
+                documentURL: "https://gw.example/",
+            },
+        },
+    ]);
+    assert.equal(s?.directive, "script-src-elem");
+    assert.equal(s?.blockedUri, "https://evil.example/x.js");
+});
+test("summariseViolation falls back to violated-directive", () => {
+    const s = summariseViolation({ "csp-report": { "violated-directive": "img-src", "blocked-uri": "data" } });
+    assert.equal(s?.directive, "img-src");
+});
+test("summariseViolation returns null for junk", () => {
+    assert.equal(summariseViolation(null), null);
+    assert.equal(summariseViolation("nope"), null);
+    assert.equal(summariseViolation({}), null);
+    assert.equal(summariseViolation({ random: "field" }), null);
+});
+test("summariseViolation truncates over-long fields", () => {
+    const long = "a".repeat(5000);
+    const s = summariseViolation({ "csp-report": { "blocked-uri": long } });
+    assert.ok(s);
+    assert.ok((s.blockedUri).length <= 256);
+});

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/query-logs.d.ts

@@ -22,10 +22,43 @@ export declare const queryLogsDefinition: {
                 type: string;
                 description: string;
             };
+            labels: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                };
+                description: string;
+            };
             limit: {
                 type: string;
                 description: string;
             };
+            aggregate: {
+                type: string;
+                description: string;
+                properties: {
+                    op: {
+                        type: string;
+                        enum: string[];
+                    };
+                    by: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    k: {
+                        type: string;
+                        description: string;
+                    };
+                    step: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
         };
         required: string[];
     };
@@ -36,6 +69,13 @@ export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
     duration?: string;
     level?: string;
     limit?: number;
+    labels?: Record<string, string>;
+    aggregate?: {
+        op: "count_over_time" | "sum" | "topk";
+        by?: string[];
+        k?: number;
+        step?: string;
+    };
 }, ctx?: RequestContext): Promise<{
     content: {
         type: "text";

package/dist/tools/query-logs.js

@@ -1,8 +1,8 @@
 import { defaultContext } from "../context.js";
-import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
 export const queryLogsDefinition = {
     name: "query_logs",
-    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Supports filtering by log level and search query.",
+    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Filter by log level, a free-text/regex search, OR structured `labels` (exact-match on backend-extracted fields like method/status/url/environment — far more reliable than regex on structured JSON logs).",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,9 +22,25 @@ export const queryLogsDefinition = {
                 type: "string",
                 description: "Filter by log level: 'error', 'warn', 'info', 'debug'",
             },
+            labels: {
+                type: "object",
+                additionalProperties: { type: "string" },
+                description: "Structured equality filters on backend-extracted fields, AND'd together, e.g. {\"method\":\"GET\",\"url\":\"/\",\"status\":\"200\",\"environment\":\"prod\"}. Prefer this over `query` for structured JSON logs — the literal text rarely appears verbatim. Label names must be [a-zA-Z_][a-zA-Z0-9_]* (max 20).",
+            },
             limit: {
                 type: "number",
-                description: "Maximum number of log entries to return. Default: 100",
+                description: "Maximum number of log entries to return. Default: 100. Ignored when `aggregate` is set.",
+            },
+            aggregate: {
+                type: "object",
+                description: "Server-side aggregation — returns grouped counts, not raw rows, so you get a number instead of a haystack. op: 'count_over_time' (time series of counts per bucket), 'sum' (total per group over the window), 'topk' (top-k groups by total). Example: {\"op\":\"topk\",\"by\":[\"url\"],\"k\":10} for the busiest paths. Honours `labels`/`query` filters.",
+                properties: {
+                    op: { type: "string", enum: ["count_over_time", "sum", "topk"] },
+                    by: { type: "array", items: { type: "string" }, description: "Group-by label names (required for topk)." },
+                    k: { type: "number", description: "Top-k count (default 10)." },
+                    step: { type: "string", description: "Bucket size for count_over_time, e.g. '15m'. Defaults to ~1/60th of the window." },
+                },
+                required: ["op"],
             },
         },
         required: ["service"],
@@ -38,6 +54,12 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
     const durationErr = validateDuration(duration);
     if (durationErr)
         return errorResponse(durationErr);
+    const labelsErr = validateLogLabels(args.labels);
+    if (labelsErr)
+        return errorResponse(labelsErr);
+    const aggErr = validateLogAggregate(args.aggregate);
+    if (aggErr)
+        return errorResponse(aggErr);
     const connectors = registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "logs");
     if (connectors.length === 0) {
         return {
@@ -47,6 +69,49 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
             isError: true,
         };
     }
+    // Aggregate mode (Q-LOG2): route to the connector's queryLogAggregate.
+    if (args.aggregate) {
+        const aggResults = [];
+        const aggErrors = [];
+        let capable = 0;
+        for (const connector of connectors) {
+            if (!connector.queryLogAggregate)
+                continue;
+            capable++;
+            try {
+                const q = {
+                    service: args.service,
+                    duration,
+                    labels: args.labels,
+                    query: args.query,
+                    op: args.aggregate.op,
+                    by: args.aggregate.by,
+                    k: args.aggregate.k,
+                    step: args.aggregate.step,
+                };
+                aggResults.push(await connector.queryLogAggregate(q));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`Log aggregate failed on ${connector.name}:`, msg);
+                aggErrors.push(`${connector.name}: ${msg}`);
+            }
+        }
+        if (capable === 0) {
+            return errorResponse("No log backend supports aggregation (queryLogAggregate).");
+        }
+        if (aggResults.length === 0) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: aggErrors.length ? `Aggregate failed: ${aggErrors.join("; ")}` : "No data returned", service: args.service, duration }) }],
+                isError: aggErrors.length > 0,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(aggResults.length === 1 ? aggResults[0] : aggResults, null, 2) },
+            ],
+        };
+    }
     const results = [];
     const errors = [];
     for (const connector of connectors) {
@@ -59,6 +124,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
                 duration,
                 level: args.level,
                 limit: args.limit,
+                labels: args.labels,
             });
             results.push(result);
         }

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/tools/validation.d.ts

@@ -8,6 +8,19 @@ export declare function validateMetricName(metric: string, registry: ConnectorRe
  */
 export declare function sanitizeLabelValue(value: string): string | null;
 export declare function validateServiceName(service: string): string | null;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export declare function validateLogLabels(labels: unknown): string | null;
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export declare function validateLogAggregate(aggregate: unknown): string | null;
 export declare function errorResponse(message: string): {
     content: {
         type: "text";