@checkstack/ai-backend 0.1.6 → 0.3.0

package/src/tools/system-issues.test.ts

@@ -0,0 +1,236 @@
+import { describe, test, expect } from "bun:test";
+import type { AuthUser } from "@checkstack/backend-api";
+import type { SystemSignal, SystemSignalsMap } from "@checkstack/catalog-common";
+import type {
+  SystemSignalsContributor,
+  SystemSignalsContribution,
+} from "../extension-points";
+import {
+  mergeSystemSignalsMaps,
+  collectSystemSignals,
+  toSystemIssuesOutput,
+  type SystemSignalsCollection,
+} from "./system-issues";
+
+const signal = (over: Partial<SystemSignal> = {}): SystemSignal => ({
+  source: "incident",
+  tone: "error",
+  label: "Critical incident",
+  ...over,
+});
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.read"],
+};
+
+/** A contributor that is accessible and returns `signals`. */
+const ok = (
+  sourceId: string,
+  signals: SystemSignalsMap,
+): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => ({
+    accessible: true,
+    signals,
+  }),
+});
+
+/** A contributor the principal cannot access. */
+const denied = (sourceId: string): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => ({
+    accessible: false,
+    signals: {},
+  }),
+});
+
+/** A contributor that throws while reading. */
+const throwing = (sourceId: string): SystemSignalsContributor => ({
+  sourceId,
+  read: async (): Promise<SystemSignalsContribution> => {
+    throw new Error(`${sourceId} exploded`);
+  },
+});
+
+const emptyCollection = (
+  merged: SystemSignalsMap,
+): SystemSignalsCollection => ({
+  merged,
+  checkedSources: [],
+  inaccessibleSources: [],
+  failedSources: [],
+});
+
+describe("mergeSystemSignalsMaps", () => {
+  test("merges two maps by systemId, concatenating signal arrays", () => {
+    const a: SystemSignalsMap = {
+      sysA: [signal({ source: "incident", label: "Incident" })],
+      sysB: [signal({ source: "incident", label: "B incident" })],
+    };
+    const b: SystemSignalsMap = {
+      sysA: [signal({ source: "slo", tone: "warn", label: "SLO at risk" })],
+      sysC: [signal({ source: "anomaly", tone: "warn", label: "Anomaly" })],
+    };
+
+    const merged = mergeSystemSignalsMaps([a, b]);
+
+    expect(Object.keys(merged).sort()).toEqual(["sysA", "sysB", "sysC"]);
+    // sysA gets both sources concatenated.
+    expect(merged.sysA).toHaveLength(2);
+    expect(merged.sysA.map((s) => s.source)).toEqual(["incident", "slo"]);
+    expect(merged.sysB).toHaveLength(1);
+    expect(merged.sysC).toHaveLength(1);
+  });
+
+  test("does not mutate the input maps", () => {
+    const a: SystemSignalsMap = { sysA: [signal()] };
+    const b: SystemSignalsMap = { sysA: [signal({ source: "slo" })] };
+
+    mergeSystemSignalsMaps([a, b]);
+
+    expect(a.sysA).toHaveLength(1);
+    expect(b.sysA).toHaveLength(1);
+  });
+
+  test("skips empty signal arrays", () => {
+    const merged = mergeSystemSignalsMaps([{ sysA: [] }, { sysB: [signal()] }]);
+    expect(Object.keys(merged)).toEqual(["sysB"]);
+  });
+});
+
+describe("collectSystemSignals", () => {
+  test("merges signals from accessible contributors and lists them as checked", async () => {
+    const contributors = [
+      ok("incident", { sysA: [signal({ source: "incident" })] }),
+      ok("slo", {
+        sysA: [signal({ source: "slo", tone: "warn", label: "SLO" })],
+        sysB: [signal({ source: "slo", tone: "warn", label: "SLO B" })],
+      }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    expect(result.merged.sysA.map((s) => s.source)).toEqual([
+      "incident",
+      "slo",
+    ]);
+    expect(result.merged.sysB).toHaveLength(1);
+    expect(result.checkedSources.sort()).toEqual(["incident", "slo"]);
+    expect(result.inaccessibleSources).toEqual([]);
+    expect(result.failedSources).toEqual([]);
+  });
+
+  test("reports an inaccessible source distinctly (not as empty/clear)", async () => {
+    const contributors = [
+      denied("incident"),
+      ok("slo", { sysA: [signal({ source: "slo" })] }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    // The denied source contributes no signals but IS surfaced so the model
+    // can say "could not check incidents" instead of "no incidents".
+    expect(Object.keys(result.merged)).toEqual(["sysA"]);
+    expect(result.inaccessibleSources).toEqual(["incident"]);
+    expect(result.checkedSources).toEqual(["slo"]);
+    expect(result.failedSources).toEqual([]);
+  });
+
+  test("reports a throwing contributor as failed without breaking the call", async () => {
+    const contributors = [
+      throwing("boom"),
+      ok("incident", { sysA: [signal({ source: "incident" })] }),
+    ];
+
+    const result = await collectSystemSignals({ contributors, principal });
+
+    expect(Object.keys(result.merged)).toEqual(["sysA"]);
+    expect(result.failedSources).toEqual(["boom"]);
+    expect(result.checkedSources).toEqual(["incident"]);
+  });
+
+  test("no contributors produces no entries and empty coverage", async () => {
+    const result = await collectSystemSignals({ contributors: [], principal });
+    expect(result.merged).toEqual({});
+    expect(result.checkedSources).toEqual([]);
+    expect(result.inaccessibleSources).toEqual([]);
+    expect(result.failedSources).toEqual([]);
+  });
+});
+
+describe("toSystemIssuesOutput", () => {
+  test("groups signals by system and counts totals", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [signal({ source: "incident" }), signal({ source: "slo" })],
+        sysB: [signal({ source: "anomaly" })],
+      }),
+    });
+
+    expect(out.totalSystems).toBe(2);
+    expect(out.totalSignals).toBe(3);
+    const sysA = out.systems.find((s) => s.systemId === "sysA");
+    expect(sysA?.signals.map((s) => s.source)).toEqual(["incident", "slo"]);
+  });
+
+  test("passes per-source coverage through to the output", () => {
+    const out = toSystemIssuesOutput({
+      collection: {
+        merged: { sysA: [signal()] },
+        checkedSources: ["incident", "slo"],
+        inaccessibleSources: ["healthcheck"],
+        failedSources: ["dependency"],
+      },
+    });
+
+    expect(out.checkedSources).toEqual(["incident", "slo"]);
+    expect(out.inaccessibleSources).toEqual(["healthcheck"]);
+    expect(out.failedSources).toEqual(["dependency"]);
+  });
+
+  test("narrows to the requested systemIds", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [signal()],
+        sysB: [signal()],
+      }),
+      systemIds: ["sysB"],
+    });
+
+    expect(out.systems.map((s) => s.systemId)).toEqual(["sysB"]);
+    expect(out.totalSystems).toBe(1);
+  });
+
+  test("drops href/accessRule/iconName, keeps source/tone/label/detail/since", () => {
+    const out = toSystemIssuesOutput({
+      collection: emptyCollection({
+        sysA: [
+          signal({
+            detail: "2 of 3 checks failing",
+            since: "2026-06-07T00:00:00Z",
+            href: "/checkstack/x",
+            accessRule: {
+              id: "x",
+              resource: "x",
+              level: "read",
+              pluginId: "p",
+              description: "view x",
+            },
+            iconName: "TriangleAlert",
+          }),
+        ],
+      }),
+    });
+
+    const s = out.systems[0].signals[0];
+    expect(s).toEqual({
+      source: "incident",
+      tone: "error",
+      label: "Critical incident",
+      detail: "2 of 3 checks failing",
+      since: "2026-06-07T00:00:00Z",
+    });
+  });
+});

package/src/tools/system-issues.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { AuthUser } from "@checkstack/backend-api";
+import {
+  catalogAccess,
+  pluginMetadata as catalogPluginMetadata,
+} from "@checkstack/catalog-common";
+import type { SystemSignal, SystemSignalsMap } from "@checkstack/catalog-common";
+import type { SystemSignalsContributor } from "../extension-points";
+import type { RegisteredAiTool } from "../tool-registry";
+
+/** Input for `system.issues`: optionally narrow the answer to specific systems. */
+export const SystemIssuesInputSchema = z.object({
+  /**
+   * When provided, only signals for these system ids are returned. Omit to get
+   * issues across ALL systems the principal can see.
+   */
+  systemIds: z.array(z.string()).optional(),
+});
+export type SystemIssuesInput = z.infer<typeof SystemIssuesInputSchema>;
+
+/** One signal as surfaced to the model (the source it came from is carried inline). */
+export const SystemIssueSignalSchema = z.object({
+  source: z.string(),
+  tone: z.enum(["error", "warn", "info"]),
+  label: z.string(),
+  detail: z.string().optional(),
+  since: z.string().optional(),
+});
+
+/** All current issues for one system. */
+export const SystemIssuesGroupSchema = z.object({
+  systemId: z.string(),
+  signals: z.array(SystemIssueSignalSchema),
+});
+
+/** The model-facing result: issues grouped by system, plus per-source coverage. */
+export const SystemIssuesOutputSchema = z.object({
+  /** One entry per system that currently has at least one issue. */
+  systems: z.array(SystemIssuesGroupSchema),
+  /** Total number of systems with issues (== `systems.length`). */
+  totalSystems: z.number(),
+  /** Total number of individual signals across all systems. */
+  totalSignals: z.number(),
+  /** Sources that were successfully checked (the answer covers these). */
+  checkedSources: z.array(z.string()),
+  /**
+   * Sources the caller lacks permission to read. These were NOT checked, so an
+   * empty `systems` does NOT mean these sources are clear - tell the operator
+   * they could not be checked due to access.
+   */
+  inaccessibleSources: z.array(z.string()),
+  /** Sources that errored while being read (also not reflected in `systems`). */
+  failedSources: z.array(z.string()),
+});
+export type SystemIssuesOutput = z.infer<typeof SystemIssuesOutputSchema>;
+
+/** Per-source outcome of a {@link collectSystemSignals} fan-out. */
+export interface SystemSignalsCollection {
+  merged: SystemSignalsMap;
+  checkedSources: string[];
+  inaccessibleSources: string[];
+  failedSources: string[];
+}
+
+/**
+ * Merge several contributors' {@link SystemSignalsMap}s into one map keyed by
+ * systemId, concatenating the signal arrays for systems that appear in more than
+ * one source. Pure and order-stable (sources are concatenated in input order),
+ * so it is unit-testable without standing up an environment.
+ */
+export function mergeSystemSignalsMaps(
+  maps: SystemSignalsMap[],
+): SystemSignalsMap {
+  const merged: SystemSignalsMap = {};
+  for (const map of maps) {
+    for (const [systemId, signals] of Object.entries(map)) {
+      if (signals.length === 0) continue;
+      const existing = merged[systemId];
+      if (existing) {
+        existing.push(...signals);
+      } else {
+        merged[systemId] = [...signals];
+      }
+    }
+  }
+  return merged;
+}
+
+/**
+ * Shape a merged {@link SystemSignalsMap} into the model-friendly grouped
+ * result, optionally narrowed to `systemIds`. Drops the link/icon fields the
+ * model does not need (`href`, `accessRule`, `iconName`) and keeps
+ * source/tone/label/detail/since.
+ */
+export function toSystemIssuesOutput({
+  collection,
+  systemIds,
+}: {
+  collection: SystemSignalsCollection;
+  systemIds?: string[];
+}): SystemIssuesOutput {
+  const allow = systemIds ? new Set(systemIds) : undefined;
+  const systems = Object.entries(collection.merged)
+    .filter(([systemId]) => !allow || allow.has(systemId))
+    .map(([systemId, signals]) => ({
+      systemId,
+      signals: signals.map((s: SystemSignal) => ({
+        source: s.source,
+        tone: s.tone,
+        label: s.label,
+        detail: s.detail,
+        since: s.since,
+      })),
+    }));
+  return {
+    systems,
+    totalSystems: systems.length,
+    totalSignals: systems.reduce((sum, s) => sum + s.signals.length, 0),
+    checkedSources: collection.checkedSources,
+    inaccessibleSources: collection.inaccessibleSources,
+    failedSources: collection.failedSources,
+  };
+}
+
+/**
+ * Read every contributor's signals for `principal` and return the merged map
+ * plus per-source coverage. Each source is classified so the caller can tell
+ * "checked and clear" apart from "skipped":
+ *  - checked: read succeeded and the principal could access it,
+ *  - inaccessible: the principal lacked access (`accessible: false`),
+ *  - failed: the contributor threw.
+ * A throwing/denied source never breaks the whole call.
+ */
+export async function collectSystemSignals({
+  contributors,
+  principal,
+}: {
+  contributors: SystemSignalsContributor[];
+  principal: AuthUser;
+}): Promise<SystemSignalsCollection> {
+  const settled = await Promise.allSettled(
+    contributors.map((c) => c.read({ principal })),
+  );
+  const maps: SystemSignalsMap[] = [];
+  const checkedSources: string[] = [];
+  const inaccessibleSources: string[] = [];
+  const failedSources: string[] = [];
+  for (const [index, result] of settled.entries()) {
+    const { sourceId } = contributors[index];
+    if (result.status !== "fulfilled") {
+      failedSources.push(sourceId);
+      continue;
+    }
+    if (!result.value.accessible) {
+      inaccessibleSources.push(sourceId);
+      continue;
+    }
+    checkedSources.push(sourceId);
+    maps.push(result.value.signals);
+  }
+  return {
+    merged: mergeSystemSignalsMaps(maps),
+    checkedSources,
+    inaccessibleSources,
+    failedSources,
+  };
+}
+
+/**
+ * `system.issues` - the single "what are the current issues" tool. It fans out
+ * across every backend `SystemSignalsContributor` (failing health checks,
+ * breaching/at-risk SLOs, active anomalies, open incidents, active
+ * maintenances, dependency problems) and returns them aggregated across systems
+ * in ONE call. `effect: "read"` (auto-runs).
+ *
+ * The `contributors` array is the live array from
+ * `createSystemSignalsExtensionPoint`, read at execute time so contributors
+ * registered during plugin init are always seen.
+ */
+export function createSystemIssuesTool({
+  contributors,
+}: {
+  contributors: SystemSignalsContributor[];
+}): RegisteredAiTool<SystemIssuesInput, SystemIssuesOutput> {
+  return {
+    name: "system.issues",
+    description:
+      "Return ALL current system issues - failing health checks, breaching or at-risk SLOs, active anomalies, open incidents, active maintenances, and dependency problems - aggregated across every system in ONE call. Use this FIRST whenever asked whether there are any issues, what is wrong, what is down, or for an overall health overview, before reaching for any per-domain tool. Read-only. Optionally pass systemIds to narrow the answer to specific systems. The result lists `checkedSources`, plus `inaccessibleSources` (you lack permission to read these - they were NOT checked, so do not report them as clear) and `failedSources` (errored). If either is non-empty, tell the operator those sources could not be checked.",
+    effect: "read",
+    input: SystemIssuesInputSchema,
+    output: SystemIssuesOutputSchema,
+    // The TOOL is gated by catalog.system.read; PER-SOURCE access is enforced
+    // inside each contributor (a source the principal cannot see returns {}).
+    requiredAccessRules: [
+      qualifyAccessRuleId(catalogPluginMetadata, catalogAccess.system.read),
+    ],
+    async execute({
+      input,
+      principal,
+    }: {
+      input: SystemIssuesInput;
+      principal: AuthUser;
+    }) {
+      const collection = await collectSystemSignals({ contributors, principal });
+      return toSystemIssuesOutput({ collection, systemIds: input.systemIds });
+    },
+  };
+}

package/src/tools/tool-set.e2e.test.ts

@@ -38,7 +38,7 @@ describe("ai-backend's own platform tool set", () => {
   test("docs + probe tools are registered and qualified", () => {
     const registry = buildOwnRegistry();
     const names = registry.getTools().map((t) => t.name);
-    for (const expected of ["ai.searchDocs", "ai.getDoc", "ai.probeUrl"]) {
+    for (const expected of ["ai_searchDocs", "ai_getDoc", "ai_probeUrl"]) {
       expect(names).toContain(expected);
     }
   });

package/tsconfig.json

@@ -7,9 +7,15 @@
     {
       "path": "../ai-common"
     },
+    {
+      "path": "../auth-common"
+    },
     {
       "path": "../backend-api"
     },
+    {
+      "path": "../catalog-common"
+    },
     {
       "path": "../common"
     },