@artemis-studio/plugin-sdk 2026.9.43 → 2026.9.44

package/index.js

@@ -9,6 +9,8 @@ export const ApiError = outsideStudio('ApiError');
 export const CONTRACT = outsideStudio('CONTRACT');
 export const CapabilityGate = outsideStudio('CapabilityGate');
 export const ConfirmByTyping = outsideStudio('ConfirmByTyping');
+export const METRIC_RANGES = outsideStudio('METRIC_RANGES');
+export const MetricChart = outsideStudio('MetricChart');
 export const NAV_GROUPS = outsideStudio('NAV_GROUPS');
 export const NodeOutcomeSummary = outsideStudio('NodeOutcomeSummary');
 export const OutcomeSummary = outsideStudio('OutcomeSummary');
@@ -27,3 +29,4 @@ export const request = outsideStudio('request');
 export const rootRoute = outsideStudio('rootRoute');
 export const useCan = outsideStudio('useCan');
 export const useMe = outsideStudio('useMe');
+export const usePluginSeries = outsideStudio('usePluginSeries');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artemis-studio/plugin-sdk",
-  "version": "2026.9.43",
+  "version": "2026.9.44",
   "description": "Build the UI of an Artemis Studio plugin: typings for the Studio APIs a plugin may use, and a Vite preset.",
   "license": "Apache-2.0",
   "repository": {

package/types/kernel/api/schema.d.ts

@@ -1700,6 +1700,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/clusters/{clusterId}/metrics/plugin": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["plugin"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/clusters/{clusterId}/health": {
         parameters: {
             query?: never;
@@ -2068,6 +2084,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/clusters/{clusterId}/alerts/plugin-metrics": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["pluginMetrics"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/clusters/{clusterId}/alerts/history": {
         parameters: {
             query?: never;
@@ -2686,6 +2718,8 @@ export interface components {
             scope?: string | null;
             enabled: boolean;
             channelIds: string[];
+            /** @description False when the rule watches a plugin metric whose plugin is not running */
+            sourceAvailable: boolean;
             /** Format: date-time */
             createdAt: string;
             /** Format: date-time */
@@ -5168,6 +5202,13 @@ export interface components {
             /** Format: int32 */
             pageSize: number;
         };
+        PluginMetricView: {
+            metric: string;
+            plugin: string;
+            description: string;
+            unit: string;
+            subject: string;
+        };
         AlertFiringPageView: {
             items: components["schemas"]["AlertFiringView"][];
             /** Format: int64 */
@@ -8542,6 +8583,34 @@ export interface operations {
             };
         };
     };
+    plugin: {
+        parameters: {
+            query?: {
+                metric?: string;
+                subject?: string;
+                from?: string;
+                to?: string;
+                step?: string;
+            };
+            header?: never;
+            path: {
+                clusterId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["MetricSeriesResponse"];
+                };
+            };
+        };
+    };
     health: {
         parameters: {
             query?: never;
@@ -9095,6 +9164,28 @@ export interface operations {
             };
         };
     };
+    pluginMetrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                clusterId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["PluginMetricView"][];
+                };
+            };
+        };
+    };
     history_2: {
         parameters: {
             query?: {

package/types/kernel/metrics/ChartPanel.d.ts

@@ -0,0 +1,28 @@
+import type { ApiError } from '../api/request.ts';
+/** Every metric plot is this tall, whatever it is currently able to show. */
+export declare const CHART_HEIGHT = 220;
+/**
+ * A titled panel around one metric plot, and the three states it can be in.
+ *
+ * Failure, emptiness and loading are rendered as three different things at one
+ * fixed height (ADR-0055). Both halves of that matter:
+ *
+ * - a metrics read that returned 500 used to render "No samples in this window
+ *   yet", which presents an outage as a fact about the cluster — and a flat empty
+ *   chart during an incident reads as "quiet", the most expensive possible
+ *   misreading;
+ * - a panel that collapses while loading and expands when data arrives moves the
+ *   page under a pointer already travelling towards something else.
+ */
+export declare function ChartPanel({ title, unit, isPending, error, isEmpty, emptyLabel, note, children, }: {
+    title: string;
+    unit: string;
+    isPending: boolean;
+    error: ApiError | null;
+    /** True when the read succeeded and carried nothing for this window. */
+    isEmpty: boolean;
+    emptyLabel: string;
+    /** A coverage caveat that belongs beside the title, not inside a tooltip. */
+    note?: React.ReactNode;
+    children: React.ReactNode;
+}): import("react").JSX.Element;

package/types/kernel/metrics/MetricChart.d.ts

@@ -0,0 +1,13 @@
+import type { MetricRange } from '../time/ranges.ts';
+/**
+ * Studio's time-proportional chart of one plugin metric for one subject (ADR-0055, ADR-0113):
+ * a titled panel that tells loading, failure and an empty window apart, over a live range.
+ */
+export declare function MetricChart({ clusterId, metric, subject, title, range, emptyLabel, }: {
+    clusterId: string;
+    metric: string;
+    subject: string;
+    title: string;
+    range?: MetricRange;
+    emptyLabel?: string;
+}): import("react").JSX.Element;

package/types/kernel/metrics/axis.d.ts

@@ -0,0 +1,71 @@
+import type { components } from '../api/schema.d.ts';
+import { type MetricRange } from '../time/ranges.ts';
+type MetricSeries = components['schemas']['MetricSeries'];
+/**
+ * Format an instant in the operator's chosen zone.
+ *
+ * Bare `dayjs(ms).format(...)` renders in the browser's zone, which used to leave
+ * the charts and the tables disagreeing on every deployment where the two differed
+ * — the axis in local time, every table in UTC, and nothing saying so. Everything
+ * that renders a metric timestamp goes through here.
+ */
+export declare function formatInZone(ms: number, pattern: string): string;
+export declare function tickFormatter(range: MetricRange): (ms: number) => string;
+export declare function labelFormatter(range: MetricRange): (ms: number) => string;
+/**
+ * Props for the recharts `XAxis` behind every metric chart.
+ *
+ * `type: 'number'` with `scale: 'time'` is the whole decision. The explicit
+ * `[from, to]` domain — rather than `['dataMin', 'dataMax']` — keeps the plotted
+ * width equal to the *requested* window, so a series that stops halfway through
+ * the range renders as a chart that is half empty rather than one that silently
+ * rescales to whatever data survived.
+ */
+export declare function timeAxisProps(range: MetricRange, from: number, to: number): {
+    type: "number";
+    scale: "time";
+    domain: [number, number];
+    tickFormatter: (ms: number) => string;
+    minTickGap: number;
+    stroke: string;
+};
+/**
+ * `integral` is for a metric that only ever takes whole values — a consumer
+ * count. Without it recharts picks fractional ticks for a small domain, and the
+ * integer formatter renders every one of them as the same "0": an axis of five
+ * identical labels beside bars of visibly different heights.
+ */
+export declare function yAxisProps(options?: {
+    integral?: boolean;
+}): {
+    allowDecimals?: boolean | undefined;
+    stroke: string;
+    width: number;
+};
+export declare function gridProps(): {
+    stroke: string;
+};
+/** Bucket boundaries a series is expected to cover, used to size the empty case. */
+export declare function bucketCount(range: MetricRange): number;
+/**
+ * Merge any number of series onto one row per timestamp, keyed by epoch ms.
+ *
+ * Series are merged by timestamp rather than by index because a metric with no
+ * samples in a bucket is simply omitted from its series, so two series over the
+ * same window can carry different bucket sets. Zipping them by position would
+ * silently pair a value with the wrong instant.
+ */
+export declare function mergeByTimestamp(named: Array<{
+    name: string;
+    series: MetricSeries | undefined;
+    field?: 'value' | 'peak';
+}>): Array<Record<string, number>>;
+/** The last point of a series, or `null` when there is none to state. */
+export declare function latest(series: MetricSeries | undefined): number | null;
+/** The first point of a series, for stating movement across the window. */
+export declare function earliest(series: MetricSeries | undefined): number | null;
+/** Depth runs to millions on a real cluster; an axis tick cannot carry the digits. */
+export declare function formatCount(value: number): string;
+export declare function formatExact(value: number): string;
+export declare function formatRate(value: number): string;
+export {};

package/types/kernel/metrics/pluginSeries.d.ts

@@ -0,0 +1,17 @@
+import { type UseQueryResult } from '@tanstack/react-query';
+import { ApiError } from '../api/request.ts';
+import type { components } from '../api/schema.d.ts';
+import { type MetricRange } from '../time/ranges.ts';
+type MetricSeriesResponse = components['schemas']['MetricSeriesResponse'];
+/**
+ * A plugin metric's series for one subject over a live range (ADR-0113). Needs the permission the
+ * plugin declared for the metric; without it the read fails like any cluster read the user may
+ * not make.
+ */
+export declare function usePluginSeries(clusterId: string, metric: string, subject: string, range?: MetricRange): UseQueryResult<MetricSeriesResponse, ApiError> & {
+    window: {
+        from: string;
+        to: string;
+    };
+};
+export {};

package/types/sdk/index.d.ts

@@ -22,6 +22,9 @@ export { ConfirmByTyping } from '../ui/ConfirmByTyping.tsx';
 export { NodeOutcomeSummary, OutcomeSummary, type OutcomeRow } from '../ui/NodeOutcomeSummary.tsx';
 export { Pager } from '../ui/Pager.tsx';
 export { VirtualTable, type GridColumn } from '../ui/VirtualTable.tsx';
+export { MetricChart } from '../kernel/metrics/MetricChart.tsx';
+export { usePluginSeries } from '../kernel/metrics/pluginSeries.ts';
+export { METRIC_RANGES, type MetricRange } from '../kernel/time/ranges.ts';
 /**
  * Shows a notification in Studio's own notification area. Import this, never
  * `@mantine/notifications` directly: that is not shared, so a plugin's own copy would show nothing.