@langwatch/mcp-server 1.0.0 → 2.1.0

package/src/langwatch-api.ts

@@ -82,25 +82,48 @@ export interface PromptSummary {
   version?: number;
 }
 
+export interface PromptTag {
+  name: string;
+  versionId: string;
+}
+
+export type PromptFieldList = Array<{ identifier: string; type: string }>;
+
+/**
+ * A single versioned prompt payload. `GET /api/prompts/:id` returns the
+ * requested version's data flattened to the top level (merged with the base
+ * prompt data), and `GET /api/prompts/:id/versions` returns an array of
+ * entries in this same shape — there is no nested `versions` array on the
+ * detail response.
+ */
 export interface PromptVersion {
+  versionId?: string;
   version?: number;
-  commitMessage?: string;
+  commitMessage?: string | null;
   model?: string;
+  /** Legacy single-text prompt body. */
+  prompt?: string;
   messages?: Array<{ role: string; content: string }>;
+  temperature?: number;
+  maxTokens?: number;
+  responseFormat?: Record<string, unknown> | null;
+  /** Runtime parameters: an object map of name -> JSON value, not an array. */
+  parameters?: Record<string, unknown>;
+  inputs?: PromptFieldList;
+  outputs?: PromptFieldList;
+  /** All tags on the prompt; each names the version it currently points to. */
+  tags?: PromptTag[];
 }
 
-export interface PromptDetailResponse extends PromptSummary {
-  versions?: PromptVersion[];
-  model?: string;
-  messages?: Array<{ role: string; content: string }>;
-  prompt?: Array<{ role: string; content: string }>;
-}
+export interface PromptDetailResponse extends PromptSummary, PromptVersion {}
 
 export interface PromptMutationResponse {
   id?: string;
   handle?: string;
   name?: string;
   latestVersionNumber?: number;
+  versionId?: string;
+  tags?: string[];
 }
 
 // --- HTTP client ---
@@ -153,8 +176,10 @@ interface ParsedErrorBody {
 const VALID_FAULTS: readonly HandledErrorFault[] = ["customer", "platform", "provider"];
 
 /**
- * Parses an error response body as a handled-error envelope. Accepts both the
- * REST shape (`{ error: "<code>", message, tips?, docsUrl?, fault? }`) and the
+ * Parses an error response body as a handled-error envelope. Accepts three
+ * shapes: the canonical v1 envelope
+ * (`{ error: { type, code, message, meta?, trace_id } }`), the legacy REST
+ * shape (`{ error: "<code>", message, tips?, docsUrl?, fault? }`) and the
  * serialized tRPC shape (`{ code, message?, tips?, docsUrl?, fault?, ... }`).
  * Returns an empty object when the body is not a recognizable error envelope.
  */
@@ -164,7 +189,16 @@ function parseErrorBody(responseBody: string): ParsedErrorBody {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       return {};
     }
-    const body = parsed as Record<string, unknown>;
+    const envelope = parsed as Record<string, unknown>;
+    // The canonical v1 envelope nests everything under `error`. Read the
+    // nested object as the body so one parser serves both generations.
+    const nested =
+      typeof envelope.error === "object" &&
+      envelope.error !== null &&
+      !Array.isArray(envelope.error)
+        ? (envelope.error as Record<string, unknown>)
+        : null;
+    const body = nested ?? envelope;
     // Prefer `code` (the domain discriminant) over `error` — the
     // packages/api unversioned envelope uses `error` for the HTTP status
     // text ("Not Found") while `code` holds the real code.
@@ -294,14 +328,20 @@ export async function makeRequest(
   return response.json();
 }
 
-/** Searches traces with optional filters and pagination. */
+/**
+ * Searches traces with optional filters and pagination.
+ *
+ * Paging is by `scrollId` only: pass the one the previous response returned,
+ * and stop when a response carries none. `pageOffset` used to be accepted here
+ * but was never read by the server, so an offset walk silently re-served the
+ * first page; it is rejected at the boundary now (#6808).
+ */
 export async function searchTraces(params: {
   query?: string;
   filters?: Record<string, string[]>;
   startDate: number;
   endDate: number;
   pageSize?: number;
-  pageOffset?: number;
   scrollId?: string;
   format?: "digest" | "json";
 }): Promise<SearchTracesResponse> {
@@ -365,6 +405,16 @@ export async function getPrompt(
   ) as Promise<PromptDetailResponse>;
 }
 
+/** Lists all versions of a prompt (versioned data only). */
+export async function getPromptVersions(
+  idOrHandle: string
+): Promise<PromptVersion[]> {
+  return makeRequest(
+    "GET",
+    `/api/prompts/${encodeURIComponent(idOrHandle)}/versions`
+  ) as Promise<PromptVersion[]>;
+}
+
 /** Creates a new prompt. */
 export async function createPrompt(data: {
   handle: string;

package/src/schemas/index.ts

@@ -2,3 +2,8 @@ export { filterFields, type FilterFieldInfo } from "./filter-fields.js";
 export { analyticsMetrics, type MetricInfo } from "./analytics-metrics.js";
 export { analyticsGroups, type GroupByInfo } from "./analytics-groups.js";
 export { createDatasetSchema } from "./create-dataset.js";
+export {
+  runParametersSchema,
+  runPlanScopeSchema,
+  runPlanTargetSchema,
+} from "./run-plan.js";

package/src/schemas/run-plan.ts

@@ -0,0 +1,92 @@
+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.
+ */
+
+/** 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("test_suites"),
+      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
+    .object({
+      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",
+    ),
+  z
+    .object({ mode: z.literal("scenarios") })
+    .describe("The scenarios named in scenarioIds, picked by hand"),
+]);
+
+/** The values a run supplies for the parameters its scenarios declare. */
+export const runParametersSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean()]),
+);
+
+/**
+ * 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.
+ */
+export const runPlanTargetSchema = z.object({
+  type: z
+    .enum(["connected", "prompt", "http", "code", "workflow"])
+    .describe(
+      "What kind of thing the target is. A connected agent is one that registered itself from code with connectAgent (TypeScript) or connect_agent (Python).",
+    ),
+  referenceId: z
+    .string()
+    .describe(
+      "The ID of the prompt, agent or workflow to run against. A connected agent may also be named as <name>@<environment>, for example support-agent@production; the platform resolves it.",
+    ),
+  parameters: runParametersSchema
+    .optional()
+    .describe(
+      "Parameter values this target alone runs with, by name. They override the run-level parameters for this target. Name the same agent twice with different values here to compare it on two models.",
+    ),
+});
+
+/**
+ * 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.
+ */
+export interface RunPlanTargetWire {
+  type: z.infer<typeof runPlanTargetSchema>["type"];
+  referenceId: string;
+  runParameters?: z.infer<typeof runParametersSchema>;
+}
+
+/** The targets of a tool call, as the REST body carries them. */
+export function toWireTargets(
+  targets: z.infer<typeof runPlanTargetSchema>[],
+): RunPlanTargetWire[] {
+  return targets.map((target) => ({
+    type: target.type,
+    referenceId: target.referenceId,
+    ...(target.parameters ? { runParameters: target.parameters } : {}),
+  }));
+}

package/src/schemas/suite-fields.ts

@@ -0,0 +1,149 @@
+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.
+ */
+
+/** The value types a field can hold. */
+export const SUITE_FIELD_TYPES = ["text", "number", "boolean"] as const;
+
+/** One field a test suite declares. */
+export const suiteFieldSchema = z.object({
+  identifier: z
+    .string()
+    .min(1)
+    .max(64)
+    .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."),
+});
+
+/** The fields a test suite declares, in the order the platform shows them. */
+export const suiteFieldsSchema = z
+  .array(suiteFieldSchema)
+  .max(30)
+  .describe(
+    "The fields the test suite declares, in order. Up to 30. Every scenario filed in the suite carries one value per field, and an evaluator attached to the suite reads them through its mappings.",
+  );
+
+/** The sources an evaluator input can read from. */
+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
+  .discriminatedUnion("type", [
+    z.object({
+      type: z.literal("source"),
+      sourceId: z
+        .enum(SCENARIO_MAPPING_SOURCE_IDS)
+        .describe(
+          "conversation, scenario or trace. See discover_schema({ category: 'scenarios' }) for the paths each one offers.",
+        ),
+      path: z
+        .array(z.string().min(1).max(256))
+        .min(1)
+        .max(3)
+        .describe(
+          "The path inside the source. conversation: [first_user_message] | [last_agent_message] | [transcript] | [messages]. scenario: [situation] | [criteria] | [fields, <identifier>]. trace: [contexts] | [tool_calls, <toolName>, input|output].",
+        ),
+    }),
+    z.object({
+      type: z.literal("value"),
+      value: z.string().max(65_536).describe("A literal the input reads."),
+    }),
+  ])
+  .describe(
+    "Where one evaluator input reads its value: a path into the conversation, the scenario or the trace, or a literal value.",
+  );
+
+/** One evaluator attached to a test suite or a run plan. */
+export const evaluatorAttachmentSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe(
+      "The attachment id, stable across edits. Leave it out on a new attachment and one is generated.",
+    ),
+  evaluatorId: z
+    .string()
+    .min(1)
+    .describe(
+      "The id of the saved evaluator to run. Read it from platform_list_evaluators or platform_get_evaluator.",
+    ),
+  required: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether a failing result fails the scenario. Defaults to true. A score-only evaluator reports and never gates, whatever this says.",
+    ),
+  mappings: z
+    .record(z.string().min(1).max(128), scenarioMappingSchema)
+    .describe(
+      "Where each evaluator input reads its value, keyed by input name. Read the inputs from platform_get_evaluator. A required input with no mapping makes the platform refuse the run until it is set.",
+    ),
+});
+
+/** The evaluators attached to a test suite or a run plan. */
+export const evaluatorAttachmentsSchema = z
+  .array(evaluatorAttachmentSchema)
+  .max(20)
+  .describe(
+    "The evaluators that run after every scenario run, with their mappings. Up to 20. A required evaluator that fails fails the scenario; a score-only one reports beside the verdict.",
+  );
+
+/** The values a scenario carries for the fields its suite declares. */
+export const scenarioFieldValuesSchema = z
+  .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+  .describe(
+    "The scenario's value for each field its test suite declares, by identifier, for example { golden_sql: 'SELECT ...' }. A text field takes a string, a number field a number and a boolean field true or false. A field the suite does not declare is refused. On update, an empty object clears the values.",
+  );
+
+export type SuiteField = z.infer<typeof suiteFieldSchema>;
+export type ScenarioMapping = z.infer<typeof scenarioMappingSchema>;
+export type EvaluatorAttachmentInput = z.infer<typeof evaluatorAttachmentSchema>;
+export type ScenarioFieldValues = z.infer<typeof scenarioFieldValuesSchema>;
+
+/** One attachment as the REST surface carries it: id and gate settled. */
+export interface EvaluatorAttachmentWire {
+  id: string;
+  evaluatorId: string;
+  required: boolean;
+  mappings: Record<string, ScenarioMapping>;
+}
+
+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
+ * id is generated and a missing gate defaults to required.
+ */
+export function toWireAttachments(
+  attachments: EvaluatorAttachmentInput[],
+): EvaluatorAttachmentWire[] {
+  return attachments.map((attachment) => ({
+    id: attachment.id ?? newAttachmentId(),
+    evaluatorId: attachment.evaluatorId,
+    required: attachment.required ?? true,
+    mappings: attachment.mappings,
+  }));
+}

package/src/tools/archive-run-plan.ts

@@ -0,0 +1,12 @@
+import { archiveRunPlan as apiArchiveRunPlan } from "../langwatch-api-run-plans.js";
+
+/**
+ * Handles the platform_archive_run_plan MCP tool invocation.
+ */
+export async function handleArchiveRunPlan(params: {
+  id: string;
+}): Promise<string> {
+  const result = await apiArchiveRunPlan(params.id);
+
+  return `Run plan ${result.id} is archived. Its past runs stay readable, and the name is free for a new plan.`;
+}

package/src/tools/archive-test-suite.ts

@@ -0,0 +1,12 @@
+import { archiveTestSuite as apiArchiveTestSuite } from "../langwatch-api-test-suites.js";
+
+/**
+ * Handles the platform_archive_test_suite MCP tool invocation.
+ */
+export async function handleArchiveTestSuite(params: {
+  id: string;
+}): Promise<string> {
+  const result = await apiArchiveTestSuite(params.id);
+
+  return `Test suite ${result.id} is archived, and the scenarios filed in it are archived with it.`;
+}

package/src/tools/create-scenario.ts

@@ -1,4 +1,6 @@
 import { createScenario as apiCreateScenario } from "../langwatch-api-scenarios.js";
+import type { ScenarioFieldValues } from "../schemas/suite-fields.js";
+import { formatScenarioFields } from "./format-scenario.js";
 
 /**
  * Handles the platform_create_scenario MCP tool invocation.
@@ -11,6 +13,8 @@ export async function handleCreateScenario(params: {
   situation: string;
   criteria?: string[];
   labels?: string[];
+  testSuiteId?: string | null;
+  fields?: ScenarioFieldValues;
 }): Promise<string> {
   const result = await apiCreateScenario(params);
 
@@ -25,6 +29,10 @@ export async function handleCreateScenario(params: {
   if (Array.isArray(result.labels) && result.labels.length > 0) {
     lines.push(`**Labels**: ${result.labels.join(", ")}`);
   }
+  if (result.testSuiteId) {
+    lines.push(`**Test suite**: ${result.testSuiteId}`);
+  }
+  lines.push(...formatScenarioFields(result.fields));
 
   return lines.join("\n");
 }

package/src/tools/create-test-suite.ts

@@ -0,0 +1,43 @@
+import { createTestSuite as apiCreateTestSuite } from "../langwatch-api-test-suites.js";
+import {
+  type EvaluatorAttachmentInput,
+  type SuiteField,
+  toWireAttachments,
+} from "../schemas/suite-fields.js";
+import {
+  formatEvaluatorAttachments,
+  formatSuiteFields,
+} from "./format-suite-details.js";
+
+/**
+ * Handles the platform_create_test_suite MCP tool invocation.
+ */
+export async function handleCreateTestSuite(params: {
+  name: string;
+  fields?: SuiteField[];
+  evaluators?: EvaluatorAttachmentInput[];
+}): Promise<string> {
+  const suite = await apiCreateTestSuite({
+    name: params.name,
+    ...(params.fields !== undefined ? { fields: params.fields } : {}),
+    ...(params.evaluators !== undefined
+      ? { evaluators: toWireAttachments(params.evaluators) }
+      : {}),
+  });
+
+  return [
+    `Test suite "${suite.name}" created.`,
+    "",
+    `**ID**: ${suite.id}`,
+    `**Slug**: ${suite.slug}`,
+    `**View**: ${suite.platformUrl}`,
+    ...formatSuiteFields(suite.fields),
+    ...formatEvaluatorAttachments(suite.evaluators),
+    "",
+    `> File scenarios in it with \`platform_create_scenario\` or \`platform_update_scenario\`, passing testSuiteId \`${suite.id}\`${
+      suite.fields && suite.fields.length > 0
+        ? ` and a value per field under \`fields\``
+        : ""
+    }.`,
+  ].join("\n");
+}

package/src/tools/discover-evaluator-schema.ts

@@ -1,5 +1,5 @@
-import { AVAILABLE_EVALUATORS } from "../../../langevals/ts-integration/evaluators.generated.js";
-import type { EvaluatorDefinition, EvaluatorTypes } from "../../../langevals/ts-integration/evaluators.generated.js";
+import { AVAILABLE_EVALUATORS } from "../../../../services/langevals/ts-integration/evaluators.generated.js";
+import type { EvaluatorDefinition, EvaluatorTypes } from "../../../../services/langevals/ts-integration/evaluators.generated.js";
 
 /**
  * Formats evaluator schema information for the discover_schema tool.

package/src/tools/discover-scenario-schema.ts

@@ -20,6 +20,60 @@ export function formatScenarioSchema(): string {
   lines.push(
     '- **labels** (array of strings): Tags for organizing scenarios (e.g., "auth", "happy-path", "edge-case")',
   );
+  lines.push(
+    "- **testSuiteId** (string): The test suite the scenario is filed in. Every project has a Default suite.",
+  );
+  lines.push(
+    '- **fields** (object): The scenario\'s value for each field its test suite declares, by identifier (e.g. { "golden_sql": "SELECT ..." }). A text field takes a string, a number field a number, a boolean field true or false. A field the suite does not declare is refused. A blank value skips the evaluators that read it.',
+  );
+
+  lines.push("\n## Test Suite Fields\n");
+  lines.push(
+    "A test suite reads like a dataset: it declares typed fields beyond the situation and the criteria, and every scenario filed in it carries one value per field. Declare them with `platform_create_test_suite` or `platform_update_test_suite`:",
+  );
+  lines.push("```json");
+  lines.push('{ "fields": [{ "identifier": "golden_sql", "type": "text" }, { "identifier": "row_limit", "type": "number" }] }');
+  lines.push("```");
+  lines.push(
+    "- **identifier**: lowercase letters, digits and underscores, starting with a letter. situation, criteria, name, input and output are reserved.",
+  );
+  lines.push("- **type**: text, number or boolean.");
+  lines.push(
+    "- On update, the list replaces the one the suite holds. A field an attached evaluator still reads cannot be removed.",
+  );
+
+  lines.push("\n## Evaluator Attachments\n");
+  lines.push(
+    "A saved evaluator attaches to a test suite (and, for checks that read only the conversation or the trace, to a run plan). After every scenario run the platform runs it and stores one result per evaluator on the run. A **required** pass/fail evaluator that fails fails the scenario; a score-only evaluator reports beside the verdict and never gates.",
+  );
+  lines.push("```json");
+  lines.push('{ "evaluators": [{');
+  lines.push('  "evaluatorId": "<id from platform_list_evaluators>",');
+  lines.push('  "required": true,');
+  lines.push('  "mappings": {');
+  lines.push('    "output": { "type": "source", "sourceId": "trace", "path": ["tool_calls", "run_sql", "input"] },');
+  lines.push('    "expected_output": { "type": "source", "sourceId": "scenario", "path": ["fields", "golden_sql"] }');
+  lines.push("  }");
+  lines.push("}] }");
+  lines.push("```");
+  lines.push(
+    "Each mapping names where one evaluator input reads its value. Read the evaluator's inputs from `platform_get_evaluator`; every required input needs a mapping before a run. The paths:",
+  );
+  lines.push(
+    "- **conversation**: `[\"first_user_message\"]`, `[\"last_agent_message\"]`, `[\"transcript\"]` (role: content lines) or `[\"messages\"]` (JSON)",
+  );
+  lines.push(
+    "- **scenario**: `[\"situation\"]`, `[\"criteria\"]` or `[\"fields\", \"<identifier>\"]` (a field the suite declares; not on a run plan)",
+  );
+  lines.push(
+    "- **trace**: `[\"contexts\"]` (the retrieved contexts of the run's traces) or `[\"tool_calls\", \"<toolName>\", \"input\" | \"output\"]` (the last matching tool call)",
+  );
+  lines.push(
+    '- a literal: `{ "type": "value", "value": "..." }`',
+  );
+  lines.push(
+    "A scenario whose field is blank skips the evaluators that read it, with a reason. A trace with no such tool call or no contexts fails them, with a reason. The results come back under `results.evaluations` on `platform_get_simulation_run`.",
+  );
 
   lines.push("\n## Writing a Good Situation\n");
   lines.push(

package/src/tools/format-run-plan.ts

@@ -0,0 +1,68 @@
+import type {
+  RunPlanRunResult,
+  RunPlanScope,
+} from "../langwatch-api-run-plans.js";
+
+/**
+ * The digest every run of a plan returns, whichever tool started it.
+ *
+ * It says which plan ran and whether the run created it or joined one that
+ * already carried the name, because that is the difference between a new plan
+ * and a plan whose configuration this run just replaced.
+ */
+export function formatRunPlanRun(result: RunPlanRunResult): string {
+  const lines: string[] = [];
+
+  lines.push(
+    result.created
+      ? `Run plan "${result.planName}" created and started.`
+      : `Run plan "${result.planName}" started with the configuration of this run.`,
+  );
+  lines.push("");
+  lines.push(`**Plan**: ${result.planName} (${result.runPlanId})`);
+  lines.push(`**Batch Run ID**: ${result.batchRunId}`);
+  lines.push(`**Set ID**: ${result.setId}`);
+  lines.push(`**Jobs**: ${result.jobCount}`);
+
+  if (result.skippedArchived.scenarios.length > 0) {
+    lines.push(
+      `**Skipped archived scenarios**: ${result.skippedArchived.scenarios.join(", ")}`,
+    );
+  }
+  if (result.skippedArchived.targets.length > 0) {
+    lines.push(
+      `**Skipped archived targets**: ${result.skippedArchived.targets.join(", ")}`,
+    );
+  }
+
+  lines.push(`**View**: ${result.platformUrl}`);
+  lines.push("");
+  lines.push(
+    "> Use `platform_list_simulation_runs` with the batch run ID to read the results.",
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * One line saying what a plan covers. A plan stored before scopes existed
+ * carries none, and runs the scenario list it already held.
+ */
+export function describeRunPlanScope(
+  scope: RunPlanScope | null,
+  scenarioIds: string[],
+): string {
+  if (scope === null) {
+    return `hand-picked scenarios (${scenarioIds.length})`;
+  }
+  switch (scope.mode) {
+    case "all":
+      return "every scenario in the project";
+    case "test_suites":
+      return `test suites: ${scope.testSuiteIds.join(", ")}`;
+    case "labels":
+      return `labels: ${scope.labels.join(", ")}`;
+    case "scenarios":
+      return `hand-picked scenarios (${scenarioIds.length})`;
+  }
+}

package/src/tools/format-scenario.ts

@@ -0,0 +1,14 @@
+import type { ScenarioFieldValues } from "../schemas/suite-fields.js";
+
+/** The digest lines for the values a scenario carries per suite field. */
+export function formatScenarioFields(
+  fields: ScenarioFieldValues | undefined,
+): string[] {
+  if (!fields || Object.keys(fields).length === 0) return [];
+  return [
+    "\n## Fields",
+    ...Object.entries(fields).map(
+      ([identifier, value]) => `- ${identifier}: ${JSON.stringify(value)}`,
+    ),
+  ];
+}