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

package/src/widgets/hand-off.ts

@@ -0,0 +1,102 @@
+import { useMemo } from "react"
+import { useLocale, useToolQuery } from "@miragon/mcp-toolkit-ui"
+import {
+  askAiPrompt,
+  modelContextText,
+  type AskAiPrompt,
+  type HandOffParts,
+  type ModelContextSpec,
+  type ToolSurface,
+} from "@miragon/pulse-widget-shell/widgets"
+import type { AnalyticsAskAiKey } from "../messages/en.ask-ai.js"
+import { translator } from "../messages/index.js"
+
+/** An analytics hand-off: catalogue intent + the typed parts (the surface is added by the hook). */
+export interface HandOff extends Omit<HandOffParts, "surface"> {
+  intent: AnalyticsAskAiKey
+}
+
+/** An analytics view context: static summary + the typed parts. */
+export type ViewContext = Omit<ModelContextSpec, "surface">
+
+/**
+ * The camunda7 module's surface feed, by raw name — a tier-2 cross-module
+ * reference (string, not import; cf. camunda7's `analytics-probe.ts`). It
+ * reports the camunda7 tools the deployment registers for the model; when
+ * camunda7 is not active the call fails and no camunda7 tool is ever named.
+ */
+const CAMUNDA7_SURFACE_FEED = "camunda7_widget_actions_data"
+
+/**
+ * The tools an analytics widget may name for the model:
+ *
+ * - `analytics_*` — the module is active (its own widget is rendering), and
+ *   every analytics tool a hand-off names is registered by its read-only
+ *   floor (pinned by the app's hand-off surface test);
+ * - `camunda7_*` — exactly what `camunda7_widget_actions_data` reports, once
+ *   it answered (fails closed before, and without the camunda7 module).
+ */
+export function analyticsSurface(camunda7ModelTools: readonly string[] | undefined): ToolSurface {
+  return {
+    has: (tool) => tool.startsWith("analytics_") || (camunda7ModelTools?.includes(tool) ?? false),
+  }
+}
+
+/**
+ * The surface a model description can rely on WITHOUT a live query (the
+ * adapter's `describeForModel` is a pure function): analytics tools only.
+ */
+export const ANALYTICS_ONLY_SURFACE = analyticsSurface(undefined)
+
+/** {@link analyticsSurface} over the live camunda7 feed. */
+export function useAnalyticsSurface(): ToolSurface {
+  const modelTools = useToolQuery<{ modelTools?: string[] }>(
+    ["camunda7-widget-actions"],
+    CAMUNDA7_SURFACE_FEED,
+    {},
+  ).data?.modelTools
+  return useMemo(() => analyticsSurface(modelTools), [modelTools])
+}
+
+/** Pure binding of the builders to a locale and surface (the hook's body; testable without React). */
+export function bindHandOff(locale: string, surface: ToolSurface) {
+  return {
+    surface,
+    /** The Ask-AI prompt for `HandOffButton` — null when nothing in it is available here. */
+    ask: (handOff: HandOff): AskAiPrompt | null =>
+      askAiPrompt({ ...handOff, intent: translator(locale, handOff.intent), locale, surface }),
+    /** The `HostModelContext` text for a view. */
+    context: (view: ViewContext): string => modelContextText({ ...view, surface }),
+  }
+}
+
+/**
+ * The analytics widgets' ONE way to talk to the model: Ask-AI prompts and
+ * model contexts, localized to the active locale and filtered by the live
+ * tool surface (CLAUDE.md invariant 6).
+ */
+export function useHandOff() {
+  const surface = useAnalyticsSurface()
+  const locale = useLocale()
+  return useMemo(() => bindHandOff(locale, surface), [locale, surface])
+}
+
+/**
+ * The engine scope a hand-off or model context states: the result's `engines`
+ * echo — the ids the server resolved from its CONFIGURED set for the data on
+ * screen (#336) — as the `engine` id a follow-up call takes: the one id, the
+ * aggregated list, or nothing for an unscoped library result. Never a cell
+ * prop: the scope named must be the scope of the numbers shown, and an id the
+ * server did not resolve is one analytics would refuse.
+ */
+export function engineIdsOf(
+  engines: readonly string[] | null | undefined,
+): string | string[] | undefined {
+  if (!engines || engines.length === 0) return undefined
+  return engines.length === 1 ? engines[0] : [...engines]
+}
+
+/** True when the figures add up several engines (the deliberate fleet aggregate). */
+export function isAggregate(engines: readonly string[] | null | undefined): boolean {
+  return (engines?.length ?? 0) > 1
+}

package/src/widgets/index.ts

@@ -0,0 +1,124 @@
+import { adaptDataWidget } from "@miragon/pulse-widget-shell/ui"
+import type { WidgetComponent } from "@miragon/mcp-toolkit-ui/app"
+import type { AnalyticsDashboardData, FailureDashboardData } from "@miragon/pulse-analytics-client"
+import { ExecutionSummaryKpi } from "./analytics-dashboard/execution-summary-kpi.js"
+import { ExecutionPerformanceKpi } from "./analytics-dashboard/execution-performance-kpi.js"
+import { ProcessDefinitionBreakdown } from "./analytics-dashboard/definition-breakdown.js"
+import { ActivityBottleneckTable } from "./analytics-dashboard/activity-bottleneck-table.js"
+import { FailureSummaryKpi } from "./failure-dashboard/summary-kpi.js"
+import { ErrorPatternsTable } from "./failure-dashboard/error-patterns-table.js"
+import { FailureRateTable } from "./failure-dashboard/failure-rate-table.js"
+import { ClusterCompareWidget, type ClusterCompareData } from "./cluster-compare.js"
+import { VersionCompareWidget, type VersionCompareData } from "./version-compare.js"
+import { EngineCompareWidget, type EngineCompareData } from "./engine-compare.js"
+import { EngineLandscapeWidget, type EngineLandscapeData } from "./engine-landscape.js"
+import { type BpmnHeatmapData } from "@miragon/pulse-widget-shell/widgets"
+import { AnalyticsBpmnHeatmap, type AnalyticsBpmnHeatmapData } from "./bpmn-heatmap.js"
+import { AnalyticsSettingsWidget, type AnalyticsSettingsViewData } from "./settings-section.js"
+import {
+  describeActivityBottlenecks,
+  describeBpmnHeatmap,
+  describeClusterCompare,
+  describeDefinitionBreakdown,
+  describeEngineCompare,
+  describeEngineLandscape,
+  describeErrorPatterns,
+  describeExecutionPerformance,
+  describeExecutionSummary,
+  describeFailureRates,
+  describeFailureSummary,
+  describeVersionCompare,
+} from "./model-descriptions.js"
+
+export type {
+  AnalyticsDashboardData,
+  FailureDashboardData,
+  ClusterCompareData,
+  VersionCompareData,
+  EngineCompareData,
+  EngineLandscapeData,
+  BpmnHeatmapData,
+  AnalyticsBpmnHeatmapData,
+  AnalyticsSettingsViewData,
+}
+
+export const ANALYTICS_DATA_TYPES = {
+  dashboard: "analytics:dashboard",
+  failureDashboard: "analytics:failureDashboard",
+  clusterCompare: "analytics:clusterCompare",
+  versionCompare: "analytics:versionCompare",
+  engineCompare: "analytics:engineCompare",
+  engineLandscape: "analytics:engineLandscape",
+  bpmnHeatmap: "analytics:bpmnHeatmap",
+  settings: "analytics:settings",
+} as const
+
+// Every widget passes a `describeForModel` so the model always knows the view,
+// its active filters (period / engine scope) and the headline numbers — see
+// `model-descriptions.ts` for the house pattern.
+export const analyticsWidgets: Record<string, WidgetComponent> = {
+  "analytics:execution-summary-kpi": adaptDataWidget(
+    ExecutionSummaryKpi,
+    ANALYTICS_DATA_TYPES.dashboard,
+    describeExecutionSummary,
+  ),
+  "analytics:execution-performance-kpi": adaptDataWidget(
+    ExecutionPerformanceKpi,
+    ANALYTICS_DATA_TYPES.dashboard,
+    describeExecutionPerformance,
+  ),
+  "analytics:process-definition-breakdown": adaptDataWidget(
+    ProcessDefinitionBreakdown,
+    ANALYTICS_DATA_TYPES.dashboard,
+    describeDefinitionBreakdown,
+  ),
+  "analytics:activity-bottleneck-table": adaptDataWidget(
+    ActivityBottleneckTable,
+    ANALYTICS_DATA_TYPES.dashboard,
+    describeActivityBottlenecks,
+  ),
+  "analytics:failure-summary-kpi": adaptDataWidget(
+    FailureSummaryKpi,
+    ANALYTICS_DATA_TYPES.failureDashboard,
+    describeFailureSummary,
+  ),
+  "analytics:error-patterns-table": adaptDataWidget(
+    ErrorPatternsTable,
+    ANALYTICS_DATA_TYPES.failureDashboard,
+    describeErrorPatterns,
+  ),
+  "analytics:failure-rate-table": adaptDataWidget(
+    FailureRateTable,
+    ANALYTICS_DATA_TYPES.failureDashboard,
+    describeFailureRates,
+  ),
+  "analytics:cluster-compare": adaptDataWidget(
+    ClusterCompareWidget,
+    ANALYTICS_DATA_TYPES.clusterCompare,
+    describeClusterCompare,
+  ),
+  "analytics:version-compare": adaptDataWidget(
+    VersionCompareWidget,
+    ANALYTICS_DATA_TYPES.versionCompare,
+    describeVersionCompare,
+  ),
+  "analytics:engine-compare": adaptDataWidget(
+    EngineCompareWidget,
+    ANALYTICS_DATA_TYPES.engineCompare,
+    describeEngineCompare,
+  ),
+  "analytics:engine-landscape": adaptDataWidget(
+    EngineLandscapeWidget,
+    ANALYTICS_DATA_TYPES.engineLandscape,
+    describeEngineLandscape,
+  ),
+  "analytics:bpmn-heatmap": adaptDataWidget(
+    AnalyticsBpmnHeatmap,
+    ANALYTICS_DATA_TYPES.bpmnHeatmap,
+    describeBpmnHeatmap,
+  ),
+  // No describeForModel here: the widget renders its ModelContext inline (the
+  // settings tab mounts it without pipeline data, so only the component knows
+  // the self-fetched view).
+  "analytics:settings": adaptDataWidget(AnalyticsSettingsWidget, ANALYTICS_DATA_TYPES.settings),
+}

package/src/widgets/model-descriptions.dashboard.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from "vitest"
+import type { AnalyticsDashboardData, CompareKpiDelta } from "@miragon/pulse-analytics-client"
+import type { AnalyticsBpmnHeatmapData } from "./bpmn-heatmap.js"
+import {
+  describeActivityBottlenecks,
+  describeBpmnHeatmap,
+  describeClusterCompare,
+  describeDefinitionBreakdown,
+  describeEngineCompare,
+  describeExecutionPerformance,
+  describeExecutionSummary,
+} from "./model-descriptions.js"
+
+/**
+ * The analytics-dashboard, comparison and heatmap model descriptions (#336
+ * facts in #338's modelContextText): the scope is the data's echo, window
+ * flows stay apart from the live gauges, and an unmeasured figure is left out.
+ */
+
+const dashboard = (over: Partial<AnalyticsDashboardData> = {}): AnalyticsDashboardData => ({
+  processDefinitionKey: null,
+  period: "7d",
+  engines: ["prod-a", "prod-b"],
+  totalCount: 40,
+  completedCount: 30,
+  incidentsCreated: 5,
+  incidentsResolved: 2,
+  incidentRatePct: 12.5,
+  avgDurationMs: 60_000,
+  medianDurationMs: 45_000,
+  p95DurationMs: 187_000,
+  runningNow: 156,
+  openIncidentsNow: 12,
+  previous: null,
+  activityBreakdown: [],
+  activityCount: 0,
+  definitionBreakdown: [
+    {
+      processDefinitionKey: "order",
+      totalInstances: 30,
+      completed: 25,
+      runningNow: 100,
+      incidentsCreated: 4,
+      avgDurationMs: 1,
+    },
+    {
+      processDefinitionKey: "refund",
+      totalInstances: 10,
+      completed: 5,
+      runningNow: null,
+      incidentsCreated: 1,
+      avgDurationMs: 2,
+    },
+  ],
+  ...over,
+})
+
+describe("dashboard model descriptions", () => {
+  it("labels the fleet aggregate with its engines and the period it covers (K33)", () => {
+    const text = describeExecutionSummary(dashboard(), {})
+    expect(text).toContain('Ids: engine=["prod-a","prod-b"], period="7d"\n')
+    expect(text).toContain("(aggregated)")
+    expect(text).toContain(
+      "Tools: analytics_analyze_process_performance, analytics_find_failed_instances",
+    )
+  })
+
+  it("reads the scope from the data, never from the cell props", () => {
+    const text = describeExecutionSummary(
+      dashboard({ processDefinitionKey: "order", engines: ["prod-a"], period: "1d" }),
+      { engine: "prod-b", period: "30d" },
+    )
+    expect(text).toContain('Ids: engine="prod-a", processDefinitionKey="order", period="1d"\n')
+    expect(text).not.toContain("prod-b")
+    // Scoped to one process: no definition count.
+    expect(text).not.toContain("processDefinitions=")
+  })
+
+  it("keeps window flows and the live gauges apart (N77)", () => {
+    const text = describeExecutionSummary(dashboard(), {})
+    expect(text).toContain(
+      "processDefinitions=2, startedInWindow=40, completedInWindow=30, incidentsCreatedInWindow=5, incidentsResolvedInWindow=2, runningNow=156, openIncidentsNow=12",
+    )
+    expect(text).toContain("incidents, not failed instances")
+  })
+
+  it("never reads an unreported gauge or an empty duration window as 0 (N78)", () => {
+    const text = describeExecutionSummary(
+      dashboard({ runningNow: null, openIncidentsNow: null }),
+      {},
+    )
+    expect(text).not.toMatch(/runningNow|openIncidentsNow/)
+    const perf = describeExecutionPerformance(
+      dashboard({
+        avgDurationMs: null,
+        medianDurationMs: null,
+        p95DurationMs: null,
+        incidentRatePct: null,
+      }),
+      {},
+    )
+    expect(perf).toContain("No instance ended in the period")
+    expect(perf).not.toMatch(/DurationMs|incidentRatePct/)
+    expect(describeExecutionPerformance(dashboard(), {})).toContain(
+      "avgDurationMs=60000, medianDurationMs=45000, p95DurationMs=187000, incidentRatePct=12.5",
+    )
+  })
+
+  it("states the previous period's rate the screen judges against, and when it is noise", () => {
+    const previous = {
+      totalCount: 30,
+      incidentsCreated: 2,
+      incidentRatePct: 6.7,
+      partial: false,
+      suppressed: false,
+    }
+    const scoped = { processDefinitionKey: "order" }
+    const text = describeExecutionPerformance(dashboard({ ...scoped, previous }), {})
+    expect(text).toContain("incidentRatePct=12.5, previousPeriodIncidentRatePct=6.7")
+    expect(text).not.toContain("NotReliable")
+    expect(text).not.toContain("mix")
+    const noisy = describeExecutionPerformance(
+      dashboard({ ...scoped, previous: { ...previous, suppressed: true } }),
+      {},
+    )
+    expect(noisy).toContain("previousPeriodComparisonNotReliable=true")
+  })
+
+  // Simpson's paradox: a rate over several processes moves with their mix.
+  it("says a rate over several processes is not judged against the previous period", () => {
+    const previous = {
+      totalCount: 30,
+      incidentsCreated: 2,
+      incidentRatePct: 6.7,
+      partial: false,
+      suppressed: true,
+    }
+    const text = describeExecutionPerformance(dashboard({ previous }), {})
+    expect(text).toContain("reflects their mix and is not judged")
+    expect(text).toContain("previousPeriodIncidentRatePct=6.7")
+    expect(text).not.toContain("NotReliable")
+  })
+
+  it("names the busiest definition with its window flows and live state", () => {
+    const text = describeDefinitionBreakdown(dashboard(), {})
+    expect(text).toContain(
+      'busiestProcessDefinitionKey="order", busiestStartedInWindow=30, busiestIncidentsCreatedInWindow=4, busiestRunningNow=100',
+    )
+    expect(text).toContain("Tools: analytics_show_dashboard")
+  })
+
+  it("names the process of the top activity — ids repeat across models (N84)", () => {
+    const text = describeActivityBottlenecks(
+      dashboard({
+        activityBreakdown: [
+          {
+            processDefinitionKey: "invoice",
+            activityId: "StartEvent_1",
+            activityType: "startEvent",
+            executionCount: 9,
+            avgDurationMs: 10,
+            p95DurationMs: 20,
+            totalTimeMs: 90,
+          },
+        ],
+      }),
+      {},
+    )
+    expect(text).toContain('topProcessDefinitionKey="invoice", topActivityId="StartEvent_1"')
+    expect(text).toContain('Ids: engine=["prod-a","prod-b"], period="7d"')
+    // The whole breakdown is on screen: no "in all" count.
+    expect(text).not.toContain("activitiesInAll")
+  })
+
+  it("says a cut list is the top of more activities", () => {
+    const row = {
+      processDefinitionKey: "invoice",
+      activityId: "Task_A",
+      activityType: "userTask",
+      executionCount: 9,
+      avgDurationMs: 10,
+      p95DurationMs: 20,
+      totalTimeMs: 90,
+    }
+    const text = describeActivityBottlenecks(
+      dashboard({ activityBreakdown: [row], activityCount: 37 }),
+      {},
+    )
+    expect(text).toContain("rows=1, activitiesInAll=37")
+  })
+})
+
+const delta: CompareKpiDelta = {
+  started_per_day_delta_pct: 5,
+  incident_rate_delta_pp: -1.5,
+  element_incident_rate_delta_pp: null,
+  avg_duration_delta_pct: 0,
+  p95_duration_delta_pct: null,
+}
+
+describe("the comparison descriptions", () => {
+  it("cluster compare: re-runs as asked, states the windows as measured", () => {
+    const text = describeClusterCompare(
+      {
+        engines: ["prod-a"],
+        processDefinitionKey: null,
+        activityId: null,
+        deploymentTimestamp: "2026-07-01T12:00:00Z",
+        requestedWindowDays: { before: 7, after: 7 },
+        windowDays: { before: 7, after: 0.42 },
+        partial: true,
+        minBucketSize: 10,
+        suppressed: true,
+        kpis: [],
+        delta,
+      },
+      {},
+    )
+    // The tool takes whole days: the requested windows, never the measured 0.42.
+    expect(text).toContain(
+      'Ids: engine="prod-a", deploymentTimestamp="2026-07-01T12:00:00Z", windowBeforeDays=7, windowAfterDays=7\n',
+    )
+    expect(text).toContain("measuredBeforeDays=7, measuredAfterDays=0.42")
+    expect(text).toContain("starts compare per day")
+    expect(text).toContain('largestDelta="startedPerDayDeltaPct"')
+    expect(text).toContain("suppressed=true")
+    expect(text).toContain("treat the deltas as noise")
+    expect(text).not.toMatch(/failure/i)
+  })
+
+  it("engine compare: the process is held fixed", () => {
+    const text = describeEngineCompare(
+      {
+        engineA: "prod-a",
+        engineB: "prod-b",
+        processDefinitionKey: "order",
+        windowDays: 14,
+        activityId: null,
+        minBucketSize: 10,
+        suppressed: false,
+        kpis: [],
+        delta,
+      },
+      {},
+    )
+    expect(text).toContain(
+      'Ids: processDefinitionKey="order", engineA="prod-a", engineB="prod-b", windowDays=14',
+    )
+    expect(text).toContain("attributable to the engine")
+    expect(text).not.toContain("noise")
+  })
+})
+
+describe("describeBpmnHeatmap", () => {
+  const heatmap = (engines: string[]): AnalyticsBpmnHeatmapData => ({
+    processDefinitionKey: "order",
+    period: "7d",
+    engines,
+    frequency: { Task_A: 12, Task_B: 4 },
+    durationSec: { Task_A: 1.04, Task_B: 9.26 },
+  })
+
+  it("names the engines whose heat it adds up (K33)", () => {
+    const fleet = describeBpmnHeatmap(heatmap(["prod-a", "prod-b"]), {})
+    expect(fleet).toContain(
+      'Ids: engine=["prod-a","prod-b"], processDefinitionKey="order", period="7d"',
+    )
+    expect(fleet).toContain("(aggregated)")
+    expect(describeBpmnHeatmap(heatmap(["prod-b"]), {})).toContain(
+      'Ids: engine="prod-b", processDefinitionKey="order", period="7d"',
+    )
+  })
+
+  it("the hottest and slowest element as facts", () => {
+    const text = describeBpmnHeatmap(heatmap(["prod-a"]), {})
+    expect(text).toContain('hottestActivityId="Task_A", hottestExecutions=12')
+    expect(text).toContain('slowestActivityId="Task_B", slowestAvgSec=9.3')
+    expect(text).toContain("Tools: analytics_element_bottleneck")
+  })
+})