@vellumai/assistant 0.11.8 → 0.11.9-staging.1

package/src/tools/watch/watch-retro-report.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+
+import { RiskLevel } from "../../permissions/types.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
+
+/**
+ * How a watch retrospective hands its report to the daemon.
+ *
+ * **The card cannot come from `ui_show`.** A retrospective runs as a
+ * `clientless` wake, which pins the turn non-interactive, and
+ * `conversation-tool-setup` gates the whole `ui_surface` tool family on a
+ * client being present (`return channelCapabilities?.supportsDynamicUi ??
+ * !hasNoClient`). So `ui_show` is not merely denied in this turn, it is absent
+ * from the tool set, and a retrospective told to call it can only report that
+ * it cannot. This tool is an ordinary one and passes that gate untouched.
+ *
+ * **It records; it does not render.** The executor validates the payload and
+ * returns, and nothing here writes to the conversation. What makes the card is
+ * `watch-retro.ts` reading this call back out of the turn's own history once
+ * the turn has finished, and appending the `ui_surface` block itself. Two
+ * reasons for the split. A surface appended from inside the turn can land
+ * between a persisted `tool_use` and its `tool_result`, which is the ordering
+ * hazard the memory retrospective's skill card defers around
+ * (`memory-retrospective-skill-card.ts`); waiting until the turn is over avoids
+ * it rather than detecting it. And the report is then held in the one place
+ * that survives a crash between the call and the append: the transcript.
+ *
+ * **Validation is the model-facing half.** The payload is the card's own
+ * shape, so one the renderer could not draw is refused here, while the model
+ * still has a turn left to correct it. The daemon parses it again before
+ * appending, since a tool result is not a promise about what was persisted.
+ *
+ * **Questions are validated by shape, and the shape is not advertised.** The
+ * surface schema is tolerant and strips what it does not recognize, so a
+ * question sent as `question`/`value` instead of `prompt`/`label` parses clean
+ * and draws a page with no text on it. Checking the shape here turns that into
+ * a rejection naming the field, which the model has a turn left to act on.
+ * Advertising it too would be the surer teacher, but the always-loaded payload
+ * is within a few hundred bytes of the budget
+ * (`browser-skill-baseline-tool-payload`) and the question shape is around 450
+ * of them, spent on every request by every caller for a tool one flow uses.
+ * The divergence is safe in a way the general rule in `zod-tool-schema.ts`
+ * warns it is not: a model reaching this tool has been sent here by
+ * `RETRO_INSTRUCTIONS`, which names every field, so there is no caller that
+ * sees the terse schema without the contract.
+ */
+
+/** One alternative on a `pick` or a `gate`. */
+const questionOptionSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  note: z.string().optional().catch(undefined),
+});
+
+/**
+ * One question, held to what the card can actually page through.
+ *
+ * A `pick` or a `gate` with fewer than two options is one button, which is not
+ * a question, and the renderer drops it. More than four is the questionnaire
+ * the paging exists to avoid, on a page that then scrolls. Rejecting either
+ * here means the model hears about the gap it could not name instead of the
+ * user reading a page that is missing or too long to tap through.
+ */
+const questionSchema = z
+  .object({
+    id: z.string().min(1),
+    kind: z.enum(["fill", "pick", "gate"]),
+    prompt: z.string().min(1),
+    eyebrow: z.string().optional().catch(undefined),
+    suggestion: z.string().optional().catch(undefined),
+    // No `.catch`, for the same reason `questions` has none, and for one more:
+    // a swallowed option array reads as an empty one, so a mistyped `label`
+    // would come back as the count complaint below. That answer sends the
+    // model to add options it already sent.
+    options: z.array(questionOptionSchema).optional(),
+  })
+  .refine(
+    (question) => {
+      if (question.kind === "fill") {
+        return true;
+      }
+      const count = question.options?.length ?? 0;
+      return count >= 2 && count <= 4;
+    },
+    {
+      error: 'a "pick" or "gate" needs two to four options',
+      path: ["options"],
+    },
+  );
+
+export const watchRetroReportInputSchema = z.looseObject({
+  task: z.string(),
+  purpose: z.string().optional().catch(undefined),
+  steps: z.array(z.string()).optional().catch(undefined),
+  eyebrow: z.string().optional().catch(undefined),
+  coverage: z.string().optional().catch(undefined),
+  // No `.catch` here, unlike the decoration around it. A swallowed questions
+  // array is the failure this schema exists to report: the card would draw
+  // without the pages the model meant to ask on, and nothing would say so.
+  questions: z.array(questionSchema).optional(),
+});
+
+/**
+ * The same payload with the question shape left off, which is what the model
+ * is shown. Derived from the validating schema rather than written out beside
+ * it, so the fields around `questions` cannot drift from what is enforced.
+ * See the note above on why this one field is not advertised.
+ */
+const watchRetroReportAdvertisedSchema = watchRetroReportInputSchema.extend({
+  questions: z.array(z.unknown()).optional(),
+});
+
+/**
+ * The first id used by more than one question, or null when they are distinct.
+ *
+ * Checked here rather than in the schema because the renderer's response to a
+ * repeat is to drop the later question, not to fail: the id is the key an
+ * answer is held under, so two questions sharing one would submit whichever
+ * answer landed last for both.
+ */
+function firstDuplicateQuestionId(
+  questions: readonly { id: string }[] | undefined,
+): string | null {
+  const seen = new Set<string>();
+  for (const question of questions ?? []) {
+    if (seen.has(question.id)) {
+      return question.id;
+    }
+    seen.add(question.id);
+  }
+  return null;
+}
+
+export async function executeWatchRetroReport(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const parsed = watchRetroReportInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return invalidToolInputResult("watch_retro_report", parsed.error);
+  }
+  const { task, steps, questions } = parsed.data;
+  if (!task || task.trim().length === 0) {
+    return {
+      content: '"task" is required: name the task the session recorded.',
+      isError: true,
+    };
+  }
+  // A record with no steps is not a record. The questions are optional and the
+  // rest is decoration, but a card whose first page is a bare title tells the
+  // user nothing about the session they just finished.
+  if (!steps || steps.length === 0) {
+    return {
+      content:
+        '"steps" is required: list what you saw, in order, as short imperative fragments.',
+      isError: true,
+    };
+  }
+  // Last, because the record is the part a card cannot do without and a report
+  // missing it should hear about that first.
+  const duplicateId = firstDuplicateQuestionId(questions);
+  if (duplicateId !== null) {
+    return {
+      content: `Two questions share the id "${duplicateId}". An id is the handle an answer comes back under, so the card keeps the first question and drops the rest. Give each one its own.`,
+      isError: true,
+    };
+  }
+  return {
+    content: JSON.stringify({ recorded: true, steps: steps.length }),
+    isError: false,
+  };
+}
+
+export const watchRetroReportTool = {
+  name: "watch_retro_report",
+  // Deliberately terse, field descriptions included: this tool is always
+  // registered, so every byte here is spent on every request. The contract is
+  // carried by the retrospective prompt, its only caller, and enforced by the
+  // validating schema above, which is stricter than what this advertises.
+  // `browser-skill-baseline-tool-payload` holds the total to a budget.
+  description:
+    "Report what a Watch (teach mode) session recorded. Only from a watch retrospective, which gives the payload shape.",
+  category: "ui-surface",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
+
+  input_schema: toToolInputSchema(watchRetroReportAdvertisedSchema, {
+    advertiseRequired: ["task", "steps"],
+  }),
+
+  async execute(
+    input: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolExecutionResult> {
+    return executeWatchRetroReport(input, context);
+  },
+} satisfies ToolDefinition;

package/src/watch/__tests__/watch-retro.test.ts

@@ -5,9 +5,12 @@ import {
   addMessage,
   createConversation,
   getConversation,
+  getMessages,
   PROVIDER_ERROR_MESSAGE_KIND,
 } from "../../persistence/conversation-crud.js";
 import { initializeDb } from "../../persistence/db-init.js";
+import { toToolInputSchema } from "../../tools/shared/zod-tool-schema.js";
+import { watchRetroReportInputSchema } from "../../tools/watch/watch-retro-report.js";
 import {
   buildRetroWakeOptions,
   buildWatchRetroPrompt,
@@ -88,8 +91,12 @@ function recordObservation(axTree: string): {
  * tool before stopping looks like from the conversation's side.
  */
 function recordingDispatch(
-  reply: string | null = "Here is what I understood.",
+  reply: string | null = null,
   metadata?: Record<string, unknown>,
+  report: Record<string, unknown> | null = {
+    task: "Filing the receipt",
+    steps: ["Open the inbox", "Save the attachment"],
+  },
 ) {
   const calls: { conversationId: string; prompt: string }[] = [];
   const dispatch = async (
@@ -97,8 +104,20 @@ function recordingDispatch(
     prompt: string,
   ): Promise<WatchRetroDispatchResult> => {
     calls.push({ conversationId, prompt });
+    const blocks: Record<string, unknown>[] = [];
     if (reply !== null) {
-      await addMessage(conversationId, "assistant", reply, {
+      blocks.push({ type: "text", text: reply });
+    }
+    if (report !== null) {
+      blocks.push({
+        type: "tool_use",
+        id: `toolu_${randomUUID()}`,
+        name: "watch_retro_report",
+        input: report,
+      });
+    }
+    if (blocks.length > 0) {
+      await addMessage(conversationId, "assistant", JSON.stringify(blocks), {
         skipIndexing: true,
         ...(metadata ? { metadata } : {}),
       });
@@ -108,6 +127,38 @@ function recordingDispatch(
   return { calls, dispatch };
 }
 
+/** A turn that ran and left nothing behind at all. */
+function emptyDispatch() {
+  return recordingDispatch(null, undefined, null);
+}
+
+/** A turn that ran and wrote prose but never called the report tool. */
+function proseOnlyDispatch(reply = "Here is what I understood.") {
+  return recordingDispatch(reply, undefined, null);
+}
+
+/**
+ * The required property names of the object schema reached by walking `path`,
+ * descending through array `items` wherever the path crosses one.
+ */
+function requiredFieldsUnder(
+  schema: Record<string, unknown>,
+  path: readonly string[],
+): string[] {
+  let node: Record<string, unknown> | undefined = schema;
+  for (const segment of path) {
+    const properties = node?.properties as
+      | Record<string, Record<string, unknown>>
+      | undefined;
+    node = properties?.[segment];
+    while (node?.items) {
+      node = node.items as Record<string, unknown>;
+    }
+  }
+  const required = node?.required;
+  return Array.isArray(required) ? (required as string[]) : [];
+}
+
 describe("watch retrospective", () => {
   test("dispatches exactly one turn carrying the session's timeline", async () => {
     const summary = recordSession([
@@ -151,7 +202,7 @@ describe("watch retrospective", () => {
     // that loads `skill-management` and then stops or errors looks invoked and
     // has said nothing.
     const result = await runWatchRetro(summary, {
-      dispatch: recordingDispatch(null).dispatch,
+      dispatch: emptyDispatch().dispatch,
     });
 
     expect(result).toEqual({ status: "failed", reason: "no_report" });
@@ -164,9 +215,11 @@ describe("watch retrospective", () => {
     // A failed LLM call persists an assistant row and returns normally, so the
     // thread has assistant text in it and still holds no account of anything.
     const result = await runWatchRetro(summary, {
-      dispatch: recordingDispatch("The model call failed.", {
-        messageKind: PROVIDER_ERROR_MESSAGE_KIND,
-      }).dispatch,
+      dispatch: recordingDispatch(
+        "The model call failed.",
+        { messageKind: PROVIDER_ERROR_MESSAGE_KIND },
+        null,
+      ).dispatch,
     });
 
     expect(result).toEqual({ status: "failed", reason: "no_report" });
@@ -186,7 +239,7 @@ describe("watch retrospective", () => {
     );
 
     const result = await runWatchRetro(summary, {
-      dispatch: recordingDispatch(null).dispatch,
+      dispatch: emptyDispatch().dispatch,
     });
 
     expect(result).toEqual({ status: "failed", reason: "no_report" });
@@ -197,7 +250,7 @@ describe("watch retrospective", () => {
     const summary = recordSession(["filing the receipt"]);
 
     const result = await runWatchRetro(summary, {
-      dispatch: recordingDispatch("   \n  ").dispatch,
+      dispatch: proseOnlyDispatch("   \n  ").dispatch,
     });
 
     expect(result).toEqual({ status: "failed", reason: "no_report" });
@@ -225,52 +278,95 @@ describe("watch retrospective", () => {
 
     const { prompt } = calls[0]!;
     expect(prompt).toContain("skill-management");
-    // The ask leads, and the record follows it.
-    expect(prompt).toContain("What I need from you");
-    expect(prompt).toContain("What I saw");
-    expect(prompt.indexOf("What I need from you")).toBeLessThan(
-      prompt.indexOf("What I saw"),
+    // One card, and the record is its first page. Order carries no priority
+    // once each question owns a page, so the record leads without costing the
+    // questions anything.
+    expect(prompt).toContain("`watch_retro_report`");
+    expect(prompt).toContain("`steps`");
+    expect(prompt.indexOf("`steps`")).toBeLessThan(
+      prompt.indexOf("`questions`"),
     );
     // The one field the recording cannot supply is always asked for.
-    expect(prompt).toContain("what they would say to start this task");
-    // And the report is not turned back into a questionnaire about itself.
     expect(prompt).toContain(
-      "do not ask them to confirm something the recording already showed you.",
+      "what they would say to start this task, in their own words",
+    );
+    // And the card is not turned back into a questionnaire about itself.
+    expect(prompt).toContain(
+      "Do not ask the user to confirm something the recording already showed you.",
     );
-    expect(prompt).toContain("No preamble");
-    // A destructive step is confirmed however plainly it was recorded. The
+    // A destructive step is asked about however plainly it was recorded. The
     // recording establishes what someone did once and nothing about whether
-    // they want it repeated unattended, so it is the one exception to the
-    // rule above.
+    // they want it repeated unattended, so it is the one exception to the rule
+    // above.
+    expect(prompt).toContain("asked however plainly the step was seen");
+  });
+
+  test("caps the questions and keeps every one of them answerable in a tap", async () => {
+    const summary = recordSession(["renaming the export"]);
+    const { calls, dispatch } = recordingDispatch();
+
+    await runWatchRetro(summary, { dispatch });
+
+    const { prompt } = calls[0]!;
+    expect(prompt).toContain("at most three");
+    // No question may be a yes/no whose "no" carries nothing back: a binary
+    // that packs an inferred rule into it spends the question and returns
+    // nothing, leaving the user owed a follow-up they cannot see.
+    expect(prompt).toContain('Never ask a yes/no whose "no" tells you nothing');
     expect(prompt).toContain(
-      "Always confirm any destructive or irreversible step, even one the recording showed plainly",
+      "If you cannot name the alternatives, you do not understand the gap well enough to ask about it",
     );
   });
 
-  test("puts the report last in the turn, after the skill it hands off to", async () => {
+  test("makes every skip land on a safe answer", async () => {
+    const summary = recordSession(["archiving the thread"]);
+    const { calls, dispatch } = recordingDispatch();
+
+    await runWatchRetro(summary, { dispatch });
+
+    const { prompt } = calls[0]!;
+    // Every page is skippable, so every page's default is what the model
+    // actually gets from a user who taps through. A `fill` keeps its
+    // suggestion; a `pick` keeps the reading the recording supports.
+    expect(prompt).toContain(
+      "Put your best guess in `suggestion` so skipping keeps a working phrase",
+    );
+    expect(prompt).toContain(
+      "The first option is the default and must be the reading the recording supports",
+    );
+    // The gate is the one place the default is deliberately not the guess.
+    // Watching someone do a destructive thing once says nothing about whether
+    // they want it repeated with nobody looking, so a skipped gate must land
+    // on the cautious answer rather than on what was recorded.
+    expect(prompt).toContain(
+      'The first option must be the cautious one ("Ask me first"), because a skipped question takes it.',
+    );
+  });
+
+  test("puts the card last in the turn, after the skill it hands off to", async () => {
     const summary = recordSession(["renaming the export"]);
     const { calls, dispatch } = recordingDispatch();
 
     await runWatchRetro(summary, { dispatch });
 
     const { prompt } = calls[0]!;
-    // The report is what the user is shown when a session ends, so it has to
-    // be the turn's last prose. A client renders the final text block as the
-    // response and folds everything before it into collapsed intermediate
-    // work, so a `skill_load` issued after the report demotes the report to
-    // an "Earlier activity" row the user has to unfold to read.
+    // The card is what the user is shown when a session ends, so nothing may
+    // follow it. Prose written after it reads as a sign-off nobody asked for,
+    // and a client folds everything before a turn's last text block into
+    // collapsed intermediate work.
     expect(prompt).toContain("Load the `skill-management` skill first");
     expect(
       prompt.indexOf("Load the `skill-management` skill first"),
-    ).toBeLessThan(prompt.indexOf("What I need from you"));
-    expect(prompt).toContain("That report is the last thing you do this turn");
-    // A sign-off is another text block after the report, which puts the report
-    // back on the wrong side of the same rule, so it is refused by name.
+    ).toBeLessThan(prompt.indexOf("`watch_retro_report`"));
+    expect(prompt).toContain("That call is the last thing you do this turn");
     expect(prompt).toContain("no sign-off");
     expect(prompt).toContain("no further tool call");
+    // One card, not a card per question: a second `ui_show` would replace the
+    // paging with a stack of surfaces, which is the shape this replaced.
+    expect(prompt).toContain("exactly one `watch_retro_report` call");
   });
 
-  test("writes the report even when the skill it hands off to will not load", async () => {
+  test("shows the card even when the skill it hands off to will not load", async () => {
     const summary = recordSession(["filing the receipt"]);
     const { calls, dispatch } = recordingDispatch();
 
@@ -279,14 +375,11 @@ describe("watch retrospective", () => {
     const { prompt } = calls[0]!;
     // `skill-management` is a selector, and a managed or workspace skill of the
     // same id replaces the bundled one in the catalog. Putting the load ahead
-    // of the report is what lets a shadow, or the refusal a clientless wake
+    // of the card is what lets a shadow, or the refusal a clientless wake
     // gives an inline-command load, land before the user has been told
     // anything. Neither may become the retro: the session is recorded and the
     // account of it is what the user is owed.
-    expect(prompt).toContain(
-      "Write the report below whether or not that load succeeds",
-    );
-    expect(prompt).toContain("do not report on the load and do not retry it");
+    expect(prompt).toContain("Report whether or not the skill loaded");
     // The failure is still named, so a missing handoff does not read as a
     // report that simply chose not to ask about authoring.
     expect(prompt).toContain("could not open the skill-authoring flow");
@@ -299,14 +392,116 @@ describe("watch retrospective", () => {
     await runWatchRetro(summary, { dispatch });
 
     const { prompt } = calls[0]!;
-    expect(prompt).toContain(
-      "Do not author or scaffold a skill until the four points that step names are settled",
-    );
+    expect(prompt).toContain("Do not author or scaffold a skill yet");
     // The retro delegates authoring to the skill-management flow rather than
     // naming the tool that writes a skill, so nothing here can reach it.
     expect(prompt).not.toContain("scaffold_managed_skill");
   });
 
+  test("draws the card from the turn's report call", async () => {
+    const summary = recordSession(["filing the receipt"]);
+    const { dispatch } = recordingDispatch();
+
+    const result = await runWatchRetro(summary, { dispatch });
+
+    expect(result).toEqual({
+      status: "dispatched",
+      conversationId: summary.conversationId,
+    });
+    expect(getConversation(summary.conversationId)!.surfacedAt).not.toBeNull();
+
+    // The card is appended by the daemon, not by the turn: nothing the model
+    // can call renders a surface in a clientless wake.
+    const appended = getMessages(summary.conversationId).at(-1)!;
+    const surface = appended.content.find(
+      (block) => block.type === "ui_surface",
+    ) as { surfaceType: string; data: Record<string, unknown> } | undefined;
+    expect(surface?.surfaceType).toBe("card");
+    expect(surface?.data.template).toBe("watch_retro");
+    expect((surface?.data.templateData as { task: string }).task).toBe(
+      "Filing the receipt",
+    );
+
+    // `title`, `subtitle` and `body` are the whole report for a renderer too
+    // old to know the template, so they are derived here rather than left to
+    // the model to remember.
+    expect(surface?.data.title).toBe("Filing the receipt");
+    expect(surface?.data.body).toContain("1. Open the inbox");
+
+    // Providers drop `ui_surface` when serializing history, so without the
+    // fallback sibling the model's next turn would not know what it showed.
+    const fallback = appended.content.find(
+      (block) =>
+        block.type === "text" &&
+        (block as { _surfaceFallback?: boolean })._surfaceFallback === true,
+    );
+    expect(fallback).toBeDefined();
+  });
+
+  test("a turn that wrote prose but never reported is not a report", async () => {
+    const summary = recordSession(["filing the receipt"]);
+
+    // Prose is no longer the report, so a turn that narrates the session and
+    // never calls the tool has produced nothing the user can be shown. Left
+    // counting, it would surface a thread with an account in it that no card
+    // backs and no answer can be given to.
+    const result = await runWatchRetro(summary, {
+      dispatch: proseOnlyDispatch("Here is what I saw. You filed a receipt.")
+        .dispatch,
+    });
+
+    expect(result).toEqual({ status: "failed", reason: "no_report" });
+    expect(getConversation(summary.conversationId)!.surfacedAt).toBeNull();
+  });
+
+  test("a report call with no task is not a report", async () => {
+    const summary = recordSession(["filing the receipt"]);
+    const { dispatch } = recordingDispatch(null, undefined, {
+      task: "   ",
+      steps: ["Open the inbox"],
+    });
+
+    // The payload schema is tolerant by design, so an empty task parses. A
+    // card whose first page has no title is not an account of anything, and
+    // the append is the report test, so it has to reject here.
+    const result = await runWatchRetro(summary, { dispatch });
+    expect(result).toEqual({ status: "failed", reason: "no_report" });
+  });
+
+  test("the newest report call wins", async () => {
+    const summary = recordSession(["filing the receipt"]);
+    const conversationId = summary.conversationId;
+    const dispatch = async (): Promise<WatchRetroDispatchResult> => {
+      // A model that corrects itself calls again rather than editing.
+      for (const task of ["First reading", "Corrected reading"]) {
+        await addMessage(
+          conversationId,
+          "assistant",
+          JSON.stringify([
+            {
+              type: "tool_use",
+              id: `toolu_${randomUUID()}`,
+              name: "watch_retro_report",
+              input: { task, steps: ["Open the inbox"] },
+            },
+          ]),
+          { skipIndexing: true },
+        );
+      }
+      return { invoked: true };
+    };
+
+    await runWatchRetro(summary, { dispatch });
+
+    const appended = getMessages(conversationId).at(-1)!;
+    const surface = appended.content.find(
+      (block) => block.type === "ui_surface",
+    ) as { data: Record<string, unknown> } | undefined;
+    expect((surface?.data.templateData as { task: string }).task).toBe(
+      "Corrected reading",
+    );
+  });
+
   test("says so when the render was bounded", async () => {
     const narrations = Array.from(
       { length: DEFAULT_MAX_ENTRIES + 5 },
@@ -709,4 +904,37 @@ describe("watch retrospective", () => {
     expect(prompt).toContain("<ax-tree>");
     expect(prompt).toContain("</ax-tree>");
   });
+
+  /**
+   * The instructions are the only place the model learns what to put in a
+   * question, and a field they leave unnamed is one it has to invent a name
+   * for. The surface schema strips what it does not recognize, so an invented
+   * name draws a page with no text on it rather than failing anywhere.
+   *
+   * Read out of the tool's validating schema instead of listed here, so a
+   * field added to the payload cannot be added without a line about it. The
+   * validating one rather than the advertised one, because the question shape
+   * is deliberately not advertised: the prompt is where the model gets it, so
+   * the prompt is what has to be complete.
+   */
+  test("the instructions name every field a question requires", async () => {
+    // A timeline of two words, so a field name found below is one the
+    // instructions wrote rather than one the recording happened to contain.
+    const { sessionId } = recordObservation("Window: Editor");
+    const prompt = buildWatchRetroPrompt(renderWatchTimeline(sessionId));
+
+    const schema = toToolInputSchema(watchRetroReportInputSchema);
+    const questionShape = requiredFieldsUnder(schema, ["questions"]);
+    const optionShape = requiredFieldsUnder(schema, ["questions", "options"]);
+
+    // The two the dev-QA payload came back without, named so the guard reads
+    // as the thing it is defending rather than as an empty loop if the shape
+    // lookup ever returns nothing.
+    expect(questionShape).toContain("prompt");
+    expect(optionShape).toContain("label");
+
+    for (const field of [...questionShape, ...optionShape]) {
+      expect(prompt).toMatch(new RegExp(`\\b${field}\\b`));
+    }
+  });
 });