@checkstack/healthcheck-backend 1.5.0 → 1.6.0

package/src/ai/healthcheck-propose.ts

@@ -0,0 +1,290 @@
+import { stringify as toYaml } from "yaml";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  HealthCheckApi,
+  CreateHealthCheckConfigurationSchema,
+  healthCheckAccess,
+  pluginMetadata as healthcheckPluginMetadata,
+  type HealthCheckConfiguration,
+  type HealthCheckStrategyDto,
+  type CollectorDto,
+} from "@checkstack/healthcheck-common";
+import { z } from "zod";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import { validateCollectorAssertions } from "./assertion-validation";
+
+/**
+ * Input for the `healthcheck.propose` composite tool (plan OQ-6, Phase 5) - the
+ * mirror of the flagship `automation.propose`. The model authors a structured
+ * draft health-check configuration (the hard part of "NL -> health check");
+ * this tool VALIDATES that draft against the live strategy/collector registries
+ * via the published `validateConfiguration` RPC (the SAME deep migrate-then-
+ * validate-strict path the create / gitops-apply path uses) and returns it for
+ * a human to apply via the propose/apply gate. The shape reuses
+ * `CreateHealthCheckConfigurationSchema` so the model is constrained to a valid
+ * create skeleton (name, strategyId, config, intervalSeconds, collectors).
+ */
+export const HealthcheckProposeInputSchema =
+  CreateHealthCheckConfigurationSchema;
+
+export type HealthcheckProposeInput = z.infer<
+  typeof HealthcheckProposeInputSchema
+>;
+
+/** Output returned once a human applies the proposal (the created config). */
+export interface HealthcheckProposeApplyResult {
+  configuration: HealthCheckConfiguration;
+}
+
+class HealthcheckProposeValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly issues: Array<{ path: Array<string | number>; message: string }>,
+  ) {
+    super(message);
+    this.name = "HealthcheckProposeValidationError";
+  }
+}
+
+/**
+ * Flatten structured validation issues into a single, model-actionable string.
+ * The dry-run error surfaces to the model as plain text (a tool error), so the
+ * detail must live IN the message - not just the `issues` array - for the model
+ * to self-correct.
+ */
+function formatIssues(
+  issues: Array<{ path: Array<string | number>; message: string }>,
+): string {
+  return issues
+    .map((issue) =>
+      issue.path.length > 0
+        ? `${issue.path.join(".")}: ${issue.message}`
+        : issue.message,
+    )
+    .join("; ");
+}
+
+/**
+ * Appended to every health-check propose summary + the tool description: a newly
+ * created health check does NOT execute until it is assigned to a system, which
+ * the model must tell the operator (it cannot assign automatically yet).
+ */
+const SYSTEM_ASSIGNMENT_HINT =
+  "A new health check does not run until it is assigned to a system - after it is applied, tell the operator they must assign it to a system (Health Checks -> the check -> assign to a system) for it to start running.";
+
+/**
+ * Validate a drafted health-check configuration via the health-check plugin's
+ * `validateConfiguration` RPC - the SAME deep migrate-then-validate-strict path
+ * the create / gitops-apply path uses, so propose-time errors are identical to
+ * apply-time errors (a wrong config type or unknown key now surfaces at propose
+ * time, not just at apply). Throws a {@link HealthcheckProposeValidationError}
+ * carrying every structured issue when the draft is invalid; on success
+ * resolves the strategy + collector DTOs (via the published introspection RPCs)
+ * so the caller can render a precise confirm card with human-readable names.
+ */
+export async function validateHealthcheckDraft({
+  input,
+  rpcClient,
+}: {
+  input: HealthcheckProposeInput;
+  rpcClient: RpcClient;
+}): Promise<{ strategy: HealthCheckStrategyDto; collectors: CollectorDto[] }> {
+  const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+
+  // Deep validation authority: identical to apply-time / gitops-apply.
+  const validation = await healthcheckClient.validateConfiguration({
+    name: input.name,
+    strategyId: input.strategyId,
+    config: input.config,
+    intervalSeconds: input.intervalSeconds,
+    collectors: input.collectors,
+  });
+  if (!validation.valid) {
+    throw new HealthcheckProposeValidationError(
+      `The drafted health check is invalid: ${formatIssues(validation.errors)}`,
+      validation.errors,
+    );
+  }
+
+  // Valid: resolve human-readable DTOs for the confirm card. The strategy is
+  // guaranteed to exist (validation passed), so a missing DTO would be a
+  // registry/introspection mismatch - fall back to the raw id rather than
+  // failing the (already-valid) proposal.
+  const strategies = await healthcheckClient.getStrategies();
+  const strategy: HealthCheckStrategyDto = strategies.find(
+    (s) => s.id === input.strategyId,
+  ) ?? {
+    id: input.strategyId,
+    displayName: input.strategyId,
+    category: "other",
+    configSchema: {},
+  };
+
+  const availableCollectors = input.collectors?.length
+    ? await healthcheckClient.getCollectors({ strategyId: input.strategyId })
+    : [];
+  const resolvedCollectors: CollectorDto[] = [];
+  for (const entry of input.collectors ?? []) {
+    const collector = availableCollectors.find(
+      (c) => c.id === entry.collectorId,
+    );
+    if (collector) resolvedCollectors.push(collector);
+  }
+
+  // Assertion field/operator are free-form strings that `validateConfiguration`
+  // does not check, so an assertion with a bogus field/operator would save and
+  // then render as empty dropdowns in the editor. Validate them against each
+  // collector's RESULT schema + the canonical operator vocabulary so the model
+  // gets a precise, self-correcting error instead.
+  const resultSchemasById = new Map<string, Record<string, unknown>>();
+  for (const collector of availableCollectors) {
+    resultSchemasById.set(collector.id, collector.resultSchema);
+  }
+  const assertionIssues = validateCollectorAssertions({
+    collectors: input.collectors,
+    resultSchemasById,
+  });
+  if (assertionIssues.length > 0) {
+    throw new HealthcheckProposeValidationError(
+      `The drafted health check has invalid assertions: ${formatIssues(assertionIssues)}`,
+      assertionIssues,
+    );
+  }
+
+  return { strategy, collectors: resolvedCollectors };
+}
+
+/**
+ * Pull the script source out of a collector config entry, if any. Inline-script
+ * (TS) and shell `script` collectors carry their source under `script` or
+ * `source`; we surface it on the confirm card so the human reviewing the
+ * proposal sees exactly what code would run. Returns undefined for non-script
+ * collectors.
+ */
+export function extractCollectorScriptSource(
+  config: Record<string, unknown>,
+): string | undefined {
+  const candidate = config.script ?? config.source;
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+/**
+ * `healthcheck.propose` - the mirror of `automation.propose` (plan OQ-6,
+ * Phase 5): natural language -> validated draft health check -> human applies.
+ * The AI NEVER silently creates a health check. `dryRun` validates the draft
+ * against the live registries WITHOUT mutating; the actual `createConfiguration`
+ * happens only at `apply`, behind the propose/apply token gate.
+ *
+ * `effect: "mutate"` - creating a health-check configuration is a
+ * non-destructive create, so it auto-applies in AUTO mode and is confirm-gated
+ * in APPROVE mode via the Phase 4 permission machinery, exactly like
+ * `automation.propose`. It is NOT `destructive`.
+ *
+ * Authorization: a SINGLE `requiredAccessRules` of `healthcheck.healthcheck.manage`
+ * (one rule, so the framework's AND-gate is correct - the same privilege the UI
+ * create form requires), and the propose/apply service re-checks `isAllowed` at
+ * BOTH propose and apply time. The underlying RPC calls use the USER-SCOPED
+ * client passed at call time, so handler-side authorization (access rules AND
+ * per-resource/team scoping) is enforced exactly as a direct UI/RPC call; the
+ * resolver gate + the propose/apply re-check are the additional authorization
+ * authority for this composite tool, identical to `automation.propose`.
+ */
+export function createHealthcheckProposeTool(): RegisteredAiTool<
+  HealthcheckProposeInput,
+  HealthcheckProposeApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: HealthcheckProposeInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<HealthcheckProposeInput>> => {
+    // Validate the draft against the live strategy/collector registries WITHOUT
+    // creating anything (the same registries the UI pickers read).
+    const { strategy, collectors } = await validateHealthcheckDraft({
+      input,
+      rpcClient,
+    });
+
+    const scriptCollectors = (input.collectors ?? []).filter((entry) =>
+      extractCollectorScriptSource(entry.config),
+    );
+
+    // Render the full draft for human review: the configuration fields plus the
+    // resolved strategy/collector names and any script source.
+    const yaml = toYaml({
+      healthCheck: {
+        name: input.name,
+        strategy: strategy.displayName,
+        strategyId: input.strategyId,
+        intervalSeconds: input.intervalSeconds,
+        config: input.config,
+        ...(input.collectors?.length
+          ? {
+              collectors: input.collectors.map((entry) => {
+                const match = collectors.find(
+                  (c) => c.id === entry.collectorId,
+                );
+                return {
+                  collector: match?.displayName ?? entry.collectorId,
+                  collectorId: entry.collectorId,
+                  config: entry.config,
+                  ...(entry.assertions?.length
+                    ? { assertions: entry.assertions }
+                    : {}),
+                };
+              }),
+            }
+          : {}),
+      },
+    });
+
+    const collectorCount = input.collectors?.length ?? 0;
+    const scriptNote =
+      scriptCollectors.length > 0
+        ? ` (includes ${scriptCollectors.length} script collector${scriptCollectors.length === 1 ? "" : "s"})`
+        : "";
+    const summary = `Create health check "${input.name}" using strategy "${strategy.displayName}" with ${collectorCount} collector(s), running every ${input.intervalSeconds}s${scriptNote}. ${SYSTEM_ASSIGNMENT_HINT}`;
+
+    return {
+      summary,
+      // The validated, ready-to-apply payload captured at propose time. The
+      // chat confirm card / editor seeds from this; the YAML is for display.
+      payload: { ...input, yaml } as HealthcheckProposeInput & { yaml: string },
+    };
+  };
+
+  return {
+    name: "healthcheck.propose",
+    description:
+      "Validate a drafted health check (strategy, collectors, interval, and any inline script source) and return it for a human to review and apply. Never creates a health check directly - a person must approve the proposal. Use this to turn a natural-language health-check request (including a script health check) into a concrete, validated draft after testing the script with testScript. If you do not know what an endpoint returns, call probeUrl first to inspect its status code and body, then assert on the real response. Use getCapabilitySchema to get exact collector config fields AND the assertable result fields + valid operators before drafting assertions (assertion field must be a result-schema field like statusCode, operator must be a full word like equals/greaterThan, never an abbreviation). Note: a newly created health check does not run until the operator assigns it to a system.",
+    effect: "mutate",
+    input: HealthcheckProposeInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(
+        healthcheckPluginMetadata,
+        healthCheckAccess.configuration.manage,
+      ),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      // Only reached via `apply` (the propose/apply token gate). The create
+      // handler runs its own zod + registry validation; this re-validates the
+      // server-stored payload against the input schema is already done by the
+      // propose/apply service before we get here.
+      const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+      const configuration = await healthcheckClient.createConfiguration({
+        name: input.name,
+        strategyId: input.strategyId,
+        config: input.config,
+        intervalSeconds: input.intervalSeconds,
+        collectors: input.collectors,
+      });
+      return { configuration };
+    },
+  };
+}

package/src/ai/healthcheck-script-tools.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import {
+  GetScriptContextOutputSchema,
+  TestScriptOutputSchema,
+} from "@checkstack/ai-common";
+import {
+  createHealthcheckGetScriptContextTool,
+  createHealthcheckTestScriptTool,
+} from "./healthcheck-script-tools";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["healthcheck.healthcheck.manage"],
+};
+
+/** A canned collector test result the stub RPC returns; the tool must map it through. */
+const CANNED_RESULT = {
+  result: { statusCode: 200 },
+  stdout: "probe ok\n",
+  stderr: "",
+  exitCode: 0,
+  durationMs: 42,
+  timedOut: false,
+  error: undefined,
+};
+
+function fakeHealthcheckRpcClient(): RpcClient {
+  return {
+    forPlugin: () => ({
+      testCollectorScript: mock(() => Promise.resolve(CANNED_RESULT)),
+    }),
+  } as unknown as RpcClient;
+}
+
+describe("healthcheck.getScriptContext tool", () => {
+  test("declares read effect + healthcheck manage gate, no dryRun", () => {
+    const tool = createHealthcheckGetScriptContextTool();
+    expect(tool.name).toBe("healthcheck.getScriptContext");
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual([
+      "healthcheck.healthcheck.manage",
+    ]);
+    expect(tool.dryRun).toBeUndefined();
+  });
+
+  test("resolves a healthcheck-script context from the real SDK bundle", async () => {
+    const tool = createHealthcheckGetScriptContextTool();
+    const out = await tool.execute({
+      input: { context: "healthcheck-script" },
+      principal,
+      rpcClient: fakeHealthcheckRpcClient(),
+    });
+    expect(GetScriptContextOutputSchema.safeParse(out).success).toBe(true);
+    expect(out.context).toBe("healthcheck-script");
+    expect(out.declarations.length).toBeGreaterThan(0);
+  });
+});
+
+describe("healthcheck.testScript tool", () => {
+  test("declares read effect + healthcheck manage gate, no dryRun", () => {
+    const tool = createHealthcheckTestScriptTool();
+    expect(tool.name).toBe("healthcheck.testScript");
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual([
+      "healthcheck.healthcheck.manage",
+    ]);
+    expect(tool.dryRun).toBeUndefined();
+  });
+
+  test("maps the RPC result fields through to the tool output", async () => {
+    const tool = createHealthcheckTestScriptTool();
+    const out = await tool.execute({
+      input: {
+        context: "healthcheck-script",
+        source: "export default async () => ({ statusCode: 200 });",
+        timeoutMs: 10_000,
+      },
+      principal,
+      rpcClient: fakeHealthcheckRpcClient(),
+    });
+    expect(TestScriptOutputSchema.safeParse(out).success).toBe(true);
+    expect(out.result).toEqual(CANNED_RESULT.result);
+    expect(out.stdout).toBe(CANNED_RESULT.stdout);
+    expect(out.stderr).toBe(CANNED_RESULT.stderr);
+    expect(out.exitCode).toBe(CANNED_RESULT.exitCode);
+    expect(out.durationMs).toBe(CANNED_RESULT.durationMs);
+    expect(out.timedOut).toBe(false);
+    // sandboxDowngraded is computed from the active policy and always surfaced.
+    expect(typeof out.sandboxDowngraded).toBe("boolean");
+  });
+});

package/src/ai/healthcheck-script-tools.ts

@@ -0,0 +1,179 @@
+import { SDK_EDITOR_BUNDLE_DTS } from "@checkstack/sdk/editor-bundle";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import { resolveActiveSandboxPolicy } from "@checkstack/backend-api";
+import {
+  HealthCheckApi,
+  CollectorScriptTestInputSchema,
+  healthCheckAccess,
+  pluginMetadata as healthcheckPluginMetadata,
+} from "@checkstack/healthcheck-common";
+import {
+  GetScriptContextOutputSchema,
+  TestScriptInputSchema,
+  TestScriptOutputSchema,
+  type GetScriptContextOutput,
+  type TestScriptOutput,
+} from "@checkstack/ai-common";
+import { resolveScriptContext } from "@checkstack/ai-backend";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import { z } from "zod";
+
+/**
+ * The healthcheck script-context rule that gates BOTH script tools. These are
+ * single-context (healthcheck-only) tools, so the resolver gate by the
+ * healthcheck configuration-manage rule is the authority - there is no
+ * cross-context surface, so no in-execute context assertion is needed (the old
+ * cross-context tools needed one because they fanned out to multiple plugins;
+ * these only ever handle healthcheck contexts).
+ */
+const HEALTHCHECK_MANAGE_RULE = qualifyAccessRuleId(
+  healthcheckPluginMetadata,
+  healthCheckAccess.configuration.manage,
+);
+
+/** The two healthcheck script contexts this plugin's tools handle. */
+const HealthcheckScriptContextSchema = z.enum([
+  "healthcheck-script",
+  "healthcheck-shell",
+]);
+
+export const HealthcheckGetScriptContextInputSchema = z.object({
+  context: HealthcheckScriptContextSchema,
+});
+export type HealthcheckGetScriptContextInput = z.infer<
+  typeof HealthcheckGetScriptContextInputSchema
+>;
+
+/**
+ * `healthcheck.getScriptContext` - return the SDK symbols / imports / type
+ * signatures for a HEALTHCHECK script context by PURE extraction from the
+ * generated SDK editor bundle (the same DTS Monaco mounts). `effect: "read"` -
+ * it composes a static build-time resource and persists nothing, so it
+ * auto-runs in chat.
+ *
+ * This is a single-context (healthcheck-only) tool, so it is gated directly by
+ * the healthcheck configuration-manage rule at the resolver - no in-execute
+ * context assertion is needed.
+ */
+export function createHealthcheckGetScriptContextTool(): RegisteredAiTool<
+  HealthcheckGetScriptContextInput,
+  GetScriptContextOutput
+> {
+  return {
+    name: "healthcheck.getScriptContext",
+    description:
+      "Return the SDK symbols, imports, and type signatures available to a health-check script in a given context (healthcheck-script, healthcheck-shell). Use this before drafting or testing a script so you import the correct module and helper and match the runtime context shape.",
+    effect: "read",
+    input: HealthcheckGetScriptContextInputSchema,
+    output: GetScriptContextOutputSchema,
+    requiredAccessRules: [HEALTHCHECK_MANAGE_RULE],
+    async execute({ input }) {
+      const resolved = resolveScriptContext({
+        context: input.context,
+        bundle: SDK_EDITOR_BUNDLE_DTS,
+      });
+      return {
+        context: resolved.context,
+        language: resolved.language,
+        sdkModule: resolved.sdkModule,
+        helper: resolved.helper,
+        declarations: resolved.declarations,
+        shellEnv: resolved.shellEnv ? [...resolved.shellEnv] : undefined,
+        starterExample: resolved.starterExample,
+        allowsManagedPackages: resolved.allowsManagedPackages,
+      };
+    },
+  };
+}
+
+export const HealthcheckTestScriptInputSchema = TestScriptInputSchema.extend({
+  context: HealthcheckScriptContextSchema,
+});
+export type HealthcheckTestScriptInput = z.infer<
+  typeof HealthcheckTestScriptInputSchema
+>;
+
+/**
+ * Resolve whether the active GLOBAL sandbox policy fell back to the fail-closed
+ * profile (no provider, or the provider threw). Surfaced as `sandboxDowngraded`
+ * so the model/operator NEVER gets a silent downgrade. Pure read of the same
+ * global policy the runners themselves resolve, so it is pod-consistent; any
+ * read failure conservatively reports a downgrade rather than masking one.
+ */
+async function resolveSandboxDowngraded(): Promise<boolean> {
+  try {
+    const { failedClosed } = await resolveActiveSandboxPolicy();
+    return failedClosed;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * `healthcheck.testScript` - run a DRAFT health-check script through the
+ * EXISTING fail-closed sandbox by calling `healthCheckContract.testCollectorScript`
+ * via the USER-SCOPED client passed at call time, so handler-side authorization
+ * is enforced exactly as a direct UI/RPC call. No model call is made, so the
+ * spend ledger is untouched.
+ *
+ * `effect: "read"` - it persists NOTHING about platform config (no health
+ * check, no row). It still counts toward the per-principal tool budget
+ * (enforced by the chat loop around every tool call).
+ *
+ * This is a single-context (healthcheck-only) tool, gated directly by the
+ * healthcheck configuration-manage rule at the resolver - no in-execute context
+ * assertion is needed.
+ *
+ * Safety inherited from the RPC test path:
+ *   - The fail-closed global sandbox enforces no egress / scratch FS / privilege
+ *     drop; `sandboxDowngraded` surfaces a fallback so it is never silent.
+ *   - This tool passes NO `secretOverrides` and NO `secretEnv`, so only
+ *     `__SECRET_<NAME>__` placeholders are ever present - the model never
+ *     supplies secret values.
+ *   - `timeoutMs` is capped at 30s in the input (stricter than the RPC's 300s).
+ */
+export function createHealthcheckTestScriptTool(): RegisteredAiTool<
+  HealthcheckTestScriptInput,
+  TestScriptOutput
+> {
+  return {
+    name: "healthcheck.testScript",
+    description:
+      "Run a drafted health-check script in the secure fail-closed sandbox and return its result, stdout/stderr, and any error - WITHOUT creating any health check. Use this to validate a draft before proposing it. Never pass real secret values; the sandbox injects placeholders only.",
+    effect: "read",
+    input: HealthcheckTestScriptInputSchema,
+    output: TestScriptOutputSchema,
+    requiredAccessRules: [HEALTHCHECK_MANAGE_RULE],
+    async execute({ input, rpcClient }) {
+      const healthCheckClient = rpcClient.forPlugin(HealthCheckApi);
+      const kind =
+        input.context === "healthcheck-script" ? "typescript" : "shell";
+      const sandboxDowngraded = await resolveSandboxDowngraded();
+
+      // Map the tool input -> CollectorScriptTestInputSchema, parsing the loose
+      // `sampleContext` through the RPC's own schema (unknown keys are stripped,
+      // types narrowed). NEVER pass secretEnv / secretOverrides: the model never
+      // supplies secret values, so only placeholders can ever appear in the run.
+      const rpcInput = CollectorScriptTestInputSchema.parse({
+        kind,
+        script: input.source,
+        config: input.config,
+        env: input.env,
+        runContext: input.sampleContext,
+        timeoutMs: input.timeoutMs,
+      });
+      const raw = await healthCheckClient.testCollectorScript(rpcInput);
+
+      return {
+        result: raw.result,
+        stdout: raw.stdout,
+        stderr: raw.stderr,
+        exitCode: raw.exitCode,
+        durationMs: raw.durationMs,
+        timedOut: raw.timedOut,
+        error: raw.error,
+        sandboxDowngraded,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,123 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createHealthcheckUpdateTool } from "./healthcheck-update";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["healthcheck.healthcheck.manage"],
+};
+
+const httpStrategy = {
+  id: "healthcheck-http.http",
+  displayName: "HTTP",
+  description: "HTTP probe",
+  category: "network",
+  configSchema: { type: "object", properties: { url: { type: "string" } } },
+};
+
+const existing = {
+  id: "hc1",
+  name: "google-com-http",
+  strategyId: "healthcheck-http.http",
+  config: { url: "https://google.com" },
+  intervalSeconds: 60,
+  collectors: [],
+  paused: false,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient(overrides: Record<string, ReturnType<typeof mock>>): {
+  rpcClient: RpcClient;
+  fns: Record<string, ReturnType<typeof mock>>;
+} {
+  const fns = {
+    getConfiguration: mock(() => Promise.resolve(existing)),
+    validateConfiguration: mock(() =>
+      Promise.resolve({ valid: true, errors: [] }),
+    ),
+    getStrategies: mock(() => Promise.resolve([httpStrategy])),
+    getCollectors: mock(() => Promise.resolve([])),
+    updateConfiguration: mock(() =>
+      Promise.resolve({ ...existing, intervalSeconds: 30 }),
+    ),
+    ...overrides,
+  };
+  return {
+    rpcClient: { forPlugin: () => fns } as unknown as RpcClient,
+    fns,
+  };
+}
+
+describe("healthcheck.update tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createHealthcheckUpdateTool();
+    expect(tool.name).toBe("healthcheck.update");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["healthcheck.healthcheck.manage"]);
+  });
+
+  test("dryRun merges the partial body and deep-validates, NEVER updating", async () => {
+    const { rpcClient, fns } = fakeRpcClient({});
+    const tool = createHealthcheckUpdateTool();
+    const preview = await tool.dryRun!({
+      input: { id: "hc1", body: { intervalSeconds: 30 } },
+      principal,
+      rpcClient,
+    });
+    expect(fns.validateConfiguration).toHaveBeenCalledTimes(1);
+    expect(fns.updateConfiguration).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("google-com-http");
+    expect(preview.summary).toContain("30s");
+    expect(preview.payload).toEqual({ id: "hc1", body: { intervalSeconds: 30 } });
+    // The before -> after diff captures exactly what changes.
+    expect(preview.diff).toEqual([
+      { path: "intervalSeconds", before: 60, after: 30 },
+    ]);
+  });
+
+  test("dryRun throws when the id is unknown", async () => {
+    const { rpcClient } = fakeRpcClient({
+      getConfiguration: mock(() => Promise.resolve(undefined)),
+    });
+    const tool = createHealthcheckUpdateTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope", body: {} }, principal, rpcClient }),
+    ).rejects.toThrow(/No health check found/);
+  });
+
+  test("dryRun surfaces a deep validation error from the merged config", async () => {
+    const { rpcClient } = fakeRpcClient({
+      validateConfiguration: mock(() =>
+        Promise.resolve({
+          valid: false,
+          errors: [{ path: ["config", "url"], message: "Expected string" }],
+        }),
+      ),
+    });
+    const tool = createHealthcheckUpdateTool();
+    await expect(
+      tool.dryRun!({
+        input: { id: "hc1", body: { config: { url: 1 } } },
+        principal,
+        rpcClient,
+      }),
+    ).rejects.toThrow(/invalid/i);
+  });
+
+  test("execute (apply) updates via updateConfiguration", async () => {
+    const { rpcClient, fns } = fakeRpcClient({});
+    const tool = createHealthcheckUpdateTool();
+    const result = await tool.execute({
+      input: { id: "hc1", body: { intervalSeconds: 30 } },
+      principal,
+      rpcClient,
+    });
+    expect(fns.updateConfiguration).toHaveBeenCalledWith({
+      id: "hc1",
+      body: { intervalSeconds: 30 },
+    });
+    expect(result.configuration.id).toBe("hc1");
+  });
+});