@langwatch/mcp-server 2.1.0 → 2.2.0

package/src/public-http-request.ts

@@ -3,7 +3,7 @@ import { request as httpRequest, type RequestOptions } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 
-import { classify } from "@langwatch/ssrf";
+import { classify } from "@langwatch/egress/ssrf";
 
 const MAX_REDIRECTS = 5;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -20,7 +20,10 @@ const SENSITIVE_REDIRECT_HEADERS = new Set([
   "x-access-token",
 ]);
 
-type DnsResolver = (hostname: string, options: { all: true; verbatim: true }) => Promise<ResolvedAddress[]>;
+type DnsResolver = (
+  hostname: string,
+  options: { all: true; verbatim: true },
+) => Promise<ResolvedAddress[]>;
 
 interface ResolvedAddress {
   address: string;
@@ -34,7 +37,9 @@ export interface PublicDestination {
 }
 
 function unsafeDestinationError(): Error {
-  return new Error("HTTP agent destinations must resolve only to globally routable public addresses");
+  return new Error(
+    "HTTP agent destinations must resolve only to globally routable public addresses",
+  );
 }
 
 function hostnameWithoutBrackets(hostname: string): string {
@@ -66,21 +71,21 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T
 
 export function headersForRedirect(
   headers: Record<string, string> | undefined,
-  crossOrigin: boolean
+  crossOrigin: boolean,
 ): Record<string, string> | undefined {
   if (!headers || !crossOrigin) {
     return headers;
   }
 
   const safeHeaders = Object.fromEntries(
-    Object.entries(headers).filter(([name]) => !SENSITIVE_REDIRECT_HEADERS.has(name.toLowerCase()))
+    Object.entries(headers).filter(([name]) => !SENSITIVE_REDIRECT_HEADERS.has(name.toLowerCase())),
   );
   return Object.keys(safeHeaders).length > 0 ? safeHeaders : undefined;
 }
 
 export async function resolvePublicDestination(
   input: string,
-  resolver: DnsResolver = dnsLookup
+  resolver: DnsResolver = dnsLookup,
 ): Promise<PublicDestination> {
   let url: URL;
   try {
@@ -89,7 +94,11 @@ export async function resolvePublicDestination(
     throw new Error("HTTP agent URL is invalid");
   }
 
-  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username !== "" || url.password !== "") {
+  if (
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.username !== "" ||
+    url.password !== ""
+  ) {
     throw unsafeDestinationError();
   }
 
@@ -104,7 +113,7 @@ export async function resolvePublicDestination(
   try {
     addresses = await withTimeout(
       resolver(hostname, { all: true, verbatim: true }),
-      REQUEST_TIMEOUT_MS
+      REQUEST_TIMEOUT_MS,
     );
   } catch {
     throw new Error("HTTP agent destination could not be resolved");
@@ -135,7 +144,7 @@ interface PublicJsonRequestOptions {
 
 function requestBody(
   destination: PublicDestination,
-  options: PublicJsonRequestOptions
+  options: PublicJsonRequestOptions,
 ): Promise<{ body: string; location?: string; statusCode: number }> {
   return new Promise((resolve, reject) => {
     const hostname = hostnameWithoutBrackets(destination.url.hostname);
@@ -198,7 +207,7 @@ function requestBody(
 export async function requestPublicJson(
   input: string,
   options: PublicJsonRequestOptions = {},
-  redirectCount = 0
+  redirectCount = 0,
 ): Promise<Record<string, unknown>> {
   const destination = await resolvePublicDestination(input);
   const response = await requestBody(destination, options);
@@ -210,7 +219,7 @@ export async function requestPublicJson(
     const redirectUrl = new URL(response.location, destination.url);
     const redirectHeaders = headersForRedirect(
       options.headers,
-      redirectUrl.origin !== destination.url.origin
+      redirectUrl.origin !== destination.url.origin,
     );
     const preserveBody = response.statusCode === 307 || response.statusCode === 308;
     return requestPublicJson(
@@ -223,7 +232,7 @@ export async function requestPublicJson(
             headers: redirectHeaders,
             method: "GET",
           },
-      redirectCount + 1
+      redirectCount + 1,
     );
   }
 

package/src/schemas/analytics-metrics.ts

@@ -124,17 +124,7 @@ export const analyticsMetrics: MetricInfo[] = [
     category: "events",
     name: "event_score",
     label: "Event Score",
-    allowedAggregations: [
-      "terms",
-      "avg",
-      "sum",
-      "min",
-      "max",
-      "median",
-      "p99",
-      "p95",
-      "p90",
-    ],
+    allowedAggregations: ["terms", "avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
     description: "Numeric score from events (requires event_type key and metrics key)",
   },
   {
@@ -142,8 +132,7 @@ export const analyticsMetrics: MetricInfo[] = [
     name: "event_details",
     label: "Event Details",
     allowedAggregations: ["cardinality"],
-    description:
-      "Event detail key/value distribution (requires event_type key and details key)",
+    description: "Event detail key/value distribution (requires event_type key and details key)",
   },
   // evaluations
   {
@@ -158,8 +147,7 @@ export const analyticsMetrics: MetricInfo[] = [
     name: "evaluation_pass_rate",
     label: "Evaluation Pass Rate",
     allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
-    description:
-      "Percentage of traces passing evaluation (requires evaluator_id key)",
+    description: "Percentage of traces passing evaluation (requires evaluator_id key)",
   },
   {
     category: "evaluations",

package/src/schemas/create-dataset.ts

@@ -16,6 +16,7 @@ export const DATASET_COLUMN_TYPES = [
   "annotations",
   "evaluations",
   "image",
+  "file",
 ] as const;
 
 /**
@@ -34,10 +35,8 @@ export const datasetColumnDefinitionSchema = z.object({
 });
 
 /**
- * Zod schema for the platform_create_dataset MCP tool parameters.
- *
- * Extracted so it can be shared between the MCP tool registration
- * (create-mcp-server.ts) and unit tests.
+ * Zod schema for the platform_create_dataset MCP tool parameters,
+ * extracted so it's shared between create-mcp-server.ts and unit tests.
  */
 export const createDatasetSchema = z.object({
   name: z.string().min(1).describe("Dataset name"),

package/src/schemas/run-plan.ts

@@ -1,24 +1,18 @@
 import { z } from "zod";
 
 /**
- * Typed inputs for the run plan tools.
- *
- * Each one mirrors the zod the platform validates the REST body with, so an
- * agent is told what is accepted before the request goes out rather than
- * after: `suiteScopeSchema` and `suiteTargetSchema` on the server side.
+ * Typed inputs for the run plan tools, mirroring the platform's REST
+ * validation (`suiteScopeSchema` and `suiteTargetSchema`) so an agent
+ * learns what's accepted before the request goes out.
  */
 
 /** What a run plan covers. */
 export const runPlanScopeSchema = z.discriminatedUnion("mode", [
-  z
-    .object({ mode: z.literal("all") })
-    .describe("Every non-archived scenario of the project"),
+  z.object({ mode: z.literal("all") }).describe("Every non-archived scenario of the project"),
   z
     .object({
       mode: z.literal("test_suites"),
-      testSuiteIds: z
-        .array(z.string())
-        .describe("The test suite IDs whose scenarios to run"),
+      testSuiteIds: z.array(z.string()).describe("The test suite IDs whose scenarios to run"),
     })
     .describe("The non-archived scenarios filed in the given test suites"),
   z
@@ -26,9 +20,7 @@ export const runPlanScopeSchema = z.discriminatedUnion("mode", [
       mode: z.literal("labels"),
       labels: z.array(z.string()).describe("The labels to select scenarios by"),
     })
-    .describe(
-      "The non-archived scenarios carrying at least one of the given labels",
-    ),
+    .describe("The non-archived scenarios carrying at least one of the given labels"),
   z
     .object({ mode: z.literal("scenarios") })
     .describe("The scenarios named in scenarioIds, picked by hand"),
@@ -41,12 +33,9 @@ export const runParametersSchema = z.record(
 );
 
 /**
- * One thing a plan runs its scenarios against, and the values that target
- * alone runs with.
- *
- * The parameters are what makes a comparison run: two targets may name the
- * same agent with different values, and the platform runs and reports each one
- * on its own.
+ * One thing a plan runs its scenarios against, and the values it alone
+ * runs with. Parameters make a comparison run: two targets may name the
+ * same agent with different values, each run and reported on its own.
  */
 export const runPlanTargetSchema = z.object({
   type: z
@@ -67,12 +56,9 @@ export const runPlanTargetSchema = z.object({
 });
 
 /**
- * One target as `/api/v1` carries it.
- *
- * The tool input spells the per-target values `parameters`, beside the
- * run-level `parameters` an agent already knows. The REST body spells them
- * `runParameters`, because a target holds the values it runs with rather than
- * the values of a run.
+ * One target as `/api/v1` carries it. Tool input spells per-target
+ * values `parameters`, beside run-level `parameters`; the REST body
+ * spells them `runParameters` since a target holds the values it runs with.
  */
 export interface RunPlanTargetWire {
   type: z.infer<typeof runPlanTargetSchema>["type"];
@@ -81,9 +67,7 @@ export interface RunPlanTargetWire {
 }
 
 /** The targets of a tool call, as the REST body carries them. */
-export function toWireTargets(
-  targets: z.infer<typeof runPlanTargetSchema>[],
-): RunPlanTargetWire[] {
+export function toWireTargets(targets: z.infer<typeof runPlanTargetSchema>[]): RunPlanTargetWire[] {
   return targets.map((target) => ({
     type: target.type,
     referenceId: target.referenceId,

package/src/schemas/suite-fields.ts

@@ -1,14 +1,7 @@
 import { z } from "zod";
 
-/**
- * Typed inputs for the fields a test suite declares, the evaluators attached
- * to a suite or a run plan, and the values a scenario carries per field.
- *
- * Each one mirrors the zod the platform validates the REST body with
- * (`suiteFieldDefinitionsSchema`, `evaluatorAttachmentsSchema` and
- * `scenarioFieldValuesSchema` on the server side), so an agent is told what
- * is accepted before the request goes out rather than after.
- */
+// Typed inputs for suite fields, evaluators, and scenario values that mirror the
+// server-side validation schemas so agents know what's accepted before sending.
 
 /** The value types a field can hold. */
 export const SUITE_FIELD_TYPES = ["text", "number", "boolean"] as const;
@@ -19,16 +12,11 @@ export const suiteFieldSchema = z.object({
     .string()
     .min(1)
     .max(64)
-    .regex(
-      /^[a-z][a-z0-9_]*$/,
-      "Lowercase letters, digits and underscores, starting with a letter",
-    )
+    .regex(/^[a-z][a-z0-9_]*$/, "Lowercase letters, digits and underscores, starting with a letter")
     .describe(
       "The field name, as scenarios and evaluator mappings address it, for example golden_sql. Lowercase letters, digits and underscores, starting with a letter. situation, criteria, name, input and output are reserved.",
     ),
-  type: z
-    .enum(SUITE_FIELD_TYPES)
-    .describe("The value type every scenario carries for this field."),
+  type: z.enum(SUITE_FIELD_TYPES).describe("The value type every scenario carries for this field."),
 });
 
 /** The fields a test suite declares, in the order the platform shows them. */
@@ -40,11 +28,7 @@ export const suiteFieldsSchema = z
   );
 
 /** The sources an evaluator input can read from. */
-export const SCENARIO_MAPPING_SOURCE_IDS = [
-  "conversation",
-  "scenario",
-  "trace",
-] as const;
+export const SCENARIO_MAPPING_SOURCE_IDS = ["conversation", "scenario", "trace"] as const;
 
 /** Where one evaluator input reads its value: a source path or a literal. */
 export const scenarioMappingSchema = z
@@ -130,8 +114,7 @@ export interface EvaluatorAttachmentWire {
   mappings: Record<string, ScenarioMapping>;
 }
 
-const newAttachmentId = (): string =>
-  `att_${crypto.randomUUID().replace(/-/g, "").slice(0, 21)}`;
+const newAttachmentId = (): string => `att_${crypto.randomUUID().replace(/-/g, "").slice(0, 21)}`;
 
 /**
  * The attachments of a tool call, as the REST body carries them: a missing

package/src/schemas/triggers.ts

@@ -0,0 +1,365 @@
+import { z } from "zod";
+
+/** The shape of an automation on the `/api/v1/triggers` surface, stated once for
+ *  the tool registrations and the API client. Every type is inferred from its
+ *  schema, so what the API sends and what a caller reads cannot drift. */
+
+export const triggerActionSchema = z.enum([
+  "SEND_EMAIL",
+  "SEND_SLACK_MESSAGE",
+  "SEND_WEBHOOK",
+  "ADD_TO_DATASET",
+  "ADD_TO_ANNOTATION_QUEUE",
+]);
+export const alertTypeSchema = z.enum(["CRITICAL", "WARNING", "INFO"]);
+
+/** The delivery configuration each channel reads, stated per channel so an agent
+ *  can configure one without a round trip. Each passes unknown fields through:
+ *  every Slack field is optional, so a webhook destination would otherwise read
+ *  as an empty Slack one and be sent as nothing. */
+const emailActionParamsSchema = z
+  .object({
+    members: z
+      .array(z.string())
+      .min(1)
+      .describe("Who receives the email. Any address, not only teammates."),
+  })
+  .passthrough();
+
+const slackActionParamsSchema = z
+  .object({
+    slackIntegrationId: z
+      .string()
+      .optional()
+      .describe(
+        "The Slack connection to post through (an organization connection or one of this project's; they are listed in LangWatch under Settings, Integrations, Slack). A bot connection also needs `slackChannelId`; a webhook connection needs nothing else. Preferred over `slackWebhook` and `slackBotToken`.",
+      ),
+    slackDelivery: z
+      .enum(["webhook", "bot"])
+      .optional()
+      .describe(
+        "How the message reaches Slack. `webhook` posts to an incoming webhook URL, `bot` posts as the LangWatch Slack app. With `slackIntegrationId` it follows the connection's kind. Absent without a connection means `webhook`.",
+      ),
+    slackWebhook: z
+      .string()
+      .optional()
+      .describe(
+        "Legacy, accepted for one release: an incoming webhook URL (https://hooks.slack.com/...). It is stored as a Slack connection and the automation keeps only the connection id. Send `slackIntegrationId` instead.",
+      ),
+    slackChannelId: z
+      .string()
+      .optional()
+      .describe("The channel the bot posts in, for a bot connection or `bot` delivery."),
+    slackBotToken: z
+      .string()
+      .optional()
+      .describe(
+        "Legacy, accepted for one release: a bot token, stored as a Slack connection. It never reads back. Send `slackIntegrationId` instead.",
+      ),
+    slackBotTokenSet: z
+      .boolean()
+      .optional()
+      .describe(
+        "Legacy. Read: whether an automation not yet moved to a connection stores its own bot token. Write: true keeps it.",
+      ),
+  })
+  .passthrough();
+
+const webhookActionParamsSchema = z
+  .object({
+    url: z.string().describe("Where the request goes. https only, and not a private host."),
+    method: z.enum(["POST", "PUT", "PATCH"]).optional(),
+    headers: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Static headers sent with every delivery. The values are credentials: they read back as [redacted], and sending [redacted] back keeps the stored ones. Changing `url` means sending the values again in the same call.",
+      ),
+    bodyTemplate: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "A Liquid template for the JSON body. Absent sends the standard LangWatch envelope.",
+      ),
+    signingSecret: z
+      .string()
+      .nullable()
+      .optional()
+      .describe("Signs every delivery so the receiver can verify it."),
+  })
+  .passthrough();
+
+const datasetActionParamsSchema = z
+  .object({
+    datasetId: z.string().describe("The dataset matched traces are appended to."),
+    datasetMapping: z
+      .object({
+        mapping: z.record(z.string(), z.unknown()),
+        expansions: z.array(z.string()).optional(),
+      })
+      .describe("How a trace becomes a row in that dataset."),
+  })
+  .passthrough();
+
+const annotationQueueActionParamsSchema = z
+  .object({
+    annotators: z
+      .array(z.object({ id: z.string(), name: z.string() }))
+      .min(1)
+      .describe("Who the queued items go to."),
+  })
+  .passthrough();
+
+export const actionParamsSchema = z.union([
+  emailActionParamsSchema,
+  slackActionParamsSchema,
+  webhookActionParamsSchema,
+  datasetActionParamsSchema,
+  annotationQueueActionParamsSchema,
+]);
+
+/** The write-side Slack shape: a redacted read round-trips, but a WRITE with no
+ *  destination cannot deliver, so it is refused with the field named. A
+ *  connection decides its own kind; without one, the legacy fields need a
+ *  webhook URL, or a channel and a token. */
+const slackActionParamsWriteSchema = slackActionParamsSchema.superRefine((params, ctx) => {
+  const delivery = params.slackDelivery ?? "webhook";
+  if (delivery === "bot" && !params.slackChannelId) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackChannelId"],
+      message: params.slackIntegrationId
+        ? "a bot connection needs the channel to post in"
+        : "bot delivery needs the channel to post in",
+    });
+  }
+  if (params.slackIntegrationId) return;
+  if (delivery === "webhook" && !params.slackWebhook) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackIntegrationId"],
+      message: "name the Slack connection to post through",
+    });
+  }
+  if (delivery === "bot" && !params.slackBotToken && params.slackBotTokenSet !== true) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackIntegrationId"],
+      message: "bot delivery needs the Slack connection to post through",
+    });
+  }
+});
+
+const ACTION_PARAMS_SCHEMA_BY_ACTION: Partial<Record<string, z.ZodTypeAny>> = {
+  SEND_EMAIL: emailActionParamsSchema,
+  SEND_SLACK_MESSAGE: slackActionParamsWriteSchema,
+  SEND_WEBHOOK: webhookActionParamsSchema,
+  ADD_TO_DATASET: datasetActionParamsSchema,
+  ADD_TO_ANNOTATION_QUEUE: annotationQueueActionParamsSchema,
+};
+
+/** A WRITE's `actionParams` is bound to the channel named in `action`, or a
+ *  `SEND_WEBHOOK` with `{}` slips through the all-optional Slack shape and is
+ *  refused server-side with worse words. An action this build does not know
+ *  validates against the loose union, the tolerance reads keep. */
+export function validateActionParamsForAction({
+  action,
+  actionParams,
+}: {
+  action: string;
+  actionParams: unknown;
+}): { ok: true } | { ok: false; message: string } {
+  const schema = ACTION_PARAMS_SCHEMA_BY_ACTION[action] ?? actionParamsSchema;
+  const parsed = schema.safeParse(actionParams);
+  if (parsed.success) return { ok: true };
+  const issues = parsed.error.issues
+    .map((issue) => `${issue.path.join(".") || "(actionParams)"}: ${issue.message}`)
+    .join("; ");
+  return {
+    ok: false,
+    message: `actionParams does not fit ${action} — ${issues}`,
+  };
+}
+
+/** How `filters` is written. A keyed field sent flat never matches, so each
+ *  keyed shape is spelled out; see the `/api/v1/triggers` 422 for the refusal. */
+export const TRIGGER_FILTERS_DESCRIPTION = [
+  "Trace conditions as a JSON object string.",
+  'Unkeyed fields take a list of values: {"traces.error":["true"]}.',
+  'Keyed fields nest a key above the list. evaluations.* is keyed by the MONITOR id (the `id` from `platform_list_monitors` / GET /api/v1/monitors, not its evaluatorId): {"evaluations.passed":{"<monitorId>":["false"]}}.',
+  'metadata.value is keyed by the metadata key: {"metadata.value":{"<key>":["true"]}}.',
+  "A keyed field sent as a bare list, or keyed by anything but a monitor id, is refused.",
+].join(" ");
+
+export const TRIGGER_FILTER_QUERY_DESCRIPTION = [
+  "Trace query in the syntax the traces view uses; the alternative to `filters`, and it supersedes them.",
+  'Examples: status:error · evaluator:"<evaluator name>" AND evaluatorVerdict:fail · trace.attribute.<key>:<value>.',
+].join(" ");
+
+/** Stated on the create tool: Slack needs a connection or it never posts. */
+export const SLACK_DELIVERY_NOTE =
+  'For SEND_SLACK_MESSAGE, send {"slackIntegrationId":"<connection id>"} for a webhook connection, or {"slackIntegrationId":"<connection id>","slackChannelId":"C..."} for a bot connection. Slack connections are listed and added in LangWatch under Settings, Integrations, Slack (organization-wide or for one project); they are also listed by GET /api/v1/slack-connections and `langwatch slack-connection list`, or ask the user for the id. slackIntegrationId is preferred: a legacy {"slackWebhook":"https://hooks.slack.com/..."} or {"slackDelivery":"bot","slackBotToken":"xoxb-...","slackChannelId":"C..."} is still accepted for one release and is stored as a connection. A Slack automation with no connection will never post.';
+
+export const graphAlertSchema = z
+  .object({
+    seriesName: z.string().describe("The series on the graph to watch."),
+    operator: z.enum(["gt", "lt", "gte", "lte", "eq"]),
+    threshold: z.number(),
+    timePeriod: z
+      .union([
+        z.literal(1),
+        z.literal(5),
+        z.literal(15),
+        z.literal(30),
+        z.literal(60),
+        z.literal(1440),
+      ])
+      .describe("The window, in minutes, the series is read over."),
+  })
+  .describe("The rule an alert fires by. Send it with `customGraphId` and `alertType`.");
+
+/** What a scheduled report renders and when. Structured, not a loose record: an
+ *  agent that cannot see the field names guesses them, and a guess is a 422.
+ *  The server holds a write to this same shape, so looseness only delays it. */
+export const reportSchema = z
+  .object({
+    source: z
+      .discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("dashboard"),
+          dashboardId: z.string(),
+        }),
+        z.object({
+          kind: z.literal("customGraph"),
+          customGraphId: z.string(),
+        }),
+        z.object({
+          kind: z.literal("traceQuery"),
+          filters: z.record(z.string(), z.unknown()).optional(),
+          metric: z.string().optional(),
+          topN: z.number().int().min(1).max(100).optional(),
+        }),
+      ])
+      .describe("What the report renders: a dashboard, one graph, or a table of traces."),
+    schedule: z
+      .object({
+        cron: z
+          .string()
+          .describe(
+            'A 5-field cron expression (minute hour day-of-month month day-of-week), for example "0 9 * * 1". It can send at most every 15 minutes.',
+          ),
+        timezone: z.string().describe('An IANA timezone, for example "Europe/Amsterdam" or "UTC".'),
+      })
+      .describe("When it sends."),
+    compareToPrevious: z
+      .boolean()
+      .optional()
+      .describe("Include a this-period-versus-last comparison."),
+  })
+  .describe(
+    "What a scheduled report renders and when. Send it with a channel that can carry a message: email or Slack.",
+  );
+
+export const templatesSchema = z
+  .object({
+    slackTemplateType: z.enum(["string", "block_kit"]).nullable().optional(),
+    slackTemplate: z.string().nullable().optional(),
+    emailSubjectTemplate: z.string().nullable().optional(),
+    emailBodyTemplate: z.string().nullable().optional(),
+  })
+  .describe(
+    "The Liquid templates the message is rendered from. Absent fields render the LangWatch default.",
+  );
+
+export const notificationCadenceSchema = z
+  .enum(["immediate", "5min_digest", "15min_digest", "hourly_digest"])
+  .describe(
+    "How often a notification automation may send. A new one starts on a five-minute digest.",
+  );
+
+/**
+ * What a read answers with. Permissive on purpose: an MCP client talks to whichever LangWatch it
+ * is pointed at, so an unknown field is carried through and a field a deployment does not send
+ * yet is absent rather than fatal.
+ */
+export const triggerSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    action: z.string(),
+    /** Where it delivers. The rule it fires by is stated separately, below,
+     *  the same way a write states it. */
+    actionParams: z.record(z.string(), z.unknown()).default({}),
+    graphAlert: graphAlertSchema.nullable().optional(),
+    // A read stays tolerant of a deployment that words this differently; a
+    // write is held to `reportSchema`.
+    report: z.record(z.string(), z.unknown()).nullable().optional(),
+    filters: z.record(z.string(), z.unknown()).default({}),
+    filterQuery: z.string().nullable().optional(),
+    kind: z.string().optional(),
+    customGraphId: z.string().nullable().optional(),
+    notificationCadence: z.string().nullable().optional(),
+    traceDebounceMs: z.number().nullable().optional(),
+    templates: z.record(z.string(), z.unknown()).optional(),
+    active: z.boolean(),
+    message: z.string().nullable(),
+    alertType: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    platformUrl: z.string().optional(),
+  })
+  .passthrough();
+
+const triggerFireSchema = z
+  .object({
+    id: z.string(),
+    triggerId: z.string(),
+    customGraphId: z.string().nullable(),
+    firedAt: z.string(),
+    resolvedAt: z.string().nullable(),
+  })
+  .passthrough();
+
+/** A page of fires: `{ fires, nextCursor }`, or the bare array an older
+ *  deployment answers with, which has no next page. */
+export const triggerFirePageSchema = z.union([
+  z.array(triggerFireSchema).transform((fires) => ({ fires, nextCursor: null })),
+  z
+    .object({
+      fires: z.array(triggerFireSchema).optional(),
+      data: z.array(triggerFireSchema).optional(),
+      nextCursor: z.string().nullable().optional(),
+    })
+    .transform(({ fires, data, nextCursor }) => ({
+      fires: fires ?? data ?? [],
+      nextCursor: nextCursor ?? null,
+    })),
+]);
+
+export const testFireResultSchema = z
+  .object({
+    channel: z.string(),
+    recipientCount: z.number(),
+    usedDefault: z.boolean(),
+    missingVariables: z.array(z.string()).default([]),
+    errors: z.array(z.string()).default([]),
+    httpStatus: z.number().optional(),
+  })
+  .passthrough();
+
+export const deletedTriggerSchema = z.object({
+  id: z.string(),
+  deleted: z.boolean(),
+});
+
+export type Trigger = z.infer<typeof triggerSchema>;
+export type TriggerFirePage = z.infer<typeof triggerFirePageSchema>;
+export type TestFireResult = z.infer<typeof testFireResultSchema>;
+export type TriggerAction = z.infer<typeof triggerActionSchema>;
+export type TriggerAlertType = z.infer<typeof alertTypeSchema>;
+export type TriggerActionParams = z.infer<typeof actionParamsSchema>;
+export type GraphAlertRule = z.infer<typeof graphAlertSchema>;
+export type ReportRule = z.infer<typeof reportSchema>;
+export type TriggerTemplates = z.infer<typeof templatesSchema>;
+export type NotificationCadence = z.infer<typeof notificationCadenceSchema>;