@vellumai/assistant 0.11.8 → 0.11.9-staging.2

package/src/__tests__/workspace-migration-152-repair-retired-fireworks-minimax-m2p7-model-id.test.ts

@@ -0,0 +1,233 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { repairRetiredFireworksMinimaxM2p7ModelIdMigration } from "../workspace/migrations/152-repair-retired-fireworks-minimax-m2p7-model-id.js";
+import { WORKSPACE_MIGRATIONS } from "../workspace/migrations/registry.js";
+import { assertNotLiveDb } from "./assert-not-live-db.js";
+
+const STALE = "accounts/fireworks/models/minimax-m2p7";
+const REPLACEMENT = "accounts/fireworks/models/minimax-m3";
+
+let workspaceDir: string;
+
+function freshWorkspace(): void {
+  workspaceDir = join(
+    tmpdir(),
+    `vellum-migration-152-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(workspaceDir, { recursive: true });
+}
+
+function writeConfig(data: Record<string, unknown>): void {
+  writeFileSync(
+    join(workspaceDir, "config.json"),
+    JSON.stringify(data, null, 2) + "\n",
+  );
+}
+
+function readConfig(): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(workspaceDir, "config.json"), "utf-8"));
+}
+
+function seedRows(rows: Array<{ name: string; provider: string }>): void {
+  mkdirSync(join(workspaceDir, "data", "db"), { recursive: true });
+  const db = new Database(join(workspaceDir, "data", "db", "assistant.db"));
+  db.run(`CREATE TABLE IF NOT EXISTS provider_connections (
+    name TEXT PRIMARY KEY,
+    provider TEXT NOT NULL,
+    auth TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`);
+  for (const row of rows) {
+    db.query(
+      `INSERT INTO provider_connections (name, provider, auth, created_at, updated_at) VALUES (?, ?, '{"type":"api_key"}', 1, 1)`,
+    ).run(row.name, row.provider);
+  }
+  db.close();
+}
+
+beforeEach(() => {
+  freshWorkspace();
+});
+
+afterEach(() => {
+  if (existsSync(workspaceDir)) {
+    assertNotLiveDb(workspaceDir);
+    rmSync(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+describe("152-repair-retired-fireworks-minimax-m2p7-model-id migration", () => {
+  test("has correct migration id and is registered", () => {
+    expect(repairRetiredFireworksMinimaxM2p7ModelIdMigration.id).toBe(
+      "152-repair-retired-fireworks-minimax-m2p7-model-id",
+    );
+    expect(WORKSPACE_MIGRATIONS.map((m) => m.id)).toContain(
+      "152-repair-retired-fireworks-minimax-m2p7-model-id",
+    );
+  });
+
+  test("repairs the stale ID in default, call sites, and profiles", () => {
+    writeConfig({
+      llm: {
+        default: { provider: "fireworks", model: STALE },
+        callSites: {
+          recall: { model: STALE, maxTokens: 4096 },
+          heartbeat: { model: `${STALE}-tuned` },
+          malformed: STALE,
+        },
+        profiles: {
+          "cost-optimized": { provider: "vellum", model: STALE },
+          legacy: { model: STALE },
+        },
+      },
+    });
+
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+
+    const llm = readConfig().llm as Record<string, any>;
+    expect(llm.default.model).toBe(REPLACEMENT);
+    expect(llm.callSites.recall.model).toBe(REPLACEMENT);
+    expect(llm.callSites.recall.maxTokens).toBe(4096);
+    // Non-exact matches and malformed leaves are untouched.
+    expect(llm.callSites.heartbeat.model).toBe(`${STALE}-tuned`);
+    expect(llm.callSites.malformed).toBe(STALE);
+    // Managed profiles stamped provider "vellum" carry Fireworks model IDs.
+    expect(llm.profiles["cost-optimized"].model).toBe(REPLACEMENT);
+    expect(llm.profiles.legacy.model).toBe(REPLACEMENT);
+  });
+
+  test("repairs entry-bound fragments whose row kind is fireworks or vellum", () => {
+    seedRows([
+      { name: "my-fireworks", provider: "fireworks" },
+      { name: "managed-alt", provider: "vellum" },
+    ]);
+    writeConfig({
+      llm: {
+        profiles: {
+          bound: { provider: "my-fireworks", model: STALE },
+          managed: { provider: "managed-alt", model: STALE },
+        },
+      },
+    });
+
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+
+    const llm = readConfig().llm as Record<string, any>;
+    expect(llm.profiles.bound.model).toBe(REPLACEMENT);
+    expect(llm.profiles.managed.model).toBe(REPLACEMENT);
+  });
+
+  test("leaves fragments with an explicit other provider untouched", () => {
+    seedRows([{ name: "byo-compat", provider: "openai-compatible" }]);
+    writeConfig({
+      llm: {
+        default: { provider: "openai-compatible", model: STALE },
+        profiles: {
+          byo: { provider: "openai-compatible", model: STALE },
+          // Entry-bound profile whose row kind is not repairable.
+          compatBound: { provider: "byo-compat", model: STALE },
+          // Entry name with no row: dangling, so nothing proves it is a
+          // fireworks-kind route.
+          dangling: { provider: "ghost", model: STALE },
+        },
+      },
+    });
+
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+
+    const llm = readConfig().llm as Record<string, any>;
+    expect(llm.default.model).toBe(STALE);
+    expect(llm.profiles.byo.model).toBe(STALE);
+    expect(llm.profiles.compatBound.model).toBe(STALE);
+    expect(llm.profiles.dangling.model).toBe(STALE);
+  });
+
+  test("leaves entry-name providers untouched when no DB file exists", () => {
+    writeConfig({
+      llm: {
+        profiles: { bound: { provider: "my-fireworks", model: STALE } },
+      },
+    });
+
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+
+    const llm = readConfig().llm as Record<string, any>;
+    expect(llm.profiles.bound.model).toBe(STALE);
+  });
+
+  test("throws when an entry-name provider needs rows and the DB is unreadable", () => {
+    // A DB file without the provider_connections table is unqueryable, so
+    // the run must fail (and retry later) instead of skipping the profile.
+    mkdirSync(join(workspaceDir, "data", "db"), { recursive: true });
+    writeFileSync(join(workspaceDir, "data", "db", "assistant.db"), "");
+    writeConfig({
+      llm: {
+        profiles: { bound: { provider: "my-fireworks", model: STALE } },
+      },
+    });
+
+    expect(() =>
+      repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir),
+    ).toThrow();
+    const llm = readConfig().llm as Record<string, any>;
+    expect(llm.profiles.bound.model).toBe(STALE);
+
+    // Vendor and absent providers never need the rows, so the same broken
+    // DB does not block their repair.
+    writeConfig({
+      llm: {
+        default: { provider: "fireworks", model: STALE },
+        profiles: { legacy: { model: STALE } },
+      },
+    });
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+    const repaired = readConfig().llm as Record<string, any>;
+    expect(repaired.default.model).toBe(REPLACEMENT);
+    expect(repaired.profiles.legacy.model).toBe(REPLACEMENT);
+  });
+
+  test("is idempotent and a no-op without the stale ID", () => {
+    writeConfig({
+      llm: {
+        default: { provider: "fireworks", model: STALE },
+        profiles: { fine: { provider: "fireworks", model: REPLACEMENT } },
+      },
+    });
+
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+    const first = readConfig();
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+    expect(readConfig()).toEqual(first);
+
+    const llm = first.llm as Record<string, any>;
+    expect(llm.default.model).toBe(REPLACEMENT);
+    expect(llm.profiles.fine.model).toBe(REPLACEMENT);
+  });
+
+  test("handles missing config, missing llm block, and invalid JSON", () => {
+    // No config.json at all.
+    expect(() =>
+      repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir),
+    ).not.toThrow();
+
+    writeConfig({ theme: "dark" });
+    repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir);
+    expect(readConfig()).toEqual({ theme: "dark" });
+
+    writeFileSync(join(workspaceDir, "config.json"), "{not json");
+    expect(() =>
+      repairRetiredFireworksMinimaxM2p7ModelIdMigration.run(workspaceDir),
+    ).not.toThrow();
+  });
+});

package/src/agent/attachments.ts

@@ -1,3 +1,4 @@
+import { extractedTextForFileBlock } from "../providers/content-block-size.js";
 import {
   attachmentIdFragment,
   type ContentBlock,
@@ -64,6 +65,10 @@ export function attachmentsToReferenceBlocks(
       } as ContentBlock;
     }
 
+    const extractedText = extractedTextForFileBlock(
+      ref.mimeType,
+      ref.extractedText,
+    );
     return {
       type: "file",
       source: {
@@ -73,7 +78,7 @@ export function attachmentsToReferenceBlocks(
         sizeBytes: ref.sizeBytes,
         filename: ref.filename,
       },
-      extracted_text: ref.extractedText,
+      ...(extractedText !== undefined ? { extracted_text: extractedText } : {}),
     } as ContentBlock;
   });
 }
@@ -99,6 +104,10 @@ export function attachmentsToContentBlocks(
         } as ContentBlock;
       }
 
+      const extractedText = extractedTextForFileBlock(
+        attachment.mimeType,
+        attachment.extractedText,
+      );
       return {
         type: "file",
         source: {
@@ -107,7 +116,9 @@ export function attachmentsToContentBlocks(
           data: attachment.data,
           filename: attachment.filename,
         },
-        extracted_text: attachment.extractedText,
+        ...(extractedText !== undefined
+          ? { extracted_text: extractedText }
+          : {}),
         ...attachmentIdFragment(attachment.id),
       } as ContentBlock;
     }),

package/src/agent/loop.ts

@@ -2,7 +2,6 @@ import type { AnsweredQuestion } from "../api/events/question-answered.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { recordEstimate } from "../context/estimator-calibration.js";
 import { preModelCallSanitize } from "../context/outbound-sanitize.js";
-import { turnStartUserMessageHasSpotlight } from "../context/strip-injections.js";
 import {
   estimatePromptTokensRaw,
   estimatePromptTokensWithTools,
@@ -1551,21 +1550,6 @@ export class AgentLoop {
           providerConfig.cacheTtl = this.config.cacheTtl;
         }
 
-        // Cache-anchor signal for turns whose opening message is volatile. The
-        // memory-v3 `<memory_spotlight>` block is the only injected block that
-        // is strip-and-replaced from every user message each turn, so when it
-        // is present that message's bytes do not recur next turn and a
-        // long-TTL breakpoint on it could never be read back. The provider
-        // marks it at the short TTL instead. Derived from the history actually
-        // being sent rather than from configuration, so turns where memory
-        // contributed no spotlight keep a normal anchor. Read off the
-        // turn-starting message, so the signal holds for every request in the
-        // turn rather than flipping once tool results arrive. Only set when
-        // true so the wire/config stays byte-identical when absent.
-        if (turnStartUserMessageHasSpotlight(history)) {
-          providerConfig.mutableLatestUserMessage = true;
-        }
-
         // Per-call LLM call-site identifier. Surfaces on the per-call
         // `config.callSite` so `RetryProvider.normalizeSendMessageOptions`
         // can route through `resolveCallSiteConfig` against
@@ -1652,7 +1636,7 @@ export class AgentLoop {
         // Sanitize the outbound history right before sending: drop accumulated
         // media, collapse old AX-tree snapshots, and convert historical
         // web-search results to text. See {@link preModelCallSanitize}.
-        const providerHistory = timeSyncSection(
+        const sanitizedHistory = timeSyncSection(
           "agent-loop:pre-model-call-sanitize",
           () => preModelCallSanitize(history),
           (sanitized) => ({ messageCount: sanitized.length }),
@@ -1837,7 +1821,7 @@ export class AgentLoop {
         let response: ProviderResponse;
         try {
           response = await traceAsyncSection("agent-loop:provider-send", () =>
-            this.provider.sendMessage(providerHistory, providerOptions),
+            this.provider.sendMessage(sanitizedHistory, providerOptions),
           );
         } catch (llmCallError) {
           // Skip recording on abort — the user cancelled the request and
@@ -1855,7 +1839,7 @@ export class AgentLoop {
             // misrepresent both.
             const rawRequest = {
               provider: this.provider.name,
-              messages: providerHistory,
+              messages: sanitizedHistory,
               tools: providerOptions.tools,
               systemPrompt: providerOptions.systemPrompt,
               config: providerOptions.config,

package/src/api/README.md

@@ -5,9 +5,12 @@ evals, future external clients. This directory is the **source of truth** for
 the wire contracts the assistant exposes: schemas, types, and pure helpers.
 
 Internal assistant code imports the files in this directory via relative paths
-(e.g. `../../api/events/open-url.js`). External consumers import the
-materialized npm-style package `@vellumai/assistant-api`, regenerated into
-`clients/web/node_modules/` by `clients/web/scripts/postinstall.ts`.
+(e.g. `../../api/events/open-url.js`). External consumers import it as the
+workspace package `@vellumai/assistant-api`, a `workspace:*` symlink to this
+directory, so an edit here reaches them immediately. The generated HTTP
+client is separate: it comes from `assistant/openapi.yaml`, regenerated with
+`cd assistant && bun run generate:openapi` and consumed by
+`cd clients/web && bun run openapi-ts`.
 
 ## Architecture
 
@@ -110,8 +113,9 @@ Handler-level tests in the consuming domain modules typically need no change
 Run before push, in order:
 
 ```bash
-# In clients/web — regenerate the @vellumai/assistant-api bundle
-bun run scripts/postinstall.ts
+# Regenerate the OpenAPI spec and the web client from it
+( cd assistant && bun run generate:openapi )
+( cd clients/web && bun run openapi-ts )
 
 # Type-check both packages
 ( cd assistant && bunx tsc --noEmit )

package/src/api/index.ts

@@ -31,7 +31,6 @@ import { ContextCompactedEventSchema } from "./events/context-compacted.js";
 import { ContextWindowUsageEventSchema } from "./events/context-window-usage.js";
 import { ConversationErrorEventSchema } from "./events/conversation-error.js";
 import { ConversationInferenceProfileUpdatedEventSchema } from "./events/conversation-inference-profile-updated.js";
-import { ConversationListInvalidatedEventSchema } from "./events/conversation-list-invalidated.js";
 import { ConversationNoticeEventSchema } from "./events/conversation-notice.js";
 import { ConversationTitleUpdatedEventSchema } from "./events/conversation-title-updated.js";
 import { DiskPressureStatusChangedEventSchema } from "./events/disk-pressure-status-changed.js";
@@ -321,12 +320,6 @@ export {
   type ConversationInferenceProfileUpdatedEvent,
   ConversationInferenceProfileUpdatedEventSchema,
 } from "./events/conversation-inference-profile-updated.js";
-export {
-  type ConversationListInvalidatedEvent,
-  ConversationListInvalidatedEventSchema,
-  type ConversationListInvalidatedReason,
-  ConversationListInvalidatedReasonSchema,
-} from "./events/conversation-list-invalidated.js";
 export {
   type ConversationNoticeEvent,
   ConversationNoticeEventSchema,
@@ -913,6 +906,15 @@ export {
   TableSurfaceDataSchema,
   type VisualSurfaceData,
   VisualSurfaceDataSchema,
+  WATCH_RETRO_MAX_QUESTIONS,
+  type WatchRetroOption,
+  WatchRetroOptionSchema,
+  type WatchRetroQuestion,
+  type WatchRetroQuestionKind,
+  WatchRetroQuestionKindSchema,
+  WatchRetroQuestionSchema,
+  type WatchRetroSurfaceData,
+  WatchRetroSurfaceDataSchema,
   type WorkResultDiff,
   WorkResultDiffSchema,
   type WorkResultItem,
@@ -978,7 +980,6 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ContextWindowUsageEventSchema,
   ConversationErrorEventSchema,
   ConversationInferenceProfileUpdatedEventSchema,
-  ConversationListInvalidatedEventSchema,
   ConversationNoticeEventSchema,
   ConversationTitleUpdatedEventSchema,
   DiskPressureStatusChangedEventSchema,

package/src/api/package.json

@@ -8,6 +8,7 @@
     ".": "./index.ts"
   },
   "dependencies": {
+    "@vellumai/service-contracts": "workspace:*",
     "zod": "4.3.6"
   }
 }

package/src/api/responses/conversation-message.ts

@@ -22,6 +22,7 @@
  * gateway, evals) import via `@vellumai/assistant-api`.
  */
 
+import { ReactionEmojiFieldsSchema } from "@vellumai/service-contracts/reactions";
 import { z } from "zod";
 
 import {
@@ -358,6 +359,7 @@ const SlackMessageLinkSchema = z.object({
 
 const SlackReactionSchema = z.object({
   emoji: z.string(),
+  ...ReactionEmojiFieldsSchema.shape,
   op: z.enum(["added", "removed"]),
   actorDisplayName: z.string().optional(),
   targetChannelTs: z.string(),
@@ -621,6 +623,7 @@ export const ConversationMessageSchema = z.object({
   reaction: z
     .object({
       emoji: z.string(),
+      ...ReactionEmojiFieldsSchema.shape,
       op: z.enum(["added", "removed"]),
       targetMessageId: z.string(),
       actorDisplayName: z.string().optional(),
@@ -639,6 +642,11 @@ export const ConversationMessageSchema = z.object({
     })
     .optional(),
   slackMessage: ConversationSlackMessageSchema.optional(),
+  /** Unix ms at which the message was deleted on its channel after the daemon
+   *  stored it (a Slack or Discord deletion the gateway forwarded). The stored
+   *  content stays for audit and the Inspect view; clients render a tombstone
+   *  in place of the content, mirroring what the channel now shows. */
+  deletedAt: z.number().optional(),
   /**
    * Queue state for a user message that is still waiting in the daemon's
    * in-memory queue (enqueued while the agent was mid-turn, not yet drained or

package/src/api/responses/home.ts

@@ -17,6 +17,10 @@
  * (web client, gateway, evals) import via `@vellumai/assistant-api`.
  */
 
+import {
+  type GuardianRequestStatus,
+  GuardianRequestStatusSchema,
+} from "@vellumai/service-contracts/guardian-requests";
 import { z } from "zod";
 
 // ---------------------------------------------------------------------------
@@ -107,24 +111,9 @@ export const FeedItemDetailPanelSchema = z.object({
 });
 export type FeedItemDetailPanel = z.infer<typeof FeedItemDetailPanelSchema>;
 
-/**
- * Canonical guardian-request status projected onto a feed item.
- *
- * Values mirror `GuardianRequestStatusSchema` in
- * `@vellumai/gateway-client` (this file is copied verbatim into client
- * packages, so it cannot import the contract; the daemon's projection
- * writer asserts the two stay aligned at compile time).
- */
-export const FeedItemGuardianStatusSchema = z.enum([
-  "pending",
-  "approved",
-  "denied",
-  "expired",
-  "cancelled",
-]);
-export type FeedItemGuardianStatus = z.infer<
-  typeof FeedItemGuardianStatusSchema
->;
+/** Canonical guardian-request status projected onto a feed item. */
+export const FeedItemGuardianStatusSchema = GuardianRequestStatusSchema;
+export type FeedItemGuardianStatus = GuardianRequestStatus;
 
 /** Whether the guardian is being asked to approve or to answer. */
 export const FeedItemGuardianIntentSchema = z.enum(["approval", "question"]);

package/src/api/surfaces.ts

@@ -86,6 +86,23 @@ export function describeSurfaceDataStringParseFailure(
   }
 }
 
+/**
+ * Required string that coerces a scalar, treating an absent field as blank.
+ *
+ * `z.coerce.string()` is not a validator on a missing field: it stringifies
+ * whatever it is handed, so `undefined` parses successfully as the literal
+ * "undefined" and a trailing `.catch()` never runs. That string then renders,
+ * and a field the model simply failed to send reads to the user as a word
+ * nobody wrote. A blank is what the callers already handle: an empty title
+ * falls back to a default, and an empty prompt or label is what the watch
+ * retro card filters an unanswerable question out on.
+ */
+const coercedString = () =>
+  z.preprocess(
+    (value) => (value === undefined || value === null ? "" : value),
+    z.coerce.string().catch(""),
+  );
+
 /** Optional string that drops (rather than rejects on) a non-string value. */
 const tolerantString = () => z.string().optional().catch(undefined);
 
@@ -111,7 +128,7 @@ export const CardSurfaceDataSchema = z.object({
   subtitle: z.string().optional(),
   body: z.string().optional(),
   metadata: z
-    .array(z.object({ label: z.coerce.string(), value: z.coerce.string() }))
+    .array(z.object({ label: coercedString(), value: coercedString() }))
     .optional(),
   /** Optional template name for specialized rendering (e.g. "weather_forecast"). */
   template: z.string().optional(),
@@ -298,7 +315,7 @@ export const FormFieldSchema = z.object({
     .optional()
     .catch(undefined),
   options: z
-    .array(z.object({ label: z.coerce.string(), value: z.coerce.string() }))
+    .array(z.object({ label: coercedString(), value: coercedString() }))
     .optional()
     .catch(undefined),
 });
@@ -353,7 +370,7 @@ export const TableColumnSchema = z.object({
 export type TableColumn = z.infer<typeof TableColumnSchema>;
 
 export const TableCellValueSchema = z.object({
-  text: z.coerce.string().catch(""),
+  text: coercedString(),
   /** SF Symbol name. */
   icon: tolerantString(),
   /** Semantic token: "success" | "warning" | "error" | "muted". */
@@ -402,7 +419,7 @@ export const DynamicPagePreviewSchema = z.object({
   description: tolerantString(),
   icon: tolerantString(),
   metrics: z
-    .array(z.object({ label: z.coerce.string(), value: z.coerce.string() }))
+    .array(z.object({ label: coercedString(), value: coercedString() }))
     .optional()
     .catch(undefined),
   context: z.enum(["app_create", "general"]).optional().catch(undefined),
@@ -467,7 +484,7 @@ export const WorkResultSectionTypeSchema = z.enum([
 export type WorkResultSectionType = z.infer<typeof WorkResultSectionTypeSchema>;
 
 const workResultLabelValue = () => ({
-  label: z.coerce.string().catch(""),
+  label: coercedString(),
   value: z.union([z.string(), z.number()]).catch(""),
 });
 
@@ -483,7 +500,7 @@ export type WorkResultMetadata = z.infer<typeof WorkResultMetadataSchema>;
 
 export const WorkResultItemSchema = z.object({
   id: tolerantString(),
-  title: z.coerce.string().catch(""),
+  title: coercedString(),
   description: tolerantString(),
   status: tolerantString(),
   tone: WorkResultToneSchema.optional().catch(undefined),
@@ -506,7 +523,7 @@ export type WorkResultDiff = z.infer<typeof WorkResultDiffSchema>;
 
 export const WorkResultSectionSchema = z.object({
   id: tolerantString(),
-  title: z.coerce.string().catch(""),
+  title: coercedString(),
   description: tolerantString(),
   type: WorkResultSectionTypeSchema.optional().catch(undefined),
   items: recordArray(WorkResultItemSchema).optional().catch(undefined),
@@ -523,6 +540,96 @@ export const WorkResultSurfaceDataSchema = z.object({
 });
 export type WorkResultSurfaceData = z.infer<typeof WorkResultSurfaceDataSchema>;
 
+/**
+ * A watch retrospective: what a teach session recorded, and the few things the
+ * recording could not settle.
+ *
+ * Carried as the `templateData` of a `card` surface under the `watch_retro`
+ * template, rather than as a surface type of its own. A renderer that does not
+ * know the template still knows `card`, so it draws the surface's `title`,
+ * `subtitle` and `body` instead of an unsupported-surface notice: the retro is
+ * the whole of what a finished session gives the user, so it has to survive a
+ * client older than the template.
+ *
+ * Rendered as a paged card, one thing per page: the record first, then a page
+ * per question. That shape is the payload's only real constraint: a question
+ * list long enough to scroll is a questionnaire, so `questions` is capped at
+ * three and the cap is enforced here rather than asked for in the prompt.
+ *
+ * Tolerant like every other surface schema. A malformed question is dropped
+ * and the rest of the card still renders, because the record is the half the
+ * user is owed and it does not depend on the questions parsing.
+ */
+export const WatchRetroQuestionKindSchema = z.enum(["fill", "pick", "gate"]);
+export type WatchRetroQuestionKind = z.infer<
+  typeof WatchRetroQuestionKindSchema
+>;
+
+/**
+ * One answer to a `pick` or `gate` question.
+ *
+ * **The first option is the default**, and that is the whole of the
+ * preselection contract. There is no `selected` flag to disagree with the
+ * ordering. On a `pick` it is the reading the recording supports; on a `gate`
+ * it is the cautious answer, which is the one case where the default is
+ * deliberately not the model's guess.
+ */
+export const WatchRetroOptionSchema = z.object({
+  id: coercedString(),
+  label: coercedString(),
+  /** Short qualifier under the label, e.g. marking the model's own reading. */
+  note: tolerantString(),
+});
+export type WatchRetroOption = z.infer<typeof WatchRetroOptionSchema>;
+
+export const WatchRetroQuestionSchema = z.object({
+  id: coercedString(),
+  kind: WatchRetroQuestionKindSchema.catch("pick"),
+  prompt: coercedString(),
+  /** Eyebrow above the prompt, naming why this one is being asked. */
+  eyebrow: tolerantString(),
+  /** `fill` only: the pre-filled value, so skipping keeps a working answer. */
+  suggestion: tolerantString(),
+  /** `pick` and `gate`: the alternatives. First is the default. */
+  options: recordArray(WatchRetroOptionSchema).optional().catch(undefined),
+});
+export type WatchRetroQuestion = z.infer<typeof WatchRetroQuestionSchema>;
+
+/** How many questions one card may carry. See the schema note. */
+export const WATCH_RETRO_MAX_QUESTIONS = 3;
+
+export const WatchRetroSurfaceDataSchema = z.object({
+  /** The task, named in one line. The card's title. */
+  task: coercedString(),
+  /** What the task is for. The one sentence that makes the steps mean something. */
+  purpose: tolerantString(),
+  /**
+   * The steps, in order, as imperative fragments rather than sentences:
+   * "Open the Sentry issue", not "You opened the Sentry issue from the alert
+   * email". It is about to become a procedure, so it reads as one already.
+   */
+  steps: z.preprocess(
+    (value) =>
+      Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string" && entry.trim())
+        : [],
+    z.array(z.string()),
+  ),
+  /** Session facts for the eyebrow, e.g. "Watched 4 min · 11 screens". */
+  eyebrow: tolerantString(),
+  /** Set when the recording was bounded, naming which end is missing. */
+  coverage: tolerantString(),
+  questions: z
+    .preprocess(
+      (value) =>
+        Array.isArray(value) ? value.slice(0, WATCH_RETRO_MAX_QUESTIONS) : [],
+      recordArray(WatchRetroQuestionSchema),
+    )
+    .optional()
+    .catch(undefined),
+});
+export type WatchRetroSurfaceData = z.infer<typeof WatchRetroSurfaceDataSchema>;
+
 /**
  * Inline visual: a self-contained html fragment rendered in a sandboxed
  * frame. Model-invokable via `ui_show`, which validates the fragment (no