@vellumai/assistant 0.8.1 → 0.8.2

package/src/tools/registry.ts

@@ -10,7 +10,7 @@ import { hostFileWriteTool } from "./host-filesystem/write.js";
 import { hostShellTool } from "./host-terminal/host-shell.js";
 import { toProviderSafeToolName } from "./provider-tool-name.js";
 import { registerSystemTools } from "./system/register.js";
-import type { Tool } from "./types.js";
+import type { PluginTool, Tool } from "./types.js";
 import { allUiSurfaceTools } from "./ui-surface/definitions.js";
 import { registerUiSurfaceTools } from "./ui-surface/registry.js";
 
@@ -193,19 +193,29 @@ export function registerSkillTools(newTools: Tool[]): Tool[] {
  */
 export function registerPluginTools(
   pluginName: string,
-  newTools: Tool[],
+  newTools: PluginTool[],
 ): Tool[] {
-  const stamped: Tool[] = newTools.map((tool) =>
-    withProviderSafeToolName({
-      ...tool,
+  const stamped: Tool[] = newTools.map((pluginTool) => {
+    const { input_schema, ...rest } = pluginTool;
+    const tool: Tool = {
+      ...rest,
+      category: "plugin",
       origin: "plugin" as const,
       ownerPluginId: pluginName,
       ownerSkillId: undefined,
       ownerMcpServerId: undefined,
       ownerSkillBundled: undefined,
       ownerSkillVersionHash: undefined,
-    }),
-  );
+      getDefinition(): ToolDefinition {
+        return {
+          name: pluginTool.name,
+          description: pluginTool.description,
+          input_schema,
+        };
+      },
+    };
+    return withProviderSafeToolName(tool);
+  });
 
   const accepted: Tool[] = [];
   for (const tool of stamped) {

package/src/tools/schedule/create.ts

@@ -150,7 +150,7 @@ export async function executeScheduleCreate(
           `  Status: ${job.status}`,
           ``,
           `Integrations: ${integrations}`,
-          `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn the user about any missing capabilities before confirming the schedule is ready.`,
+          `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn about any missing capabilities before confirming the schedule is ready.`,
         ].join("\n"),
         isError: false,
       };
@@ -239,7 +239,7 @@ export async function executeScheduleCreate(
         `  Next run: ${nextRunDate}`,
         ``,
         `Integrations: ${integrations}`,
-        `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn the user about any missing capabilities before confirming the schedule is ready.`,
+        `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn about any missing capabilities before confirming the schedule is ready.`,
       ].join("\n"),
       isError: false,
     };

package/src/tools/schema-transforms.ts

@@ -23,8 +23,13 @@ export function injectActivityField(
       return def;
     }
 
-    const schema = def.input_schema as Record<string, unknown>;
-    if (schema.type !== "object" || !schema.properties) {
+    const schema = def.input_schema as Record<string, unknown> | undefined;
+    if (
+      schema == null ||
+      typeof schema !== "object" ||
+      schema.type !== "object" ||
+      !schema.properties
+    ) {
       return def;
     }
 

package/src/tools/side-effects.ts

@@ -14,6 +14,7 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
   "web_fetch",
   "document_create",
   "document_update",
+  "document_delete",
   "schedule_create",
   "schedule_update",
   "schedule_delete",

package/src/tools/skills/delete-managed.ts

@@ -1,3 +1,4 @@
+import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { deleteManagedSkill } from "../../skills/managed-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -17,19 +18,18 @@ export async function executeDeleteManagedSkill(
     };
   }
 
-  const removeFromIndex = input.remove_from_index !== false;
-
-  const result = deleteManagedSkill(skillId.trim(), removeFromIndex);
+  const result = deleteManagedSkill(skillId.trim());
 
   if (!result.deleted) {
     return { content: `Error: ${result.error}`, isError: true };
   }
 
+  refreshSkillCapabilityMemories();
+
   return {
     content: JSON.stringify({
       deleted: true,
       skill_id: skillId.trim(),
-      index_updated: result.indexUpdated,
     }),
     isError: false,
   };

package/src/tools/skills/execute.ts

@@ -30,7 +30,7 @@ class SkillExecuteTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a progress update.",
+              "Brief non-technical explanation of what you are doing and why, shown as a progress update.",
           },
         },
         required: ["tool", "input", "activity"],

package/src/tools/skills/scaffold-managed.ts

@@ -1,3 +1,4 @@
+import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { createManagedSkill } from "../../skills/managed-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -93,7 +94,6 @@ export async function executeScaffoldManagedSkill(
         ? sanitizeFrontmatterValue(input.emoji)
         : undefined,
     overwrite: input.overwrite === true,
-    addToIndex: input.add_to_index !== false,
     includes,
   });
 
@@ -101,12 +101,13 @@ export async function executeScaffoldManagedSkill(
     return { content: `Error: ${result.error}`, isError: true };
   }
 
+  refreshSkillCapabilityMemories();
+
   return {
     content: JSON.stringify({
       created: true,
       skill_id: skillId.trim(),
       path: result.path,
-      index_updated: result.indexUpdated,
     }),
     isError: false,
   };

package/src/tools/subagent/notify-parent.ts

@@ -59,7 +59,7 @@ class NotifyParentTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
           },
         },
         required: ["message", "activity"],

package/src/tools/system/request-permission.ts

@@ -53,7 +53,7 @@ const FRIENDLY_NAMES: Record<PermissionType, string> = {
 class RequestSystemPermissionTool implements Tool {
   name = "request_system_permission";
   description =
-    "Ask the user to grant a macOS system permission via System Settings. " +
+    "Request a macOS system permission via System Settings. " +
     "Use when a tool fails with a permission/access error (e.g. 'Operation not permitted', 'EACCES', sandbox denial). " +
     "Do not explain how to open System Settings manually - this tool handles it with a clickable button.";
   category = "system";
@@ -74,7 +74,7 @@ class RequestSystemPermissionTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Short explanation of why this permission is needed (shown to the user)",
+              "Short explanation of why this permission is needed (shown in the prompt)",
           },
         },
         required: ["permission_type", "activity"],

package/src/tools/terminal/safe-env.ts

@@ -46,6 +46,7 @@ export const SAFE_ENV_VARS = [
   "IS_CONTAINERIZED",
   "IS_PLATFORM",
   "VELLUM_CLOUD",
+  "VELLUM_SANDBOX_RUNTIME",
   "CES_SERVICE_TOKEN",
   "VELLUM_PROFILER_RUN_ID",
   "VELLUM_PROFILER_MODE",
@@ -59,6 +60,37 @@ export const SAFE_ENV_VARS = [
   "VELLUM_BACKUP_KEY_PATH",
 ] as const;
 
+export const KATA_SAFE_ENV_VARS = [
+  "LD_LIBRARY_PATH",
+  "VELLUM_APT_DATA_ROOT",
+  "VELLUM_APT_DATA_SUITE",
+  "VELLUM_APT_DATA_MIRROR",
+] as const;
+
+const KATA_APT_DATA_ROOT = "/data/system";
+
+function kataAptPaths(dataRoot: string): string[] {
+  return [
+    `${dataRoot}/bin`,
+    `${dataRoot}/usr/local/sbin`,
+    `${dataRoot}/usr/local/bin`,
+    `${dataRoot}/usr/sbin`,
+    `${dataRoot}/usr/bin`,
+    `${dataRoot}/sbin`,
+    `${dataRoot}/usr/games`,
+    `${dataRoot}/games`,
+  ];
+}
+
+function kataAptLibraryPaths(dataRoot: string): string[] {
+  return [
+    `${dataRoot}/usr/local/lib`,
+    `${dataRoot}/usr/lib`,
+    `${dataRoot}/usr/lib/x86_64-linux-gnu`,
+    `${dataRoot}/usr/lib/aarch64-linux-gnu`,
+  ];
+}
+
 /**
  * Keys that buildSanitizedEnv always injects into the returned env,
  * independent of what is present in process.env.
@@ -70,13 +102,40 @@ export const ALWAYS_INJECTED_ENV_VARS = [
   "VELLUM_WORKSPACE_DIR",
 ] as const;
 
+function appendUniquePathEntries(
+  value: string | undefined,
+  entries: readonly string[],
+): string {
+  const parts = value ? value.split(":").filter(Boolean) : [];
+  for (const entry of entries) {
+    if (!parts.includes(entry)) {
+      parts.push(entry);
+    }
+  }
+  return parts.join(":");
+}
+
 export function buildSanitizedEnv(): Record<string, string> {
   const env: Record<string, string> = {};
-  for (const key of SAFE_ENV_VARS) {
+  const isKataRuntime = process.env.VELLUM_SANDBOX_RUNTIME === "kata";
+  const safeEnvVars = isKataRuntime
+    ? [...SAFE_ENV_VARS, ...KATA_SAFE_ENV_VARS]
+    : SAFE_ENV_VARS;
+
+  for (const key of safeEnvVars) {
     if (process.env[key] != null) {
       env[key] = process.env[key]!;
     }
   }
+  if (isKataRuntime) {
+    const kataAptDataRoot = env.VELLUM_APT_DATA_ROOT ?? KATA_APT_DATA_ROOT;
+    env.VELLUM_APT_DATA_ROOT = kataAptDataRoot;
+    env.PATH = appendUniquePathEntries(env.PATH, kataAptPaths(kataAptDataRoot));
+    env.LD_LIBRARY_PATH = appendUniquePathEntries(
+      env.LD_LIBRARY_PATH,
+      kataAptLibraryPaths(kataAptDataRoot),
+    );
+  }
   // Always inject an internal gateway base for local control-plane/API calls.
   const internalGatewayBase = getGatewayInternalBaseUrl();
   env.INTERNAL_GATEWAY_BASE_URL = internalGatewayBase;

package/src/tools/tool-manifest.ts

@@ -11,6 +11,7 @@ import {
   isCesSecureInstallEnabled,
   isCesToolsEnabled,
 } from "../credential-execution/feature-gates.js";
+import { askQuestionTool } from "./ask-question/ask-question-tool.js";
 import { makeAuthenticatedRequestTool } from "./credential-execution/make-authenticated-request.js";
 import { manageSecureCommandTool } from "./credential-execution/manage-secure-command-tool.js";
 import { runAuthenticatedCommandTool } from "./credential-execution/run-authenticated-command.js";
@@ -91,6 +92,7 @@ export const explicitTools: Tool[] = [
   recallTool,
   credentialStoreTool,
   notifyParentTool,
+  askQuestionTool,
   // NOTE: external skill tools (registered via registerExternalTools in
   // registry.ts) are intentionally NOT included here. `explicitTools` is a
   // module-level const whose value is fixed at first evaluation, so

package/src/tools/types.ts

@@ -75,22 +75,25 @@ export { RiskLevel } from "@vellumai/skill-host-contracts";
 // Assistant-side concrete overlays
 // ---------------------------------------------------------------------------
 
-export interface ToolExecutionResult {
+/**
+ * Public, narrow subset of {@link ToolExecutionResult} that plugin-authored
+ * tools are responsible for producing. Re-exported from
+ * `@vellumai/plugin-api` as `ToolExecutionResult` — the type name plugin
+ * authors actually import. The daemon-internal version below extends
+ * this and adds runtime-only fields (risk metadata, approval
+ * bookkeeping, sensitive-output bindings, etc.) that the executor
+ * populates around the call — plugins MUST NOT set those.
+ *
+ * Adding fields here is a non-breaking change; renaming or removing
+ * fields is breaking and gated on a major bump of `@vellumai/plugin-api`.
+ */
+export interface PluginToolExecutionResult {
+  /** Textual result shown to the model in the tool-result block. Empty string is valid. */
   content: string;
+  /** When true, the agent loop treats `content` as an error and may surface it / retry. */
   isError: boolean;
-  diff?: DiffInfo;
-  /** Optional status message for display (e.g. timeout, truncation). */
+  /** Optional short status message for client display (e.g. `"truncated"`, `"timed out"`). */
   status?: string;
-  /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
-  contentBlocks?: ContentBlock[];
-  /**
-   * Runtime-internal sensitive output bindings (placeholder -> real value).
-   * Populated by the executor when tool output contains
-   * `<vellum-sensitive-output>` directives. The agent loop merges these
-   * into a per-run substitution map for deterministic post-generation
-   * replacement. MUST NOT be emitted in client-facing events or logs.
-   */
-  sensitiveBindings?: SensitiveOutputBinding[];
   /**
    * When true, the agent loop should yield control back to the user after
    * returning this result — tool results are pushed to history and the loop
@@ -101,6 +104,20 @@ export interface ToolExecutionResult {
    * the LLM voluntarily end its turn.
    */
   yieldToUser?: boolean;
+}
+
+export interface ToolExecutionResult extends PluginToolExecutionResult {
+  diff?: DiffInfo;
+  /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
+  contentBlocks?: ContentBlock[];
+  /**
+   * Runtime-internal sensitive output bindings (placeholder -> real value).
+   * Populated by the executor when tool output contains
+   * `<vellum-sensitive-output>` directives. The agent loop merges these
+   * into a per-run substitution map for deterministic post-generation
+   * replacement. MUST NOT be emitted in client-facing events or logs.
+   */
+  sensitiveBindings?: SensitiveOutputBinding[];
   /** Risk level from the classifier (populated during permission check). */
   riskLevel?: string;
   /** Human-readable reason for the risk classification. */
@@ -190,19 +207,37 @@ export type ToolLifecycleEventHandler = (
   event: ToolLifecycleEvent,
 ) => void | Promise<void>;
 
-export interface ToolContext {
-  workingDir: string;
+/**
+ * Public, narrow subset of {@link ToolContext} handed to plugin-authored
+ * tools. Re-exported from `@vellumai/plugin-api` as `ToolContext` — the
+ * type name plugin authors actually import. The daemon-internal version
+ * below extends this and adds host-only fields (CES client, trust class,
+ * lifecycle handlers, requester metadata, host-bash proxy, etc.). Plugin
+ * tools see this shape only — the runtime still hands them the full
+ * {@link ToolContext} value, but the structural extension here guarantees
+ * the assignment without a manual cast.
+ *
+ * Adding fields here is a non-breaking change; renaming or removing
+ * fields is breaking and gated on a major bump of `@vellumai/plugin-api`.
+ */
+export interface PluginToolContext {
+  /** Identifier of the conversation this tool invocation belongs to. */
   conversationId: string;
+  /** Working directory the daemon was launched from. */
+  workingDir: string;
+  /** Per-turn request id for cross-component log correlation. */
+  requestId?: string;
+  /** Cooperative cancellation signal for long-running tools. Tools should check `signal.aborted` periodically (or forward `signal` to fetch / child-process options). */
+  signal?: AbortSignal;
+  /** Optional incremental-output callback for streaming tools. Streaming tools should fall back to returning the full result in `content` when this is absent. */
+  onOutput?: (chunk: string) => void;
+}
+
+export interface ToolContext extends PluginToolContext {
   /** Logical assistant scope for multi-assistant routing. */
   assistantId?: string;
   /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
   taskRunId?: string;
-  /** Per-message request ID for log correlation across conversation/connection boundaries. */
-  requestId?: string;
-  /** Optional callback for streaming incremental output to the client. */
-  onOutput?: (chunk: string) => void;
-  /** Abort signal for cooperative cancellation. Tools should check this periodically. */
-  signal?: AbortSignal;
   /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error). */
   onToolLifecycleEvent?: ToolLifecycleEventHandler;
   /** Optional resolver for proxy tools - delegates execution to an external client. */
@@ -338,3 +373,19 @@ export interface Tool {
     context: ToolContext,
   ): Promise<ToolExecutionResult>;
 }
+
+/**
+ * Plugin-facing tool shape. The narrow surface plugin authors implement;
+ * differs from {@link Tool} in three ways:
+ * - Plugins declare `input_schema` as a top-level field instead of
+ *   implementing `getDefinition()`. The registration boundary synthesizes
+ *   `getDefinition()` from `{name, description, input_schema}` before the
+ *   tool enters the internal registry.
+ * - `category` is registry-owned and stamped to `"plugin"` when the tool is
+ *   registered.
+ * - All ownership stamps (`origin`, `ownerPluginId`, etc.) are set
+ *   authoritatively by the bootstrap; plugin authors leave them blank.
+ */
+export type PluginTool = Omit<Tool, "category" | "getDefinition"> & {
+  input_schema: object;
+};

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

@@ -28,7 +28,7 @@ function proxyExecute(): Promise<ToolExecutionResult> {
 export const uiShowTool: Tool = {
   name: "ui_show",
   description:
-    "Show structured data or UI to the user. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
+    "Surface structured data or UI in the conversation. For long-form writing use the document skill; for interactive apps use the app-builder skill.\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' +
     '- 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' +
@@ -36,7 +36,8 @@ export const uiShowTool: Tool = {
     '- 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? }",
+    "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n\n" +
+    "Proactively show a task_progress card before multi-step or long-running work (web searches, file operations, research). Show it before your first tool call, then update steps as work progresses.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -91,17 +92,17 @@ export const uiShowTool: Tool = {
             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 the user explicitly asks for a separate window.',
+              '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.',
           },
           await_action: {
             type: "boolean",
             description:
-              "Whether to block until the user interacts with an action. Defaults to true when actions are provided.",
+              "Whether to 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 the user may click multiple buttons. Defaults to false.",
+              "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.",
           },
         },
         required: ["surface_type", "data"],

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

@@ -114,8 +114,11 @@ import {
   createDeepgramProvider,
   DeepgramTtsError,
 } from "../providers/deepgram-provider.js";
-import { createElevenLabsProvider } from "../providers/elevenlabs-provider.js";
-import { ElevenLabsTtsError } from "../providers/elevenlabs-provider.js";
+import {
+  createElevenLabsProvider,
+  ElevenLabsTtsError,
+  extractElevenLabsErrorMessage,
+} from "../providers/elevenlabs-provider.js";
 import { createFishAudioProvider } from "../providers/fish-audio-provider.js";
 import { FishAudioTtsError } from "../providers/fish-audio-provider.js";
 import { providerFactories } from "../providers/index.js";
@@ -396,6 +399,77 @@ describe("ElevenLabs TTS provider adapter", () => {
       );
     }
   });
+
+  // -- Upstream error-body extraction --------------------------------------
+
+  describe("extractElevenLabsErrorMessage", () => {
+    test("extracts message from standard { detail: { message } } shape", () => {
+      const body = JSON.stringify({
+        detail: {
+          type: "payment_required",
+          code: "paid_plan_required",
+          message:
+            "Free users cannot use library voices via the API. Please upgrade your subscription to use this voice.",
+          status: "payment_required",
+        },
+      });
+      expect(extractElevenLabsErrorMessage(body)).toBe(
+        "Free users cannot use library voices via the API. Please upgrade your subscription to use this voice.",
+      );
+    });
+
+    test("falls back to { detail: '...' } when detail is a string", () => {
+      const body = JSON.stringify({ detail: "Voice not found" });
+      expect(extractElevenLabsErrorMessage(body)).toBe("Voice not found");
+    });
+
+    test("falls back to { message: '...' } when present", () => {
+      const body = JSON.stringify({ message: "Quota exceeded" });
+      expect(extractElevenLabsErrorMessage(body)).toBe("Quota exceeded");
+    });
+
+    test("returns trimmed raw body when not JSON", () => {
+      expect(extractElevenLabsErrorMessage("  upstream timeout  ")).toBe(
+        "upstream timeout",
+      );
+    });
+
+    test("truncates oversized raw bodies", () => {
+      const long = "x".repeat(1000);
+      const result = extractElevenLabsErrorMessage(long);
+      expect(result).not.toBeUndefined();
+      // 200-char limit plus an ellipsis character.
+      expect(result!.length).toBeLessThanOrEqual(201);
+      expect(result!.endsWith("…")).toBe(true);
+    });
+
+    test("returns undefined for empty input", () => {
+      expect(extractElevenLabsErrorMessage("")).toBeUndefined();
+      expect(extractElevenLabsErrorMessage("   \n  ")).toBeUndefined();
+    });
+
+    test("returns truncated raw body when JSON is malformed", () => {
+      // Not valid JSON despite the leading `{` — falls through to raw fallback.
+      const body = "{not really json}";
+      expect(extractElevenLabsErrorMessage(body)).toBe("{not really json}");
+    });
+
+    test("ignores empty-string message fields", () => {
+      const body = JSON.stringify({ detail: { message: "   " } });
+      // Falls through to top-level message — also absent — then to raw body.
+      const result = extractElevenLabsErrorMessage(body);
+      expect(result).not.toBeUndefined();
+      // Raw body fallback contains the JSON text itself.
+      expect(result).toContain("detail");
+    });
+
+    test("trims whitespace from extracted messages", () => {
+      const body = JSON.stringify({
+        detail: { message: "  hello world  " },
+      });
+      expect(extractElevenLabsErrorMessage(body)).toBe("hello world");
+    });
+  });
 });
 
 // ===========================================================================

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

@@ -49,6 +49,73 @@ export class ElevenLabsTtsError extends Error {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Error-body parser
+// ---------------------------------------------------------------------------
+
+/** Maximum number of characters of a fallback raw body to surface in an error message. */
+const MAX_RAW_ERROR_BODY_CHARS = 200;
+
+/**
+ * Best-effort extraction of a user-facing error message from an ElevenLabs
+ * error response body.
+ *
+ * ElevenLabs returns structured errors in the shape:
+ * ```json
+ * { "detail": { "status": "...", "code": "...", "message": "..." } }
+ * ```
+ * but also occasionally returns `{ "message": "..." }`, `{ "detail": "..." }`,
+ * HTML pages (502/503 from their CDN), or free-form text. We try the
+ * structured shapes first, fall back to a trimmed/truncated raw body, and
+ * return `undefined` when nothing useful is present.
+ *
+ * Exported for unit testing.
+ */
+export function extractElevenLabsErrorMessage(
+  body: string,
+): string | undefined {
+  if (!body) return undefined;
+  const trimmed = body.trim();
+  if (!trimmed) return undefined;
+
+  // Try JSON envelopes first.
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (parsed && typeof parsed === "object") {
+        const root = parsed as { detail?: unknown; message?: unknown };
+
+        // Standard ElevenLabs shape: { detail: { message } }
+        if (root.detail && typeof root.detail === "object") {
+          const detailMessage = (root.detail as { message?: unknown }).message;
+          if (typeof detailMessage === "string" && detailMessage.trim()) {
+            return detailMessage.trim();
+          }
+        }
+
+        // Fallback shape: { detail: "..." }
+        if (typeof root.detail === "string" && root.detail.trim()) {
+          return root.detail.trim();
+        }
+
+        // Fallback shape: { message: "..." }
+        if (typeof root.message === "string" && root.message.trim()) {
+          return root.message.trim();
+        }
+      }
+    } catch {
+      // Not valid JSON — fall through to the raw-body fallback.
+    }
+  }
+
+  // Raw body fallback (HTML pages, plain text). Truncate to keep error
+  // messages reasonable when surfaced to UI clients.
+  if (trimmed.length > MAX_RAW_ERROR_BODY_CHARS) {
+    return `${trimmed.slice(0, MAX_RAW_ERROR_BODY_CHARS)}…`;
+  }
+  return trimmed;
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -180,9 +247,16 @@ export function createElevenLabsProvider(): TtsProvider {
 
       if (!response.ok) {
         const errorText = await response.text().catch(() => "");
+        // Surface the upstream provider message verbatim when extractable —
+        // the daemon route wraps it with a single "TTS synthesis failed:"
+        // prefix on the way out. The HTTP status is preserved on `statusCode`
+        // and logged by the daemon, so we don't embed it in the message text.
+        const message =
+          extractElevenLabsErrorMessage(errorText) ??
+          `ElevenLabs returned HTTP ${response.status}`;
         throw new ElevenLabsTtsError(
           "ELEVENLABS_TTS_HTTP_ERROR",
-          `ElevenLabs TTS returned ${response.status}: ${errorText}`,
+          message,
           response.status,
         );
       }

package/src/types/onboarding-context.ts

@@ -4,4 +4,6 @@ export interface OnboardingContext {
   tone: string;
   userName?: string;
   assistantName?: string;
+  googleConnected?: boolean;
+  googleScopes?: string[];
 }