@checkstack/maintenance-backend 1.3.0 → 1.4.0

package/src/ai/maintenance-add-update.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceAddUpdateTool } from "./maintenance-add-update";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+function fakeRpcClient({
+  addUpdate,
+}: {
+  addUpdate: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ addUpdate }),
+  } as unknown as RpcClient;
+}
+
+describe("maintenance.addUpdate tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createMaintenanceAddUpdateTool();
+    expect(tool.name).toBe("maintenance.addUpdate");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes without posting", async () => {
+    const addUpdate = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ addUpdate });
+    const tool = createMaintenanceAddUpdateTool();
+    const preview = await tool.dryRun!({
+      input: { maintenanceId: "m1", message: "Patching now" },
+      principal,
+      rpcClient,
+    });
+    expect(addUpdate).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Patching now");
+  });
+
+  test("execute posts via addUpdate", async () => {
+    const addUpdate = mock(() =>
+      Promise.resolve({ id: "u1", maintenanceId: "m1", message: "Patching now" }),
+    );
+    const rpcClient = fakeRpcClient({ addUpdate });
+    const tool = createMaintenanceAddUpdateTool();
+    const result = await tool.execute({
+      input: {
+        maintenanceId: "m1",
+        message: "Patching now",
+        statusChange: "in_progress",
+      },
+      principal,
+      rpcClient,
+    });
+    expect(addUpdate).toHaveBeenCalledWith({
+      maintenanceId: "m1",
+      message: "Patching now",
+      statusChange: "in_progress",
+    });
+    expect(result.update.id).toBe("u1");
+  });
+});

package/src/ai/maintenance-add-update.ts

@@ -0,0 +1,61 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  AddMaintenanceUpdateInputSchema,
+  maintenanceAccess,
+  pluginMetadata,
+  type MaintenanceUpdate,
+  type AddMaintenanceUpdateInput,
+} from "@checkstack/maintenance-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Output returned once a human applies the update (the posted update). */
+export interface MaintenanceAddUpdateApplyResult {
+  update: MaintenanceUpdate;
+}
+
+/**
+ * `maintenance.addUpdate` - post a status update (message + optional status
+ * change) to an existing maintenance window.
+ *
+ * `effect: "mutate"` - a non-destructive append, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode. The underlying RPC runs through the
+ * USER-SCOPED client, so handler-side authorization is enforced exactly as a
+ * direct UI/RPC call.
+ */
+export function createMaintenanceAddUpdateTool(): RegisteredAiTool<
+  AddMaintenanceUpdateInput,
+  MaintenanceAddUpdateApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: AddMaintenanceUpdateInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<AddMaintenanceUpdateInput>> => {
+    return {
+      summary: `Post an update to maintenance "${input.maintenanceId}"${input.statusChange ? ` (status -> ${input.statusChange})` : ""}: "${input.message}".`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "maintenance.addUpdate",
+    description:
+      "Post a status update (a message, optionally changing the maintenance status) to an existing maintenance window. Never posts directly; a person must approve unless the conversation is in auto mode. Find the maintenance id with the maintenance read tools first.",
+    effect: "mutate",
+    input: AddMaintenanceUpdateInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      const update = await maintenanceClient.addUpdate(input);
+      return { update };
+    },
+  };
+}

package/src/ai/maintenance-close.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceCloseTool } from "./maintenance-close";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+function fakeRpcClient({
+  closeMaintenance,
+}: {
+  closeMaintenance: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ closeMaintenance }),
+  } as unknown as RpcClient;
+}
+
+describe("maintenance.close tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createMaintenanceCloseTool();
+    expect(tool.name).toBe("maintenance.close");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes without closing", async () => {
+    const closeMaintenance = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ closeMaintenance });
+    const tool = createMaintenanceCloseTool();
+    const preview = await tool.dryRun!({
+      input: { id: "m1", message: "Done early" },
+      principal,
+      rpcClient,
+    });
+    expect(closeMaintenance).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Done early");
+  });
+
+  test("execute closes via closeMaintenance", async () => {
+    const closeMaintenance = mock(() =>
+      Promise.resolve({ id: "m1", systemIds: ["s1"] }),
+    );
+    const rpcClient = fakeRpcClient({ closeMaintenance });
+    const tool = createMaintenanceCloseTool();
+    const result = await tool.execute({
+      input: { id: "m1", message: "Done early" },
+      principal,
+      rpcClient,
+    });
+    expect(closeMaintenance).toHaveBeenCalledWith({
+      id: "m1",
+      message: "Done early",
+    });
+    expect(result.maintenance.id).toBe("m1");
+  });
+});

package/src/ai/maintenance-close.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  maintenanceAccess,
+  pluginMetadata,
+  type MaintenanceWithSystems,
+} from "@checkstack/maintenance-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/**
+ * Input for `maintenance.close`: the maintenance id plus an optional closing
+ * message. Closing sets the maintenance status to completed early.
+ */
+export const MaintenanceCloseInputSchema = z.object({
+  id: z.string(),
+  message: z.string().optional(),
+});
+export type MaintenanceCloseInput = z.infer<typeof MaintenanceCloseInputSchema>;
+
+/** Output returned once a human applies the close (the closed maintenance). */
+export interface MaintenanceCloseApplyResult {
+  maintenance: MaintenanceWithSystems;
+}
+
+/**
+ * `maintenance.close` - close a maintenance window early (sets status to
+ * completed).
+ *
+ * `effect: "mutate"` - a non-destructive status change, so it auto-applies in
+ * AUTO mode and is confirm-gated in APPROVE mode. The underlying RPC runs through
+ * the USER-SCOPED client, so handler-side authorization is enforced exactly as a
+ * direct UI/RPC call.
+ */
+export function createMaintenanceCloseTool(): RegisteredAiTool<
+  MaintenanceCloseInput,
+  MaintenanceCloseApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: MaintenanceCloseInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<MaintenanceCloseInput>> => {
+    return {
+      summary: `Close maintenance "${input.id}" early (status -> completed)${input.message ? `: "${input.message}"` : ""}.`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "maintenance.close",
+    description:
+      "Close a maintenance window early by id, setting its status to completed, with an optional closing message. Never closes directly; a person must approve unless the conversation is in auto mode. Find the id with the maintenance read tools first.",
+    effect: "mutate",
+    input: MaintenanceCloseInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      const maintenance = await maintenanceClient.closeMaintenance(input);
+      return { maintenance };
+    },
+  };
+}

package/src/ai/maintenance-create.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceCreateTool } from "./maintenance-create";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+function fakeRpcClient({
+  createMaintenance,
+}: {
+  createMaintenance: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ createMaintenance }),
+  } as unknown as RpcClient;
+}
+
+const isoStart = "2026-07-01T10:00:00.000Z";
+const isoEnd = "2026-07-01T12:00:00.000Z";
+
+describe("maintenance.create tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createMaintenanceCreateTool();
+    expect(tool.name).toBe("maintenance.create");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes the window without creating it", async () => {
+    const createMaintenance = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ createMaintenance });
+    const tool = createMaintenanceCreateTool();
+    const preview = await tool.dryRun!({
+      input: {
+        title: "DB upgrade",
+        startAt: new Date(isoStart),
+        endAt: new Date(isoEnd),
+        systemIds: ["s1"],
+      },
+      principal,
+      rpcClient,
+    });
+    expect(createMaintenance).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("DB upgrade");
+  });
+
+  test("coerces ISO string dates to Date instances before the RPC", async () => {
+    let received: { startAt: unknown; endAt: unknown } | undefined;
+    const createMaintenance = mock(
+      (arg: { startAt: unknown; endAt: unknown }) => {
+        received = arg;
+        return Promise.resolve({ id: "m1", systemIds: ["s1"] });
+      },
+    );
+    const rpcClient = fakeRpcClient({ createMaintenance });
+    const tool = createMaintenanceCreateTool();
+    // The model sends ISO strings; the tool-local schema coerces them.
+    const parsed = tool.input.parse({
+      title: "DB upgrade",
+      startAt: isoStart,
+      endAt: isoEnd,
+      systemIds: ["s1"],
+    });
+    await tool.execute({ input: parsed, principal, rpcClient });
+    expect(received?.startAt instanceof Date).toBe(true);
+    expect(received?.endAt instanceof Date).toBe(true);
+  });
+
+  test("rejects when endAt is not after startAt", () => {
+    const tool = createMaintenanceCreateTool();
+    const result = tool.input.safeParse({
+      title: "Bad window",
+      startAt: isoEnd,
+      endAt: isoStart,
+      systemIds: ["s1"],
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/ai/maintenance-create.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  maintenanceAccess,
+  pluginMetadata,
+  type MaintenanceWithSystems,
+} from "@checkstack/maintenance-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/**
+ * Tool-local create schema. The exported `CreateMaintenanceInputSchema` is a
+ * `ZodEffects` (it carries a `.refine`) whose `startAt` / `endAt` are `z.date()`;
+ * the model only ever sends ISO strings, so this mirror coerces those two fields
+ * to `Date` (via `z.coerce.date()`) while reproducing the same field set and the
+ * same `endAt > startAt` invariant. The exported schema is NOT mutated. The
+ * coerced values are real `Date` instances, exactly what the RPC client expects.
+ */
+export const MaintenanceCreateInputSchema = z
+  .object({
+    title: z.string().min(1),
+    description: z.string().optional(),
+    suppressNotifications: z.boolean().optional(),
+    startAt: z.coerce.date(),
+    endAt: z.coerce.date(),
+    systemIds: z.array(z.string()).min(1),
+  })
+  .refine((v) => v.endAt > v.startAt, {
+    message: "endAt must be after startAt",
+    path: ["endAt"],
+  });
+export type MaintenanceCreateInput = z.infer<typeof MaintenanceCreateInputSchema>;
+
+/** Output returned once a human applies the proposal (the created maintenance). */
+export interface MaintenanceCreateApplyResult {
+  maintenance: MaintenanceWithSystems;
+}
+
+/**
+ * `maintenance.create` - schedule a new maintenance window.
+ *
+ * `effect: "mutate"` - creating a maintenance is a non-destructive create, so it
+ * auto-applies in AUTO mode and is confirm-gated in APPROVE mode via the
+ * propose/apply machinery. `dryRun` summarizes the window without creating it;
+ * `execute` (reached only via `apply`) performs the create through the
+ * USER-SCOPED client, so handler-side authorization (access rules AND
+ * per-resource/team scoping) is enforced exactly as a direct UI/RPC call.
+ */
+export function createMaintenanceCreateTool(): RegisteredAiTool<
+  MaintenanceCreateInput,
+  MaintenanceCreateApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: MaintenanceCreateInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<MaintenanceCreateInput>> => {
+    return {
+      summary: `Create maintenance "${input.title}" from ${input.startAt.toISOString()} to ${input.endAt.toISOString()} affecting ${input.systemIds.length} system(s)${input.suppressNotifications ? " (notifications suppressed)" : ""}.`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "maintenance.create",
+    description:
+      "Schedule a new maintenance window over one or more systems with a start and end time. Provide startAt/endAt as ISO 8601 timestamps; endAt must be after startAt. Never creates directly; a person must approve unless the conversation is in auto mode. Find system ids with the catalog read tools first.",
+    effect: "mutate",
+    input: MaintenanceCreateInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      const maintenance = await maintenanceClient.createMaintenance(input);
+      return { maintenance };
+    },
+  };
+}

package/src/ai/maintenance-delete.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceDeleteTool } from "./maintenance-delete";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+const maintenance = {
+  id: "m1",
+  title: "DB upgrade",
+  description: "Planned upgrade",
+  suppressNotifications: false,
+  status: "scheduled" as const,
+  startAt: new Date(),
+  endAt: new Date(),
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  systemIds: ["s1"],
+  updates: [],
+  links: [],
+};
+
+function fakeRpcClient({
+  getMaintenance,
+  deleteMaintenance,
+}: {
+  getMaintenance: ReturnType<typeof mock>;
+  deleteMaintenance: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getMaintenance, deleteMaintenance }),
+  } as unknown as RpcClient;
+}
+
+describe("maintenance.delete tool", () => {
+  test("declares destructive effect + the manage rule", () => {
+    const tool = createMaintenanceDeleteTool();
+    expect(tool.name).toBe("maintenance.delete");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun resolves the target and NEVER deletes", async () => {
+    const getMaintenance = mock(() => Promise.resolve(maintenance));
+    const deleteMaintenance = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ getMaintenance, deleteMaintenance });
+    const tool = createMaintenanceDeleteTool();
+    const preview = await tool.dryRun!({
+      input: { id: "m1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteMaintenance).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("DB upgrade");
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "m1" });
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getMaintenance: mock(() => Promise.resolve(null)),
+      deleteMaintenance: mock(),
+    });
+    const tool = createMaintenanceDeleteTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No maintenance found/);
+  });
+
+  test("execute (apply) deletes via deleteMaintenance", async () => {
+    const deleteMaintenance = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({
+      getMaintenance: mock(() => Promise.resolve(maintenance)),
+      deleteMaintenance,
+    });
+    const tool = createMaintenanceDeleteTool();
+    const result = await tool.execute({
+      input: { id: "m1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteMaintenance).toHaveBeenCalledWith({ id: "m1" });
+    expect(result).toEqual({ id: "m1", deleted: true });
+  });
+});

package/src/ai/maintenance-delete.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  maintenanceAccess,
+  pluginMetadata,
+} from "@checkstack/maintenance-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `maintenance.delete`: the maintenance id to remove. */
+export const MaintenanceDeleteInputSchema = z.object({
+  id: z.string(),
+});
+export type MaintenanceDeleteInput = z.infer<typeof MaintenanceDeleteInputSchema>;
+
+/** Output returned once a human applies the deletion. */
+export interface MaintenanceDeleteApplyResult {
+  id: string;
+  deleted: true;
+}
+
+/**
+ * `maintenance.delete` - delete a maintenance window by id.
+ *
+ * `effect: "destructive"` - deletion is irreversible, so it ALWAYS routes through
+ * the propose/apply confirm card in BOTH permission modes (it can never
+ * auto-apply). `dryRun` resolves the target maintenance so the confirm card names
+ * exactly what will be removed; `execute` (reached only via `apply`) performs the
+ * delete through the USER-SCOPED client, so handler-side authorization is
+ * enforced exactly as a direct UI/RPC call.
+ */
+export function createMaintenanceDeleteTool(): RegisteredAiTool<
+  MaintenanceDeleteInput,
+  MaintenanceDeleteApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: MaintenanceDeleteInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<MaintenanceDeleteInput>> => {
+    const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+    const maintenance = await maintenanceClient.getMaintenance({ id: input.id });
+    if (!maintenance) {
+      throw new Error(
+        `No maintenance found with id "${input.id}". List maintenances first to get a valid id.`,
+      );
+    }
+    return {
+      summary: `Delete maintenance "${maintenance.title}". This is permanent and also removes its updates and links.`,
+      payload: { id: input.id },
+    };
+  };
+
+  return {
+    name: "maintenance.delete",
+    description:
+      "Delete a maintenance window by id. DESTRUCTIVE and irreversible - it also removes the maintenance's updates and links. Never deletes directly; a person must approve the confirmation. Find the id with the maintenance read tools first.",
+    effect: "destructive",
+    input: MaintenanceDeleteInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      await maintenanceClient.deleteMaintenance({ id: input.id });
+      return { id: input.id, deleted: true };
+    },
+  };
+}

package/src/ai/maintenance-remove-link.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceRemoveLinkTool } from "./maintenance-remove-link";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+function fakeRpcClient({
+  removeLink,
+}: {
+  removeLink: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ removeLink }),
+  } as unknown as RpcClient;
+}
+
+describe("maintenance.removeLink tool", () => {
+  test("declares destructive effect + the manage rule", () => {
+    const tool = createMaintenanceRemoveLinkTool();
+    expect(tool.name).toBe("maintenance.removeLink");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes and NEVER removes", async () => {
+    const removeLink = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ removeLink });
+    const tool = createMaintenanceRemoveLinkTool();
+    const preview = await tool.dryRun!({
+      input: { id: "l1" },
+      principal,
+      rpcClient,
+    });
+    expect(removeLink).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "l1" });
+  });
+
+  test("execute (apply) removes via removeLink", async () => {
+    const removeLink = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ removeLink });
+    const tool = createMaintenanceRemoveLinkTool();
+    const result = await tool.execute({
+      input: { id: "l1" },
+      principal,
+      rpcClient,
+    });
+    expect(removeLink).toHaveBeenCalledWith({ id: "l1" });
+    expect(result).toEqual({ id: "l1", removed: true });
+  });
+});