@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

package/src/tools/tool-profiler.ts

@@ -33,11 +33,31 @@ export class ToolProfiler {
   startRequest(): void {
     this.tools.clear();
     this.requestStartMs = Date.now();
-    const rss = process.memoryUsage().rss;
+    const rss = this.sampleRssBytes() ?? 0;
     this.rssStartBytes = rss;
     this.peakRssBytes = rss;
   }
 
+  /**
+   * Sample the current RSS in bytes, returning `null` if the reading fails.
+   *
+   * Bun 1.3.11 can throw `SystemError: Failed to get memory usage, errno: 2`
+   * from the underlying syscall. Resource metrics are best-effort — a failed
+   * sample must never propagate, so it is logged and reported as `null` and the
+   * caller keeps its last known peak.
+   */
+  private sampleRssBytes(): number | null {
+    try {
+      return process.memoryUsage().rss;
+    } catch (err) {
+      log.warn(
+        { err },
+        "Failed to sample RSS memory; skipping profiler sample",
+      );
+      return null;
+    }
+  }
+
   recordToolCompletion(
     toolName: string,
     durationMs: number,
@@ -57,8 +77,8 @@ export class ToolProfiler {
       stats.errors++;
     }
 
-    const currentRss = process.memoryUsage().rss;
-    if (currentRss > this.peakRssBytes) {
+    const currentRss = this.sampleRssBytes();
+    if (currentRss !== null && currentRss > this.peakRssBytes) {
       this.peakRssBytes = currentRss;
     }
   }
@@ -156,6 +176,10 @@ export function startToolProfilingRequest(conversationId: string): void {
 /**
  * Record a completed tool invocation into the conversation's profiler.
  * A no-op when no profiling window is active (e.g. standalone tool runs).
+ *
+ * The tool has already completed by the time this runs, so profiling is pure
+ * observation: any failure here is swallowed and logged rather than allowed to
+ * propagate into the executor and fail the agent loop.
  */
 export function recordToolCompletion(
   conversationId: string,
@@ -163,9 +187,16 @@ export function recordToolCompletion(
   durationMs: number,
   isError: boolean,
 ): void {
-  profilersByConversation
-    .get(conversationId)
-    ?.recordToolCompletion(toolName, durationMs, isError);
+  try {
+    profilersByConversation
+      .get(conversationId)
+      ?.recordToolCompletion(toolName, durationMs, isError);
+  } catch (err) {
+    log.warn(
+      { err, conversationId, toolName },
+      "Tool profiler failed to record completion; continuing",
+    );
+  }
 }
 
 /** Emit the end-of-turn profiling summary log for a conversation. */

package/src/tools/ui-surface/channel-variants.ts

@@ -0,0 +1,101 @@
+/**
+ * Per-conversation wire projections of the UI surface tool definitions.
+ *
+ * Slack renders exactly one surface — the task_progress card (everything else
+ * is rejected at execution; see `isSlackTaskProgressUiException` in
+ * `daemon/conversation-surfaces.ts`) — so Slack conversations get a `ui_show`
+ * variant documenting only that shape instead of the full multi-surface docs.
+ * Activation-rail conversations additionally get the `activation_moment`
+ * telemetry param, which no other conversation pays schema tokens for (the
+ * emit path is gated on `isActivationSession` regardless).
+ *
+ * Projection contract: shared definition objects are never mutated (variants
+ * are module-level constants swapped in via spread-copy), and the projected
+ * set is a pure function of per-conversation-stable state, so a
+ * conversation's tools+system prompt-cache prefix stays stable across turns.
+ */
+
+import type { ToolDefinition } from "../../providers/types.js";
+import { ACTIVATION_MOMENT_PARAMS } from "../../telemetry/activation-funnel.js";
+import { TASK_PROGRESS_TEMPLATE_SHAPE } from "./surface-shape-docs.js";
+
+const SLACK_UI_SHOW_DESCRIPTION = `Show a live task-progress card for the current work — the only surface this channel renders. data: { template: "task_progress", templateData: ${TASK_PROGRESS_TEMPLATE_SHAPE} }. Show it early on multi-step turns and advance step statuses via ui_update as work progresses.`;
+
+const SLACK_UI_SHOW_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    surface_type: {
+      type: "string",
+      enum: ["card"],
+      description: "Always card on this channel",
+    },
+    title: {
+      type: "string",
+      description: "Optional surface title",
+    },
+    data: {
+      type: "object",
+      description:
+        'Card data: { template: "task_progress", templateData: { title, status, steps } }',
+    },
+  },
+  required: ["surface_type", "data"],
+};
+
+/**
+ * Swap UI surface tool definitions for channel-appropriate variants. Returns
+ * the input array unchanged (same identity) for channels without a variant.
+ */
+export function projectUiToolsForChannel(
+  definitions: ToolDefinition[],
+  channel: string | undefined,
+): ToolDefinition[] {
+  if (channel !== "slack") {
+    return definitions;
+  }
+  return definitions.map((def) =>
+    def.name === "ui_show"
+      ? {
+          ...def,
+          description: SLACK_UI_SHOW_DESCRIPTION,
+          input_schema: SLACK_UI_SHOW_INPUT_SCHEMA,
+        }
+      : def,
+  );
+}
+
+const ACTIVATION_MOMENT_PROPERTY = {
+  type: "string",
+  enum: ACTIVATION_MOMENT_PARAMS,
+  description:
+    "Activation-rail telemetry tag. Set this when this surface IS one of the activation funnel moments; the milestone is recorded automatically when the user commits the surface. Omit for all non-activation surfaces.",
+};
+
+/**
+ * Add the optional `activation_moment` param to ui_show's schema. Applied
+ * only for activation-rail conversations (`isActivationSession`) — the rail
+ * bootstrap prompt instructs the tagging, and the daemon's emit path reads
+ * the tag from tool input independently of this schema.
+ */
+export function injectActivationMomentParam(
+  definitions: ToolDefinition[],
+): ToolDefinition[] {
+  return definitions.map((def) => {
+    if (def.name !== "ui_show") {
+      return def;
+    }
+    const schema = def.input_schema as {
+      properties?: Record<string, unknown>;
+    };
+    return {
+      ...def,
+      input_schema: {
+        ...schema,
+        properties: {
+          ...schema.properties,
+          activation_moment: ACTIVATION_MOMENT_PROPERTY,
+        },
+      },
+    };
+  });
+}

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

@@ -2,19 +2,25 @@
  * UI surface tool definitions.
  *
  * These tools allow the model to show, update, and dismiss just-in-time UI
- * surfaces (cards, forms, lists, confirmations) on a connected macOS client.
+ * surfaces (cards, tables, forms, confirmations) on a connected macOS client.
  * They are proxy tools -- execution is forwarded to the client and never
  * handled locally by the daemon.
  */
 
 import { RiskLevel } from "../../permissions/types.js";
 import { isWeakOpenModel } from "../../providers/weak-open-model.js";
-import { ACTIVATION_MOMENT_PARAMS } from "../../telemetry/activation-funnel.js";
 import type {
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
+import {
+  asRecord,
+  hasContent,
+  SURFACE_TYPE_NAMES,
+  UI_SHOW_TYPE_DOCS,
+  uiShowTeachingError,
+} from "./surface-shape-docs.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -36,6 +42,13 @@ function proxyExecute(toolName: string) {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> => {
+    if (toolName === "ui_show") {
+      const teachingError = uiShowTeachingError(input);
+      if (teachingError !== null) {
+        return { content: teachingError, isError: true };
+      }
+    }
+
     if (toolName === "ui_show" && isEmptyDynamicPage(input)) {
       return {
         content: isWeakOpenModel(context.attribution?.resolvedModel)
@@ -135,22 +148,6 @@ function isEmptyUpdate(input: Record<string, unknown>): boolean {
   return data === null || !hasContent(data);
 }
 
-function hasContent(value: unknown): boolean {
-  if (value === null || value === undefined) {
-    return false;
-  }
-  if (Array.isArray(value)) {
-    return value.length > 0;
-  }
-  if (typeof value === "object") {
-    return Object.values(value).some(hasContent);
-  }
-  if (typeof value === "string") {
-    return value.trim().length > 0;
-  }
-  return true;
-}
-
 function isEmptyDynamicPage(input: Record<string, unknown>): boolean {
   if (input.surface_type !== "dynamic_page") {
     return false;
@@ -211,12 +208,6 @@ function collectRoutingText(input: Record<string, unknown>): string[] {
   return values;
 }
 
-function asRecord(value: unknown): Record<string, unknown> | null {
-  return value !== null && typeof value === "object"
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
 function addString(values: string[], value: unknown): void {
   if (typeof value === "string") {
     values.push(value);
@@ -231,21 +222,7 @@ export const uiShowTool = {
   name: "ui_show",
   description:
     'Surface structured data or UI in the conversation. For long-form writing use the document skill. For interactive apps, dashboards, games, calculators, or durable tools, call `skill_load` with `skill: "app-builder"` and use the app-builder workflow; do not use `dynamic_page` as a substitute for a persistent app. App-like `dynamic_page` calls are rejected.\n\n' +
-    "Surface types (data shapes):\n" +
-    '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
-    "- copy_block: { text, label?, language? }. Shows copyable text with a visible copy button; use for prompts, commands, paths, or snippets the user should copy.\n" +
-    '- choice: { description?, options: [{ id, title, description?, recommended?, data? }], selectionMode?: "single"|"multiple", commitOnSelect?, submitLabel? }. Single-select choices commit on option click by default. Use for outcome offers and follow-up choices; mark the strongest option with recommended: true.\n' +
-    "- oauth_connect: { providerKey, displayName?, description?, logoUrl? }. Shows a managed OAuth connection CTA in chat; use when the current task needs a managed integration account (Google, Linear, GitHub, etc.) instead of asking the user to visit settings or attempting OAuth through shell/tools. The client supplies the CTA label. Do not include OAuth scopes in the surface; managed providers use the platform's configured scopes.\n" +
-    '- table: { columns: [{ id, label }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
-    '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
-    '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
-    "- confirmation: { message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }\n" +
-    "- dynamic_page: { html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } }\n" +
-    "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n" +
-    "- task_preferences: {} (no data needed — categories are rendered client-side)\n" +
-    '- work_result: { eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] }. Shows a structured receipt after real work: what changed, what was skipped, proof points, and next actions. Keep display-only unless explicit follow-up buttons are needed.\n' +
-    '- channel_setup: { channel: "slack" | "telegram" | "phone" }. Opens the channel setup panel in a side drawer. Returns success only after a connected client confirms the panel rendered (an error means the user does NOT see the panel — never claim it is open after an error). The user then completes credential entry at their own pace. Slack shows a full setup wizard; Telegram and Phone show credential forms (the assistant handles remaining setup steps like webhooks in chat after the user saves credentials).\n\n' +
-    "For multi-step or long-running turns (web searches, file operations, research), show a task_progress card early and keep its steps updated as work progresses. Coarse steps are fine, and you can add or revise them as the work takes shape — a rough card beats no signal.",
+    UI_SHOW_TYPE_DOCS,
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
@@ -255,26 +232,12 @@ export const uiShowTool = {
     properties: {
       surface_type: {
         type: "string",
-        enum: [
-          "card",
-          "channel_setup",
-          "choice",
-          "copy_block",
-          "oauth_connect",
-          "form",
-          "list",
-          "table",
-          "confirmation",
-          "dynamic_page",
-          "file_upload",
-          "task_preferences",
-          "work_result",
-        ],
+        enum: SURFACE_TYPE_NAMES,
         description: "The type of surface to display",
       },
       title: {
         type: "string",
-        description: "Optional title for the surface window",
+        description: "Optional surface title",
       },
       data: {
         type: "object",
@@ -286,12 +249,11 @@ export const uiShowTool = {
         items: {
           type: "object",
           properties: {
-            id: { type: "string", description: "Unique action identifier" },
-            label: { type: "string", description: "Button label text" },
+            id: { type: "string" },
+            label: { type: "string" },
             style: {
               type: "string",
               enum: ["primary", "secondary", "destructive"],
-              description: "Visual style of the button",
             },
           },
           required: ["id", "label"],
@@ -302,23 +264,17 @@ export const uiShowTool = {
         type: "string",
         enum: ["inline", "panel"],
         description:
-          'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline". Prefer inline — only use panel when a separate window is explicitly requested.',
+          'Where to render: "inline" (default, embedded in chat) or "panel" (floating window; only when explicitly requested)',
       },
       await_action: {
         type: "boolean",
         description:
-          "Whether to block until an action is selected. Defaults to true when actions are provided.",
+          "Block until an action is selected. Defaults to true when actions are provided.",
       },
       persistent: {
         type: "boolean",
         description:
-          "When true, clicking an action does not dismiss the surface — the card stays visible and only the clicked action is marked as spent. Use for launcher or menu-style cards where multiple buttons may be clicked. Defaults to false.",
-      },
-      activation_moment: {
-        type: "string",
-        enum: ACTIVATION_MOMENT_PARAMS,
-        description:
-          "Activation-rail telemetry tag (cohort only). Set this when this surface IS one of the activation funnel moments; the milestone is recorded automatically when the user commits the surface. Omit for all non-activation surfaces.",
+          "Keep the surface visible after an action is clicked (clicked actions are marked spent). For launcher/menu cards. Defaults to false.",
       },
     },
     required: ["surface_type", "data"],

package/src/tools/ui-surface/surface-shape-docs.ts

@@ -0,0 +1,229 @@
+/**
+ * Point-of-use shape documentation and essential-content guards for ui_show
+ * surfaces.
+ *
+ * Each entry documents one surface type: a one-phrase `purpose` (used in the
+ * unknown-type index error) and the full data `shape` spec (returned inside a
+ * teaching error when a payload is missing its load-bearing content). Keeping
+ * the specs here rather than in the always-present tool description lets the
+ * model recover the exact shape at the moment it gets one wrong.
+ *
+ * Guards are advisory and intentionally minimal: they check only the fields
+ * without which the surface renders blank or broken (mirroring the tolerant
+ * contract in `api/surfaces.ts` — a renderable payload must never be
+ * rejected). Normalization the daemon already performs (e.g. top-level
+ * `template`/`title` lifted into card data by `normalizeCardShowData`) must
+ * stay accepted, so card has no guard here.
+ */
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Whether a value carries any renderable content: a non-empty string, a
+ * non-empty array, a non-empty primitive, or an object with at least one
+ * content-bearing value (recursively).
+ */
+export function hasContent(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (typeof value === "object") {
+    return Object.values(value).some(hasContent);
+  }
+  if (typeof value === "string") {
+    return value.trim().length > 0;
+  }
+  return true;
+}
+
+function isNonEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isNonEmptyArray(value: unknown): boolean {
+  return Array.isArray(value) && value.length > 0;
+}
+
+interface SurfaceShapeDoc {
+  /** One-phrase purpose, shown in the unknown-surface_type index error. */
+  purpose: string;
+  /** Full `data` shape spec, shown in per-type teaching errors. */
+  shape: string;
+  /**
+   * Returns a description of the missing load-bearing content, or null when
+   * the payload has enough to render. Absent for types the daemon normalizes
+   * leniently (card), that render fine with defaults (file_upload), or that
+   * have bespoke handling (dynamic_page).
+   */
+  missingContent?: (data: Record<string, unknown>) => string | null;
+}
+
+/** templateData shape of a task_progress card (shared with channel variants). */
+export const TASK_PROGRESS_TEMPLATE_SHAPE =
+  '{ title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] }';
+
+export const SURFACE_SHAPE_DOCS: Record<string, SurfaceShapeDoc> = {
+  card: {
+    purpose: "structured info card, supports templates like task_progress",
+    shape: `{ title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Template "task_progress" renders a live step tracker — templateData: ${TASK_PROGRESS_TEMPLATE_SHAPE}; advance it via ui_update as steps finish. Other card templates are documented by the skills that use them`,
+  },
+  copy_block: {
+    purpose: "copyable text with a visible copy button",
+    shape:
+      "{ text, label?, language? } — shows copyable text with a visible copy button; use for prompts, commands, paths, or snippets the user should copy",
+    missingContent: (data) =>
+      isNonEmptyString(data.text)
+        ? null
+        : "`data.text` must be a non-empty string",
+  },
+  choice: {
+    purpose: "clickable options for the user to pick from",
+    shape:
+      '{ description?, options: [{ id, title, description?, recommended?, data? }], selectionMode?: "single"|"multiple", commitOnSelect?, submitLabel? }. Single-select choices commit on option click by default; mark the strongest option with recommended: true',
+    missingContent: (data) =>
+      isNonEmptyArray(data.options)
+        ? null
+        : "`data.options` must be a non-empty array",
+  },
+  table: {
+    purpose: "tabular data, optionally with selectable rows",
+    shape:
+      '{ columns: [{ id, label }], rows: [{ id, cells: Record<columnId, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }',
+    missingContent: (data) =>
+      isNonEmptyArray(data.columns)
+        ? null
+        : "`data.columns` must be a non-empty array",
+  },
+  work_result: {
+    purpose: "structured receipt after completed work",
+    shape:
+      '{ eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] } — structured receipt after real work; keep display-only unless follow-up buttons are needed',
+    missingContent: (data) =>
+      hasContent(data)
+        ? null
+        : "`data` must carry at least a summary, metrics, or sections",
+  },
+  oauth_connect: {
+    purpose: "managed OAuth connection button for an integration account",
+    shape:
+      "{ providerKey, displayName?, description?, logoUrl? } — managed OAuth connection CTA; use when the task needs a managed integration account (Google, Linear, GitHub, ...) instead of settings or shell OAuth. Do not include OAuth scopes; managed providers use the platform's configured scopes",
+    missingContent: (data) =>
+      isNonEmptyString(data.providerKey)
+        ? null
+        : "`data.providerKey` must name the provider to connect",
+  },
+  form: {
+    purpose: "input form, single or multi-page",
+    shape:
+      '{ description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }',
+    missingContent: (data) =>
+      isNonEmptyArray(data.fields) || isNonEmptyArray(data.pages)
+        ? null
+        : "`data.fields` (or `data.pages`) must be a non-empty array",
+  },
+  confirmation: {
+    purpose: "confirm/cancel prompt",
+    shape:
+      "{ message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }",
+    missingContent: (data) =>
+      isNonEmptyString(data.message)
+        ? null
+        : "`data.message` must be a non-empty string",
+  },
+  file_upload: {
+    purpose: "prompt the user to upload files",
+    shape: "{ prompt, acceptedTypes?, maxFiles? }",
+  },
+  dynamic_page: {
+    purpose: "custom HTML page for transient UI only, never app-like builds",
+    shape:
+      "{ html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } } — custom visual HTML for transient surfaces only, never app-like builds",
+  },
+  channel_setup: {
+    purpose: "open the Slack/Telegram/Phone setup panel",
+    shape: '{ channel: "slack" | "telegram" | "phone" }',
+    missingContent: (data) =>
+      data.channel === "slack" ||
+      data.channel === "telegram" ||
+      data.channel === "phone"
+        ? null
+        : '`data.channel` must be one of "slack", "telegram", "phone"',
+  },
+};
+
+/** Model-facing surface_type enum, derived so docs and schema cannot drift. */
+export const SURFACE_TYPE_NAMES = Object.keys(SURFACE_SHAPE_DOCS);
+
+const SURFACE_TYPE_INDEX = SURFACE_TYPE_NAMES.map(
+  (name) => `${name} (${SURFACE_SHAPE_DOCS[name]!.purpose})`,
+).join("; ");
+
+/**
+ * Types whose full shape rides in the always-present tool description —
+ * together they cover ~95% of fleet ui_show calls. The rest appear there as
+ * a one-line index and get their shape from the teaching error on first
+ * misuse.
+ */
+const HOT_SURFACE_TYPES = [
+  "card",
+  "copy_block",
+  "choice",
+  "table",
+  "work_result",
+  "oauth_connect",
+  "dynamic_page",
+] as const;
+
+const COLD_SURFACE_INDEX = SURFACE_TYPE_NAMES.filter(
+  (name) => !(HOT_SURFACE_TYPES as readonly string[]).includes(name),
+)
+  .map((name) => `${name} (${SURFACE_SHAPE_DOCS[name]!.purpose})`)
+  .join(", ");
+
+/** The surface-types section of the ui_show tool description. */
+export const UI_SHOW_TYPE_DOCS = [
+  "Surface types (data shapes):",
+  ...HOT_SURFACE_TYPES.map(
+    (name) => `- ${name}: ${SURFACE_SHAPE_DOCS[name]!.shape}`,
+  ),
+  `Other types: ${COLD_SURFACE_INDEX}. Send your best-guess data — if required content is missing, the error returns the exact shape.`,
+].join("\n");
+
+/**
+ * Teaching error for a ui_show payload that would render nothing, or null
+ * when the payload is displayable. Unknown/missing surface_type gets the
+ * full type index; a known type missing its load-bearing content gets that
+ * type's exact shape. dynamic_page emptiness is handled by the bespoke
+ * model-aware envelopes in `definitions.ts`, not here.
+ */
+export function uiShowTeachingError(
+  input: Record<string, unknown>,
+): string | null {
+  const surfaceType = input.surface_type;
+  if (
+    typeof surfaceType !== "string" ||
+    !Object.hasOwn(SURFACE_SHAPE_DOCS, surfaceType)
+  ) {
+    const got =
+      typeof surfaceType === "string" && surfaceType.trim().length > 0
+        ? `"${surfaceType}" is not a surface type`
+        : "`surface_type` is missing";
+    return `Error: ui_show was not displayed — ${got}. Valid types: ${SURFACE_TYPE_INDEX}. Resend ui_show with one of these surface_type values; if a type's data is missing required content, the error will include its exact shape.`;
+  }
+  const doc = SURFACE_SHAPE_DOCS[surfaceType]!;
+  if (!doc.missingContent) {
+    return null;
+  }
+  const missing = doc.missingContent(asRecord(input.data) ?? {});
+  if (missing === null) {
+    return null;
+  }
+  return `Error: ui_show ${surfaceType} was not displayed — ${missing}, so the user saw nothing. Data shape: ${doc.shape}. Resend ui_show with the missing content filled in.`;
+}

package/src/tts/__tests__/provider-adapters.test.ts

@@ -1520,6 +1520,24 @@ describe("Deepgram TTS provider adapter", () => {
     }
   });
 
+  test("surfaces a friendly, JSON-free message on a 401 auth failure", async () => {
+    mockFetchError(401, '{"err_code":"INVALID_AUTH","err_msg":"expired"}');
+
+    const provider = createDeepgramProvider();
+
+    try {
+      await provider.synthesize(makeRequest());
+      throw new Error("Expected synthesize to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(DeepgramTtsError);
+      const message = (err as DeepgramTtsError).message;
+      expect(message).not.toContain("{");
+      expect(message).not.toContain("INVALID_AUTH");
+      expect(message).toContain("API key");
+      expect(message).toContain("Settings");
+    }
+  });
+
   test("throws DEEPGRAM_TTS_EMPTY_RESPONSE on empty audio body", async () => {
     mockFetchReturning(new Uint8Array(0));
 

package/src/tts/provider-catalog.ts

@@ -54,11 +54,9 @@ const DEFINITIONS = {
 /**
  * Definitions in display order (e.g. settings dropdowns).
  */
-// vellum is deliberately absent: managed mode is selected via
-// `services.tts.mode`, not the provider picker — today's settings UI writes
-// only `provider` + an API key, which the schema rejects for vellum. The
-// definition stays in DEFINITIONS so managed-mode resolution works.
+// vellum leads: it is the managed option, selected like any other provider.
 const CATALOG: readonly TtsProviderDefinition[] = [
+  DEFINITIONS.vellum,
   DEFINITIONS.elevenlabs,
   DEFINITIONS["fish-audio"],
   DEFINITIONS.deepgram,

package/src/tts/providers/deepgram-provider.ts

@@ -12,6 +12,7 @@
 
 import { getConfig } from "../../config/loader.js";
 import type { TtsDeepgramProviderConfig } from "../../config/schemas/tts.js";
+import { describeTtsAuthFailure } from "../../providers/voice-error-copy.js";
 import { getProviderKeyAsync } from "../../security/secure-keys.js";
 import { getLogger } from "../../util/logger.js";
 import { resolvePcmOutputSampleRateHz } from "../pcm-sample-rates.js";
@@ -208,9 +209,17 @@ async function performTtsRequest(
 
   if (!response.ok) {
     const errorText = await response.text().catch(() => "");
+    log.debug(
+      { status: response.status, body: errorText.slice(0, 300) },
+      "Deepgram TTS non-200 response",
+    );
+    const message =
+      response.status === 401 || response.status === 403
+        ? describeTtsAuthFailure("Deepgram")
+        : `Deepgram text-to-speech failed (HTTP ${response.status}).`;
     throw new DeepgramTtsError(
       "DEEPGRAM_TTS_HTTP_ERROR",
-      `Deepgram TTS returned ${response.status}: ${errorText}`,
+      message,
       response.status,
     );
   }

package/src/types/onboarding-context.ts

@@ -18,4 +18,12 @@ export interface OnboardingContext {
   initialMessage?: string;
   /** Skills to eagerly load on first turn (e.g. ["geo-writing", "document-editor"]). Informational — the bootstrap template drives actual loading. */
   skills?: string[];
+  /**
+   * Findings from the pre-chat onboarding research that the user explicitly
+   * kept on the results screen (removed/rejected claims are excluded
+   * client-side). Rendered into the persona's onboarding section so they're
+   * available from the very first turn — the greeting turn is barred from
+   * `recall`/file reads and would otherwise be blind to them.
+   */
+  researchFindings?: string[];
 }