@nimbus-dev/connectors 0.5.0 → 0.6.0

package/connectors/launchdarkly/src/flag-state.ts

@@ -0,0 +1,178 @@
+/**
+ * Pure helpers for the LaunchDarkly flag tools: the one-environment read projection and the
+ * rollout-weight arithmetic. Kept apart from the tool registration so both are testable alone.
+ */
+
+/** LaunchDarkly rollout weights are thousandths of a percent: 0..100000, and a flag sums to 100000. */
+export const FULL_ROLLOUT = 100_000;
+
+export interface RolloutWeightInput {
+  readonly variationId: string;
+  readonly percent: number;
+}
+
+/**
+ * `weights` as the `rolloutWeights` map the semantic patch takes (variation id -> thousandths of a
+ * percent). Fails closed: duplicate ids, a percent with more than three decimals, or a total that is
+ * not EXACTLY 100% all throw before any request is made. (The API only says the sum "should" be 100%;
+ * what it does on a mismatch is not stated, so this connector does not find out on a production flag.)
+ */
+export function rolloutWeightsOf(weights: readonly RolloutWeightInput[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  let total = 0;
+  for (const w of weights) {
+    if (Object.hasOwn(out, w.variationId)) {
+      throw new Error(`variationId ${w.variationId} appears more than once`);
+    }
+    const thousandths = Math.round(w.percent * 1000);
+    if (Math.abs(w.percent * 1000 - thousandths) > 1e-6) {
+      throw new Error(`percent ${String(w.percent)} has more than 3 decimal places`);
+    }
+    out[w.variationId] = thousandths;
+    total += thousandths;
+  }
+  if (total !== FULL_ROLLOUT) {
+    throw new Error(
+      `weights must sum to exactly 100 percent, got ${String(total / 1000)}; nothing was changed`,
+    );
+  }
+  return out;
+}
+
+/** The `on` a flag-change reply shows for `environmentKey`, when it is a boolean. */
+export function echoedOn(response: unknown, environmentKey: string): boolean | undefined {
+  const envs =
+    isRecord(response) && isRecord(response["environments"]) ? response["environments"] : {};
+  const env = envs[environmentKey];
+  return isRecord(env) && typeof env["on"] === "boolean" ? env["on"] : undefined;
+}
+
+/** `environmentKey`'s fallthrough rollout object in a flag-change reply, when there is one. */
+function fallthroughRolloutOf(
+  response: Record<string, unknown>,
+  environmentKey: string,
+): Record<string, unknown> | undefined {
+  const envs = isRecord(response["environments"]) ? response["environments"] : {};
+  const env = envs[environmentKey];
+  const fallthrough = isRecord(env) && isRecord(env["fallthrough"]) ? env["fallthrough"] : {};
+  const rollout = fallthrough["rollout"];
+  return isRecord(rollout) ? rollout : undefined;
+}
+
+/**
+ * The echoed rollout weights by variation id, or `undefined` when any entry cannot be resolved to a
+ * variation id and a numeric weight.
+ */
+function echoedWeights(
+  rollout: Record<string, unknown>,
+  variations: readonly unknown[],
+): Record<string, number> | undefined {
+  const echoed: Record<string, number> = {};
+  const entries = Array.isArray(rollout["variations"]) ? rollout["variations"] : [];
+  for (const entry of entries) {
+    const row = isRecord(entry) ? entry : {};
+    const index = row["variation"];
+    const weight = row["weight"];
+    const variation = typeof index === "number" ? variations[index] : undefined;
+    const id = isRecord(variation) ? variation["_id"] : undefined;
+    if (typeof id !== "string" || typeof weight !== "number") return undefined;
+    echoed[id] = weight;
+  }
+  return echoed;
+}
+
+/**
+ * True only when the reply carries `environmentKey`'s fallthrough rollout and its weights (by
+ * variation id, a missing id counting as 0) equal `requested`. A reply without them is not a
+ * confirmation.
+ */
+export function rolloutEchoed(
+  response: unknown,
+  environmentKey: string,
+  requested: Readonly<Record<string, number>>,
+): boolean {
+  if (!isRecord(response)) return false;
+  const rollout = fallthroughRolloutOf(response, environmentKey);
+  if (rollout === undefined || !Array.isArray(rollout["variations"])) return false;
+  const variations = Array.isArray(response["variations"]) ? response["variations"] : [];
+  const echoed = echoedWeights(rollout, variations);
+  if (echoed === undefined) return false;
+  const ids = new Set([...Object.keys(requested), ...Object.keys(echoed)]);
+  for (const id of ids) {
+    if ((requested[id] ?? 0) !== (echoed[id] ?? 0)) return false;
+  }
+  return true;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function numberOrUndefined(v: unknown): number | undefined {
+  return typeof v === "number" ? v : undefined;
+}
+
+/**
+ * The state of one flag in one environment, from `GET /flags/{p}/{f}?env={e}`.
+ *
+ * Variation references (`fallthrough.variation`, `offVariation`, `rollout.variations[].variation`)
+ * are read as INDICES into `variations[]`, which is how the schema describes `fallthrough.variation`.
+ * The same schema calls `offVariation` an "ID" in one place; the raw number is returned beside the
+ * resolved id so a caller can see which reading applied. Pinned by a fixture; live-check item.
+ */
+export function projectFlagState(
+  raw: unknown,
+  ids: { projectKey: string; flagKey: string; environmentKey: string },
+): Record<string, unknown> {
+  const flag = isRecord(raw) ? raw : {};
+  const envs = isRecord(flag["environments"]) ? flag["environments"] : {};
+  const env = envs[ids.environmentKey];
+  if (!isRecord(env)) {
+    throw new Error(`LaunchDarkly environment not found: ${ids.environmentKey}`);
+  }
+  const rawVariations = Array.isArray(flag["variations"]) ? flag["variations"] : [];
+  const variations = rawVariations.map((v, index) => {
+    const row = isRecord(v) ? v : {};
+    return { index, id: row["_id"], name: row["name"], value: row["value"] };
+  });
+  const idAt = (index: unknown): unknown =>
+    typeof index === "number" ? variations[index]?.id : undefined;
+
+  const fallthroughRaw = isRecord(env["fallthrough"]) ? env["fallthrough"] : {};
+  const fallthrough: Record<string, unknown> = {};
+  if (typeof fallthroughRaw["variation"] === "number") {
+    fallthrough["variation"] = fallthroughRaw["variation"];
+    fallthrough["variationId"] = idAt(fallthroughRaw["variation"]);
+  }
+  const rollout = fallthroughRaw["rollout"];
+  if (isRecord(rollout) && Array.isArray(rollout["variations"])) {
+    fallthrough["rollout"] = rollout["variations"].map((entry) => {
+      const row = isRecord(entry) ? entry : {};
+      const weight = numberOrUndefined(row["weight"]);
+      return {
+        variation: row["variation"],
+        variationId: idAt(row["variation"]),
+        weightPercent: weight === undefined ? undefined : weight / 1000,
+      };
+    });
+  }
+  if (isRecord(rollout)) {
+    if (typeof rollout["bucketBy"] === "string")
+      fallthrough["rolloutBucketBy"] = rollout["bucketBy"];
+    if (typeof rollout["contextKind"] === "string") {
+      fallthrough["rolloutContextKind"] = rollout["contextKind"];
+    }
+  }
+  return {
+    projectKey: ids.projectKey,
+    flagKey: ids.flagKey,
+    environmentKey: ids.environmentKey,
+    on: env["on"],
+    offVariation: env["offVariation"],
+    offVariationId: idAt(env["offVariation"]),
+    fallthrough,
+    variations,
+    version: numberOrUndefined(env["version"]) ?? numberOrUndefined(flag["_version"]),
+    archived: flag["archived"],
+  };
+}

package/connectors/launchdarkly/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerLaunchdarklyTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-launchdarkly", (reg) => {
-  registerLaunchdarklyTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-launchdarkly", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerLaunchdarklyTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/launchdarkly/src/tools.ts

@@ -1,32 +1,133 @@
 import { z } from "zod";
-import { createJsonGetter, envAuthHeaders, optionalEnv } from "../../../shared/env-json-api.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  envAuthHeaders,
+  type JsonApiConfig,
+  optionalEnv,
+} from "../../../shared/env-json-api.ts";
 import { matchesResult } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
-import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { echoedOn, projectFlagState, rolloutEchoed, rolloutWeightsOf } from "./flag-state.ts";
 import { filterLaunchDarklyFlags } from "./search-filter.ts";
 
 const DEFAULT_BASE = "https://app.launchdarkly.com";
 
-const ldGet = createJsonGetter({
+const api: JsonApiConfig = {
   // `optionalEnv`, not `optionalBaseUrl`: a trailing slash on the override is left as given.
   base: () => `${optionalEnv("LAUNCHDARKLY_BASE_URL", DEFAULT_BASE)}/api/v2`,
   label: "LaunchDarkly",
   headers: envAuthHeaders({ env: "LAUNCHDARKLY_TOKEN", scheme: "" }),
-});
+};
+
+const ldGet = createJsonGetter(api);
+const ldSend = createJsonSender(api);
+
+/**
+ * A semantic patch needs `domain-model=launchdarkly.semanticpatch` appended to Content-Type, else
+ * LaunchDarkly treats the body as a JSON patch and answers 400
+ * (https://launchdarkly.com/docs/guides/api/rest-api, "append `domain-model=launchdarkly.semanticpatch`
+ * to your `Content-Type` header").
+ */
+const SEMANTIC_PATCH_HEADERS = {
+  "Content-Type": "application/json; domain-model=launchdarkly.semanticpatch",
+} as const;
+
+/** Written into the flag's change history, so the audit trail says who made the change. */
+const CHANGE_COMMENT = "Changed by Nimbus after owner approval";
 
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const LAUNCHDARKLY_TOOL_NAMES = [
   "launchdarkly_list",
   "launchdarkly_get",
   "launchdarkly_search",
+  "launchdarkly_flag_state_get",
+  "launchdarkly_flag_toggle",
+  "launchdarkly_flag_rollout_set",
 ] as const;
 
-export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
+/**
+ * LaunchDarkly project, environment and flag keys: letters, digits, `.`, `_`, `-`, but never `.` or
+ * `..` alone: `encodeURIComponent("..")` is `..`, and a URL parser collapses it out of the path.
+ */
+const keyArg = z
+  .string()
+  .regex(
+    /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/,
+    "letters, digits, '.', '_' and '-' only; not '.' or '..'",
+  );
+
+/** The read tools keep accepting any key (it is percent-encoded), but never a dot segment. */
+const readKeyArg = z
+  .string()
+  .min(1)
+  .regex(/^(?!\.{1,2}$)/, "not '.' or '..'");
+
+const flagArgs = z.object({
+  projectKey: keyArg,
+  environmentKey: keyArg,
+  flagKey: keyArg,
+});
+
+type FlagArgs = z.infer<typeof flagArgs>;
+
+function flagPath(p: { projectKey: string; flagKey: string }): string {
+  return `/flags/${encodeURIComponent(p.projectKey)}/${encodeURIComponent(p.flagKey)}`;
+}
+
+/** One environment's slice of a flag, so the read stays small however many environments exist. */
+async function readFlagState(p: FlagArgs): Promise<Record<string, unknown>> {
+  const search = new URLSearchParams({ env: p.environmentKey });
+  const raw = await ldGet(`${flagPath(p)}?${search.toString()}`);
+  return projectFlagState(raw, p);
+}
+
+/**
+ * The result of a flag change: the facts, not LaunchDarkly's whole flag document. `confirmed` is
+ * true only when the reply SHOWS the requested state; false means the server accepted the write
+ * but its reply does not show the new state.
+ */
+function changed(
+  p: FlagArgs,
+  response: unknown,
+  confirmed: (response: unknown) => boolean,
+): Record<string, unknown> {
+  const flag = (response ?? {}) as { environments?: Record<string, { on?: unknown }> };
+  return {
+    ok: true,
+    confirmed: confirmed(response),
+    projectKey: p.projectKey,
+    environmentKey: p.environmentKey,
+    flagKey: p.flagKey,
+    on: flag.environments?.[p.environmentKey]?.on,
+  };
+}
+
+/** Scope: `flag:<projectKey>/<environmentKey>/<flagKey>`. */
+function flagScope(p: FlagArgs): { kind: string; value: string } {
+  return { kind: "flag", value: `${p.projectKey}/${p.environmentKey}/${p.flagKey}` };
+}
+
+export function registerLaunchdarklyTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "launchdarkly",
+    scopeEnv: "NIMBUS_MCP_LAUNCHDARKLY_WRITE_SCOPE",
+    scopeKinds: ["flag"],
+  });
+
   reg(
     "launchdarkly_list",
     "List LaunchDarkly projects, or feature flags for a project. Without `projectKey`, returns the account's projects (`/projects`). With `projectKey`, returns that project's flags (`/flags/{projectKey}`), capped at `limit` (default 100).",
     z.object({
-      projectKey: z.string().min(1).optional(),
+      projectKey: readKeyArg.optional(),
       limit: z.number().int().min(1).max(500).optional(),
     }),
     async (p) => {
@@ -44,8 +145,8 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
     "launchdarkly_get",
     "Fetch one LaunchDarkly feature flag by project key + flag key. Throws when no match is found.",
     z.object({
-      projectKey: z.string().min(1),
-      flagKey: z.string().min(1),
+      projectKey: readKeyArg,
+      flagKey: readKeyArg,
     }),
     async (p) => {
       return jsonResult(
@@ -58,7 +159,7 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
     "launchdarkly_search",
     "Substring search across a project's feature flags. Matches the query against flag key, name, description, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
     z.object({
-      projectKey: z.string().min(1),
+      projectKey: readKeyArg,
       query: z.string().min(1),
       limit: z.number().int().min(1).max(200).optional(),
     }),
@@ -69,4 +170,77 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
       return matchesResult(flags, filterLaunchDarklyFlags, p);
     },
   );
+
+  reg(
+    "launchdarkly_flag_state_get",
+    "Read one feature flag's state in ONE environment (`GET /flags/{projectKey}/{flagKey}?env={environmentKey}`): on/off, off variation, fallthrough (a single variation or a percentage rollout, with variation ids and weights in percent), the variation list and the environment's version. Smaller than `launchdarkly_get`, which returns every environment. Variation references are read as indices into `variations` (LaunchDarkly's schema is ambiguous for `offVariation`); the raw number is returned beside the resolved id.",
+    flagArgs,
+    async (p) => jsonResult(await readFlagState(p)),
+  );
+
+  registerWriteTool(
+    "launchdarkly_flag_toggle",
+    {
+      mutates: "launchdarkly.flag.toggle",
+      recoverable: true,
+      scopeTargetOf: flagScope,
+    },
+    "Turn a feature flag on or off in ONE environment (`PATCH /flags/{projectKey}/{flagKey}`, semantic patch turnFlagOn / turnFlagOff). Reversible by toggling back. An environment that requires approvals answers 405 and nothing changes.",
+    flagArgs.extend({ on: z.boolean() }),
+    async (p) => {
+      const response = await ldSend(
+        "PATCH",
+        flagPath(p),
+        {
+          environmentKey: p.environmentKey,
+          comment: CHANGE_COMMENT,
+          instructions: [{ kind: p.on ? "turnFlagOn" : "turnFlagOff" }],
+        },
+        SEMANTIC_PATCH_HEADERS,
+      );
+      return jsonResult(changed(p, response, (r) => echoedOn(r, p.environmentKey) === p.on));
+    },
+  );
+
+  registerWriteTool(
+    "launchdarkly_flag_rollout_set",
+    {
+      mutates: "launchdarkly.flag.rollout.set",
+      // The previous fallthrough (variation or weights, bucketBy, context kind) is recorded in the
+      // audit pre-state. This tool does not restore it, so the write is not marked recoverable.
+      recoverable: false,
+      capturePreState: readFlagState,
+      scopeTargetOf: flagScope,
+    },
+    "Set a feature flag's fallthrough to a percentage rollout in ONE environment (`PATCH /flags/{projectKey}/{flagKey}`, semantic patch updateFallthroughVariationOrRollout). `weights` maps variation ids (from `launchdarkly_flag_state_get`) to percent; they must sum to exactly 100 with at most 3 decimals, else nothing is sent. The previous fallthrough is recorded in the audit pre-state; this tool does not restore it, and a rollout's bucketBy / context kind are not set by it.",
+    flagArgs.extend({
+      weights: z
+        .array(
+          z.object({
+            variationId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+            percent: z.number().min(0).max(100),
+          }),
+        )
+        .min(1)
+        .max(20),
+    }),
+    async (p) => {
+      // Validated here, not with `.refine` on the schema: a refined schema loses `.shape`, which
+      // the registrar passes to the MCP SDK as the tool's input schema.
+      const rolloutWeights = rolloutWeightsOf(p.weights);
+      const response = await ldSend(
+        "PATCH",
+        flagPath(p),
+        {
+          environmentKey: p.environmentKey,
+          comment: CHANGE_COMMENT,
+          instructions: [{ kind: "updateFallthroughVariationOrRollout", rolloutWeights }],
+        },
+        SEMANTIC_PATCH_HEADERS,
+      );
+      return jsonResult(
+        changed(p, response, (r) => rolloutEchoed(r, p.environmentKey, rolloutWeights)),
+      );
+    },
+  );
 }

package/connectors/pagerduty/src/tools.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { guardedFetch } from "../../../shared/guarded-fetch.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -18,7 +19,8 @@ const API = "https://api.pagerduty.com";
 async function pdFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
   const rel = path.startsWith("/") ? path : `/${path}`;
   const url = path.startsWith("http") ? path : `${API}${rel}`;
-  const res = await fetch(url, {
+  // guardedFetch: a write answered with a redirect is refused, and a GET follows only same-origin.
+  const res = await guardedFetch("PagerDuty", url, {
     ...init,
     headers: {
       Accept: "application/vnd.pagerduty+json;version=2",
@@ -30,11 +32,59 @@ async function pdFetch(token: string, path: string, init?: RequestInit): Promise
   return toRestFetchResult(res);
 }
 
-async function pdIncidentPutMutation(actionLabel: string, pathSuffix: string, incidentId: string) {
+/**
+ * A linear-time email shape check (no regex, so no backtracking): at most 254 characters, no
+ * whitespace or control characters, exactly one `@`, a non-empty local part, and a domain that
+ * contains a `.` that is neither its first nor its last character.
+ */
+export function isEmailShape(email: string): boolean {
+  if (email.length === 0 || email.length > 254) return false;
+  for (let i = 0; i < email.length; i++) {
+    const c = email.charCodeAt(i);
+    if (c <= 0x20 || (c >= 0x7f && c <= 0xa0) || c === 0x2028 || c === 0x2029 || c === 0xfeff) {
+      return false;
+    }
+  }
+  const at = email.indexOf("@");
+  if (at < 1 || at !== email.lastIndexOf("@")) return false;
+  const domain = email.slice(at + 1);
+  // A "." strictly inside the domain: neither its first nor its last character.
+  return domain.length >= 3 && domain.slice(1, -1).includes(".");
+}
+
+/**
+ * The `From` header PagerDuty requires on an incident update: "The email address of a valid user
+ * associated with the account making the request". Writes only. Throws before any request.
+ * The gateway injects it from the Vault key `pagerduty.from_email`.
+ */
+function requirePdFromEmail(): string {
+  const email = requireProcessEnv("PAGERDUTY_FROM_EMAIL");
+  if (!isEmailShape(email)) {
+    throw new Error("PAGERDUTY_FROM_EMAIL is not an email address");
+  }
+  return email;
+}
+
+/** Incident ids are short alphanumerics; anything else never reaches a URL. */
+const incidentIdSchema = z.string().regex(/^[A-Za-z0-9]{1,64}$/);
+
+/**
+ * `PUT /incidents/{id}` with `{incident:{type:"incident_reference", status}}` and a required
+ * `From` header: the only update endpoint
+ * https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident documents
+ * (retrieved 2026-11-06). There is no `/acknowledge` or `/resolve` sub-endpoint.
+ */
+async function pdIncidentPut(
+  actionLabel: string,
+  change: { readonly status: "acknowledged" | "resolved" } | { readonly escalation_level: number },
+  incidentId: string,
+) {
+  const from = requirePdFromEmail();
   const token = requireProcessEnv("PAGERDUTY_API_TOKEN");
-  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}/${pathSuffix}`, {
+  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}`, {
     method: "PUT",
-    body: JSON.stringify({ incident: { type: "incident_reference", id: incidentId } }),
+    headers: { From: from },
+    body: JSON.stringify({ incident: { type: "incident_reference", ...change } }),
   });
   if (!res.ok) {
     throw new Error(`PagerDuty ${actionLabel} ${String(res.status)}: ${res.text.slice(0, 400)}`);
@@ -42,6 +92,24 @@ async function pdIncidentPutMutation(actionLabel: string, pathSuffix: string, in
   return jsonResult(res.json ?? { ok: true });
 }
 
+/** The incident as it stands: status, assignments, escalation level. Audited before a write. */
+async function readIncidentPreState(incidentId: string): Promise<Record<string, unknown>> {
+  requirePdFromEmail();
+  const token = requireProcessEnv("PAGERDUTY_API_TOKEN");
+  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}`);
+  if (!res.ok) {
+    throw new Error(`PagerDuty pre-state ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+  const inc = (res.json as { incident?: Record<string, unknown> } | null)?.incident ?? {};
+  return {
+    id: incidentId,
+    status: inc["status"],
+    assignments: inc["assignments"],
+    escalation_level: inc["escalation_level"] ?? null,
+    escalation_policy: inc["escalation_policy"],
+  };
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const PAGERDUTY_TOOL_NAMES = [
   "pd_incident_list",
@@ -51,13 +119,6 @@ export const PAGERDUTY_TOOL_NAMES = [
   "pd_incident_escalate",
 ] as const;
 
-/** The incident status changes, which differ only in the word they PUT. */
-const INCIDENT_STATUS_ACTIONS = [
-  { action: "acknowledge", description: "Acknowledge an incident." },
-  { action: "resolve", description: "Resolve an incident." },
-  { action: "escalate", description: "Escalate an incident." },
-] as const;
-
 export function registerPagerdutyTools(
   server: ConsentServer & { tool: (...args: never) => unknown },
 ): void {
@@ -107,20 +168,54 @@ export function registerPagerdutyTools(
     (parsed) => `/incidents/${encodeURIComponent(parsed.incidentId)}`,
   );
 
-  // The three incident status changes are the same PUT with a different status
-  // word, so they are declared rather than written out three times. Each keeps
-  // its own description; the rest was identical.
-  for (const { action, description } of INCIDENT_STATUS_ACTIONS) {
-    registerWriteTool(
-      `pd_incident_${action}`,
-      {
-        mutates: `pagerduty.incident.${action}`,
-        recoverable: true,
-        scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
-      },
-      description,
-      z.object({ incidentId: z.string().min(1) }),
-      async (parsed) => pdIncidentPutMutation(action, action, parsed.incidentId),
-    );
-  }
+  // Literal tool ids and `mutates` strings, so a static scan reads them. None can be undone
+  // through these tools (there is no unacknowledge, reopen or de-escalate), so each records the
+  // incident's prior state in the audit.
+  const incidentArgs = z.object({ incidentId: incidentIdSchema });
+  const incidentScope = (p: { incidentId: string }) => ({
+    kind: "incident",
+    value: p.incidentId,
+  });
+
+  registerWriteTool(
+    "pd_incident_acknowledge",
+    {
+      mutates: "pagerduty.incident.acknowledge",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    "Acknowledge an incident (`PUT /incidents/{id}` with status acknowledged). Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs,
+    async (p) => pdIncidentPut("acknowledge", { status: "acknowledged" }, p.incidentId),
+  );
+
+  registerWriteTool(
+    "pd_incident_resolve",
+    {
+      mutates: "pagerduty.incident.resolve",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    "Resolve an incident (`PUT /incidents/{id}` with status resolved); it cannot be reopened through these tools. Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs,
+    async (p) => pdIncidentPut("resolve", { status: "resolved" }, p.incidentId),
+  );
+
+  registerWriteTool(
+    "pd_incident_escalate",
+    {
+      mutates: "pagerduty.incident.escalate",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    // `escalation_level` ("Escalate the incident to this level in the escalation policy.", an
+    // integer) is a property of the `incident` body of PUT /incidents/{id} in PagerDuty's OpenAPI
+    // schema (github.com/PagerDuty/api-schema, reference/REST/openapiv3.json, retrieved 2026-11-06).
+    "Escalate an incident to the given level of its escalation policy (`PUT /incidents/{id}` with `escalation_level`); it cannot be de-escalated through these tools. Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs.extend({ escalationLevel: z.number().int().min(1).max(20) }),
+    async (p) => pdIncidentPut("escalate", { escalation_level: p.escalationLevel }, p.incidentId),
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },