@checkstack/incident-backend 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # @checkstack/incident-backend
 
+## 1.6.1
+
+### Patch Changes
+
+- Updated dependencies [13373ce]
+  - @checkstack/common@0.14.0
+  - @checkstack/backend-api@0.21.1
+  - @checkstack/cache-api@0.3.10
+  - @checkstack/ai-backend@0.1.1
+  - @checkstack/ai-common@0.1.1
+  - @checkstack/auth-common@0.8.1
+  - @checkstack/automation-backend@0.5.1
+  - @checkstack/automation-common@0.4.1
+  - @checkstack/catalog-backend@1.4.1
+  - @checkstack/catalog-common@2.3.1
+  - @checkstack/command-backend@0.2.1
+  - @checkstack/incident-common@1.4.1
+  - @checkstack/integration-backend@0.4.1
+  - @checkstack/integration-common@0.7.1
+  - @checkstack/notification-common@1.3.1
+  - @checkstack/signal-common@0.2.7
+  - @checkstack/cache-utils@0.2.15
+
+## 1.6.0
+
+### Minor Changes
+
+- 9dcc848: Plugin-owned AI tools: every domain plugin contributes its own AI tools (chat assistant + automation AI action), and `ai-backend` is platform-only.
+
+  Every plugin-specific AI tool is owned by the plugin whose domain it acts on, registered via that plugin's own `aiToolExtensionPoint` / `aiToolProjectionExtensionPoint` from its init - the same path an external plugin author uses. `ai-backend` no longer imports or depends on any capability plugin's `*-common`; the dependency direction is strictly plugin -> ai-platform. Pure helpers (`computeFieldDiff`, capability-summary, `ScriptContextKind`) live in `@checkstack/ai-common`.
+
+  Tools shipped:
+
+  - Health checks and automations: full CRUD - `healthcheck.propose` / `automation.propose` and `*.update` (`mutate`, deep-validated) and `*.delete` (`destructive`, always confirm-gated). `healthcheck.propose`'s dry-run calls the new deep `validateConfiguration` so propose-time validation matches apply-time. Assertions are validated against the collector's result schema and the canonical operator vocabulary. Capability-catalog tools (`ai.listCapabilities`, `ai.getCapabilitySchema`), script context tools (`ai.getScriptContext`, `ai.testScript`), and notify-subscriber tools (`healthcheck.notifySystemSubscribers` / `...GroupSubscribers`).
+  - Catalog: `catalog.createSystem` / `updateSystem` / `createGroup` / `updateGroup` (`mutate`), `catalog.deleteSystem` / `deleteGroup` (`destructive`), membership tools (`mutate`), plus `catalog.listSystems` / `listGroups` read projections.
+  - Incident: `incident.create` / `update` / `addUpdate` / `resolve` / `addLink` (`mutate`), `incident.delete` / `removeLink` (`destructive`), and `incident.get` / `incident.list` read projections.
+  - Maintenance: `maintenance.create` / `update` / `addUpdate` / `close` / `addLink` (`mutate`), `maintenance.delete` / `removeLink` (`destructive`), and `maintenance.list` / `get` read projections.
+  - Read projections for SLO (`slo.listObjectives`), dependency (`dependency.list`), incident (`incident.list`), healthcheck (`healthcheck.status`), and anomaly (`anomaly.explain`), each gated by the source procedure's own access rule and routed as the principal.
+  - Documentation grounding: `ai.searchDocs` / `ai.getDoc` over a build-time bundled docs index (BM25-ish ranking), so the assistant grounds how-to answers in Checkstack's own docs offline.
+  - URL introspection: `ai.probeUrl`, an SSRF-guarded read tool the assistant uses to inspect a real endpoint before drafting a health check. Update tools compute a before -> after field diff rendered on the confirm card (approve mode) or an "Applied" card (auto mode), so a change is never silent.
+
+  `ai_analyze` automation action (automation-backend, with an editor connection picker + audited tool calls): runs a bounded AI agent on the run context as the automation's `runAs` service account, so it can never exceed that identity's permissions; destructive tools are never offered; mutating tools auto-apply through the service account's client. Produces an `automation.analysis` artifact downstream actions can branch on. The agent loop is exposed as a headless `aiAgentRunnerRef` service so automation-backend can drive it without depending on ai-backend.
+
+  `notification.notifyForSubscription` is now callable by user / application principals holding `notification.send` (previously service-only). Every tool routes through the user-scoped client, so handler-side authorization is enforced exactly as a direct UI/RPC action; the resolver gate plus the propose/apply re-check at propose AND apply are the additional authority. A systemic authz regression test asserts every registered tool falls into exactly one safe authorization category.
+
+  A new `ai_transport` enum value `automation` records the AI action's tool calls in the `ai_tool_calls` audit log. No new durable state beyond that; each tool is a thin, deterministic wrapper over an existing RPC, so every pod behaves identically.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- 9dcc848: Write-path hardening: post-commit side effects can no longer fail a committed write, multi-row mutations are now atomic, and retry-duplication is blocked at the database.
+
+  **Platform-level (automatic for all current and future plugins):**
+
+  - signal-backend: `SignalService` (broadcast / sendToUser / sendToUsers / sendToAuthorizedUsers) is now resilient by construction - a transient event-bus/queue failure is caught and logged instead of thrown. Real-time signals are best-effort UI nudges; the authoritative data is already committed by the time a mutation broadcasts, so a signal-transport blip must never turn a successful write into a client-visible error. Every plugin's broadcasts inherit this without per-call-site `try/catch` (which would inevitably be forgotten and regress). This mirrors `createCachedScope`, which already makes cache invalidation non-throwing - so the cache + signal halves of the "post-commit side effect fails the response" class are both closed at the platform seam. Durable side effects (events/hooks that drive automations, queue jobs) intentionally still surface failures. Documented in `developer-guide/backend/signals.md`.
+
+  **Atomic multi-write mutations (each previously committed row-by-row in autocommit, so a mid-sequence failure left partial/orphaned state):**
+
+  - slo-backend: `createObjective` now inserts the objective and its 1:1 streak row in one transaction; the post-create reconcile/status/notify steps are best-effort and can no longer fail the (committed) create.
+  - incident-backend: `createIncident`, `updateIncident`, `addUpdate`, and `resolveIncident` wrap their row + system-link + timeline writes in a transaction (no more wiped system associations on a failed re-insert, or status flips with no matching timeline entry).
+  - maintenance-backend: same for `createMaintenance`, `updateMaintenance`, `addUpdate`, `closeMaintenance`.
+  - automation-backend: `cancelRun` marks the run cancelled and tears down its wait locks + durable state in one transaction - previously a failure after the status update could leave a wait lock behind, letting a later trigger event resume an already-cancelled run.
+  - healthcheck-backend: `ingestSatelliteResult` commits the run row and its hourly-aggregate increment together (no orphaned run, no aggregate without a backing run). NOTE: this guarantees run/aggregate consistency but does not yet make a _duplicate satellite delivery_ idempotent - that needs a dedupe key on the high-volume runs table and is tracked as a follow-up.
+
+  **Retry-duplication blocked at the DB (paired with the SQLSTATE 23505 -> 409 mapping shipped separately):**
+
+  - catalog-backend: new unique indexes on `groups.name`, `environments.name` (consistent with `systems.name`), on `system_links (system_id, url)`, and on `system_contacts (system_id, user_id)` + `(system_id, email)` (NULLs are distinct, so user vs mailbox contacts don't interfere). Name uniqueness is CASE-INSENSITIVE: the three name indexes are functional `lower(name)` indexes (the existing `systems.name` index is rebuilt this way too), so "Api" and "api" collide while the stored value keeps its original casing. The systems pre-write name check (`getSystemByName`) is case-folded to match. Migration `0005` de-dupes any pre-existing rows first - names are preserved by suffixing later case-insensitive duplicates (" (2)", " (3)", ...), redundant contact/link rows are removed keeping the earliest. (Link URLs stay case-sensitive - URL paths are; contact emails are deduped exact-match.)
+  - incident-backend / maintenance-backend: unique index on `incident_links (incident_id, url)` / `maintenance_links (maintenance_id, url)`, with a de-dupe step in the migration.
+
+    **Behavior change:** creating a group/environment with a duplicate name, or attaching a duplicate contact/link, now returns `409 Conflict` instead of silently creating a duplicate. The migrations resolve existing duplicates on upgrade.
+
+  This is a beta patch.
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/ai-backend@0.1.0
+  - @checkstack/ai-common@0.1.0
+  - @checkstack/auth-common@0.8.0
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/automation-backend@0.5.0
+  - @checkstack/catalog-backend@1.4.0
+  - @checkstack/notification-common@1.3.0
+  - @checkstack/automation-common@0.4.0
+  - @checkstack/catalog-common@2.3.0
+  - @checkstack/integration-backend@0.4.0
+  - @checkstack/common@0.13.0
+  - @checkstack/command-backend@0.2.0
+  - @checkstack/incident-common@1.4.0
+  - @checkstack/integration-common@0.7.0
+  - @checkstack/cache-api@0.3.9
+  - @checkstack/signal-common@0.2.6
+  - @checkstack/cache-utils@0.2.14
+
 ## 1.5.0
 
 ### Minor Changes

package/drizzle/0003_careful_ken_ellis.sql

@@ -0,0 +1,10 @@
+-- Resolve any pre-existing duplicate (incident_id, url) links before enforcing
+-- uniqueness: keep the earliest by created_at/id, remove the redundant rest.
+DELETE FROM "incident_links" WHERE "id" IN (
+	SELECT "id" FROM (
+		SELECT "id", row_number() OVER (PARTITION BY "incident_id", "url" ORDER BY "created_at", "id") AS rn
+		FROM "incident_links"
+	) AS r WHERE r.rn > 1
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "incident_links_incident_url_unique" ON "incident_links" USING btree ("incident_id","url");

package/drizzle/meta/0003_snapshot.json

@@ -0,0 +1,300 @@
+{
+  "id": "1d8635bb-6fc2-4dfb-bc27-794bfb92b6fc",
+  "prevId": "0c166fdf-4881-4230-a0b3-50b6c4b89e16",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.incident_links": {
+      "name": "incident_links",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "incident_id": {
+          "name": "incident_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "label": {
+          "name": "label",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "url": {
+          "name": "url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "incident_links_incident_url_unique": {
+          "name": "incident_links_incident_url_unique",
+          "columns": [
+            {
+              "expression": "incident_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "url",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "incident_links_incident_id_incidents_id_fk": {
+          "name": "incident_links_incident_id_incidents_id_fk",
+          "tableFrom": "incident_links",
+          "tableTo": "incidents",
+          "columnsFrom": [
+            "incident_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.incident_systems": {
+      "name": "incident_systems",
+      "schema": "",
+      "columns": {
+        "incident_id": {
+          "name": "incident_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "system_id": {
+          "name": "system_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "incident_systems_incident_id_incidents_id_fk": {
+          "name": "incident_systems_incident_id_incidents_id_fk",
+          "tableFrom": "incident_systems",
+          "tableTo": "incidents",
+          "columnsFrom": [
+            "incident_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "incident_systems_incident_id_system_id_pk": {
+          "name": "incident_systems_incident_id_system_id_pk",
+          "columns": [
+            "incident_id",
+            "system_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.incident_updates": {
+      "name": "incident_updates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "incident_id": {
+          "name": "incident_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status_change": {
+          "name": "status_change",
+          "type": "incident_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "incident_updates_incident_id_incidents_id_fk": {
+          "name": "incident_updates_incident_id_incidents_id_fk",
+          "tableFrom": "incident_updates",
+          "tableTo": "incidents",
+          "columnsFrom": [
+            "incident_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.incidents": {
+      "name": "incidents",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "incident_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'investigating'"
+        },
+        "severity": {
+          "name": "severity",
+          "type": "incident_severity",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'major'"
+        },
+        "suppress_notifications": {
+          "name": "suppress_notifications",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.incident_severity": {
+      "name": "incident_severity",
+      "schema": "public",
+      "values": [
+        "minor",
+        "major",
+        "critical"
+      ]
+    },
+    "public.incident_status": {
+      "name": "incident_status",
+      "schema": "public",
+      "values": [
+        "investigating",
+        "identified",
+        "fixing",
+        "monitoring",
+        "resolved"
+      ]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -22,6 +22,13 @@
       "when": 1777907796517,
       "tag": "0002_brown_thena",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1780649381812,
+      "tag": "0003_careful_ken_ellis",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-backend",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,29 +14,32 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.18.0",
-    "@checkstack/cache-api": "0.3.6",
-    "@checkstack/cache-utils": "0.2.11",
-    "@checkstack/incident-common": "1.3.1",
-    "@checkstack/catalog-common": "2.2.3",
-    "@checkstack/catalog-backend": "1.2.0",
-    "@checkstack/notification-common": "1.2.1",
-    "@checkstack/auth-common": "0.7.2",
-    "@checkstack/command-backend": "0.1.31",
-    "@checkstack/signal-common": "0.2.5",
-    "@checkstack/integration-backend": "0.2.0",
-    "@checkstack/integration-common": "0.6.0",
-    "@checkstack/automation-backend": "0.2.0",
-    "@checkstack/automation-common": "0.2.0",
-    "@checkstack/common": "0.12.0",
+    "@checkstack/ai-backend": "0.1.0",
+    "@checkstack/ai-common": "0.1.0",
+    "@checkstack/backend-api": "0.21.0",
+    "@checkstack/cache-api": "0.3.9",
+    "@checkstack/cache-utils": "0.2.14",
+    "@checkstack/incident-common": "1.4.0",
+    "@checkstack/catalog-common": "2.3.0",
+    "@checkstack/catalog-backend": "1.4.0",
+    "@checkstack/notification-common": "1.3.0",
+    "@checkstack/auth-common": "0.8.0",
+    "@checkstack/command-backend": "0.2.0",
+    "@checkstack/signal-common": "0.2.6",
+    "@checkstack/integration-backend": "0.4.0",
+    "@checkstack/integration-common": "0.7.0",
+    "@checkstack/automation-backend": "0.5.0",
+    "@checkstack/automation-common": "0.4.0",
+    "@checkstack/common": "0.13.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
-    "@orpc/server": "^1.13.2"
+    "@orpc/contract": "^1.14.4",
+    "@orpc/server": "^1.14.4"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.4",
-    "@checkstack/test-utils-backend": "0.1.31",
+    "@checkstack/scripts": "0.4.0",
+    "@checkstack/test-utils-backend": "0.1.34",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",

package/src/ai/incident-add-link.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import type { AddIncidentLinkInput } from "@checkstack/incident-common";
+import { createIncidentAddLinkTool } from "./incident-add-link";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["incident.incident.manage"],
+};
+
+const input: AddIncidentLinkInput = {
+  incidentId: "inc1",
+  label: "Runbook",
+  url: "https://example.com/runbook",
+};
+
+function fakeRpcClient({
+  addLink,
+}: {
+  addLink: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ addLink }),
+  } as unknown as RpcClient;
+}
+
+describe("incident.addLink tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createIncidentAddLinkTool();
+    expect(tool.name).toBe("incident.addLink");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["incident.incident.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun returns a payload and NEVER adds the link", async () => {
+    const addLink = mock(() => Promise.resolve({}));
+    const rpcClient = fakeRpcClient({ addLink });
+    const tool = createIncidentAddLinkTool();
+    const preview = await tool.dryRun!({ input, principal, rpcClient });
+    expect(addLink).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Runbook");
+    expect(preview.payload).toEqual(input);
+  });
+
+  test("execute (apply) adds via addLink", async () => {
+    const created = {
+      id: "lnk1",
+      incidentId: input.incidentId,
+      label: input.label ?? null,
+      url: input.url,
+      createdAt: new Date(),
+    };
+    const addLink = mock(() => Promise.resolve(created));
+    const rpcClient = fakeRpcClient({ addLink });
+    const tool = createIncidentAddLinkTool();
+    const result = await tool.execute({ input, principal, rpcClient });
+    expect(addLink).toHaveBeenCalledWith(input);
+    expect(result.link).toEqual(created);
+  });
+});

package/src/ai/incident-add-link.ts

@@ -0,0 +1,63 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  IncidentApi,
+  incidentAccess,
+  pluginMetadata,
+  AddIncidentLinkInputSchema,
+  type AddIncidentLinkInput,
+  type IncidentLink,
+} from "@checkstack/incident-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Output returned once a human applies the link add (the created link). */
+export interface IncidentAddLinkApplyResult {
+  link: IncidentLink;
+}
+
+/**
+ * `incident.addLink` - attach a hotlink (e.g. Jira ticket, runbook) to an
+ * incident.
+ *
+ * `effect: "mutate"` - adding a link is a non-destructive 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`) attaches the link. 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 createIncidentAddLinkTool(): RegisteredAiTool<
+  AddIncidentLinkInput,
+  IncidentAddLinkApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: AddIncidentLinkInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<AddIncidentLinkInput>> => {
+    return {
+      summary: `Add link ${input.label ? `"${input.label}" ` : ""}(${input.url}) to incident ${input.incidentId}.`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "incident.addLink",
+    description:
+      "Attach a hotlink (e.g. Jira ticket, runbook, status page) to an incident with an optional label and a URL. Never adds directly; a person must approve unless the conversation is in auto mode. Find the incidentId with the incident read tools first.",
+    effect: "mutate",
+    input: AddIncidentLinkInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, incidentAccess.incident.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const incidentClient = rpcClient.forPlugin(IncidentApi);
+      const link = await incidentClient.addLink(input);
+      return { link };
+    },
+  };
+}