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

package/src/tools/engine-landscape.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest"
+import { z } from "zod"
+import type { PrometheusClient, PromSample } from "@miragon/pulse-analytics-client"
+import type { RegisteredToolMeta, ToolConfig } from "@miragon/mcp-toolkit-core/tools"
+import { createEngineScope } from "../engine-ids.js"
+import { registerEngineLandscapeTools } from "./engine-landscape.js"
+
+/** The engines this server is configured for — prod-c reports nothing. */
+const scope = createEngineScope(["prod-a", "prod-b", "prod-c"])
+const register = (r: never) => registerEngineLandscapeTools(r, scope)
+
+type Config = ToolConfig<PrometheusClient>
+
+/** Registrar stand-in that captures each tool's full config instead of an MCPServer. */
+function captureConfigs(registerModule: (register: never) => void): Map<string, Config> {
+  const configs = new Map<string, Config>()
+  const register = Object.assign(
+    (config: Config) => {
+      configs.set(config.name, config)
+    },
+    { getRegisteredTools: (): RegisteredToolMeta[] => [] },
+  )
+  registerModule(register as never)
+  return configs
+}
+
+function captureHandlers(registerModule: (register: never) => void) {
+  const configs = captureConfigs(registerModule)
+  return new Map([...configs].map(([name, c]) => [name, c.handler]))
+}
+
+/** Records every PromQL string and answers with a two-engine landscape. */
+function recordingClient(): { client: PrometheusClient; queries: string[] } {
+  const queries: string[] = []
+  const cell = (engine_id: string, process_definition_key: string, value: number): PromSample => ({
+    metric: { engine_id, process_definition_key },
+    value,
+  })
+  return {
+    client: {
+      instant: (query: string) => {
+        queries.push(query)
+        if (query.includes("process_definitions_deployed")) {
+          return Promise.resolve([cell("prod-a", "order", 1), cell("prod-b", "onboarding", 1)])
+        }
+        if (query.includes("process_instances_running")) {
+          return Promise.resolve([cell("prod-a", "order", 5)])
+        }
+        return Promise.resolve([])
+      },
+    },
+    queries,
+  }
+}
+
+describe("analytics_engine_landscape", () => {
+  it("builds the inventory matrix and issues one node-folded query per metric", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    const result = (await handlers.get("analytics_engine_landscape")!(client, {})) as {
+      engines: Array<{ engineId: string; runningInstances: number }>
+      sharedProcessKeys: string[]
+    }
+
+    // Engine omitted = the configured fleet: the silent prod-c stays visible.
+    expect(result.engines.map((e) => e.engineId)).toEqual(["prod-a", "prod-b", "prod-c"])
+    expect(result.engines[0].runningInstances).toBe(5)
+    // Each engine runs its own definition — nothing to compare like-for-like.
+    expect(result.sharedProcessKeys).toEqual([])
+    const sel = '{engine_id=~"prod-a|prod-b|prod-c"}'
+    // Every gauge folded over its own labels first: a clustered engine's
+    // nodes report the same engine-wide rows.
+    const byKey = (gauge: string, labels = "process_definition_key, engine_id") =>
+      `sum by (engine_id, process_definition_key)(max by (${labels})(${gauge}${sel}))`
+    expect(queries).toEqual([
+      byKey("camunda_process_definitions_deployed"),
+      byKey("camunda_process_instances_running"),
+      byKey("camunda_incidents_open", "process_definition_key, incident_type, engine_id"),
+      byKey("camunda_jobs_failed"),
+      `max by (engine_id)(camunda_jobs_executable${sel})`,
+      `max by (engine_id)(camunda_jobs_suspended${sel})`,
+      `max by (engine_id)(camunda_jobs_due_future${sel})`,
+      `max by (engine_id)(camunda_external_tasks_open${sel})`,
+    ])
+  })
+
+  it("applies the engine filter and keeps a non-reporting engine visible", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    const result = (await handlers.get("analytics_engine_landscape")!(client, {
+      engine: ["prod-a", "prod-c"],
+    })) as { engines: Array<{ engineId: string; reporting: boolean }> }
+
+    expect(queries.every((q) => q.includes('{engine_id=~"prod-a|prod-c"}'))).toBe(true)
+    expect(result.engines.find((e) => e.engineId === "prod-c")).toMatchObject({ reporting: false })
+  })
+
+  it("never lists another tenant's engine from a shared Prometheus (N138)", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await expect(
+      handlers.get("analytics_engine_landscape")!(client, { engine: ["prod-a", "tenant-x"] }),
+    ).rejects.toThrow(/Unknown engine "tenant-x"/)
+    expect(queries).toEqual([])
+  })
+})
+
+describe("analytics_engine_landscape registration", () => {
+  const config = captureConfigs(register).get("analytics_engine_landscape")!
+
+  it("registers under the analytics category as a read-only external read", () => {
+    expect(config.category).toBe("analytics")
+    expect(config.annotations).toEqual({
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    })
+  })
+
+  it("tells the model that counts — not per-engine rates — are the point", () => {
+    // Without this the model would divide the counts back into per-engine
+    // rates and compare them, which is exactly the confound the view exists
+    // to avoid.
+    expect(config.description).toContain("counts, not rates")
+    expect(config.description).toContain("process mixes")
+    expect(config.description).toContain("sharedProcessKeys")
+  })
+
+  it("accepts an engine list or nothing at all", () => {
+    const schema = z.object(config.inputSchema)
+    expect(schema.safeParse({}).success).toBe(true)
+    expect(schema.safeParse({ engine: ["prod-a", "prod-b"] }).success).toBe(true)
+    expect(schema.safeParse({ engine: "prod-a" }).success).toBe(true)
+  })
+})

package/src/tools/engine-landscape.ts

@@ -0,0 +1,21 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import { withEngineScope, type AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerEngineLandscapeTools(
+  register: Register,
+  engineScope: AnalyticsEngineScope,
+) {
+  register({
+    name: "analytics_engine_landscape",
+    category: "analytics",
+    description:
+      "Cross-engine overview of the process landscape: which process definitions run on which engine (the inventory matrix), the absolute load per engine (running instances, open incidents, failed jobs), and the engine-owned job backlog (executable/suspended/future-due jobs, open external tasks). Reports counts, not rates, on purpose — engines host different process mixes, so a per-engine failure rate or average duration measures the mix rather than the engine. The backlog gauges carry no process label and therefore DO compare across engines. Returns `sharedProcessKeys`: the definitions deployed on more than one engine, the only sound inputs for analytics_engine_compare. Covers the server's configured engines (omitted engine = all of them); an engine reporting no metrics at all comes back with `reporting: false`.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: schemas.engineLandscapeInput.shape,
+    handler: async (ch, args) => queries.engineLandscape(ch, withEngineScope(engineScope, args)),
+  })
+}

package/src/tools/failures.ts

@@ -0,0 +1,19 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import { withEngineScope, type AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerFailureTools(register: Register, engineScope: AnalyticsEngineScope) {
+  register({
+    name: "analytics_find_failed_instances",
+    category: "analytics",
+    description:
+      "List currently-open incident patterns from process metrics, grouped by incident type and process definition (point-in-time — what is failing right now; no message, activity or timestamps). Use for counts across engines; for the actual failed instances (ids, messages) use camunda7_list_incidents, for past ones camunda7_query_historic_incidents.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: schemas.findFailedInstancesInput.shape,
+    handler: async (ch, args) =>
+      queries.findFailedInstances(ch, withEngineScope(engineScope, args)),
+  })
+}

package/src/tools/health.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest"
+import {
+  ENGINE_HEALTH_STATUS_RULE,
+  type EngineHealthResult,
+  type PrometheusClient,
+  type PromSample,
+} from "@miragon/pulse-analytics-client"
+import type { RegisteredToolMeta, ToolConfig } from "@miragon/mcp-toolkit-core/tools"
+import { createEngineScope } from "../engine-ids.js"
+import { registerHealthTools } from "./health.js"
+
+type Config = ToolConfig<PrometheusClient>
+
+/** The fleet this server is configured for. */
+const scope = createEngineScope(["prod-a", "prod-b"])
+
+/** Registrar stand-in that captures the tool's config instead of an MCPServer. */
+function captureConfig(): Config {
+  const configs: Config[] = []
+  const register = Object.assign((config: Config) => configs.push(config), {
+    getRegisteredTools: (): RegisteredToolMeta[] => [],
+  })
+  registerHealthTools(register as never, scope)
+  return configs[0]
+}
+
+/** PrometheusClient that records every instant PromQL string and answers via `answer`. */
+function recordingClient(answer: (query: string) => PromSample[] = () => []) {
+  const queries: string[] = []
+  const client: PrometheusClient = {
+    instant: (query: string) => {
+      queries.push(query)
+      return Promise.resolve(answer(query))
+    },
+  }
+  return { client, queries }
+}
+
+const run = (client: PrometheusClient, args: Record<string, unknown>) =>
+  captureConfig().handler(client, args, {} as never) as Promise<EngineHealthResult>
+
+/** Prometheus where only `prod-a` reports its engine-state gauges (when the selector admits it). */
+const onlyProdAReports = (query: string): PromSample[] =>
+  query.includes("prod-a") &&
+  (query.includes("camunda_jobs_executable") || query.includes("camunda_external_tasks_open"))
+    ? [{ metric: { engine_id: "prod-a" }, value: 0 }]
+    : []
+
+describe("analytics_engine_health — engine scope (N138)", () => {
+  it("with engine omitted, judges exactly the configured fleet — never every engine Prometheus holds", async () => {
+    const { client, queries } = recordingClient()
+    const result = await run(client, {})
+
+    expect(result.engines).toEqual(["prod-a", "prod-b"])
+    expect(queries.every((q) => q.includes('engine_id=~"prod-a|prod-b"'))).toBe(true)
+  })
+
+  it("refuses an engine id this server is not configured for, before any query", async () => {
+    const { client, queries } = recordingClient()
+    await expect(run(client, { engine: "tenant-x" })).rejects.toThrow(
+      /Unknown engine "tenant-x".*configured engines: prod-a, prod-b/,
+    )
+    expect(queries).toEqual([])
+  })
+})
+
+describe("analytics_engine_health — verdict (N76)", () => {
+  it("reads a Prometheus without any metrics of the fleet as unknown, never healthy", async () => {
+    const { client } = recordingClient()
+    const result = await run(client, {})
+    expect(result.status).toBe("unknown")
+    expect(result.silentEngines).toEqual(["prod-a", "prod-b"])
+  })
+
+  it("reads a silent engine as unknown, not as an idle healthy one", async () => {
+    const { client } = recordingClient(onlyProdAReports)
+    const result = await run(client, { engine: "prod-b" })
+    expect(result).toMatchObject({
+      status: "unknown",
+      engines: ["prod-b"],
+      reportingEngines: [],
+      silentEngines: ["prod-b"],
+    })
+  })
+
+  it("degrades the fleet verdict while one configured engine is silent", async () => {
+    const { client } = recordingClient(onlyProdAReports)
+    const result = await run(client, {})
+    expect(result).toMatchObject({
+      status: "degraded",
+      reportingEngines: ["prod-a"],
+      silentEngines: ["prod-b"],
+    })
+  })
+})
+
+describe("analytics_engine_health — alerts (N76)", () => {
+  const alertQueries = (queries: string[]) => queries.filter((q) => q.includes("ALERTS"))
+
+  it("scopes one engine's verdict to that engine's alerts only", async () => {
+    const { client, queries } = recordingClient()
+    await run(client, { engine: "prod-a" })
+    expect(alertQueries(queries)).toEqual([
+      'ALERTS{alertstate="firing",engine_id="prod-a"}',
+      'ALERTS{alertstate="pending",engine_id="prod-a"}',
+    ])
+  })
+
+  it.each([
+    ["engine omitted", {}, "prod-a|prod-b"],
+    ["every configured engine named", { engine: ["prod-b", "prod-a"] }, "prod-b|prod-a"],
+  ])(
+    "adds the module's own engine-less alerts to a verdict over the whole fleet (%s)",
+    async (_case, args, ids) => {
+      const { client, queries } = recordingClient()
+      await run(client, args)
+      expect(alertQueries(queries)[0]).toBe(
+        `ALERTS{alertstate="firing",engine_id=~"${ids}"} or ` +
+          'ALERTS{alertstate="firing",alertname=~"CibSeven.+",engine_id=""}',
+      )
+    },
+  )
+
+  it("never lets a foreign critical alert in a shared Prometheus decide the verdict", async () => {
+    // A critical alert of somebody else's rule, carrying no engine_id: the
+    // scoped selector cannot match it, so it never reaches the verdict.
+    const { client, queries } = recordingClient(onlyProdAReports)
+    const result = await run(client, { engine: "prod-a" })
+    expect(alertQueries(queries).some((q) => !q.includes('engine_id="prod-a"'))).toBe(false)
+    expect(result.status).toBe("healthy")
+  })
+})
+
+/**
+ * #340: two health tools judge different data by different rules — each
+ * states its own in the description AND the result, and routes to the other.
+ */
+describe("analytics_engine_health verdict labeling", () => {
+  it("carries the status rule — including the unknown verdict — in every result", async () => {
+    const { client } = recordingClient()
+    const result = await run(client, {})
+    expect(result.statusRule).toBe(ENGINE_HEALTH_STATUS_RULE)
+    expect(ENGINE_HEALTH_STATUS_RULE).toMatch(
+      /^From Prometheus, over the engines in scope: unknown when none of them reports metrics;/,
+    )
+  })
+
+  it("states the rule, the engine scope and the routing to camunda7_show_engine_health", () => {
+    const { description } = captureConfig()
+    expect(description).toContain(`Status: ${ENGINE_HEALTH_STATUS_RULE}`)
+    expect(description).toContain("the silent ones (`silentEngines`")
+    expect(description).toContain(
+      "Use for fleet-wide or metric-based health; for one engine's live incident clusters use camunda7_show_engine_health.",
+    )
+  })
+})

package/src/tools/health.ts

@@ -0,0 +1,29 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { ENGINE_HEALTH_STATUS_RULE, schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerHealthTools(register: Register, engineScope: AnalyticsEngineScope) {
+  register({
+    name: "analytics_engine_health",
+    category: "analytics",
+    description:
+      "Live operational health of the CIB Seven engine(s), from Prometheus state gauges: running WIP, open incidents by type, dead jobs (retries exhausted), executable/suspended job backlog, open/unassigned user tasks, external-task backlog, deployed definitions, and which alert rules are firing/pending. " +
+      "Names the engines judged and the silent ones (`silentEngines`: their counts read 0 because nothing arrives). " +
+      `Status: ${ENGINE_HEALTH_STATUS_RULE} ` +
+      "Use for fleet-wide or metric-based health; for one engine's live incident clusters use camunda7_show_engine_health.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: schemas.engineHealthInput.shape,
+    handler: async (ch, args) => {
+      const engines = engineScope.resolve(args.engine)
+      // The module's engine-less alerts (a collector outage) only count for a
+      // verdict over the whole configured fleet.
+      return queries.engineHealth(ch, {
+        engine: engines,
+        includeFleetAlerts: engineScope.coversFleet(engines),
+      })
+    },
+  })
+}

package/src/tools/index.ts

@@ -0,0 +1,44 @@
+import type { MCPServer } from "mcp-use"
+import { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import type { ProfileSource } from "../server-locale.js"
+import type { AnalyticsEngineScope } from "../engine-ids.js"
+import { registerPerformanceTools } from "./performance.js"
+import { registerFailureTools } from "./failures.js"
+import { registerElementTools } from "./element.js"
+import { registerClusterCompareTools } from "./cluster-compare.js"
+import { registerVersionCompareTools } from "./version-compare.js"
+import { registerEngineCompareTools } from "./engine-compare.js"
+import { registerEngineLandscapeTools } from "./engine-landscape.js"
+import { registerHealthTools } from "./health.js"
+
+/**
+ * `profileStore` feeds the saved analytics defaults (`modules.analytics`) into
+ * every tool that takes `period`/`minBucketSize` — the same "explicit arg >
+ * saved setting > schema default" resolution as the widget tools, so the
+ * settings contract holds across the whole tool surface. The handlers pass the
+ * ctx the registrar hands them to `settingsFor`, so the caller resolves
+ * exactly like the settings tools' own (`resolveProfileKey`).
+ *
+ * `engineScope` holds the server's configured engine ids: every tool resolves
+ * its `engine` argument through it (omitted = all of them), so no query ever
+ * reads an engine this server is not configured for (`engine-ids.ts`).
+ */
+export function registerTools(
+  server: MCPServer,
+  client: PrometheusClient,
+  engineScope: AnalyticsEngineScope,
+  profileStore?: ProfileSource,
+): void {
+  // Strict input: an unknown (e.g. misnamed) key is a tool error naming the
+  // valid keys instead of a silently dropped filter (#329).
+  const register = createToolRegistrar(server, client, { strictInput: true })
+  registerPerformanceTools(register, engineScope, profileStore)
+  registerFailureTools(register, engineScope)
+  registerElementTools(register, engineScope, profileStore)
+  registerClusterCompareTools(register, engineScope, profileStore)
+  registerVersionCompareTools(register, engineScope, profileStore)
+  registerEngineCompareTools(register, engineScope, profileStore)
+  registerEngineLandscapeTools(register, engineScope)
+  registerHealthTools(register, engineScope)
+}

package/src/tools/performance.test.ts

@@ -0,0 +1,210 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"
+import { increaseIn, type PrometheusClient } from "@miragon/pulse-analytics-client"
+import type { RegisteredToolMeta, ToolConfig } from "@miragon/mcp-toolkit-core/tools"
+import { createEngineScope } from "../engine-ids.js"
+import { registerPerformanceTools } from "./performance.js"
+
+const scope = createEngineScope(["prod-a", "prod-b"])
+const register = (r: never) => registerPerformanceTools(r, scope)
+
+type Handler = ToolConfig<PrometheusClient>["handler"]
+
+/** Registrar stand-in that captures each tool's handler instead of an MCPServer. */
+function captureHandlers(registerModule: (register: never) => void): Map<string, Handler> {
+  const handlers = new Map<string, Handler>()
+  const register = Object.assign(
+    (config: ToolConfig<PrometheusClient>) => {
+      handlers.set(config.name, config.handler)
+    },
+    { getRegisteredTools: (): RegisteredToolMeta[] => [] },
+  )
+  registerModule(register as never)
+  return handlers
+}
+
+/** 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,
+  }
+}
+
+describe("analytics_analyze_process_performance PromQL", () => {
+  it("emits the exact KPI + activity-breakdown queries, scoped to key and engine", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await handlers.get("analytics_analyze_process_performance")!(client, {
+      processDefinitionKey: "order",
+      period: "7d",
+      includeActivityBreakdown: true,
+      engine: "prod-a",
+    })
+
+    const sel = '{process_definition_key="order",engine_id="prod-a"}'
+    const completedSel = '{process_definition_key="order",engine_id="prod-a",state="COMPLETED"}'
+    const count = (series: string) => increaseIn(series, { range: "7d" })
+    const instance = "camunda_process_instance_duration_milliseconds"
+    const activity = "camunda_activity_duration_milliseconds"
+    expect(queries).toEqual([
+      `sum(${count(`camunda_process_instance_started_total${sel}`)})`,
+      `sum(${count(`camunda_process_instance_ended_total${completedSel}`)})`,
+      `sum(${count(`camunda_incident_created_total${sel}`)})`,
+      `sum(${count(`${instance}_sum${sel}`)}) / sum(${count(`${instance}_count${sel}`)})`,
+      `histogram_quantile(0.5, sum by (le)(${count(`${instance}_bucket${sel}`)}))`,
+      `histogram_quantile(0.95, sum by (le)(${count(`${instance}_bucket${sel}`)}))`,
+      `sum by (activity_id, activity_type)(${count(`camunda_activity_ended_total${sel}`)})`,
+      `sum by (activity_id)(${count(`${activity}_sum${sel}`)})`,
+      `histogram_quantile(0.5, sum by (activity_id, le)(${count(`${activity}_bucket${sel}`)}))`,
+      `histogram_quantile(0.95, sum by (activity_id, le)(${count(`${activity}_bucket${sel}`)}))`,
+    ])
+  })
+
+  it("skips the activity-breakdown queries; engine omitted reads the configured fleet", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await handlers.get("analytics_analyze_process_performance")!(client, {
+      processDefinitionKey: "order",
+      period: "30d",
+      includeActivityBreakdown: false,
+    })
+
+    expect(queries).toHaveLength(6)
+    expect(queries.every((q) => q.includes('process_definition_key="order"'))).toBe(true)
+    expect(queries.every((q) => q.includes("[30d]"))).toBe(true)
+    // Never every engine a shared Prometheus holds (N138).
+    expect(queries.every((q) => q.includes('engine_id=~"prod-a|prod-b"'))).toBe(true)
+    expect(queries.some((q) => q.includes("camunda_activity_"))).toBe(false)
+  })
+})
+
+describe("analytics_compare_execution_periods PromQL", () => {
+  // Explicit windows are clamped to [now − retention, now] — pin now.
+  beforeAll(() => {
+    vi.useFakeTimers({ toFake: ["Date"], now: Date.parse("2026-02-10T00:00:00Z") })
+  })
+  afterAll(() => {
+    vi.useRealTimers()
+  })
+
+  it("queries each period via `[duration] @ end` historical windows", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    await handlers.get("analytics_compare_execution_periods")!(client, {
+      processDefinitionKey: "order",
+      periodAFrom: "2026-01-20T00:00:00Z",
+      periodATo: "2026-01-21T00:00:00Z",
+      periodBFrom: "2026-02-01T00:00:00Z",
+      periodBTo: "2026-02-03T00:00:00Z",
+      includeActivityBreakdown: false,
+    })
+
+    const atA = Date.parse("2026-01-21T00:00:00Z") / 1000
+    const atB = Date.parse("2026-02-03T00:00:00Z") / 1000
+    const windowA = `[86400s] @ ${atA}`
+    const windowB = `[172800s] @ ${atB}`
+    const fleet = 'engine_id=~"prod-a|prod-b"'
+    // 6 KPI queries per period, period A first.
+    expect(queries).toHaveLength(12)
+    expect(queries.slice(0, 6).every((q) => q.includes(windowA))).toBe(true)
+    expect(queries.slice(6).every((q) => q.includes(windowB))).toBe(true)
+    const started = `camunda_process_instance_started_total{process_definition_key="order",${fleet}}`
+    expect(queries[0]).toBe(`sum(${increaseIn(started, { range: "86400s", at: atA })})`)
+    expect(queries[6]).toBe(`sum(${increaseIn(started, { range: "172800s", at: atB })})`)
+  })
+})
+
+describe("analytics_compare_execution_periods windows (N79)", () => {
+  beforeAll(() => {
+    vi.useFakeTimers({ toFake: ["Date"], now: Date.parse("2026-02-10T00:00:00Z") })
+  })
+  afterAll(() => {
+    vi.useRealTimers()
+  })
+
+  const base = { processDefinitionKey: "order", includeActivityBreakdown: false }
+
+  it("clamps a window reaching past now to now and reports what was measured", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+
+    const result = (await handlers.get("analytics_compare_execution_periods")!(client, {
+      ...base,
+      periodAFrom: "2026-02-01T00:00:00Z",
+      periodATo: "2026-02-05T00:00:00Z",
+      periodBFrom: "2026-02-05T00:00:00Z",
+      periodBTo: "2026-02-15T00:00:00Z",
+    })) as { kpiComparison: Array<{ window_to: string; window_days: number; partial: boolean }> }
+
+    const now = Date.parse("2026-02-10T00:00:00Z") / 1000
+    // No `@` anchor in the future: Prometheus would answer with the elapsed
+    // part while the window is reported at full length.
+    expect(queries.slice(6).every((q) => q.includes(`[432000s] @ ${now}`))).toBe(true)
+    expect(result.kpiComparison[1]).toMatchObject({
+      window_to: "2026-02-10T00:00:00.000Z",
+      window_days: 5,
+      partial: true,
+    })
+  })
+
+  it("refuses a reversed window instead of measuring a 1-second one", async () => {
+    const handlers = captureHandlers(register)
+    const { client, queries } = recordingClient()
+    await expect(
+      handlers.get("analytics_compare_execution_periods")!(client, {
+        ...base,
+        periodAFrom: "2026-02-05T00:00:00Z",
+        periodATo: "2026-02-01T00:00:00Z",
+        periodBFrom: "2026-02-05T00:00:00Z",
+        periodBTo: "2026-02-08T00:00:00Z",
+      }),
+    ).rejects.toThrow(/periodA: the window ends before it starts/)
+    expect(queries).toEqual([])
+  })
+
+  it("refuses a window entirely before the retention", async () => {
+    const handlers = captureHandlers(register)
+    const { client } = recordingClient()
+    await expect(
+      handlers.get("analytics_compare_execution_periods")!(client, {
+        ...base,
+        periodAFrom: "2025-10-01T00:00:00Z",
+        periodATo: "2025-10-08T00:00:00Z",
+        periodBFrom: "2026-02-01T00:00:00Z",
+        periodBTo: "2026-02-08T00:00:00Z",
+      }),
+    ).rejects.toThrow(/periodA: the window lies before the 30-day Prometheus retention/)
+  })
+})
+
+describe("analytics_analyze_process_performance saved defaults", () => {
+  it("resolves the CALLER's saved period from the handler ctx the registrar hands it", async () => {
+    const store = {
+      get: (key: string) =>
+        Promise.resolve(
+          key === "user-1" ? { modules: { analytics: { defaultPeriod: "30d" } } } : undefined,
+        ),
+    }
+    const handlers = captureHandlers((r) => registerPerformanceTools(r, scope, store))
+    const handler = handlers.get("analytics_analyze_process_performance")!
+    const firstQueryFor = async (ctx?: unknown) => {
+      const { client, queries } = recordingClient()
+      await handler(client, { processDefinitionKey: "order" }, ctx as never)
+      return queries[0]
+    }
+
+    expect(await firstQueryFor({ auth: { user: { id: "user-1" } } })).toContain("[30d]")
+    // Another caller, and a request without any identity, get the schema default.
+    expect(await firstQueryFor({ auth: { user: { id: "user-2" } } })).toContain("[7d]")
+    expect(await firstQueryFor()).toContain("[7d]")
+  })
+})

package/src/tools/performance.ts

@@ -0,0 +1,38 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client"
+import { schemas, queries } from "@miragon/pulse-analytics-client"
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools"
+import type { ProfileSource } from "../server-locale.js"
+import { optionalPeriod, settingsFor } from "../settings.js"
+import { withEngineScope, type AnalyticsEngineScope } from "../engine-ids.js"
+
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>
+
+export function registerPerformanceTools(
+  register: Register,
+  engineScope: AnalyticsEngineScope,
+  profileStore?: ProfileSource,
+) {
+  register({
+    name: "analytics_analyze_process_performance",
+    category: "analytics",
+    description:
+      "Analyze process performance from metrics over a rolling window: starts, completions, incidents created (incidents, not failed instances) per 100 starts, P50/P95 duration of the instances that ENDED in the window (null when none did), and a per-activity breakdown.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: { ...schemas.analyzePerformanceInput.shape, period: optionalPeriod },
+    handler: async (ch, args, ctx) =>
+      queries.analyzePerformance(ch, {
+        ...withEngineScope(engineScope, args),
+        period: args.period ?? (await settingsFor(profileStore, ctx)).defaultPeriod,
+      }),
+  })
+
+  register({
+    name: "analytics_compare_execution_periods",
+    category: "analytics",
+    description:
+      "Compare process execution metrics between two explicit time windows (before/after a change, regression analysis), using PromQL historical windows. Windows are clamped to now and the 30-day retention and reported as measured (`partial` when cut short); a reversed or wholly out-of-range window is refused. Compare windows of different length by started_per_day.",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    inputSchema: schemas.comparePeriodsInput.shape,
+    handler: async (ch, args) => queries.comparePeriods(ch, withEngineScope(engineScope, args)),
+  })
+}