@checkstack/incident-backend 1.4.0 → 1.6.0

package/src/ai/incident-resolve.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  IncidentApi,
+  incidentAccess,
+  pluginMetadata,
+  type IncidentWithSystems,
+} from "@checkstack/incident-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `incident.resolve`: the incident id plus an optional message. */
+export const IncidentResolveInputSchema = z.object({
+  id: z.string(),
+  message: z.string().optional(),
+});
+export type IncidentResolveInput = z.infer<typeof IncidentResolveInputSchema>;
+
+/** Output returned once a human applies the resolution (the resolved incident). */
+export interface IncidentResolveApplyResult {
+  incident: IncidentWithSystems;
+}
+
+/**
+ * `incident.resolve` - mark an incident resolved by id, optionally with a final
+ * status-update message.
+ *
+ * `effect: "mutate"` - resolving is a non-destructive status change, so it
+ * auto-applies in AUTO mode and is confirm-gated in APPROVE mode. `dryRun`
+ * returns the captured payload for human review WITHOUT mutating; `execute`
+ * (reached only via `apply`) resolves the incident. The underlying RPC uses the
+ * USER-SCOPED client passed at call time, so handler-side authorization is
+ * enforced exactly as a direct UI/RPC call.
+ */
+export function createIncidentResolveTool(): RegisteredAiTool<
+  IncidentResolveInput,
+  IncidentResolveApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: IncidentResolveInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<IncidentResolveInput>> => {
+    return {
+      summary: `Resolve incident ${input.id}${input.message ? ` with message "${input.message}"` : ""}.`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "incident.resolve",
+    description:
+      "Mark an incident resolved by id, optionally with a final status-update message. Never resolves directly; a person must approve unless the conversation is in auto mode. Find the id with the incident read tools first.",
+    effect: "mutate",
+    input: IncidentResolveInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, incidentAccess.incident.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const incidentClient = rpcClient.forPlugin(IncidentApi);
+      const incident = await incidentClient.resolveIncident(input);
+      return { incident };
+    },
+  };
+}

package/src/ai/incident-update.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import type { IncidentDetail } from "@checkstack/incident-common";
+import { createIncidentUpdateTool } from "./incident-update";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["incident.incident.manage"],
+};
+
+const existing: IncidentDetail = {
+  id: "inc1",
+  title: "Old title",
+  description: "old desc",
+  status: "investigating",
+  severity: "minor",
+  suppressNotifications: false,
+  systemIds: ["sys1"],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  updates: [],
+  links: [],
+};
+
+function fakeRpcClient({
+  getIncident,
+  updateIncident,
+}: {
+  getIncident: ReturnType<typeof mock>;
+  updateIncident: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getIncident, updateIncident }),
+  } as unknown as RpcClient;
+}
+
+describe("incident.update tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createIncidentUpdateTool();
+    expect(tool.name).toBe("incident.update");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["incident.incident.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun fetches existing, returns a diff, and NEVER updates", async () => {
+    const getIncident = mock(() => Promise.resolve(existing));
+    const updateIncident = mock(() => Promise.resolve(existing));
+    const rpcClient = fakeRpcClient({ getIncident, updateIncident });
+    const tool = createIncidentUpdateTool();
+    const preview = await tool.dryRun!({
+      input: { id: "inc1", severity: "critical" },
+      principal,
+      rpcClient,
+    });
+    expect(getIncident).toHaveBeenCalledWith({ id: "inc1" });
+    expect(updateIncident).not.toHaveBeenCalled();
+    expect(preview.diff).toBeDefined();
+    expect(preview.summary).toContain("critical");
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getIncident: mock(() => Promise.resolve(null)),
+      updateIncident: mock(),
+    });
+    const tool = createIncidentUpdateTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No incident found/);
+  });
+
+  test("execute (apply) updates via updateIncident", async () => {
+    const input = { id: "inc1", title: "New title" };
+    const updated = { ...existing, title: "New title" };
+    const updateIncident = mock(() => Promise.resolve(updated));
+    const rpcClient = fakeRpcClient({
+      getIncident: mock(() => Promise.resolve(existing)),
+      updateIncident,
+    });
+    const tool = createIncidentUpdateTool();
+    const result = await tool.execute({ input, principal, rpcClient });
+    expect(updateIncident).toHaveBeenCalledWith(input);
+    expect(result.incident).toEqual(updated);
+  });
+});

package/src/ai/incident-update.ts

@@ -0,0 +1,94 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  IncidentApi,
+  incidentAccess,
+  pluginMetadata,
+  UpdateIncidentInputSchema,
+  type UpdateIncidentInput,
+  type IncidentWithSystems,
+} from "@checkstack/incident-common";
+import { computeFieldDiff, type AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Output returned once a human applies the update (the updated incident). */
+export interface IncidentUpdateApplyResult {
+  incident: IncidentWithSystems;
+}
+
+/**
+ * `incident.update` - edit an existing incident's metadata (title, description,
+ * severity, suppressNotifications, affected systems) by id. Only the provided
+ * fields change.
+ *
+ * `effect: "mutate"` - a non-destructive change, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode. `dryRun` fetches the live incident,
+ * computes a before -> after diff over the updatable fields, and rejects an
+ * unknown id with a self-correcting error; `execute` performs the update. The
+ * underlying RPC uses the USER-SCOPED client passed at call time, so
+ * handler-side authorization is enforced exactly as a direct UI/RPC call.
+ */
+export function createIncidentUpdateTool(): RegisteredAiTool<
+  UpdateIncidentInput,
+  IncidentUpdateApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: UpdateIncidentInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<UpdateIncidentInput>> => {
+    const incidentClient = rpcClient.forPlugin(IncidentApi);
+    const existing = await incidentClient.getIncident({ id: input.id });
+    if (!existing) {
+      throw new Error(
+        `No incident found with id "${input.id}". List incidents first to get a valid id.`,
+      );
+    }
+    // before -> after over the updatable subset only (the full incident also
+    // carries status/timestamps/updates/links that are not part of an update).
+    const before = {
+      title: existing.title,
+      description: existing.description,
+      severity: existing.severity,
+      suppressNotifications: existing.suppressNotifications,
+      systemIds: existing.systemIds,
+    };
+    const after = {
+      title: input.title ?? before.title,
+      description:
+        input.description === undefined
+          ? before.description
+          : (input.description ?? undefined),
+      severity: input.severity ?? before.severity,
+      suppressNotifications:
+        input.suppressNotifications ?? before.suppressNotifications,
+      systemIds: input.systemIds ?? before.systemIds,
+    };
+    const diff = computeFieldDiff({ before, after });
+    return {
+      summary: `Update incident "${after.title}" (severity ${after.severity}, ${after.systemIds.length} system(s)).`,
+      payload: input,
+      diff,
+    };
+  };
+
+  return {
+    name: "incident.update",
+    description:
+      "Update an existing incident by id with the provided fields (title, description, severity, suppressNotifications, systemIds). Only provided fields change. Never updates directly; a person must approve unless the conversation is in auto mode. Find the id with the incident read tools first.",
+    effect: "mutate",
+    input: UpdateIncidentInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, incidentAccess.incident.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const incidentClient = rpcClient.forPlugin(IncidentApi);
+      const incident = await incidentClient.updateIncident(input);
+      return { incident };
+    },
+  };
+}

package/src/ai/register-ai-tools.ts

@@ -0,0 +1,33 @@
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import { createIncidentCreateTool } from "./incident-create";
+import { createIncidentUpdateTool } from "./incident-update";
+import { createIncidentDeleteTool } from "./incident-delete";
+import { createIncidentAddUpdateTool } from "./incident-add-update";
+import { createIncidentResolveTool } from "./incident-resolve";
+import { createIncidentAddLinkTool } from "./incident-add-link";
+import { createIncidentRemoveLinkTool } from "./incident-remove-link";
+
+/**
+ * The incident plugin's AI tools, registered into the AI registry via
+ * `aiToolExtensionPoint` from this plugin's own init - NOT centralized in
+ * ai-backend. This is the canonical pattern any plugin (first- or third-party)
+ * uses to contribute AI tools without ai-backend depending on it.
+ *
+ * create/update/addUpdate/resolve/addLink are `mutate` (auto-applies in AUTO
+ * mode, confirm-gated in APPROVE mode); delete/removeLink are `destructive`, so
+ * always confirm-gated. They all go through the USER-SCOPED client passed at
+ * call time, so handler-side authorization is enforced exactly as a direct
+ * UI/RPC call; the resolver gate + the propose/apply re-check at propose AND
+ * apply time are the additional authorization authority.
+ */
+export function buildIncidentAiTools(): RegisteredAiTool[] {
+  return [
+    createIncidentCreateTool(),
+    createIncidentUpdateTool(),
+    createIncidentDeleteTool(),
+    createIncidentAddUpdateTool(),
+    createIncidentResolveTool(),
+    createIncidentAddLinkTool(),
+    createIncidentRemoveLinkTool(),
+  ];
+}

package/src/ai-projection.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { buildProjectedTool, deferredProjectionExecute } from "@checkstack/ai-backend";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import {
+  incidentContract,
+  incidentAccess,
+  pluginMetadata,
+} from "@checkstack/incident-common";
+
+describe("incident AI projection (incident.list)", () => {
+  const tool = buildProjectedTool({
+    procedure: incidentContract.listIncidents,
+    sourcePluginMetadata: pluginMetadata,
+    procedureKey: "listIncidents",
+    name: "incident.list",
+    description: "List incidents with optional status/system filters. Read-only.",
+    effect: "read",
+    execute: deferredProjectionExecute,
+  });
+
+  test("projects to a read-only tool named incident.list", () => {
+    expect(tool.name).toBe("incident.list");
+    expect(tool.effect).toBe("read");
+  });
+
+  test("carries the source procedure's own qualified access rules", () => {
+    // Derived from listIncidents' own access metadata, NOT the broad
+    // ai.chat.read rule.
+    const expected = qualifyAccessRuleId(
+      pluginMetadata,
+      incidentAccess.incident.read,
+    );
+
+    expect(tool.requiredAccessRules.length).toBeGreaterThan(0);
+    expect(tool.requiredAccessRules).toEqual([expected]);
+    expect(tool.requiredAccessRules).not.toEqual(["ai.chat.read"]);
+  });
+});

package/src/automations.test.ts

@@ -5,6 +5,7 @@
  * `core/automation-backend` cover registration validity.
  */
 import { describe, it, expect, mock } from "bun:test";
+import type { RpcClient } from "@checkstack/backend-api";
 import { SYSTEM_ACTOR } from "@checkstack/common";
 import { createMockLogger } from "@checkstack/test-utils-backend";
 
@@ -48,6 +49,7 @@ const actionContext = {
   getService: async <T,>(): Promise<T> => {
     throw new Error("not used");
   },
+  rpcClient: { forPlugin: () => ({}) } as unknown as RpcClient,
 };
 
 describe("incident automation actions", () => {

package/src/index.ts

@@ -1,5 +1,10 @@
 import * as schema from "./schema";
 import type { SafeDatabase } from "@checkstack/backend-api";
+import {
+  aiToolExtensionPoint,
+  aiToolProjectionExtensionPoint,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
 import {
   incidentAccessRules,
   incidentAccess,
@@ -42,6 +47,7 @@ import {
   incidentArtifactType,
   incidentTriggers,
 } from "./automations";
+import { buildIncidentAiTools } from "./ai/register-ai-tools";
 
 // =============================================================================
 // Plugin Definition
@@ -127,6 +133,7 @@ export default createBackendPlugin({
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
         cacheManager: coreServices.cacheManager,
+        advisoryLock: coreServices.advisoryLock,
       },
       init: async ({
         logger,
@@ -135,6 +142,7 @@ export default createBackendPlugin({
         rpcClient,
         signalService,
         cacheManager,
+        advisoryLock,
       }) => {
         logger.debug("🔧 Initializing Incident Backend...");
 
@@ -144,6 +152,7 @@ export default createBackendPlugin({
 
         const service = new IncidentService(
           database as SafeDatabase<typeof schema>,
+          advisoryLock,
         );
         // Publish the service for the PLUGIN-BACKED entity `read` accessor
         // (defined in register()). Mutations only run from here onward.
@@ -177,6 +186,44 @@ export default createBackendPlugin({
           automationActions.registerAction(action, pluginMetadata);
         }
 
+        // Register this plugin's AI tools (create/update/delete/addUpdate/
+        // resolve/addLink/removeLink) into the AI registry via the extension
+        // point - owned here, not in ai-backend.
+        const aiToolExt = env.getExtensionPoint(aiToolExtensionPoint);
+        for (const tool of buildIncidentAiTools()) {
+          aiToolExt.registerTool(tool, pluginMetadata);
+        }
+
+        // Expose this plugin's read-only AI projection (`incident.list`) via
+        // the AI projection extension point. ai-backend collects its routing in
+        // afterPluginsReady and never imports incident-common.
+        const aiProjectionExt = env.getExtensionPoint(
+          aiToolProjectionExtensionPoint,
+        );
+        aiProjectionExt.expose({
+          procedure: incidentContract.listIncidents,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "listIncidents",
+          name: "incident.list",
+          description:
+            "List incidents with optional status/system filters. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
+        // Expose a read-only projection of `getIncident` so the model can pull
+        // one incident's full timeline (updates) + links to ground its actions.
+        aiProjectionExt.expose({
+          procedure: incidentContract.getIncident,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getIncident",
+          name: "incident.get",
+          description:
+            "Get one incident with its full timeline (updates) and links. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
         // Register "Create Incident" command in the command palette
         registerSearchProvider({
           pluginMetadata,
@@ -208,9 +255,14 @@ export default createBackendPlugin({
       // associations) + register subscription specs. Per-system /
       // per-group notification group lifecycle is fully owned by
       // notification-backend now — incident never touches it.
-      afterPluginsReady: async ({ database, logger, rpcClient }) => {
+      afterPluginsReady: async ({
+        database,
+        logger,
+        rpcClient,
+        advisoryLock,
+      }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
-        const service = new IncidentService(typedDb);
+        const service = new IncidentService(typedDb, advisoryLock);
         const notificationClient = rpcClient.forPlugin(NotificationApi);
 
         await Promise.all([

package/src/schema.ts

@@ -5,6 +5,7 @@ import {
   timestamp,
   primaryKey,
   boolean,
+  uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 /**
@@ -77,12 +78,22 @@ export const incidentUpdates = pgTable("incident_updates", {
  * Hotlinks attached to an incident — e.g. a Jira ticket, runbook, or chat
  * thread. Free-form URL + optional human label.
  */
-export const incidentLinks = pgTable("incident_links", {
-  id: text("id").primaryKey(),
-  incidentId: text("incident_id")
-    .notNull()
-    .references(() => incidents.id, { onDelete: "cascade" }),
-  label: text("label"),
-  url: text("url").notNull(),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
+export const incidentLinks = pgTable(
+  "incident_links",
+  {
+    id: text("id").primaryKey(),
+    incidentId: text("incident_id")
+      .notNull()
+      .references(() => incidents.id, { onDelete: "cascade" }),
+    label: text("label"),
+    url: text("url").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // The same URL may be attached to an incident only once.
+    incidentUrlUnique: uniqueIndex("incident_links_incident_url_unique").on(
+      t.incidentId,
+      t.url,
+    ),
+  }),
+);

package/src/service.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
+import type { AdvisoryLockService } from "@checkstack/backend-api";
 import { IncidentService } from "./service";
 import {
   incidents,
@@ -7,6 +8,40 @@ import {
   incidentLinks,
 } from "./schema";
 
+/**
+ * In-memory {@link AdvisoryLockService} that faithfully serializes
+ * `withXactLock` calls per key (a racing call on the same key cannot run its
+ * `fn` until the prior call's `fn` settles) — modelling `pg_advisory_xact_lock`
+ * without a real connection. Different keys are independent.
+ */
+function makeFakeAdvisoryLock(): AdvisoryLockService {
+  const tails = new Map<string, Promise<unknown>>();
+  return {
+    tryAcquire: async () => ({ release: async () => {} }),
+    withXactLock<T>({
+      key,
+      fn,
+    }: {
+      key: string;
+      fn: () => Promise<T>;
+    }): Promise<T> {
+      const prior = tails.get(key) ?? Promise.resolve();
+      const result = prior.then(
+        () => fn(),
+        () => fn(),
+      );
+      tails.set(
+        key,
+        result.then(
+          () => undefined,
+          () => undefined,
+        ),
+      );
+      return result;
+    },
+  };
+}
+
 /**
  * Programmable mock DB that records each `select(...).from(...).where(...)`
  * (and optional `.limit(...)`) chain and returns a configurable row array
@@ -48,7 +83,7 @@ describe("IncidentService.hasActiveIncidentWithSuppression", () => {
 
   const setup = (resultsByCall: unknown[][]) => {
     dbHelper = createProgrammableSelectDb(resultsByCall);
-    service = new IncidentService(dbHelper.db as never);
+    service = new IncidentService(dbHelper.db as never, makeFakeAdvisoryLock());
   };
 
   beforeEach(() => {
@@ -134,7 +169,7 @@ describe("IncidentService.hasActiveIncidentWithSuppression", () => {
 describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () => {
   it("returns {} for an empty id set without querying", async () => {
     const dbHelper = createProgrammableSelectDb([]);
-    const service = new IncidentService(dbHelper.db as never);
+    const service = new IncidentService(dbHelper.db as never, makeFakeAdvisoryLock());
     expect(await service.getManyEntityStates([])).toEqual({});
     expect(dbHelper.getCallCount()).toBe(0);
   });
@@ -153,7 +188,7 @@ describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () =
         { incidentId: "inc-2", systemId: "sys-c" },
       ],
     ]);
-    const service = new IncidentService(dbHelper.db as never);
+    const service = new IncidentService(dbHelper.db as never, makeFakeAdvisoryLock());
     const out = await service.getManyEntityStates(["inc-1", "inc-2", "inc-x"]);
     expect(out).toEqual({
       "inc-1": {
@@ -172,7 +207,7 @@ describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () =
       // incidents query returns nothing → no second query.
       [],
     ]);
-    const service = new IncidentService(dbHelper.db as never);
+    const service = new IncidentService(dbHelper.db as never, makeFakeAdvisoryLock());
     expect(await service.getManyEntityStates(["ghost"])).toEqual({});
     expect(dbHelper.getCallCount()).toBe(1);
   });
@@ -182,7 +217,7 @@ describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () =
       [{ id: "inc-1", status: "monitoring", severity: "critical" }],
       [], // no junction rows
     ]);
-    const service = new IncidentService(dbHelper.db as never);
+    const service = new IncidentService(dbHelper.db as never, makeFakeAdvisoryLock());
     const out = await service.getManyEntityStates(["inc-1"]);
     expect(out["inc-1"]).toEqual({
       status: "monitoring",
@@ -266,6 +301,12 @@ function createDedupFakeDb() {
       // The lock key is embedded in the SQL the helper runs via tx.execute.
       let lockKey = "default";
       const tx = {
+        // A transaction handle exposes the same query surface as `db`, so a
+        // service method that wraps its writes in `db.transaction` can issue
+        // select/insert against the same backing store (e.g. createIncident,
+        // which now commits the incident + its system links atomically).
+        select: buildSelect(),
+        insert: buildInsert(),
         execute: async (sqlObj: unknown) => {
           // Drizzle sql`` carries the interpolated key in its params; the
           // helper interpolates exactly one param (the lock key).
@@ -300,7 +341,7 @@ function createDedupFakeDb() {
 describe("IncidentService.createIncidentDedupedForSystem (M3)", () => {
   it("two concurrent dedupe creates for one system open exactly ONE incident", async () => {
     const { db, store } = createDedupFakeDb();
-    const service = new IncidentService(db as never);
+    const service = new IncidentService(db as never, makeFakeAdvisoryLock());
 
     const input = {
       title: "Down",