@checkstack/anomaly-backend 1.2.7 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @checkstack/anomaly-backend
 
+## 1.3.0
+
+### Minor Changes
+
+- dbb76a2: fix(ai): guide the assistant to find all issues and fix the anomaly tool
+
+  Two assistant problems reported in production:
+
+  1. Asked "are there any issues?", the model answered from a single source (an
+     SLO breach) and missed a system with a failing health check. The chat
+     system prompt now instructs the model to check ALL issue sources before
+     answering - failing health checks (`healthcheck_status`), breaching/at-risk
+     SLOs (`slo_listObjectives`), active anomalies (`anomaly_list`), and open
+     incidents (`incident_list`) - and not to stop after the first source. It
+     also tells the model that `systemId` must be a real system UUID (resolve a
+     name via the catalog tool first) and to never invent ids or filter values.
+
+  2. The anomaly tool was named `anomaly.explain` but actually LISTS anomalies
+     with optional filters. The misleading name led the model to pass a
+     non-existent filter value ("Type validation failed") and a system
+     name/anomaly id as `systemId` ("a value was malformed"). Renamed to
+     `anomaly.list` with a description that spells out the optional filters and
+     their valid enum values (state: suspicious|anomaly|recovered, kind:
+     spike|drift, suppression: active|suppressed|all) and that `systemId` is a
+     system UUID.
+
+  Also sharpened the `healthcheck.status` and `slo.listObjectives` tool
+  descriptions to be use-case oriented ("use when asked what is failing /
+  breaching").
+
+  BREAKING: the anomaly read tool's name changes from `anomaly_explain` to
+  `anomaly_list` over the MCP `tools/list` surface. MCP clients referencing it by
+  the old name must update.
+
+- 0b6f01b: feat(anomaly): contribute anomaly signals to the backend system.issues aggregator
+
+  The anomaly plugin now registers a `system.issues` contributor (sourceId
+  `anomaly`) from its backend `init`, so the AI assistant surfaces confirmed
+  anomalies and suspicious states alongside incidents, SLOs, health checks, and
+  dependency problems.
+
+  The contributor enforces its own `anomaly_feed.read` access gate (returning an
+  empty map - never throwing - when the principal lacks access; service users are
+  trusted), then reads the current problem rows for every system from the shared,
+  durable `anomalies` table via a new global `getActiveSignalAnomalies` service
+  method (state = anomaly | suspicious, suppressed rows excluded). The answer is
+  therefore identical on every pod, and only systems with a current problem appear
+  in the result.
+
+  The row->signal mapping (source/tone/label/detail/href/accessRule/iconName) is
+  extracted into a new pure `deriveAnomalySignals` deriver in
+  `@checkstack/anomaly-common`, shared by both the backend contributor and the
+  frontend `AnomalySignalsFiller` so the two surfaces stay in lockstep. The
+  frontend filler now delegates to that deriver with unchanged behavior.
+
+### Patch Changes
+
+- Updated dependencies [dbb76a2]
+- Updated dependencies [0b6f01b]
+- Updated dependencies [0b6f01b]
+- Updated dependencies [0b6f01b]
+  - @checkstack/ai-backend@0.3.0
+  - @checkstack/healthcheck-backend@1.7.0
+  - @checkstack/anomaly-common@1.4.0
+  - @checkstack/healthcheck-common@1.6.0
+  - @checkstack/catalog-backend@1.4.8
+  - @checkstack/backend-api@0.21.6
+  - @checkstack/gitops-backend@0.5.6
+
 ## 1.2.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/anomaly-backend",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,18 +14,18 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.21.5",
-    "@checkstack/ai-backend": "0.2.0",
+    "@checkstack/backend-api": "0.21.6",
+    "@checkstack/ai-backend": "0.3.0",
     "@checkstack/common": "0.15.0",
-    "@checkstack/anomaly-common": "1.3.4",
+    "@checkstack/anomaly-common": "1.4.0",
     "@checkstack/signal-common": "0.2.9",
-    "@checkstack/healthcheck-common": "1.5.4",
+    "@checkstack/healthcheck-common": "1.6.0",
     "@checkstack/queue-api": "0.3.12",
     "@checkstack/cache-api": "0.3.12",
     "@checkstack/cache-utils": "0.2.17",
-    "@checkstack/healthcheck-backend": "1.6.7",
-    "@checkstack/catalog-backend": "1.4.7",
-    "@checkstack/gitops-backend": "0.5.5",
+    "@checkstack/healthcheck-backend": "1.7.0",
+    "@checkstack/catalog-backend": "1.4.8",
+    "@checkstack/gitops-backend": "0.5.6",
     "@checkstack/gitops-common": "0.6.3",
     "@checkstack/catalog-common": "2.3.4",
     "@checkstack/notification-common": "1.3.3",
@@ -38,7 +38,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.6.1",
-    "@checkstack/test-utils-backend": "0.1.39",
+    "@checkstack/test-utils-backend": "0.1.40",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "date-fns": "^4.4.0",

package/src/ai-projection.test.ts

@@ -5,20 +5,19 @@ import {
 } from "@checkstack/ai-backend";
 import { anomalyContract, pluginMetadata } from "@checkstack/anomaly-common";
 
-describe("anomaly AI projection (anomaly.explain)", () => {
+describe("anomaly AI projection (anomaly.list)", () => {
   test("projects getAnomalies as a read-only tool with the source procedure's access rules", () => {
     const tool = buildProjectedTool({
       procedure: anomalyContract.getAnomalies,
       sourcePluginMetadata: pluginMetadata,
       procedureKey: "getAnomalies",
-      name: "anomaly.explain",
-      description:
-        "List detected anomalies (statistical sigma/drift) for context. Read-only.",
+      name: "anomaly.list",
+      description: "List detected anomalies (statistical spikes / drift).",
       effect: "read",
       execute: deferredProjectionExecute,
     });
 
-    expect(tool.name).toBe("anomaly.explain");
+    expect(tool.name).toBe("anomaly.list");
     expect(tool.effect).toBe("read");
 
     // The projection inherits the source procedure's gating — it must NOT

package/src/plugin.ts

@@ -1,8 +1,11 @@
 import { createBackendPlugin, coreServices, type SafeDatabase } from "@checkstack/backend-api";
 import {
   aiToolProjectionExtensionPoint,
+  systemSignalsExtensionPoint,
+  createSystemAccessResolver,
   deferredProjectionExecute,
 } from "@checkstack/ai-backend";
+import { createAnomalySignalsContributor } from "./system-signals";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
 import { setupBaselineAnalyzerJob } from "./jobs/baseline-analyzer";
 import { processCheckCompleted } from "./detector";
@@ -58,9 +61,16 @@ export const plugin = createBackendPlugin({
       procedure: anomalyContract.getAnomalies,
       sourcePluginMetadata: pluginMetadata,
       procedureKey: "getAnomalies",
-      name: "anomaly.explain",
+      name: "anomaly.list",
       description:
-        "List detected anomalies (statistical sigma/drift) for context. Read-only.",
+        "List detected anomalies (statistical spikes / drift). Read-only. " +
+        "All filters are OPTIONAL - call with no arguments to list every " +
+        "anomaly, or narrow with: systemId (a system UUID from the catalog " +
+        "tool, never a system name), state (one of: suspicious, anomaly, " +
+        "recovered), kind (one of: spike, drift), suppression (one of: " +
+        "active, suppressed, all). Each result includes the anomaly's id and " +
+        "systemId. There is no per-anomaly 'explain' call - read the returned " +
+        "rows directly.",
       effect: "read",
       execute: deferredProjectionExecute,
     });
@@ -110,6 +120,20 @@ export const plugin = createBackendPlugin({
 
         const service = new AnomalyService(typedDb);
         gitopsService = service;
+
+        // Contribute anomaly problem state to the dashboard `system.issues`
+        // aggregator. The contributor gates the originating principal on
+        // anomaly's own read rule and reads globally from shared Postgres - see
+        // createAnomalySignalsContributor.
+        env
+          .getExtensionPoint(systemSignalsExtensionPoint)
+          .contribute(
+            createAnomalySignalsContributor({
+              service,
+              resolver: createSystemAccessResolver(rpcClient),
+            }),
+          );
+
         routerCache = createAnomalyRouterCache({ cacheManager, logger });
         const router = createRouter(service, logger, routerCache);
         rpc.registerRouter(router, anomalyContract);

package/src/service.ts

@@ -73,6 +73,45 @@ export class AnomalyService {
     }));
   }
 
+  /**
+   * Return the current "problem" anomaly rows across ALL systems, for the
+   * dashboard `system.issues` aggregator. Mirrors the frontend filler's two
+   * active queries (state = anomaly | suspicious, suppressed rows excluded) in a
+   * single global read so the backend signals match the frontend ones. Reads
+   * from shared, durable storage so every pod returns the same answer.
+   */
+  async getActiveSignalAnomalies(): Promise<
+    Array<{
+      systemId: string;
+      configurationId: string;
+      fieldPath: string;
+      startedAt: string;
+      state: schema.AnomalyState;
+    }>
+  > {
+    const rows = await this.db
+      .select({
+        systemId: schema.anomalies.systemId,
+        configurationId: schema.anomalies.configurationId,
+        fieldPath: schema.anomalies.fieldPath,
+        startedAt: schema.anomalies.startedAt,
+        state: schema.anomalies.state,
+      })
+      .from(schema.anomalies)
+      .where(
+        and(
+          inArray(schema.anomalies.state, ["anomaly", "suspicious"]),
+          isNull(schema.anomalies.suppressedAt),
+        ),
+      )
+      .orderBy(desc(schema.anomalies.startedAt));
+
+    return rows.map((r) => ({
+      ...r,
+      startedAt: r.startedAt.toISOString(),
+    }));
+  }
+
   /**
    * Globally suppress a single anomaly row. Snapshots the current observed
    * value and baseline so the inline detector can auto-unsuppress once the

package/src/system-signals.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthUser } from "@checkstack/backend-api";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { SystemAccessResolver } from "@checkstack/ai-backend";
+import { anomalyAccess } from "@checkstack/anomaly-common";
+import { createAnomalySignalsContributor } from "./system-signals";
+import type { AnomalyService } from "./service";
+
+type Rows = Awaited<ReturnType<AnomalyService["getActiveSignalAnomalies"]>>;
+
+const stubService = (
+  rows: Rows,
+): Pick<AnomalyService, "getActiveSignalAnomalies"> => ({
+  getActiveSignalAnomalies: async () => rows,
+});
+
+const sampleRows: Rows = [
+  {
+    systemId: "sys-1",
+    configurationId: "cfg-1",
+    fieldPath: "latency",
+    startedAt: "2026-06-07T10:00:00.000Z",
+    state: "anomaly",
+  },
+  {
+    systemId: "sys-2",
+    configurationId: "cfg-2",
+    fieldPath: "errors",
+    startedAt: "2026-06-07T11:00:00.000Z",
+    state: "suspicious",
+  },
+];
+
+// The per-source gate is owned/tested by createGatedSystemSignalsContributor.
+const allowAll: SystemAccessResolver = {
+  accessibleSystemIds: async ({ systemIds }) => systemIds,
+};
+const denyAll: SystemAccessResolver = { accessibleSystemIds: async () => [] };
+
+const withFeedRead: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: [
+    qualifyAccessRuleId(
+      { pluginId: anomalyAccess.feed.read.pluginId },
+      anomalyAccess.feed.read,
+    ),
+  ],
+};
+
+describe("createAnomalySignalsContributor", () => {
+  test("uses the anomaly source id", () => {
+    const contributor = createAnomalySignalsContributor({
+      service: stubService([]),
+      resolver: allowAll,
+    });
+    expect(contributor.sourceId).toBe("anomaly");
+  });
+
+  test("wires the service + shared deriver for an authorized principal", async () => {
+    const contributor = createAnomalySignalsContributor({
+      service: stubService(sampleRows),
+      resolver: allowAll,
+    });
+
+    const map = await contributor.read({ principal: withFeedRead });
+
+    expect(Object.keys(map.signals).sort()).toEqual(["sys-1", "sys-2"]);
+    expect(map.signals["sys-1"]?.[0]).toMatchObject({
+      source: "anomaly",
+      tone: "warn",
+      label: "Anomaly detected",
+    });
+    expect(map.signals["sys-2"]?.[0]).toMatchObject({
+      source: "anomaly",
+      tone: "info",
+      label: "Suspicious behaviour",
+    });
+  });
+
+  test("routes a non-global user through the team gate (no grants -> nothing)", async () => {
+    const contributor = createAnomalySignalsContributor({
+      service: stubService(sampleRows),
+      resolver: denyAll,
+    });
+    const principal: AuthUser = {
+      type: "user",
+      id: "u1",
+      accessRules: ["catalog.system.read"],
+    };
+
+    expect(await contributor.read({ principal })).toEqual({
+      accessible: false,
+      signals: {},
+    });
+  });
+});

package/src/system-signals.ts

@@ -0,0 +1,40 @@
+import {
+  createGatedSystemSignalsContributor,
+  type SystemAccessResolver,
+  type SystemSignalsContributor,
+} from "@checkstack/ai-backend";
+import {
+  anomalyAccess,
+  deriveAnomalySignals,
+  ANOMALY_SIGNAL_SOURCE_ID,
+} from "@checkstack/anomaly-common";
+import type { AnomalyService } from "./service";
+
+/**
+ * The slice of {@link AnomalyService} the contributor needs - the single global
+ * read of current problem rows. Narrowed so the contributor (and its test) does
+ * not depend on the full service surface.
+ */
+type SignalSource = Pick<AnomalyService, "getActiveSignalAnomalies">;
+
+/**
+ * Build the anomaly contributor for the dashboard `system.issues` aggregator.
+ * Reads active (anomaly/suspicious) rows globally from shared Postgres and runs
+ * the SAME deriver the frontend filler uses. The per-source access gate (global
+ * `anomaly.feed.read` plus per-system team grants) is applied by
+ * {@link createGatedSystemSignalsContributor}.
+ */
+export const createAnomalySignalsContributor = ({
+  service,
+  resolver,
+}: {
+  service: SignalSource;
+  resolver: SystemAccessResolver;
+}): SystemSignalsContributor =>
+  createGatedSystemSignalsContributor({
+    sourceId: ANOMALY_SIGNAL_SOURCE_ID,
+    accessRule: anomalyAccess.feed.read,
+    resolver,
+    readSignals: async () =>
+      deriveAnomalySignals({ rows: await service.getActiveSignalAnomalies() }),
+  });