@checkstack/incident-backend 1.5.0 → 1.6.1

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
@@ -180,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,

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

@@ -301,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).

package/src/service.ts

@@ -238,33 +238,38 @@ export class IncidentService {
     id: string = generateId(),
   ): Promise<IncidentWithSystems> {
 
-    await this.db.insert(incidents).values({
-      id,
-      title: input.title,
-      description: input.description,
-      status: "investigating",
-      severity: input.severity,
-      suppressNotifications: input.suppressNotifications ?? false,
-    });
-
-    // Insert system associations
-    for (const systemId of input.systemIds) {
-      await this.db.insert(incidentSystems).values({
-        incidentId: id,
-        systemId,
+    // Atomic: the incident row, its system associations, and any initial update
+    // must all commit together. Without the transaction a failure mid-loop left
+    // a committed incident with only some (or none) of its system links.
+    await this.db.transaction(async (tx) => {
+      await tx.insert(incidents).values({
+        id,
+        title: input.title,
+        description: input.description,
+        status: "investigating",
+        severity: input.severity,
+        suppressNotifications: input.suppressNotifications ?? false,
       });
-    }
 
-    // Add initial update if provided
-    if (input.initialMessage) {
-      await this.db.insert(incidentUpdates).values({
-        id: generateId(),
-        incidentId: id,
-        message: input.initialMessage,
-        statusChange: "investigating",
-        createdBy: userId,
-      });
-    }
+      // Insert system associations
+      for (const systemId of input.systemIds) {
+        await tx.insert(incidentSystems).values({
+          incidentId: id,
+          systemId,
+        });
+      }
+
+      // Add initial update if provided
+      if (input.initialMessage) {
+        await tx.insert(incidentUpdates).values({
+          id: generateId(),
+          incidentId: id,
+          message: input.initialMessage,
+          statusChange: "investigating",
+          createdBy: userId,
+        });
+      }
+    });
 
     return (await this.getIncident(id))!;
   }
@@ -293,24 +298,29 @@ export class IncidentService {
     if (input.suppressNotifications !== undefined)
       updateData.suppressNotifications = input.suppressNotifications;
 
-    await this.db
-      .update(incidents)
-      .set(updateData)
-      .where(eq(incidents.id, input.id));
-
-    // Update system associations if provided
-    if (input.systemIds !== undefined) {
-      await this.db
-        .delete(incidentSystems)
-        .where(eq(incidentSystems.incidentId, input.id));
-
-      for (const systemId of input.systemIds) {
-        await this.db.insert(incidentSystems).values({
-          incidentId: input.id,
-          systemId,
-        });
+    // Atomic: the field update and the delete-then-reinsert of system links must
+    // commit together. Without the transaction a failure after the delete left
+    // the incident with ALL system associations wiped.
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(incidents)
+        .set(updateData)
+        .where(eq(incidents.id, input.id));
+
+      // Update system associations if provided
+      if (input.systemIds !== undefined) {
+        await tx
+          .delete(incidentSystems)
+          .where(eq(incidentSystems.incidentId, input.id));
+
+        for (const systemId of input.systemIds) {
+          await tx.insert(incidentSystems).values({
+            incidentId: input.id,
+            systemId,
+          });
+        }
       }
-    }
+    });
 
     return (await this.getIncident(input.id))!;
   }
@@ -324,20 +334,25 @@ export class IncidentService {
   ): Promise<IncidentUpdate> {
     const id = generateId();
 
-    // If status change is provided, update the incident status
-    if (input.statusChange) {
-      await this.db
-        .update(incidents)
-        .set({ status: input.statusChange, updatedAt: new Date() })
-        .where(eq(incidents.id, input.incidentId));
-    }
+    // Atomic: the status flip and the timeline entry that records it must commit
+    // together. Without the transaction a failed insert left the incident in a
+    // new status with no update row explaining it (status/timeline divergence).
+    await this.db.transaction(async (tx) => {
+      // If status change is provided, update the incident status
+      if (input.statusChange) {
+        await tx
+          .update(incidents)
+          .set({ status: input.statusChange, updatedAt: new Date() })
+          .where(eq(incidents.id, input.incidentId));
+      }
 
-    await this.db.insert(incidentUpdates).values({
-      id,
-      incidentId: input.incidentId,
-      message: input.message,
-      statusChange: input.statusChange,
-      createdBy: userId,
+      await tx.insert(incidentUpdates).values({
+        id,
+        incidentId: input.incidentId,
+        message: input.message,
+        statusChange: input.statusChange,
+        createdBy: userId,
+      });
     });
 
     const [update] = await this.db
@@ -367,18 +382,21 @@ export class IncidentService {
 
     if (!existing) return undefined;
 
-    await this.db
-      .update(incidents)
-      .set({ status: "resolved", updatedAt: new Date() })
-      .where(eq(incidents.id, id));
+    // Atomic: mark resolved + write the resolution timeline entry together.
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(incidents)
+        .set({ status: "resolved", updatedAt: new Date() })
+        .where(eq(incidents.id, id));
 
-    // Add resolution update entry
-    await this.db.insert(incidentUpdates).values({
-      id: generateId(),
-      incidentId: id,
-      message: message ?? "Incident resolved",
-      statusChange: "resolved",
-      createdBy: userId,
+      // Add resolution update entry
+      await tx.insert(incidentUpdates).values({
+        id: generateId(),
+        incidentId: id,
+        message: message ?? "Incident resolved",
+        statusChange: "resolved",
+        createdBy: userId,
+      });
     });
 
     return (await this.getIncident(id))!;

package/tsconfig.json

@@ -4,6 +4,12 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../ai-backend"
+    },
+    {
+      "path": "../ai-common"
+    },
     {
       "path": "../auth-common"
     },