@vellumai/assistant 0.10.1-staging.3 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.1-staging.3",
+  "version": "0.10.1",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/card-surface-data.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+
+import { CardSurfaceDataSchema } from "../api/surfaces.js";
+
+// The wire keeps surface `data` opaque and the stream drops events that fail to
+// parse, so the canonical card schema must never reject a real payload: every
+// field is optional and unknown keys are stripped. The daemon's `ui_show`
+// normalizer parses against this schema and logs the stripped keys — that is
+// how unsupported shapes are surfaced rather than silently swallowed.
+describe("CardSurfaceDataSchema", () => {
+  test("parses an empty object", () => {
+    expect(CardSurfaceDataSchema.safeParse({}).success).toBe(true);
+  });
+
+  test("parses a title-less card and strips unknown keys", () => {
+    const parsed = CardSurfaceDataSchema.safeParse({
+      body: "hi",
+      surfaceWidgetHint: "ignored",
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data).toEqual({ body: "hi" });
+    }
+  });
+
+  test("a body-less, title-only card is still valid (renders its title)", () => {
+    expect(CardSurfaceDataSchema.safeParse({ title: "Heads up" }).success).toBe(
+      true,
+    );
+  });
+
+  test("coerces primitive metadata values to strings", () => {
+    const parsed = CardSurfaceDataSchema.safeParse({
+      metadata: [
+        { label: "Docs", value: 12 },
+        { label: "Passed", value: true },
+        { label: "Status", value: "OK" },
+      ],
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data.metadata).toEqual([
+        { label: "Docs", value: "12" },
+        { label: "Passed", value: "true" },
+        { label: "Status", value: "OK" },
+      ]);
+    }
+  });
+
+  test("the schema's keys define what the normalizer supports", () => {
+    expect(Object.keys(CardSurfaceDataSchema.shape).sort()).toEqual([
+      "body",
+      "metadata",
+      "subtitle",
+      "template",
+      "templateData",
+      "title",
+    ]);
+  });
+});

package/src/__tests__/conversation-surfaces-activation-emit.test.ts

@@ -184,7 +184,7 @@ describe("activation moment emission from ui_show surface commits", () => {
     await surfaceProxyResolver(ctx, "ui_show", {
       surface_type: "card",
       title: "Inbox cleaned",
-      data: { text: "Archived 1,240 emails" },
+      data: { body: "Archived 1,240 emails" },
       activation_moment: "first_wow_executed",
     });
 
@@ -210,7 +210,7 @@ describe("activation moment emission from ui_show surface commits", () => {
     await surfaceProxyResolver(ctx, "ui_show", {
       surface_type: "card",
       title: "Result",
-      data: { text: "x" },
+      data: { body: "x" },
       activation_moment: "first_wow_executed",
     });
     expect(queryUnreportedOnboardingEvents(0, undefined, 10)).toHaveLength(0);
@@ -283,7 +283,7 @@ describe("activation moment emission from ui_show surface commits", () => {
     await surfaceProxyResolver(ctx, "ui_show", {
       surface_type: "card",
       title: "Start something",
-      data: { text: "Kick off a draft" },
+      data: { body: "Kick off a draft" },
       actions: [{ id: "go", label: "Go", style: "primary" }],
       activation_moment: "moment_1",
     });

package/src/__tests__/conversation-surfaces-task-progress.test.ts

@@ -576,3 +576,355 @@ describe("task_progress surface compatibility", () => {
     expect(sent.some((m) => m.type === "ui_surface_show")).toBe(true);
   });
 });
+
+describe("ui_show card content recovery", () => {
+  function shownCard(sent: ServerMessage[]): CardSurfaceData | undefined {
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    );
+    if (!show || show.surfaceType !== "card") return undefined;
+    return show.data;
+  }
+
+  test("recovers body from a copy_block-style `text` field", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Inbox cleaned",
+      data: { text: "Archived 1,240 emails" },
+    });
+
+    expect(result.isError).toBe(false);
+    const card = shownCard(sent);
+    expect(card?.body).toBe("Archived 1,240 emails");
+    // The alias key is not a card field; it must not survive on the surface.
+    expect((card as Record<string, unknown>).text).toBeUndefined();
+  });
+
+  test("recovers body from a confirmation-style `message` field", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Heads up", message: "The server will restart." },
+    });
+
+    expect(shownCard(sent)?.body).toBe("The server will restart.");
+  });
+
+  test("recovers top-level subtitle and metadata into the card", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      subtitle: "saved just now",
+      metadata: [{ label: "Total", value: "$10" }],
+      data: { body: "Done" },
+    });
+
+    const card = shownCard(sent);
+    expect(card?.subtitle).toBe("saved just now");
+    expect(card?.metadata).toEqual([{ label: "Total", value: "$10" }]);
+  });
+
+  test("title-only card with actions renders with actions intact", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Restart the server?",
+      actions: [{ id: "yes", label: "Yes" }],
+      data: {},
+    });
+
+    expect(result.isError).toBe(false);
+    expect(shownCard(sent)?.title).toBe("Restart the server?");
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    )!;
+    expect(show.actions).toBeDefined();
+    expect(show.actions!.length).toBe(1);
+    expect(show.actions![0].label).toBe("Yes");
+  });
+
+  test("title-only card without actions renders without error", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Status update",
+      data: {},
+    });
+
+    expect(result.isError).toBe(false);
+    expect(shownCard(sent)?.title).toBe("Status update");
+  });
+
+  test("card with body and actions is interactive", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Confirm",
+      actions: [{ id: "ok", label: "OK" }],
+      data: { body: "Are you sure?" },
+    });
+
+    expect(result.isError).toBe(false);
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    )!;
+    expect(show.actions).toBeDefined();
+    expect(show.actions!.length).toBe(1);
+  });
+
+  // ── Body alias recovery from cross-surface keys ────────────────────
+
+  test("recovers body from choice/form-style `description` field", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Search results",
+      data: { description: "Found 12 matching documents." },
+    });
+
+    const card = shownCard(sent);
+    expect(card?.body).toBe("Found 12 matching documents.");
+    expect((card as Record<string, unknown>).description).toBeUndefined();
+  });
+
+  test("recovers body from work_result-style `summary` field", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Report", summary: "All tests passed." },
+    });
+
+    expect(shownCard(sent)?.body).toBe("All tests passed.");
+  });
+
+  test("recovers body from confirmation-style `detail` field", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Warning", detail: "This action cannot be undone." },
+    });
+
+    expect(shownCard(sent)?.body).toBe("This action cannot be undone.");
+  });
+
+  test("recovers body from top-level `description`", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Info",
+      description: "Top-level description text",
+      data: {},
+    });
+
+    expect(shownCard(sent)?.body).toBe("Top-level description text");
+  });
+
+  test("concatenates multiple body aliases when they co-occur", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Multi-alias",
+      data: {
+        description: "Found 12 documents.",
+        summary: "Search complete.",
+        detail: "Checked 3 sources.",
+      },
+    });
+
+    const body = shownCard(sent)?.body;
+    expect(body).toContain("Found 12 documents.");
+    expect(body).toContain("Search complete.");
+    expect(body).toContain("Checked 3 sources.");
+  });
+
+  // ── Title alias recovery ────────────────────────────────────────────
+
+  test("recovers title from `heading` alias", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { heading: "Results", body: "Done." },
+    });
+
+    expect(shownCard(sent)?.title).toBe("Results");
+  });
+
+  test("recovers title from `header` alias", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { header: "Status Update", body: "All good." },
+    });
+
+    expect(shownCard(sent)?.title).toBe("Status Update");
+  });
+
+  // ── Subtitle alias recovery ─────────────────────────────────────────
+
+  test("recovers subtitle from `subheading` alias", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Alert", body: "Check this.", subheading: "Important" },
+    });
+
+    expect(shownCard(sent)?.subtitle).toBe("Important");
+  });
+
+  test("recovers subtitle from table-style `caption` alias", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Table Summary", body: "Data below.", caption: "Q4 2024" },
+    });
+
+    expect(shownCard(sent)?.subtitle).toBe("Q4 2024");
+  });
+
+  // ── Alias precedence ───────────────────────────────────────────────
+
+  test("canonical `body` takes precedence over aliased `description`", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { body: "Real body", description: "Should be ignored" },
+    });
+
+    expect(shownCard(sent)?.body).toBe("Real body");
+  });
+
+  test("card with recovered `description` and actions keeps actions (has content)", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Confirm",
+      actions: [{ id: "ok", label: "OK" }],
+      data: { description: "Proceed with deployment?" },
+    });
+
+    expect(result.isError).toBe(false);
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    )!;
+    expect(show.actions).toBeDefined();
+    expect(shownCard(sent)?.body).toBe("Proceed with deployment?");
+  });
+
+  test("recovers actions nested inside data when top-level actions is absent", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Confirm deployment",
+      data: {
+        body: "Deploy to production?",
+        actions: [{ id: "yes", label: "Yes" }],
+      },
+    });
+
+    expect(result.isError).toBe(false);
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    )!;
+    expect(show.actions).toBeDefined();
+    expect(show.actions!.length).toBe(1);
+    expect(show.actions![0].label).toBe("Yes");
+  });
+
+  test("top-level actions take precedence over data.actions", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Confirm",
+      actions: [{ id: "top", label: "Top-level" }],
+      data: {
+        body: "Which actions?",
+        actions: [{ id: "nested", label: "Nested" }],
+      },
+    });
+
+    const show = sent.find(
+      (m): m is UiSurfaceShow => m.type === "ui_surface_show",
+    )!;
+    expect(show.actions!.length).toBe(1);
+    expect(show.actions![0].label).toBe("Top-level");
+  });
+
+  test("genuinely empty card (no title, body, subtitle, metadata, template, or actions) is rejected", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: {},
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("requires content");
+    expect(sent.filter((m) => m.type === "ui_surface_show")).toHaveLength(0);
+  });
+
+  test("a card with a real body broadcasts unchanged", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Plain", body: "hi" },
+    });
+
+    expect(shownCard(sent)?.body).toBe("hi");
+  });
+
+  test("a task_progress card with empty data broadcasts (template renders a shell)", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      template: "task_progress",
+      templateData: { status: "in_progress", steps: [] },
+    });
+
+    expect(result.isError).toBe(false);
+    expect(shownCard(sent)?.template).toBe("task_progress");
+  });
+});

package/src/__tests__/dynamic-page-surface.test.ts

@@ -257,100 +257,6 @@ describe("ui_show dynamic_page app substitute guard", () => {
   });
 });
 
-describe("ui_show empty card guard", () => {
-  function makeCtx(onProxy: () => void) {
-    return {
-      conversationId: "conversation-123",
-      workingDir: "/tmp",
-      trustClass: "guardian" as const,
-      proxyToolResolver: async () => {
-        onProxy();
-        return { content: "proxied", isError: false };
-      },
-    };
-  }
-
-  test("rejects a card carrying only a title and does not proxy", async () => {
-    let proxied = false;
-    const result = await uiShowTool.execute(
-      {
-        surface_type: "card",
-        title: "Vellum Internal Usage app",
-        activity: "Showing progress",
-        data: {},
-      },
-      makeCtx(() => {
-        proxied = true;
-      }),
-    );
-
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain("card requires content");
-    expect(proxied).toBe(false);
-  });
-
-  test("rejects a card with no content at all", async () => {
-    let proxied = false;
-    const result = await uiShowTool.execute(
-      { surface_type: "card", data: {} },
-      makeCtx(() => {
-        proxied = true;
-      }),
-    );
-
-    expect(result.isError).toBe(true);
-    expect(proxied).toBe(false);
-  });
-
-  test("allows a card with a body", async () => {
-    let proxied = false;
-    const result = await uiShowTool.execute(
-      { surface_type: "card", data: { title: "Plain", body: "hi" } },
-      makeCtx(() => {
-        proxied = true;
-      }),
-    );
-
-    expect(result.isError).toBe(false);
-    expect(proxied).toBe(true);
-  });
-
-  test("allows a task_progress card with empty data (template renders a shell)", async () => {
-    let proxied = false;
-    const result = await uiShowTool.execute(
-      {
-        surface_type: "card",
-        template: "task_progress",
-        templateData: { status: "in_progress", steps: [] },
-      },
-      makeCtx(() => {
-        proxied = true;
-      }),
-    );
-
-    expect(result.isError).toBe(false);
-    expect(proxied).toBe(true);
-  });
-
-  test("allows an action-only card", async () => {
-    let proxied = false;
-    const result = await uiShowTool.execute(
-      {
-        surface_type: "card",
-        title: "Confirm",
-        actions: [{ id: "ok", label: "OK" }],
-        data: {},
-      },
-      makeCtx(() => {
-        proxied = true;
-      }),
-    );
-
-    expect(result.isError).toBe(false);
-    expect(proxied).toBe(true);
-  });
-});
-
 describe("ui_update empty payload guard", () => {
   function makeCtx(onProxy: () => void) {
     return {

package/src/api/events/ui-surface-show.ts

@@ -5,9 +5,14 @@
  * form, list, table, confirmation, dynamic_page, file_upload,
  * document_preview, task_preferences) inside the chat view. The
  * concrete `data` shape depends on `surfaceType` and is owned by the
- * surface-data subsystem in `daemon/message-types/surfaces.ts`; the
- * canonical schema treats `data` as opaque on the wire so this file
- * doesn't have to mirror eight nested-payload schemas.
+ * surface-data subsystem in `daemon/message-types/surfaces.ts`
+ * (`CardSurfaceDataSchema` et al.). `data` is intentionally opaque on the
+ * wire — not for brevity, but because (1) this event is a member of the
+ * `type`-discriminated `AssistantEventSchema`, and (2) the stream parser
+ * drops any event that fails validation, so a strict per-`surfaceType`
+ * payload schema would silently vanish renderable-but-messy LLM surfaces.
+ * Consumers narrow `data` by parsing it with the canonical per-type schema
+ * (all-optional, so it never rejects a real surface) at their boundary.
  *
  * Lifecycle: a surface progresses `show` → (zero or more `update`s) →
  * (`dismiss` for cancellation OR `complete` with a `summary` /

package/src/api/index.ts

@@ -471,6 +471,7 @@ export {
   type WorkflowLeaf,
   WorkflowLeafSchema,
 } from "./responses/workflow-journal.js";
+export { type CardSurfaceData, CardSurfaceDataSchema } from "./surfaces.js";
 
 /**
  * Canonical SSE event schema for the assistant runtime.

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

@@ -225,6 +225,10 @@ export type ConversationMessageToolCall = z.infer<
 // Surface
 // ---------------------------------------------------------------------------
 
+// Intentionally more permissive than the canonical SurfaceActionSchema in
+// api/events/ui-surface-show.ts: the write-path schema uses z.enum for style
+// so new surfaces only emit known values; this read-path schema uses z.string
+// so historical surfaces with non-standard style values still parse.
 const SurfaceActionSchema = z.object({
   id: z.string(),
   label: z.string(),

package/src/api/surfaces.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical surface-data wire payloads.
+ *
+ * The `ui_surface_*` events and the conversation-message response all carry a
+ * surface `data` object whose shape depends on `surfaceType`. The wire keeps
+ * `data` opaque (`z.record`) — see `events/ui-surface-show.ts` for why — so
+ * consumers narrow it by parsing with the canonical per-type schema here. The
+ * schemas are deliberately tolerant (every field optional, Zod strip mode): a
+ * parse miss makes a renderable surface silently vanish, so they must never
+ * reject a real payload. The schema also defines what the daemon's `ui_show`
+ * normalizer *supports* — anything the model sends outside these fields is
+ * dropped (and logged) there, which is how we learn the shapes to recover.
+ *
+ * Card is the first surface type migrated to a canonical schema; the remaining
+ * types still live as hand-written interfaces in
+ * `daemon/message-types/surfaces.ts` pending migration.
+ */
+
+import { z } from "zod";
+
+export const CardSurfaceDataSchema = z.object({
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  body: z.string().optional(),
+  metadata: z
+    .array(z.object({ label: z.coerce.string(), value: z.coerce.string() }))
+    .optional(),
+  /** Optional template name for specialized rendering (e.g. "weather_forecast"). */
+  template: z.string().optional(),
+  /** Arbitrary data consumed by the template renderer. Shape depends on template. */
+  templateData: z.record(z.string(), z.unknown()).optional(),
+});
+export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;

package/src/daemon/conversation-surfaces.ts

@@ -1,5 +1,9 @@
+import * as Sentry from "@sentry/node";
 import { v4 as uuid } from "uuid";
+import { z } from "zod";
 
+import { SurfaceActionSchema } from "../api/events/ui-surface-show.js";
+import { CardSurfaceDataSchema } from "../api/surfaces.js";
 import { isActivationSession } from "../memory/activation-session-store.js";
 import {
   addAppConversationId,
@@ -70,6 +74,16 @@ import type { TrustContext } from "./trust-context.js";
 
 const log = getLogger("conversation-surfaces");
 
+// Tolerant variant of SurfaceActionSchema for parsing raw model output.
+// The canonical schema rejects unknown style values; this one coerces them
+// to "secondary" so a single mistyped style doesn't drop all actions.
+const ModelActionSchema = SurfaceActionSchema.extend({
+  style: z
+    .enum(["primary", "secondary", "destructive"])
+    .catch("secondary")
+    .optional(),
+});
+
 const MAX_UNDO_DEPTH = 10;
 
 /**
@@ -472,6 +486,27 @@ function normalizeDynamicPageShowData(
   return normalized as unknown as DynamicPageSurfaceData;
 }
 
+/** First entry that is a non-empty (trimmed) string, else undefined. */
+function firstNonEmptyString(values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/** All non-empty (trimmed) strings from the values list. */
+function allNonEmptyStrings(values: unknown[]): string[] {
+  const result: string[] = [];
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      result.push(value);
+    }
+  }
+  return result;
+}
+
 function normalizeCardShowData(
   input: Record<string, unknown>,
   rawData: Record<string, unknown>,
@@ -507,6 +542,113 @@ function normalizeCardShowData(
     normalized.body = input.body;
   }
 
+  // The model sees every surface type's schema in the ui_show tool description,
+  // so it frequently borrows keys from sibling surfaces when emitting a card.
+  // Recover those into the canonical card fields, checking both data-level and
+  // top-level (input) placement. Multiple matches are concatenated (body) or
+  // first-wins (title/subtitle); all alias keys are deleted afterward so they
+  // don't appear as droppedKeys noise.
+  //
+  // body aliases: copy_block's `text`, confirmation's `message`, generic
+  // `content`, and cross-surface `description` (choice/form/oauth/work_result/
+  // dynamic_page — 5 types use it), work_result's `summary`, confirmation's
+  // `detail`.
+  const bodyAliasKeys = [
+    "text",
+    "message",
+    "content",
+    "description",
+    "summary",
+    "detail",
+  ] as const;
+  if (typeof normalized.body !== "string" || normalized.body.trim() === "") {
+    const candidates = allNonEmptyStrings(
+      bodyAliasKeys.map((k) => {
+        const dataVal = normalized[k];
+        if (typeof dataVal === "string" && dataVal.trim().length > 0)
+          return dataVal;
+        return input[k];
+      }),
+    );
+    if (candidates.length > 0) {
+      // Temporary: concatenate all matching aliases so no content is lost.
+      // A future pass should define per-alias semantic roles (e.g. summary
+      // as a subtitle, detail as supplementary) once production telemetry
+      // reveals which combinations actually occur.
+      normalized.body = candidates.join("\n\n");
+      const usedAliases = bodyAliasKeys.filter(
+        (k) =>
+          (typeof normalized[k] === "string" &&
+            (normalized[k] as string).trim().length > 0) ||
+          (typeof input[k] === "string" &&
+            (input[k] as string).trim().length > 0),
+      );
+      Sentry.addBreadcrumb({
+        category: "card-normalization",
+        message: `alias recovery: ${usedAliases.join(", ")} → body`,
+        level: "info",
+        data: { usedAliases, candidateCount: candidates.length },
+      });
+    }
+  }
+  for (const key of bodyAliasKeys) {
+    delete normalized[key];
+  }
+
+  // title aliases: natural synonyms the model reaches for when it doesn't
+  // use `title` verbatim.
+  const titleAliasKeys = ["heading", "header", "name"] as const;
+  if (typeof normalized.title !== "string" || normalized.title.trim() === "") {
+    const aliased = firstNonEmptyString([
+      ...titleAliasKeys.map((k) => normalized[k]),
+      ...titleAliasKeys.map((k) => input[k]),
+    ]);
+    if (aliased !== undefined) {
+      normalized.title = aliased;
+      Sentry.addBreadcrumb({
+        category: "card-normalization",
+        message: `alias recovery: title`,
+        level: "info",
+      });
+    }
+  }
+  for (const key of titleAliasKeys) {
+    delete normalized[key];
+  }
+
+  // subtitle aliases: table's `caption`, natural synonym `subheading`.
+  if (
+    typeof normalized.subtitle !== "string" &&
+    typeof input.subtitle === "string"
+  ) {
+    normalized.subtitle = input.subtitle;
+  }
+  const subtitleAliasKeys = ["subheading", "caption"] as const;
+  if (
+    typeof normalized.subtitle !== "string" ||
+    normalized.subtitle.trim() === ""
+  ) {
+    const aliased = firstNonEmptyString([
+      ...subtitleAliasKeys.map((k) => normalized[k]),
+      ...subtitleAliasKeys.map((k) => input[k]),
+    ]);
+    if (aliased !== undefined) {
+      normalized.subtitle = aliased;
+      Sentry.addBreadcrumb({
+        category: "card-normalization",
+        message: `alias recovery: subtitle`,
+        level: "info",
+      });
+    }
+  }
+  for (const key of subtitleAliasKeys) {
+    delete normalized[key];
+  }
+
+  if (!Array.isArray(normalized.metadata) && Array.isArray(input.metadata)) {
+    normalized.metadata = input.metadata;
+  }
+
   // task_progress cards: additional fallbacks for title from templateData.
   if (
     normalized.template === "task_progress" &&
@@ -533,7 +675,40 @@ function normalizeCardShowData(
     ensureTaskProgressTemplateData(normalized);
   }
 
-  return normalized as unknown as CardSurfaceData;
+  // Parse, don't assert. The old `as unknown as CardSurfaceData` accepted any
+  // shape, so anything the model nested under an unmodelled key was carried
+  // through unread. Parsing draws the boundary; the dropped-key log surfaces
+  // the shapes we still don't recover, so the recovery list above can grow from
+  // real traffic rather than guesswork.
+  const droppedKeys = Object.keys(normalized).filter(
+    (key) => !(key in CardSurfaceDataSchema.shape),
+  );
+  if (droppedKeys.length > 0) {
+    log.warn(
+      { droppedKeys },
+      "ui_show card data carried keys the card contract does not model; their content will not render",
+    );
+    Sentry.addBreadcrumb({
+      category: "card-normalization",
+      message: `dropped keys: ${droppedKeys.join(", ")}`,
+      level: "warning",
+      data: { droppedKeys },
+    });
+  }
+  const parsed = CardSurfaceDataSchema.safeParse(normalized);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  log.warn(
+    { issues: parsed.error.issues },
+    "ui_show card data failed CardSurfaceDataSchema; rendering only the fields that validated",
+  );
+  return CardSurfaceDataSchema.parse({
+    title: typeof normalized.title === "string" ? normalized.title : undefined,
+    subtitle:
+      typeof normalized.subtitle === "string" ? normalized.subtitle : undefined,
+    body: typeof normalized.body === "string" ? normalized.body : undefined,
+  });
 }
 
 function normalizeTaskProgressCardPatch(
@@ -2693,9 +2868,17 @@ export async function surfaceProxyResolver(
     const surfaceType = input.surface_type as SurfaceType;
     const title = typeof input.title === "string" ? input.title : undefined;
     const rawData = isPlainObject(input.data) ? input.data : {};
-    const data = (
+    // Each surface type that has a canonical Zod schema gets parsed through it;
+    // the rest pass through raw until migrated (LUM-2134 scope). The per-type
+    // normalizers validate+recover; the union cast at the end is only for the
+    // unmigrated branches that still return hand-written interfaces.
+    const cardData =
       surfaceType === "card"
         ? normalizeCardShowData(input, rawData)
+        : undefined;
+    const data: SurfaceData =
+      cardData !== undefined
+        ? cardData
         : surfaceType === "choice"
           ? normalizeChoiceShowData(rawData)
           : surfaceType === "copy_block"
@@ -2704,21 +2887,43 @@ export async function surfaceProxyResolver(
               ? normalizeOAuthConnectShowData(rawData)
               : surfaceType === "dynamic_page"
                 ? normalizeDynamicPageShowData(input, rawData)
-                : rawData
-    ) as SurfaceData;
-    const inputActions = input.actions as
-      | Array<{
-          id: string;
-          label: string;
-          style?: string;
-          data?: Record<string, unknown>;
-        }>
-      | undefined;
+                : (rawData as SurfaceData);
+    // Parse actions through the schema instead of typecasting raw model output.
+    // The model may place actions inside `data` instead of the top-level
+    // `actions` param — recover them so they aren't silently dropped.
+    const rawActions = Array.isArray(input.actions)
+      ? input.actions
+      : Array.isArray(rawData.actions)
+        ? rawData.actions
+        : undefined;
+    let inputActions: z.infer<typeof ModelActionSchema>[] | undefined;
+    if (rawActions) {
+      const valid: z.infer<typeof ModelActionSchema>[] = [];
+      for (const raw of rawActions) {
+        const result = ModelActionSchema.safeParse(raw);
+        if (result.success) {
+          valid.push(result.data);
+        } else {
+          Sentry.addBreadcrumb({
+            category: "card-normalization",
+            message: "action parse failure (individual)",
+            level: "warning",
+            data: {
+              issuePaths: result.error.issues.map((i) => i.path.join(".")),
+              keys:
+                typeof raw === "object" && raw !== null
+                  ? Object.keys(raw)
+                  : [typeof raw],
+            },
+          });
+        }
+      }
+      inputActions = valid.length > 0 ? valid : undefined;
+    }
     const actions =
       surfaceType === "choice"
         ? buildChoiceActions(data as ChoiceSurfaceData)
         : inputActions;
-    // Interactive surfaces default to awaiting user action.
     const hasActions = Array.isArray(actions) && actions.length > 0;
     if (surfaceType === "choice" && !hasActions) {
       return {
@@ -2727,6 +2932,39 @@ export async function surfaceProxyResolver(
         isError: true,
       };
     }
+    if (cardData !== undefined) {
+      const hasTitle =
+        (typeof title === "string" && title.trim().length > 0) ||
+        (typeof cardData.title === "string" &&
+          cardData.title.trim().length > 0);
+      const hasBody =
+        typeof cardData.body === "string" && cardData.body.trim().length > 0;
+      const hasSubtitle =
+        typeof cardData.subtitle === "string" &&
+        cardData.subtitle.trim().length > 0;
+      const hasMetadata =
+        Array.isArray(cardData.metadata) && cardData.metadata.length > 0;
+      const hasTemplate = typeof cardData.template === "string";
+      if (
+        !hasTitle &&
+        !hasBody &&
+        !hasSubtitle &&
+        !hasMetadata &&
+        !hasTemplate &&
+        !hasActions
+      ) {
+        Sentry.addBreadcrumb({
+          category: "card-normalization",
+          message: "empty card rejected",
+          level: "warning",
+        });
+        return {
+          content:
+            "Error: ui_show card requires content — provide `data.body`, a `template` (e.g. task_progress with steps), `data.metadata`, `data.subtitle`, a `title`, or `actions`. The surface was not displayed because it carried no renderable content. Resend ui_show with populated card content.",
+          isError: true,
+        };
+      }
+    }
     const oauthProviderKey =
       surfaceType === "oauth_connect"
         ? (data as unknown as Record<string, unknown>).providerKey
@@ -2741,6 +2979,7 @@ export async function surfaceProxyResolver(
         isError: true,
       };
     }
+
     const isInteractive =
       surfaceType === "card"
         ? hasActions
@@ -2777,10 +3016,7 @@ export async function surfaceProxyResolver(
     const mappedActions = actions?.map((a) => ({
       id: a.id,
       label: a.label,
-      style: (a.style ?? "secondary") as
-        | "primary"
-        | "secondary"
-        | "destructive",
+      style: a.style ?? "secondary",
       ...(a.data ? { data: a.data } : {}),
     }));
 
@@ -2896,7 +3132,26 @@ export async function surfaceProxyResolver(
         const currentHtml = (stored.data as DynamicPageSurfaceData).html;
         pushUndoState(ctx.surfaceUndoStacks, surfaceId, currentHtml);
       }
-      mergedData = { ...stored.data, ...patch } as SurfaceData;
+      const rawMerged = { ...stored.data, ...patch };
+      if (stored.surfaceType === "card") {
+        // Validate the merged card data through the canonical schema so
+        // malformed patches (e.g. metadata as a string) are caught here
+        // instead of crashing the client's safeParse.
+        const parsed = CardSurfaceDataSchema.safeParse(rawMerged);
+        mergedData = parsed.success
+          ? parsed.data
+          : (CardSurfaceDataSchema.safeParse(stored.data).data ?? {});
+        if (!parsed.success) {
+          log.warn(
+            { surfaceId, issues: parsed.error.issues },
+            "ui_update card patch produced invalid merged data; reverting to stored data",
+          );
+        }
+      } else {
+        // Other surface types lack canonical Zod schemas (LUM-2134 scope).
+        // The raw merge is the best we can do until they're migrated.
+        mergedData = rawMerged as SurfaceData;
+      }
       stored.data = mergedData;
     } else {
       mergedData = patch as unknown as SurfaceData;

package/src/daemon/message-types/surfaces.ts

@@ -1,6 +1,16 @@
 // Surface types, UI surface lifecycle messages.
 
-import { z } from "zod";
+import {
+  type CardSurfaceData,
+  CardSurfaceDataSchema,
+} from "../../api/surfaces.js";
+
+// Surface `data` shapes are wire payloads owned by `@vellumai/assistant-api`.
+// Card is migrated (canonical Zod schema); the remaining types below are still
+// hand-written interfaces pending migration. Re-exported so the daemon's
+// surface protocol barrel (`message-protocol.ts`) keeps surfacing them to
+// daemon consumers under their canonical names.
+export { type CardSurfaceData, CardSurfaceDataSchema };
 
 // === Surface type definitions ===
 
@@ -37,25 +47,6 @@ export interface SurfaceAction {
   data?: Record<string, unknown>;
 }
 
-/**
- * Card surface data. Defined as a Zod schema so the type is derived (not
- * hand-maintained) and the seed-content-block schema can compose it directly
- * instead of treating card `data` as an opaque record.
- */
-export const CardSurfaceDataSchema = z.object({
-  title: z.string(),
-  subtitle: z.string().optional(),
-  body: z.string(),
-  metadata: z
-    .array(z.object({ label: z.string(), value: z.string() }))
-    .optional(),
-  /** Optional template name for specialized rendering (e.g. "weather_forecast"). */
-  template: z.string().optional(),
-  /** Arbitrary data consumed by the template renderer. Shape depends on template. */
-  templateData: z.record(z.string(), z.unknown()).optional(),
-});
-export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;
-
 export interface ChoiceOption {
   id: string;
   title: string;

package/src/tools/ui-surface/definitions.ts

@@ -45,14 +45,6 @@ function proxyExecute(toolName: string) {
       };
     }
 
-    if (toolName === "ui_show" && isEmptyCard(input)) {
-      return {
-        content:
-          "Error: ui_show card requires content — provide `data.body`, a `template` (e.g. task_progress with steps), `data.metadata`, or `actions`. The surface was not displayed because it carried only a title, which renders as a blank box. Resend ui_show with populated card content.",
-        isError: true,
-      };
-    }
-
     if (toolName === "ui_show" && isDynamicPageAppSubstitute(input)) {
       return {
         content:
@@ -168,41 +160,6 @@ function isEmptyDynamicPage(input: Record<string, unknown>): boolean {
   return typeof html !== "string" || html.trim().length === 0;
 }
 
-/**
- * A `card` ui_show carrying no renderable content — only a title (or nothing)
- * — renders as a blank bordered box. A declared `template` (task_progress,
- * weather_forecast, …) renders its own shell, and `body`/`subtitle`/`metadata`/
- * `actions` are real content; any of those passes. The model places these
- * either nested in `data` or at the top level, so both are checked. Title is
- * intentionally not content: a title-only card is the blank box.
- */
-function isEmptyCard(input: Record<string, unknown>): boolean {
-  if (input.surface_type !== "card") {
-    return false;
-  }
-  const data = asRecord(input.data) ?? {};
-
-  const template =
-    nonEmptyString(input.template) ?? nonEmptyString(data.template);
-  if (template) {
-    return false;
-  }
-
-  const hasBody = !!(nonEmptyString(input.body) ?? nonEmptyString(data.body));
-  const hasSubtitle = !!nonEmptyString(data.subtitle);
-  const hasMetadata = Array.isArray(data.metadata) && data.metadata.length > 0;
-  const actions = input.actions ?? data.actions;
-  const hasActions = Array.isArray(actions) && actions.length > 0;
-
-  return !(hasBody || hasSubtitle || hasMetadata || hasActions);
-}
-
-function nonEmptyString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim().length > 0
-    ? value
-    : undefined;
-}
-
 function isDynamicPageAppSubstitute(input: Record<string, unknown>): boolean {
   if (input.surface_type !== "dynamic_page") {
     return false;