@miragon/pulse-analytics-connector 0.0.0-stage → 0.21.0

package/src/widget-tools/comparisons.ts

@@ -0,0 +1,229 @@
+import {
+  appOnly,
+  buildDataFeedResult,
+  buildSingleWidgetView,
+  showToolBinding,
+  withToolErrors,
+  strictToolInput,
+} from "@miragon/pulse-widget-shell/server"
+import { queries, schemas, withCallerSignal } from "@miragon/pulse-analytics-client"
+import { ANALYTICS_ENGINE_LANDSCAPE_DATA } from "../tool-names.js"
+import { localizeViewFor } from "../server-locale.js"
+import { optionalMinBucketSize, settingsFor } from "../settings.js"
+import { isFleetRequest, withEngineScope } from "../engine-ids.js"
+import { namedLandscape } from "../named-views.js"
+import { NO_NAMES } from "../bpmn-name-lookup.js"
+import {
+  compareDeltaSummary,
+  engineScopeSummary,
+  suppressedNote,
+  type AnalyticsWidgetToolsContext,
+} from "./shared.js"
+
+/**
+ * The comparison family plus the cross-engine landscape they hang off.
+ *
+ * The three compare views answer "did this get worse?" along one axis at a
+ * time — across a deployment (cluster), across two versions of a process
+ * (version), across two engines running the SAME process (engine). The
+ * landscape is deliberately not a fourth comparison: engines host different
+ * process mixes, so it reports what runs where plus mix-independent signals
+ * and names the definitions for which an engine comparison actually holds.
+ */
+export function registerComparisonWidgetTools(ctx: AnalyticsWidgetToolsContext) {
+  const { server, ch, engineScope, profileStore } = ctx
+  const namesFor = ctx.namesFor ?? NO_NAMES
+
+  // --- Cluster Compare (Pre/Post deployment diff) ---
+  server.tool(
+    {
+      name: "analytics_show_cluster_compare",
+      title: "Pre/Post Deployment Comparison",
+      description:
+        "Visualize before/after KPI deltas around a deployment timestamp. Windows are clamped to now and the retention (flagged `partial`; starts compare per day). Results are flagged `suppressed` when either window has fewer than minBucketSize started or completed instances.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput({
+        ...schemas.clusterCompareInput.shape,
+        minBucketSize: optionalMinBucketSize,
+      }),
+      ...showToolBinding("analytics_show_cluster_compare", "Pre/Post Deployment Comparison"),
+    },
+    withToolErrors(async (args, toolCtx) => {
+      const { t, title } = await localizeViewFor(profileStore, toolCtx)
+      const minBucketSize =
+        args.minBucketSize ?? (await settingsFor(profileStore, toolCtx)).minBucketSize
+      const data = await queries.clusterCompare(withCallerSignal(ch, toolCtx.signal), {
+        ...withEngineScope(engineScope, args),
+        minBucketSize,
+      })
+      return buildSingleWidgetView({
+        widget: "analytics:cluster-compare",
+        app: "analytics",
+        dataType: "analytics:clusterCompare",
+        data,
+        // The view title in the language the profile names (the widget heading's
+        // own key); none with "system", where the heading names the view.
+        title: title("aClusterCompare.title"),
+        summary: t("aSum.clusterCompare", {
+          scope: data.processDefinitionKey
+            ? t("aSum.scopeForProcess", { key: data.processDefinitionKey })
+            : "",
+          engines: engineScopeSummary(t, data.engines, isFleetRequest(args.engine)),
+          deploymentTimestamp: data.deploymentTimestamp,
+          before: data.windowDays.before,
+          after: data.windowDays.after,
+          partial: data.partial ? t("aSum.clusterComparePartial") : "",
+          delta: compareDeltaSummary(data.delta),
+          suppressed: suppressedNote(data.suppressed),
+        }),
+      })
+    }),
+  )
+
+  // --- Version Compare (v1 vs v2 of one process) ---
+  server.tool(
+    {
+      name: "analytics_show_version_compare",
+      title: "Process Version Comparison",
+      description:
+        "Visualize KPI deltas between two deployed versions of the same processDefinitionKey within a shared time window. Instance counts and durations are exact per version; the incident rates show as n/a — the incident metric carries no version label, so they are not measured per version (never read them as zero). Results are flagged `suppressed` when either version has fewer than minBucketSize started or completed instances.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput({
+        ...schemas.versionCompareInput.shape,
+        minBucketSize: optionalMinBucketSize,
+      }),
+      ...showToolBinding("analytics_show_version_compare", "Process Version Comparison"),
+    },
+    withToolErrors(async (args, toolCtx) => {
+      const { t, title } = await localizeViewFor(profileStore, toolCtx)
+      const minBucketSize =
+        args.minBucketSize ?? (await settingsFor(profileStore, toolCtx)).minBucketSize
+      const data = await queries.versionCompare(withCallerSignal(ch, toolCtx.signal), {
+        ...withEngineScope(engineScope, args),
+        minBucketSize,
+      })
+      return buildSingleWidgetView({
+        widget: "analytics:version-compare",
+        app: "analytics",
+        dataType: "analytics:versionCompare",
+        data,
+        title: title("aVersionCompare.title"),
+        summary: t("aSum.versionCompare", {
+          key: data.processDefinitionKey,
+          versionA: data.versionA,
+          versionB: data.versionB,
+          windowDays: data.windowDays,
+          engines: engineScopeSummary(t, data.engines, isFleetRequest(args.engine)),
+          delta: compareDeltaSummary(data.delta),
+          suppressed: suppressedNote(data.suppressed),
+        }),
+      })
+    }),
+  )
+
+  // --- Engine Compare (ONE process, engine A vs engine B) ---
+  server.tool(
+    {
+      name: "analytics_show_engine_compare",
+      title: "Engine Comparison",
+      description:
+        "Visualize KPI deltas for ONE process definition as it runs on two configured CIB Seven engines (e.g. prod-a vs prod-b) over a shared time window. processDefinitionKey is required — engines host different process mixes, so an unscoped engine-vs-engine comparison would measure the mix, not the engines. Results are flagged `suppressed` when either engine has fewer than minBucketSize started or completed instances. For the cross-engine picture use analytics_show_engine_landscape.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput({
+        ...schemas.engineCompareInput.shape,
+        minBucketSize: optionalMinBucketSize,
+      }),
+      ...showToolBinding("analytics_show_engine_compare", "Engine Comparison"),
+    },
+    withToolErrors(async (args, toolCtx) => {
+      const { t, title } = await localizeViewFor(profileStore, toolCtx)
+      const minBucketSize =
+        args.minBucketSize ?? (await settingsFor(profileStore, toolCtx)).minBucketSize
+      const data = await queries.engineCompare(withCallerSignal(ch, toolCtx.signal), {
+        ...args,
+        engineA: engineScope.require(args.engineA, "engineA"),
+        engineB: engineScope.require(args.engineB, "engineB"),
+        minBucketSize,
+      })
+      return buildSingleWidgetView({
+        widget: "analytics:engine-compare",
+        app: "analytics",
+        dataType: "analytics:engineCompare",
+        data,
+        title: title("aEngineCompare.title"),
+        summary: t("aSum.engineCompare", {
+          engineA: data.engineA,
+          engineB: data.engineB,
+          key: data.processDefinitionKey,
+          windowDays: data.windowDays,
+          delta: compareDeltaSummary(data.delta),
+          suppressed: suppressedNote(data.suppressed),
+        }),
+      })
+    }),
+  )
+
+  // --- Engine Landscape (cross-engine overview, NOT an engine ranking) ---
+  server.tool(
+    {
+      name: "analytics_show_engine_landscape",
+      title: "Cross-Engine Landscape",
+      description:
+        "Show the cross-engine process landscape of the configured engines: which process definitions run on which engine, the absolute load per engine (running instances, open incidents, failed jobs) and the engine-owned job backlog. Counts, not rates — engines host different process mixes, so per-engine rates would measure the mix. Highlights the definitions deployed on several engines, the only sound targets for analytics_show_engine_compare.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput(schemas.engineLandscapeInput.shape),
+      ...showToolBinding("analytics_show_engine_landscape", "Cross-Engine Landscape"),
+    },
+    withToolErrors(async (args, toolCtx) => {
+      const { t, title } = await localizeViewFor(profileStore, toolCtx)
+      const data = await namedLandscape(
+        await queries.engineLandscape(
+          withCallerSignal(ch, toolCtx.signal),
+          withEngineScope(engineScope, args),
+        ),
+        namesFor,
+      )
+      return buildSingleWidgetView({
+        widget: "analytics:engine-landscape",
+        app: "analytics",
+        dataType: "analytics:engineLandscape",
+        data,
+        title: title("aLandscape.heading"),
+        summary: t("aSum.engineLandscape", {
+          engineCount: data.totals.engineCount,
+          reportingEngineCount: data.totals.reportingEngineCount,
+          processKeyCount: data.totals.processKeyCount,
+          sharedProcessKeyCount: data.totals.sharedProcessKeyCount,
+          // Unknown while no engine reports: "n/a", never a plausible 0.
+          runningInstances: data.totals.runningInstances ?? "n/a",
+          openIncidents: data.totals.openIncidents ?? "n/a",
+          shared: data.sharedProcessKeys.length
+            ? t("aSum.sharedKeys", { keys: data.sharedProcessKeys.join(", ") })
+            : "",
+        }),
+      })
+    }),
+  )
+
+  server.tool(
+    {
+      name: ANALYTICS_ENGINE_LANDSCAPE_DATA,
+      title: "Engine landscape data (internal)",
+      description:
+        "Internal JSON feed (no UI) for the cross-engine landscape widget's self-fetch — also consumed by the camunda7 cockpit's cross-engine mode. Prefer analytics_show_engine_landscape.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput(schemas.engineLandscapeInput.shape),
+      ...appOnly,
+    },
+    withToolErrors(async (args, toolCtx) => {
+      const data = await namedLandscape(
+        await queries.engineLandscape(
+          withCallerSignal(ch, toolCtx.signal),
+          withEngineScope(engineScope, args),
+        ),
+        namesFor,
+      )
+      return buildDataFeedResult({ ...data })
+    }),
+  )
+}

package/src/widget-tools/shared.ts

@@ -0,0 +1,67 @@
+import type { MCPServer } from "mcp-use"
+import type { CompareKpiDelta, PrometheusClient } from "@miragon/pulse-analytics-client"
+import type { ProfileSource, ServerT } from "../server-locale.js"
+import type { AnalyticsEngineScope } from "../engine-ids.js"
+import type { NameLookup } from "../bpmn-name-lookup.js"
+
+/**
+ * Everything the per-domain widget-tool registrars need, handed over by the
+ * `widget-tools.ts` entry — mirrors camunda7's `WidgetToolsContext`. The
+ * `_meta`/view bindings are NOT passed through: each registration spreads
+ * `showToolBinding()` / `appOnly` from `@miragon/pulse-widget-shell/server`
+ * itself, so the dual-protocol contract stays in one place.
+ */
+export interface AnalyticsWidgetToolsContext {
+  server: MCPServer
+  ch: PrometheusClient
+  /** The server's configured engine ids — every query resolves `engine` through it. */
+  engineScope: AnalyticsEngineScope
+  /** Locale for model-facing summaries plus the saved analytics defaults. */
+  profileStore?: ProfileSource
+  /** The process names behind the ids a view lists (`bpmn-name-lookup.ts`); absent → ids. */
+  namesFor?: NameLookup
+}
+
+/** Formats a nullable comparison delta ("+12.5%", "-3pp", "n/a") for summaries. */
+function fmtDelta(value: number | null, unit: string): string {
+  if (value == null) return "n/a"
+  return `${value > 0 ? "+" : ""}${value}${unit}`
+}
+
+/**
+ * Shared delta shape of the three compare queries, for one-line summaries. A
+ * null delta reads "n/a" — a side was not measured (nothing ended, nothing
+ * started) or the baseline is 0 — never a −100 %.
+ */
+export function compareDeltaSummary(delta: CompareKpiDelta): string {
+  return [
+    `starts/day ${fmtDelta(delta.started_per_day_delta_pct, "%")}`,
+    `incident rate ${fmtDelta(delta.incident_rate_delta_pp, "pp")}`,
+    ...(delta.element_incident_rate_delta_pp === null
+      ? []
+      : [`element incident rate ${fmtDelta(delta.element_incident_rate_delta_pp, "pp")}`]),
+    `avg duration ${fmtDelta(delta.avg_duration_delta_pct, "%")}`,
+    `p95 ${fmtDelta(delta.p95_duration_delta_pct, "%")}`,
+  ].join(", ")
+}
+
+export const suppressedNote = (suppressed: boolean) =>
+  suppressed ? "; flagged suppressed (sample below minBucketSize)" : ""
+
+/**
+ * The engine scope of a result, for summaries: one engine by name, or — the
+ * deliberate fleet aggregate — every engine it adds up, so a fleet-wide figure
+ * never reads as one engine's. `fleet` = the caller named no engine.
+ */
+export function engineScopeSummary(
+  t: ServerT,
+  engines: readonly string[] | null,
+  fleet: boolean,
+): string {
+  if (!engines || engines.length === 0) return ""
+  const ids = engines.map((id) => `"${id}"`).join(", ")
+  if (fleet) return t("aSum.engineScopeFleet", { count: engines.length, ids })
+  return engines.length === 1
+    ? t("aSum.engineScopeOne", { id: engines[0] })
+    : t("aSum.engineScopeSubset", { ids })
+}

package/src/widget-tools.test.ts

@@ -0,0 +1,306 @@
+import { describe, expect, it } from "vitest"
+import { parseToolResult } from "@miragon/mcp-toolkit-ui"
+import type { MCPServer } from "mcp-use"
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { registerWidgetTools } from "./widget-tools.js"
+import { createEngineScope } from "./engine-ids.js"
+import type { ProfileSource } from "./server-locale.js"
+import type { FetchBpmnXml, NameRequest } from "./bpmn-name-lookup.js"
+
+/** A feed's payload as the widget reads it (feeds answer in JSON text only). */
+const feedData = <T = Record<string, unknown>>(result: unknown): T => parseToolResult<T>(result)
+
+type Cell = { widget: string; props?: Record<string, unknown> }
+type ShowResult = { structuredContent: { layout: Array<{ row: Cell[] }> } }
+type Handler = (args: Record<string, unknown>, ctx: unknown) => Promise<ShowResult>
+
+/** Registers the widget tools on a stand-in server and returns their handlers. */
+function handlers(ch: PrometheusClient): Map<string, Handler> {
+  const byName = new Map<string, Handler>()
+  const server = {
+    tool: (definition: { name: string }, handler: Handler) => {
+      byName.set(definition.name, handler)
+    },
+  } as unknown as MCPServer
+  registerWidgetTools(server, ch, { engineScope: createEngineScope(["prod-a", "prod-b"]) })
+  return byName
+}
+
+/** PrometheusClient that records every instant PromQL string and returns no samples. */
+function recordingClient(): { client: PrometheusClient; queries: string[] } {
+  const queries: string[] = []
+  return {
+    client: {
+      instant: (query: string) => {
+        queries.push(query)
+        return Promise.resolve([])
+      },
+    },
+    queries,
+  }
+}
+
+const cells = (result: ShowResult) => result.structuredContent.layout.flatMap((r) => r.row)
+
+/**
+ * The engine-health hand-off renders `analytics_show_failure_dashboard` for
+ * ONE engine: the cells must know that scope, or their hand-offs and model
+ * contexts send the model to every engine (or the saved default) instead.
+ */
+describe("analytics_show_failure_dashboard engine scope", () => {
+  it("queries the engine and hands it to every cell", async () => {
+    const { client, queries } = recordingClient()
+    const show = handlers(client).get("analytics_show_failure_dashboard")!
+    const result = await show({ engine: "prod-b" }, {})
+
+    expect(queries.length).toBeGreaterThan(0)
+    for (const query of queries) expect(query).toContain('engine_id="prod-b"')
+    // The cells' self-fetches keep their scope through these props; their
+    // hand-offs and model contexts name the data's `engines` echo
+    // (model-descriptions.test.ts pins the `engine` id they then carry).
+    expect(cells(result)).toEqual([
+      { widget: "analytics:failure-summary-kpi", props: { engine: "prod-b" } },
+      { widget: "analytics:error-patterns-table", props: { engine: "prod-b" } },
+      { widget: "analytics:failure-rate-table", props: { engine: "prod-b" } },
+    ])
+  })
+
+  // The aggregate is the CONFIGURED fleet (#336), never the whole Prometheus:
+  // the query names every configured engine, and the data echoes them.
+  it("reads the configured fleet for the aggregate and leaves the cells unscoped", async () => {
+    const { client, queries } = recordingClient()
+    const result = await handlers(client).get("analytics_show_failure_dashboard")!({}, {})
+
+    expect(queries.length).toBeGreaterThan(0)
+    for (const query of queries) expect(query).toContain('engine_id=~"prod-a|prod-b"')
+    expect(cells(result).every((cell) => cell.props === undefined)).toBe(true)
+  })
+})
+
+describe("view titles (U3) and the heatmap's as-of stamp (U7)", () => {
+  const CTX = { auth: { user: { id: "user-1" } } }
+  function localizedHandlers(language: string): Map<string, Handler> {
+    const byName = new Map<string, Handler>()
+    const server = {
+      tool: (definition: { name: string }, handler: Handler) => {
+        byName.set(definition.name, handler)
+      },
+    } as unknown as MCPServer
+    const profileStore: ProfileSource = { get: () => Promise.resolve({ language }) }
+    registerWidgetTools(server, recordingClient().client, {
+      engineScope: createEngineScope(["prod-a"]),
+      profileStore,
+    })
+    return byName
+  }
+  const SHOWS: Array<[string, Record<string, unknown>]> = [
+    ["analytics_show_dashboard", {}],
+    ["analytics_show_failure_dashboard", {}],
+    ["analytics_show_bpmn_heatmap", { processDefinitionKey: "order" }],
+  ]
+  const titles = async (language: string) => {
+    const tools = localizedHandlers(language)
+    const results = await Promise.all(SHOWS.map(([name, args]) => tools.get(name)!(args, CTX)))
+    return results.map((r) => (r.structuredContent as unknown as { title?: string }).title)
+  }
+
+  it("titles each view in the caller's language, like the widget heading", async () => {
+    expect(await titles("de")).toEqual(["Prozessanalyse", "Fehleranalyse", "BPMN-Heatmap"])
+    expect(await titles("en")).toEqual(["Process analytics", "Failure analysis", "BPMN heatmap"])
+  })
+
+  it("stamps the heatmap with the time its values were read, in the view and the feed", async () => {
+    const tools = localizedHandlers("en")
+    const args = { processDefinitionKey: "order" }
+    const show = (await tools.get("analytics_show_bpmn_heatmap")!(args, CTX)) as unknown as {
+      structuredContent: { context: { stepData: { result: { data: { asOf?: string } } } } }
+    }
+    const feed = await tools.get("analytics_bpmn_heatmap_data")!(args, CTX)
+    const iso = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+    expect(show.structuredContent.context.stepData.result.data.asOf).toMatch(iso)
+    expect(feedData<{ asOf?: string }>(feed).asOf).toMatch(iso)
+  })
+})
+
+/**
+ * The heatmap says WHY it has no diagram only when the server knows it: no
+ * lookup injected (camunda7 not active), or a lookup that failed or found
+ * nothing. The widget picks its text from that and never guesses.
+ */
+describe("the heatmap's missing-diagram cause", () => {
+  type Diagram = { bpmnXml?: string | null; bpmnMissing?: string }
+
+  /**
+   * The diagram fields of the show tool's payload (a cause at most, never the
+   * XML: the model reads that payload on some hosts), of the heat feed (none)
+   * and of the diagram feed the widget reads the XML from.
+   */
+  async function payloads(fetchBpmnXml?: FetchBpmnXml, engines = ["prod-a"]) {
+    const byName = new Map<string, Handler>()
+    const server = {
+      tool: (definition: { name: string }, handler: Handler) => {
+        byName.set(definition.name, handler)
+      },
+    } as unknown as MCPServer
+    registerWidgetTools(server, recordingClient().client, {
+      engineScope: createEngineScope(engines),
+      fetchBpmnXml,
+    })
+    const args = { processDefinitionKey: "order" }
+    const show = (await byName.get("analytics_show_bpmn_heatmap")!(args, {})) as unknown as {
+      structuredContent: { context: { stepData: { result: { data: Diagram } } } }
+    }
+    const heat = feedData<Diagram>(await byName.get("analytics_bpmn_heatmap_data")!(args, {}))
+    const diagram = feedData<Diagram>(await byName.get("analytics_bpmn_xml_data")!(args, {}))
+    const fields = ({ bpmnXml, bpmnMissing }: Diagram) => ({ bpmnXml, bpmnMissing })
+    return {
+      show: fields(show.structuredContent.context.stepData.result.data),
+      heat: fields(heat),
+      diagram: fields(diagram),
+    }
+  }
+
+  it("names the missing camunda7 module only when no lookup was injected", async () => {
+    const { show, heat, diagram } = await payloads()
+    expect(show).toEqual({ bpmnXml: undefined, bpmnMissing: "no-camunda7" })
+    expect(heat).toEqual({ bpmnXml: undefined, bpmnMissing: undefined })
+    expect(diagram).toEqual({ bpmnXml: null, bpmnMissing: "no-camunda7" })
+  })
+
+  it("says the lookup found nothing when it failed or returned null", async () => {
+    const failing: FetchBpmnXml = () => Promise.reject(new Error("ECONNREFUSED"))
+    const empty: FetchBpmnXml = () => Promise.resolve(null)
+    for (const fetcher of [failing, empty]) {
+      const { show, diagram } = await payloads(fetcher)
+      expect(show).toEqual({ bpmnXml: undefined, bpmnMissing: "not-loaded" })
+      expect(diagram).toEqual({ bpmnXml: null, bpmnMissing: "not-loaded" })
+    }
+  })
+
+  it("keeps the XML out of the show payload and the heat feed when the diagram is there", async () => {
+    const xml = '<?xml version="1.0"?><definitions />'
+    const { show, heat, diagram } = await payloads(() => Promise.resolve(xml))
+    expect(show).toEqual({ bpmnXml: undefined, bpmnMissing: undefined })
+    expect(heat).toEqual({ bpmnXml: undefined, bpmnMissing: undefined })
+    expect(diagram).toEqual({ bpmnXml: xml, bpmnMissing: undefined })
+  })
+
+  // The process may run on a later engine only: the first engine of the
+  // scope (configuration order) that has the model draws it.
+  it("reads the diagram from the engines of its scope in order", async () => {
+    const xml = '<?xml version="1.0"?><definitions />'
+    const asked: Array<[string, string | undefined]> = []
+    const fetcher: FetchBpmnXml = (key, engine) => {
+      asked.push([key, engine])
+      if (engine === "prod-a") return Promise.reject(new Error("503"))
+      return Promise.resolve(engine === "prod-c" ? xml : null)
+    }
+    const { diagram } = await payloads(fetcher, ["prod-a", "prod-b", "prod-c"])
+    expect(diagram).toEqual({ bpmnXml: xml, bpmnMissing: undefined })
+    expect(asked.slice(0, 3)).toEqual([
+      ["order", "prod-a"],
+      ["order", "prod-b"],
+      ["order", "prod-c"],
+    ])
+  })
+})
+
+/**
+ * The names behind the ids (U13): the dashboard, the failure dashboard and
+ * the landscape carry the process (and, for the activity breakdown, the
+ * element) names the lookup knows, in the show tool's payload and in its
+ * feed alike. The dashboard judges its rate against the caller's saved
+ * comparison floor.
+ */
+describe("the names behind the ids", () => {
+  const ORDER = { process_definition_key: "order" }
+  /** One process with one activity, an open incident group and a deployment. */
+  const client: PrometheusClient = {
+    instant: (query: string) => {
+      if (query.includes("by (process_definition_key, activity_id, activity_type)")) {
+        return Promise.resolve([
+          { metric: { ...ORDER, activity_id: "Task_A", activity_type: "userTask" }, value: 2 },
+        ])
+      }
+      if (query.includes("by (process_definition_key, incident_type)")) {
+        return Promise.resolve([{ metric: { ...ORDER, incident_type: "failedJob" }, value: 1 }])
+      }
+      if (query.includes("by (engine_id, process_definition_key)")) {
+        return Promise.resolve([{ metric: { ...ORDER, engine_id: "prod-a" }, value: 1 }])
+      }
+      if (query.includes("by (process_definition_key)")) {
+        return Promise.resolve([{ metric: ORDER, value: 3 }])
+      }
+      if (query.includes("process_instance_started_total")) {
+        return Promise.resolve([{ metric: {}, value: 4 }])
+      }
+      return Promise.resolve([])
+    },
+  }
+  const NAMES = { order: { name: "Order fulfillment", elements: { Task_A: "Pack" } } }
+
+  async function run(name: string) {
+    const byName = new Map<string, Handler>()
+    const server = {
+      tool: (definition: { name: string }, handler: Handler) => {
+        byName.set(definition.name, handler)
+      },
+    } as unknown as MCPServer
+    const calls: Array<[string[], NameRequest | undefined]> = []
+    const profileStore: ProfileSource = {
+      get: () => Promise.resolve({ modules: { analytics: { minBucketSize: 3 } } }),
+    }
+    registerWidgetTools(server, client, {
+      engineScope: createEngineScope(["prod-a"]),
+      profileStore,
+      namesFor: (keys, request) => {
+        calls.push([[...keys], request])
+        return Promise.resolve(NAMES)
+      },
+    })
+    const ctx = { auth: { user: { id: "user-1" } } }
+    const result = await byName.get(name)!({}, ctx)
+    return { content: feedData(result), calls }
+  }
+
+  /** The payload of a show tool (its step data) or of a feed (the content itself). */
+  const payloadOf = (content: Record<string, unknown>) =>
+    ((content.context as { stepData?: { result?: { data?: unknown } } } | undefined)?.stepData
+      ?.result?.data ?? content) as Record<string, unknown>
+
+  it.each([
+    "analytics_show_dashboard",
+    "analytics_dashboard_data",
+    "analytics_show_failure_dashboard",
+    "analytics_failure_dashboard_data",
+    "analytics_show_engine_landscape",
+    "analytics_engine_landscape_data",
+  ])("%s carries the names", async (name) => {
+    const { content, calls } = await run(name)
+    expect(JSON.stringify(content)).toContain('"names":{"order":{"name":"Order fulfillment"')
+    expect(calls).toHaveLength(1)
+    expect(calls[0][0]).toContain("order")
+  })
+
+  it("asks for the elements of the activity breakdown only", async () => {
+    const { calls } = await run("analytics_dashboard_data")
+    expect(calls[0][1]?.elementIds).toEqual({ order: ["Task_A"] })
+    const failures = await run("analytics_failure_dashboard_data")
+    expect(failures.calls[0][1]?.elementIds).toEqual({ order: [] })
+  })
+
+  // A process that runs only on a later engine is named too: each view says
+  // which engines its rows come from, the landscape per process.
+  it("reads the models on the engines the rows come from", async () => {
+    const failures = await run("analytics_failure_dashboard_data")
+    expect(failures.calls[0][1]?.engines).toEqual(["prod-a"])
+    const landscape = await run("analytics_engine_landscape_data")
+    expect(landscape.calls[0][1]?.enginesByKey).toEqual({ order: ["prod-a"] })
+  })
+
+  it("judges the dashboard's rate against the caller's saved comparison floor", async () => {
+    const { content } = await run("analytics_dashboard_data")
+    // 4 starts in each window, the saved floor 3: a change of the rate is judged.
+    expect(payloadOf(content).previous).toMatchObject({ totalCount: 4, suppressed: false })
+  })
+})