@checkstack/healthcheck-backend 1.5.0 → 1.6.0

package/src/ai/healthcheck-update.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  HealthCheckApi,
+  UpdateHealthCheckConfigurationSchema,
+  healthCheckAccess,
+  pluginMetadata as healthcheckPluginMetadata,
+  type HealthCheckConfiguration,
+} from "@checkstack/healthcheck-common";
+import { computeFieldDiff, type AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import {
+  validateHealthcheckDraft,
+  type HealthcheckProposeInput,
+} from "./healthcheck-propose";
+
+/**
+ * Input for `healthcheck.update`: the id plus a PARTIAL configuration body. Only
+ * the provided fields change; the rest are kept from the existing config. The
+ * merged result is deep-validated before apply, exactly like create.
+ */
+export const HealthcheckUpdateInputSchema = z.object({
+  id: z.string().min(1),
+  body: UpdateHealthCheckConfigurationSchema,
+});
+export type HealthcheckUpdateInput = z.infer<typeof HealthcheckUpdateInputSchema>;
+
+/** Output returned once a human applies the update (the updated config). */
+export interface HealthcheckUpdateApplyResult {
+  configuration: HealthCheckConfiguration;
+}
+
+/**
+ * Merge a partial update body over the existing config into a full create-shaped
+ * configuration, so it can run through the SAME deep validation as create.
+ */
+function mergeConfig({
+  existing,
+  body,
+}: {
+  existing: HealthCheckConfiguration;
+  body: HealthcheckUpdateInput["body"];
+}): HealthcheckProposeInput {
+  return {
+    name: body.name ?? existing.name,
+    strategyId: body.strategyId ?? existing.strategyId,
+    config: body.config ?? existing.config,
+    intervalSeconds: body.intervalSeconds ?? existing.intervalSeconds,
+    collectors: body.collectors ?? existing.collectors,
+  };
+}
+
+/**
+ * `healthcheck.update` - update an existing health-check configuration by id.
+ *
+ * `effect: "mutate"` - a non-destructive change, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode, like `healthcheck.propose`. `dryRun`
+ * merges the partial body over the live config and deep-validates the RESULT
+ * (the same migrate-then-validate-strict path as create, including assertion
+ * field/operator validation), so an invalid edit is rejected with a precise,
+ * self-correcting error before apply.
+ */
+export function createHealthcheckUpdateTool(): RegisteredAiTool<
+  HealthcheckUpdateInput,
+  HealthcheckUpdateApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: HealthcheckUpdateInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<HealthcheckUpdateInput>> => {
+    const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+    const existing = await healthcheckClient.getConfiguration({ id: input.id });
+    if (!existing) {
+      throw new Error(
+        `No health check found with id "${input.id}". List health checks first to get a valid id.`,
+      );
+    }
+    const merged = mergeConfig({ existing, body: input.body });
+    // Deep-validate the merged result (throws with structured detail if invalid,
+    // including bad assertion fields/operators).
+    const { strategy } = await validateHealthcheckDraft({
+      input: merged,
+      rpcClient,
+    });
+    // before -> after diff over the updatable fields only (the existing config
+    // also carries id/timestamps/paused that are not part of an update).
+    const before = mergeConfig({ existing, body: {} });
+    const diff = computeFieldDiff({ before, after: merged });
+    return {
+      summary: `Update health check "${merged.name}" (strategy "${strategy.displayName}", every ${merged.intervalSeconds}s, ${merged.collectors?.length ?? 0} collector(s)).`,
+      payload: input,
+      diff,
+    };
+  };
+
+  return {
+    name: "healthcheck.update",
+    description:
+      "Update an existing health-check configuration by id with a partial body (only provided fields change). The merged result is validated like create (use getCapabilitySchema for exact config fields and assertable result fields + operators). Never updates directly; a person must approve unless the conversation is in auto mode. Find the id with the health-check read tools first.",
+    effect: "mutate",
+    input: HealthcheckUpdateInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(
+        healthcheckPluginMetadata,
+        healthCheckAccess.configuration.manage,
+      ),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+      const configuration = await healthcheckClient.updateConfiguration({
+        id: input.id,
+        body: input.body,
+      });
+      return { configuration };
+    },
+  };
+}

package/src/ai/notify-subscribers.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import {
+  healthcheckSystemSubscription,
+  healthcheckGroupSubscription,
+} from "@checkstack/healthcheck-common";
+import {
+  createNotifySystemSubscribersTool,
+  createNotifySystemGroupSubscribersTool,
+} from "./notify-subscribers";
+
+const principal: AuthUser = {
+  type: "application",
+  id: "svc",
+  name: "Svc",
+  accessRules: ["notification.notification.send.manage"],
+  teamIds: [],
+};
+
+function makeRpcClient() {
+  const notifyMock = mock(async (_input: unknown) => ({ notifiedCount: 3 }));
+  const rpcClient = {
+    forPlugin: () => ({ notifyForSubscription: notifyMock }),
+  } as unknown as RpcClient;
+  return { rpcClient, notifyMock };
+}
+
+describe("notify-subscriber tools", () => {
+  it("system tool: metadata + dispatches under the system spec", async () => {
+    const tool = createNotifySystemSubscribersTool();
+    expect(tool.name).toBe("healthcheck.notifySystemSubscribers");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "notification.notification.send.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+
+    const { rpcClient, notifyMock } = makeRpcClient();
+    const result = await tool.execute({
+      input: {
+        systemId: "sys-1",
+        systemName: "API Gateway",
+        title: "Degraded",
+        body: "API Gateway is unhealthy",
+        importance: "warning",
+        actionLabel: "View",
+        actionUrl: "https://x/sys-1",
+      },
+      principal,
+      rpcClient,
+    });
+
+    expect(result).toEqual({ notifiedCount: 3 });
+    const call = notifyMock.mock.calls[0]![0] as {
+      specId: string;
+      resourceKeys: string[];
+      subjects: Array<{ kind: string; id: string; name: string }>;
+      action?: { label: string; url: string };
+    };
+    expect(call.specId).toBe(healthcheckSystemSubscription.specId);
+    expect(call.resourceKeys).toEqual(["sys-1"]);
+    expect(call.subjects[0]).toMatchObject({
+      kind: "catalog.system",
+      id: "sys-1",
+      name: "API Gateway",
+    });
+    expect(call.action).toEqual({ label: "View", url: "https://x/sys-1" });
+  });
+
+  it("system tool: dryRun summarizes without sending", async () => {
+    const tool = createNotifySystemSubscribersTool();
+    const { rpcClient, notifyMock } = makeRpcClient();
+    const preview = await tool.dryRun!({
+      input: {
+        systemId: "sys-1",
+        title: "Hi",
+        body: "Body",
+      } as never,
+      principal,
+      rpcClient,
+    });
+    expect(preview.summary).toContain("sys-1");
+    expect(notifyMock).not.toHaveBeenCalled();
+  });
+
+  it("group tool: dispatches under the group spec with a group subject", async () => {
+    const tool = createNotifySystemGroupSubscribersTool();
+    expect(tool.name).toBe("healthcheck.notifySystemGroupSubscribers");
+    const { rpcClient, notifyMock } = makeRpcClient();
+    await tool.execute({
+      input: {
+        groupId: "grp-1",
+        groupName: "Prod",
+        title: "Degraded",
+        body: "A system in Prod is unhealthy",
+      },
+      principal,
+      rpcClient,
+    });
+    const call = notifyMock.mock.calls[0]![0] as {
+      specId: string;
+      resourceKeys: string[];
+      subjects: Array<{ kind: string; id: string }>;
+    };
+    expect(call.specId).toBe(healthcheckGroupSubscription.specId);
+    expect(call.resourceKeys).toEqual(["grp-1"]);
+    expect(call.subjects[0]).toMatchObject({ kind: "catalog.group", id: "grp-1" });
+  });
+});

package/src/ai/notify-subscribers.ts

@@ -0,0 +1,176 @@
+/**
+ * AI tools to notify the subscribers of a system or system group under the
+ * health-status subscription specs this plugin owns.
+ *
+ * These are hand-authored `mutate` tools. They call
+ * `notification.notifyForSubscription` through the call-time `rpcClient`
+ * (user-scoped in chat; the automation's `runAs` service account in the AI
+ * action), so the caller must hold `notification.send`. The notification
+ * backend enforces that rule for non-service callers and validates the
+ * resource keys, so a tool can only reach real subscribers.
+ */
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient } from "@checkstack/backend-api";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import {
+  NotificationApi,
+  notificationAccess,
+  pluginMetadata as notificationPluginMetadata,
+} from "@checkstack/notification-common";
+import {
+  createSystemSubject,
+  createGroupSubject,
+} from "@checkstack/catalog-common";
+import {
+  healthcheckSystemSubscription,
+  healthcheckGroupSubscription,
+} from "@checkstack/healthcheck-common";
+
+const NOTIFICATION_SEND_RULE = qualifyAccessRuleId(
+  notificationPluginMetadata,
+  notificationAccess.send,
+);
+
+const baseInputShape = {
+  title: z.string().min(1).describe("Notification title"),
+  body: z.string().min(1).describe("Notification body (supports markdown)"),
+  importance: z
+    .enum(["info", "warning", "critical"])
+    .optional()
+    .describe("Severity; defaults to 'info'"),
+  actionLabel: z.string().optional().describe("Optional action button label"),
+  actionUrl: z.string().optional().describe("Optional action button URL"),
+};
+
+const NotifySystemSubscribersInputSchema = z.object({
+  systemId: z.string().min(1).describe("Id of the system whose subscribers to notify"),
+  systemName: z
+    .string()
+    .optional()
+    .describe("Display name of the system (falls back to the id)"),
+  ...baseInputShape,
+});
+export type NotifySystemSubscribersInput = z.infer<
+  typeof NotifySystemSubscribersInputSchema
+>;
+
+const NotifyGroupSubscribersInputSchema = z.object({
+  groupId: z.string().min(1).describe("Id of the system group whose subscribers to notify"),
+  groupName: z
+    .string()
+    .optional()
+    .describe("Display name of the group (falls back to the id)"),
+  ...baseInputShape,
+});
+export type NotifyGroupSubscribersInput = z.infer<
+  typeof NotifyGroupSubscribersInputSchema
+>;
+
+export interface NotifyResult {
+  notifiedCount: number;
+}
+
+function actionFrom(input: {
+  actionLabel?: string;
+  actionUrl?: string;
+}): { label: string; url: string } | undefined {
+  return input.actionLabel && input.actionUrl
+    ? { label: input.actionLabel, url: input.actionUrl }
+    : undefined;
+}
+
+/**
+ * `healthcheck.notifySystemSubscribers` - notify everyone subscribed to a
+ * system's health status.
+ */
+export function createNotifySystemSubscribersTool(): RegisteredAiTool<
+  NotifySystemSubscribersInput,
+  NotifyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: NotifySystemSubscribersInput;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<NotifySystemSubscribersInput>> => ({
+    summary: `Notify subscribers of system "${input.systemName ?? input.systemId}": ${input.title}`,
+    payload: input,
+  });
+
+  return {
+    name: "healthcheck.notifySystemSubscribers",
+    description:
+      "Notify everyone subscribed to a system's health status. Requires confirmation before it sends (unless in auto mode). Provide the system id (and ideally its name).",
+    effect: "mutate",
+    input: NotifySystemSubscribersInputSchema,
+    requiredAccessRules: [NOTIFICATION_SEND_RULE],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const result = await rpcClient.forPlugin(NotificationApi).notifyForSubscription({
+        specId: healthcheckSystemSubscription.specId,
+        resourceKeys: [input.systemId],
+        title: input.title,
+        body: input.body,
+        importance: input.importance,
+        action: actionFrom(input),
+        subjects: [
+          createSystemSubject({
+            id: input.systemId,
+            name: input.systemName ?? input.systemId,
+            url: input.actionUrl,
+          }),
+        ],
+      });
+      return { notifiedCount: result.notifiedCount };
+    },
+  };
+}
+
+/**
+ * `healthcheck.notifySystemGroupSubscribers` - notify everyone subscribed to a
+ * system group's health status.
+ */
+export function createNotifySystemGroupSubscribersTool(): RegisteredAiTool<
+  NotifyGroupSubscribersInput,
+  NotifyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: NotifyGroupSubscribersInput;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<NotifyGroupSubscribersInput>> => ({
+    summary: `Notify subscribers of system group "${input.groupName ?? input.groupId}": ${input.title}`,
+    payload: input,
+  });
+
+  return {
+    name: "healthcheck.notifySystemGroupSubscribers",
+    description:
+      "Notify everyone subscribed to a system group's health status. Requires confirmation before it sends (unless in auto mode). Provide the group id (and ideally its name).",
+    effect: "mutate",
+    input: NotifyGroupSubscribersInputSchema,
+    requiredAccessRules: [NOTIFICATION_SEND_RULE],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const result = await rpcClient.forPlugin(NotificationApi).notifyForSubscription({
+        specId: healthcheckGroupSubscription.specId,
+        resourceKeys: [input.groupId],
+        title: input.title,
+        body: input.body,
+        importance: input.importance,
+        action: actionFrom(input),
+        subjects: [
+          createGroupSubject({
+            id: input.groupId,
+            name: input.groupName ?? input.groupId,
+            url: input.actionUrl,
+          }),
+        ],
+      });
+      return { notifiedCount: result.notifiedCount };
+    },
+  };
+}

package/src/ai/register-ai-tools.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { buildHealthcheckAiTools } from "./register-ai-tools";
+
+describe("buildHealthcheckAiTools", () => {
+  test("registers propose/update/delete with the right effects + manage rule", () => {
+    const tools = buildHealthcheckAiTools();
+    const byName = new Map(tools.map((t) => [t.name, t]));
+
+    expect(byName.get("healthcheck.propose")?.effect).toBe("mutate");
+    expect(byName.get("healthcheck.update")?.effect).toBe("mutate");
+    // Delete is destructive, so the propose/apply gate ALWAYS confirms it.
+    expect(byName.get("healthcheck.delete")?.effect).toBe("destructive");
+
+    // The mutating tools are gated by the manage rule.
+    for (const name of [
+      "healthcheck.propose",
+      "healthcheck.update",
+      "healthcheck.delete",
+    ] as const) {
+      expect(byName.get(name)?.requiredAccessRules).toEqual([
+        "healthcheck.healthcheck.manage",
+      ]);
+    }
+  });
+
+  test("registers the read-only capability tools gated by the read rule", () => {
+    const tools = buildHealthcheckAiTools();
+    const byName = new Map(tools.map((t) => [t.name, t]));
+
+    for (const name of [
+      "healthcheck.listCapabilities",
+      "healthcheck.getCapabilitySchema",
+    ] as const) {
+      const tool = byName.get(name);
+      expect(tool?.effect).toBe("read");
+      expect(tool?.requiredAccessRules).toEqual([
+        "healthcheck.healthcheck.read",
+      ]);
+    }
+  });
+});

package/src/ai/register-ai-tools.ts

@@ -0,0 +1,53 @@
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import { createHealthcheckProposeTool } from "./healthcheck-propose";
+import { createHealthcheckUpdateTool } from "./healthcheck-update";
+import { createHealthcheckDeleteTool } from "./healthcheck-delete";
+import {
+  createHealthcheckListCapabilitiesTool,
+  createHealthcheckGetCapabilitySchemaTool,
+} from "./healthcheck-capabilities";
+import {
+  createHealthcheckGetScriptContextTool,
+  createHealthcheckTestScriptTool,
+} from "./healthcheck-script-tools";
+import {
+  createNotifySystemSubscribersTool,
+  createNotifySystemGroupSubscribersTool,
+} from "./notify-subscribers";
+
+/**
+ * The health-check plugin's AI tools, registered into the AI registry via
+ * `aiToolExtensionPoint` from this plugin's own init - NOT centralized in
+ * ai-backend. This is the canonical pattern any plugin (first- or third-party)
+ * uses to contribute AI tools without ai-backend depending on it.
+ *
+ * The propose/update/delete tools are propose/apply-gated mutating tools
+ * (create/update are `mutate`; delete is `destructive`, so always confirm-gated).
+ * They go through the USER-SCOPED client passed at call time, so handler-side
+ * authorization is enforced exactly as a direct UI/RPC call; the resolver gate +
+ * the propose/apply re-check at propose AND apply time are the additional
+ * authorization authority.
+ *
+ * The two capability tools (`healthcheck.listCapabilities` /
+ * `healthcheck.getCapabilitySchema`) are `read` tools gated by the healthcheck
+ * config read rule; the resolver gate is their authority.
+ *
+ * The two script tools (`healthcheck.getScriptContext` /
+ * `healthcheck.testScript`) are `read` tools gated by the healthcheck
+ * configuration-manage rule. They are the healthcheck half of what used to be
+ * cross-plugin script-context tools in ai-backend; being single-context, the
+ * resolver gate is their authority (no in-execute context re-check).
+ */
+export function buildHealthcheckAiTools(): RegisteredAiTool[] {
+  return [
+    createHealthcheckProposeTool(),
+    createHealthcheckUpdateTool(),
+    createHealthcheckDeleteTool(),
+    createHealthcheckListCapabilitiesTool(),
+    createHealthcheckGetCapabilitySchemaTool(),
+    createHealthcheckGetScriptContextTool(),
+    createHealthcheckTestScriptTool(),
+    createNotifySystemSubscribersTool(),
+    createNotifySystemGroupSubscribersTool(),
+  ];
+}

package/src/ai/shell-env-table.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { buildShellRunContextEnv } from "../collector-script-test";
+import { HEALTHCHECK_SHELL_ENV } from "@checkstack/ai-backend";
+
+/**
+ * Drift guard (OQ-2): the static `HEALTHCHECK_SHELL_ENV` descriptor table is
+ * hand-maintained in ai-backend (cross-plugin import is deliberately avoided in
+ * the runtime code). This test asserts every reserved `CHECKSTACK_*` var the
+ * real producer (`buildShellRunContextEnv`) emits for a representative sample
+ * context is described in the static table. If the producer gains a new
+ * reserved var, this test fails until the table is updated.
+ */
+describe("HEALTHCHECK_SHELL_ENV drift guard", () => {
+  test("the static table describes every reserved var the producer emits", () => {
+    const produced = buildShellRunContextEnv({
+      check: { id: "c1", name: "Check One", intervalSeconds: 60 },
+      system: { id: "s1", name: "System One" },
+      environment: {
+        id: "e1",
+        name: "prod",
+        // A custom field exercises the CHECKSTACK_ENV_<FIELD> derivation.
+        fields: { region: "eu-central-1" },
+      },
+    });
+
+    const tableNames = new Set(HEALTHCHECK_SHELL_ENV.map((v) => v.name));
+    // The dynamic per-field var is covered by the wildcard descriptor.
+    tableNames.add("CHECKSTACK_ENV_REGION");
+
+    for (const producedName of Object.keys(produced)) {
+      expect(tableNames.has(producedName)).toBe(true);
+    }
+    // And the well-known reserved names must each be present verbatim.
+    for (const reserved of [
+      "CHECKSTACK_CHECK_ID",
+      "CHECKSTACK_CHECK_NAME",
+      "CHECKSTACK_CHECK_INTERVAL_SECONDS",
+      "CHECKSTACK_SYSTEM_ID",
+      "CHECKSTACK_SYSTEM_NAME",
+      "CHECKSTACK_ENV_ID",
+      "CHECKSTACK_ENV_NAME",
+    ]) {
+      expect(Object.keys(produced)).toContain(reserved);
+      expect(HEALTHCHECK_SHELL_ENV.some((v) => v.name === reserved)).toBe(true);
+    }
+  });
+});

package/src/automations.test.ts

@@ -2,7 +2,7 @@
  * Behaviour tests for the healthcheck automation triggers + actions.
  */
 import { describe, expect, it, mock } from "bun:test";
-import type { Logger } from "@checkstack/backend-api";
+import type { Logger, RpcClient } from "@checkstack/backend-api";
 import type { QueueManager } from "@checkstack/queue-api";
 import { createMockLogger } from "@checkstack/test-utils-backend";
 
@@ -28,6 +28,7 @@ const ctxBase = {
   getService: async <T,>(): Promise<T> => {
     throw new Error("not used");
   },
+  rpcClient: { forPlugin: () => ({}) } as unknown as RpcClient,
 };
 
 describe("healthcheck triggers", () => {

package/src/automations.ts

@@ -42,8 +42,14 @@ import type { HealthCheckService } from "./service";
 
 // ─── Payload schemas — match the hook payloads exactly ─────────────────
 
+// Phase 3b: the optional `environmentId` is present only for a PER-ENVIRONMENT
+// health change (the env-qualified `health` entity id); it is ABSENT for the
+// system-rollup change. Existing automations reading `systemId` are unaffected
+// (the rollup carries the bare systemId); new automations can filter on
+// `environmentId` to react to a specific environment's health.
 const systemDegradedPayloadSchema = z.object({
   systemId: z.string(),
+  environmentId: z.string().optional(),
   systemName: z.string().optional(),
   previousStatus: HealthCheckStatusSchema,
   newStatus: HealthCheckStatusSchema,
@@ -54,6 +60,7 @@ const systemDegradedPayloadSchema = z.object({
 
 const systemHealthyPayloadSchema = z.object({
   systemId: z.string(),
+  environmentId: z.string().optional(),
   systemName: z.string().optional(),
   previousStatus: HealthCheckStatusSchema,
   healthyChecks: z.number(),
@@ -63,6 +70,7 @@ const systemHealthyPayloadSchema = z.object({
 
 const systemHealthChangedPayloadSchema = z.object({
   systemId: z.string(),
+  environmentId: z.string().optional(),
   systemName: z.string().optional(),
   previousStatus: HealthCheckStatusSchema,
   newStatus: HealthCheckStatusSchema,
@@ -158,7 +166,7 @@ export const checkFailedTrigger: TriggerDefinition<
 
 // Triggers carry heterogeneous config types (all healthcheck triggers are
 // currently config-less). The registry accepts the `<unknown, unknown>` shape
-// and re-validates config against each trigger's own `configSchema` at load,
+// and re-validates config against each trigger's own versioned `config` at load,
 // so the registration array is widened here — mirroring
 // `registerBuiltinTriggers` in automation-backend.
 export const healthCheckTriggers: TriggerDefinition<unknown, unknown>[] = [

package/src/collector-script-test.test.ts

@@ -53,6 +53,36 @@ describe("buildShellRunContextEnv", () => {
       CHECKSTACK_SYSTEM_NAME: "web-1",
     });
   });
+
+  test("emits CHECKSTACK_ENV_* vars mirroring the real shell collector", () => {
+    const env = buildShellRunContextEnv({
+      system: { id: "s1", name: "web-1" },
+      environment: {
+        id: "env-prod",
+        name: "production",
+        fields: { baseUrl: "https://prod.example.com", region: "eu-west-1" },
+      },
+    });
+    expect(env).toEqual({
+      CHECKSTACK_SYSTEM_ID: "s1",
+      CHECKSTACK_SYSTEM_NAME: "web-1",
+      CHECKSTACK_ENV_ID: "env-prod",
+      CHECKSTACK_ENV_NAME: "production",
+      CHECKSTACK_ENV_BASE_URL: "https://prod.example.com",
+      CHECKSTACK_ENV_REGION: "eu-west-1",
+    });
+  });
+
+  test("keeps the first key on a normalized collision (first-wins)", () => {
+    const env = buildShellRunContextEnv({
+      environment: {
+        id: "e",
+        name: "n",
+        fields: { baseUrl: "first", "base-url": "second" },
+      },
+    });
+    expect(env.CHECKSTACK_ENV_BASE_URL).toBe("first");
+  });
 });
 
 describe("buildCollectorContext", () => {
@@ -74,6 +104,28 @@ describe("buildCollectorContext", () => {
   test("defaults config to an empty object", () => {
     expect(buildCollectorContext({})).toEqual({ config: {} });
   });
+
+  test("includes environment when present, mirroring the inline collector", () => {
+    expect(
+      buildCollectorContext({
+        config: {},
+        runContext: {
+          environment: {
+            id: "env-prod",
+            name: "production",
+            fields: { baseUrl: "https://prod.example.com" },
+          },
+        },
+      }),
+    ).toEqual({
+      config: {},
+      environment: {
+        id: "env-prod",
+        name: "production",
+        fields: { baseUrl: "https://prod.example.com" },
+      },
+    });
+  });
 });
 
 describe("runCollectorScriptTest — typescript", () => {
@@ -94,7 +146,7 @@ describe("runCollectorScriptTest — typescript", () => {
       },
       deps: { esmRunner: runner },
     });
-    expect(calls[0]?.helperModuleName).toBe("@checkstack/healthcheck");
+    expect(calls[0]?.helperModuleName).toBe("@checkstack/sdk/healthcheck");
     expect(calls[0]?.helperFunctionName).toBe("defineHealthCheck");
     expect(calls[0]?.context).toEqual({
       config: { threshold: 0.6 },