@vellumai/assistant 0.6.4 → 0.6.6

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

@@ -0,0 +1,224 @@
+/**
+ * xAI TTS provider adapter.
+ *
+ * Wraps the xAI REST text-to-speech API (`/v1/tts`) behind the uniform
+ * {@link TtsProvider} interface. Reads the API key from the secure credential
+ * store under `credential/xai/api_key` and the model configuration from the
+ * `services.tts.providers.xai` config section.
+ */
+
+import { getConfig } from "../../config/loader.js";
+import type { TtsXaiProviderConfig } from "../../config/schemas/tts.js";
+import { credentialKey } from "../../security/credential-key.js";
+import { getSecureKeyAsync } from "../../security/secure-keys.js";
+import { getLogger } from "../../util/logger.js";
+import type {
+  TtsProvider,
+  TtsProviderCapabilities,
+  TtsSynthesisRequest,
+  TtsSynthesisResult,
+} from "../types.js";
+
+const log = getLogger("tts:xai");
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+export type XaiTtsErrorCode =
+  | "XAI_TTS_NO_API_KEY"
+  | "XAI_TTS_HTTP_ERROR"
+  | "XAI_TTS_EMPTY_RESPONSE"
+  | "XAI_TTS_REQUEST_FAILED";
+
+export class XaiTtsError extends Error {
+  readonly code: XaiTtsErrorCode;
+  readonly statusCode?: number;
+
+  constructor(code: XaiTtsErrorCode, message: string, statusCode?: number) {
+    super(message);
+    this.name = "XaiTtsError";
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const XAI_API_BASE = "https://api.x.ai";
+
+/** Map from xAI codec names to MIME content types. */
+const FORMAT_CONTENT_TYPE: Record<string, string> = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  pcm: "audio/pcm",
+};
+
+// ---------------------------------------------------------------------------
+// Provider implementation
+// ---------------------------------------------------------------------------
+
+/** Parameters for xAI's `/v1/tts` output_format payload. */
+interface XaiOutputParams {
+  /** xAI codec name (`mp3`, `wav`, or `pcm`). */
+  codec: string;
+  /** Sample rate in Hz. */
+  sample_rate: number;
+  /** MP3 bit rate. Omitted for non-MP3 codecs. */
+  bit_rate?: number;
+  /** Content-type key for the FORMAT_CONTENT_TYPE lookup. */
+  contentTypeKey: string;
+}
+
+/**
+ * Resolve the xAI output codec, sample rate, and bit rate based on the
+ * synthesis request and provider config.
+ *
+ * **PCM path** (`outputFormat: "pcm"`):
+ *   The media-stream transport needs raw headerless PCM for mu-law transcoding.
+ *   We request `codec=pcm&sample_rate=16000` — matching the ElevenLabs /
+ *   Deepgram 16 kHz PCM convention and the downstream `audioBufferToFrames`
+ *   expectation (16 kHz -> 8 kHz downsample).
+ *
+ * **MP3 path** (`config.format === "mp3"`):
+ *   Uses the configured sample rate and bit rate.
+ *
+ * **WAV path** (`config.format === "wav"`):
+ *   Uses the configured sample rate; bit rate is not meaningful for WAV.
+ */
+function resolveOutputParams(
+  request: TtsSynthesisRequest,
+  config: TtsXaiProviderConfig,
+): XaiOutputParams {
+  if (request.outputFormat === "pcm") {
+    return {
+      codec: "pcm",
+      sample_rate: 16_000,
+      contentTypeKey: "pcm",
+    };
+  }
+
+  if (config.format === "mp3") {
+    return {
+      codec: "mp3",
+      sample_rate: config.sampleRate,
+      bit_rate: config.bitRate,
+      contentTypeKey: "mp3",
+    };
+  }
+
+  return {
+    codec: "wav",
+    sample_rate: config.sampleRate,
+    contentTypeKey: "wav",
+  };
+}
+
+/** Resolve the voice ID: request override > config > default. */
+function resolveVoiceId(
+  request: TtsSynthesisRequest,
+  config: TtsXaiProviderConfig,
+): string {
+  return request.voiceId?.trim() || config.voiceId || "eve";
+}
+
+export function createXaiProvider(): TtsProvider {
+  const capabilities: TtsProviderCapabilities = {
+    supportsStreaming: false,
+    supportedFormats: ["mp3", "wav"],
+  };
+
+  return {
+    id: "xai",
+    capabilities,
+
+    async synthesize(
+      request: TtsSynthesisRequest,
+    ): Promise<TtsSynthesisResult> {
+      const apiKey = await getSecureKeyAsync(credentialKey("xai", "api_key"));
+      if (!apiKey) {
+        throw new XaiTtsError(
+          "XAI_TTS_NO_API_KEY",
+          "xAI API key not configured. " +
+            "Add it via: assistant credentials set --service xai --field api_key <key>",
+        );
+      }
+
+      const config = getConfig().services.tts.providers.xai;
+      const output = resolveOutputParams(request, config);
+      const voiceId = resolveVoiceId(request, config);
+
+      const body = {
+        text: request.text,
+        voice_id: voiceId,
+        language: config.language,
+        output_format: {
+          codec: output.codec,
+          sample_rate: output.sample_rate,
+          ...(output.bit_rate ? { bit_rate: output.bit_rate } : {}),
+        },
+      };
+
+      log.info(
+        {
+          voiceId,
+          codec: output.codec,
+          sampleRate: output.sample_rate,
+          textLength: request.text.length,
+        },
+        "Starting xAI TTS synthesis",
+      );
+
+      let response: Response;
+      try {
+        response = await fetch(`${XAI_API_BASE}/v1/tts`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(body),
+          signal: request.signal,
+        });
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") throw err;
+        throw new XaiTtsError(
+          "XAI_TTS_REQUEST_FAILED",
+          `xAI TTS request failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new XaiTtsError(
+          "XAI_TTS_HTTP_ERROR",
+          `xAI TTS returned ${response.status}: ${errorText}`,
+          response.status,
+        );
+      }
+
+      const arrayBuffer = await response.arrayBuffer();
+      if (arrayBuffer.byteLength === 0) {
+        throw new XaiTtsError(
+          "XAI_TTS_EMPTY_RESPONSE",
+          "xAI TTS returned an empty audio response",
+        );
+      }
+
+      const contentType =
+        FORMAT_CONTENT_TYPE[output.contentTypeKey] ?? "audio/mpeg";
+
+      log.debug(
+        { bytes: arrayBuffer.byteLength },
+        "xAI TTS synthesis complete",
+      );
+
+      return {
+        audio: Buffer.from(arrayBuffer),
+        contentType,
+      };
+    },
+  };
+}

package/src/tts/types.ts

@@ -20,6 +20,7 @@ export type TtsProviderId =
   | "elevenlabs"
   | "fish-audio"
   | "deepgram"
+  | "xai"
   | (string & {});
 
 // ---------------------------------------------------------------------------
@@ -99,6 +100,35 @@ export interface TtsSynthesisResult {
   contentType: string;
 }
 
+// ---------------------------------------------------------------------------
+// Alignment / viseme events
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-phoneme alignment event emitted by TTS providers that expose
+ * character- or phoneme-level alignment metadata alongside the audio
+ * stream (e.g. ElevenLabs Turbo with alignment).
+ *
+ * Consumers (e.g. the Meet avatar lip-sync path) map these events to
+ * blendshape weights at the rendered timestamp. Providers that do not
+ * expose alignment metadata simply never invoke the callback; the
+ * caller is expected to fall back to an amplitude-envelope approximation
+ * derived from the PCM stream.
+ */
+export interface TtsAlignmentEvent {
+  /**
+   * Phoneme label or character — free-form string that the consumer maps
+   * to renderer-specific blendshape weights. Providers typically emit
+   * IPA-style phoneme labels, viseme codes, or individual characters
+   * depending on their alignment granularity.
+   */
+  phoneme: string;
+  /** Normalized intensity in the range [0, 1]. */
+  weight: number;
+  /** Milliseconds from the start of the synthesized utterance. */
+  timestamp: number;
+}
+
 // ---------------------------------------------------------------------------
 // Provider capabilities
 // ---------------------------------------------------------------------------
@@ -110,6 +140,15 @@ export interface TtsProviderCapabilities {
 
   /** Audio formats the provider can produce (e.g. `["mp3", "wav", "opus"]`). */
   supportedFormats: string[];
+
+  /**
+   * Whether the provider can emit {@link TtsAlignmentEvent}s via the optional
+   * `onAlignment` callback of `synthesizeStream`. Consumers use this to pick
+   * between a viseme-driven lip-sync path and an RMS-amplitude fallback.
+   *
+   * Optional for backwards compatibility — treat `undefined` as `false`.
+   */
+  alignment?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -145,9 +184,16 @@ export interface TtsProvider {
    * The `onChunk` callback is invoked with each audio chunk as it arrives
    * from the upstream provider. The returned promise resolves with the
    * complete concatenated result once all chunks have been delivered.
+   *
+   * Providers that advertise `capabilities.alignment === true` also invoke
+   * the optional `onAlignment` callback with per-phoneme alignment events
+   * interleaved with the audio chunks. Providers that don't support
+   * alignment simply never call it; callers must tolerate a silent
+   * channel and fall back to amplitude-based heuristics.
    */
   synthesizeStream?(
     request: TtsSynthesisRequest,
     onChunk: (chunk: Uint8Array) => void,
+    onAlignment?: (event: TtsAlignmentEvent) => void,
   ): Promise<TtsSynthesisResult>;
 }

package/src/types/tar-stream.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Minimal ambient types for `tar-stream` v3, which ships no type definitions.
+ *
+ * We only declare the surface used by `runtime/migrations/vbundle-tar-stream.ts`
+ * (the `extract()` factory and its `"entry"` event shape). If additional usage
+ * is needed later, extend this file rather than adding `@types/tar-stream` —
+ * the DT types target v2 and do not match v3's streamx-based extractor.
+ */
+declare module "tar-stream" {
+  import type { Readable, Writable } from "node:stream";
+
+  export interface TarHeader {
+    name: string;
+    size: number;
+    type:
+      | "file"
+      | "link"
+      | "symlink"
+      | "character-device"
+      | "block-device"
+      | "directory"
+      | "fifo"
+      | "contiguous-file"
+      | "pax-header"
+      | "pax-global-header"
+      | "gnu-long-path"
+      | "gnu-long-link-path"
+      | "other"
+      | string;
+    linkname?: string | null;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    mtime?: Date;
+    pax?: Record<string, string> | null;
+  }
+
+  export interface ExtractOptions {
+    filenameEncoding?: string;
+    allowUnknownFormat?: boolean;
+  }
+
+  export type EntryCallback = (err?: Error | null) => void;
+
+  export interface Extract extends Writable {
+    on(
+      event: "entry",
+      listener: (
+        header: TarHeader,
+        stream: Readable,
+        next: EntryCallback,
+      ) => void,
+    ): this;
+    on(event: "finish", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+    on(event: "close", listener: () => void): this;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    destroy(err?: Error): void;
+  }
+
+  export function extract(opts?: ExtractOptions): Extract;
+
+  // `pack` exists but is unused by the runtime migrations code; declare it
+  // permissively so importers that reach for it still type-check.
+  export function pack(opts?: unknown): Writable;
+}

package/src/util/json.ts

@@ -8,3 +8,20 @@ export function parseJsonSafe<T = unknown>(text: string): T | null {
     return null;
   }
 }
+
+/** Tolerant JSON parse that returns `{}` for invalid or non-object payloads. */
+export function safeParseRecord(raw: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}

package/src/util/platform.ts

@@ -59,8 +59,14 @@ export function normalizeAssistantId(assistantId: string): string {
  * Docker mode relocates the workspace via `VELLUM_WORKSPACE_DIR` rather
  * than `BASE_DATA_DIR`, so honoring `BASE_DATA_DIR` here does not affect
  * containerized deployments.
+ *
+ * Exported so other daemon-side consumers (e.g. the meet-join orphan reaper
+ * in `skills/meet-join/daemon/docker-runner.ts`) can derive a per-instance
+ * identifier from the same canonical root. Do not replace with ad-hoc
+ * `process.env.BASE_DATA_DIR` reads — this helper is the single source of
+ * truth for per-instance path resolution.
  */
-function vellumRoot(): string {
+export function vellumRoot(): string {
   const baseDataDir = process.env.BASE_DATA_DIR?.trim();
   if (baseDataDir) return join(baseDataDir, ".vellum");
   return join(homedir(), ".vellum");
@@ -324,8 +330,8 @@ export function getWorkspaceDir(): string {
  * so paths stay concise and portable across machines.
  *
  * Examples:
- *   /Users/sidd/.vellum/workspace → ~/.vellum/workspace
- *   /data/.vellum/workspace       → /data/.vellum/workspace
+ *   /Users/alice/.vellum/workspace → ~/.vellum/workspace
+ *   /data/.vellum/workspace        → /data/.vellum/workspace
  */
 export function getWorkspaceDirDisplay(): string {
   const abs = getWorkspaceDir();
@@ -410,7 +416,6 @@ export function ensureDataDir(): void {
     // Workspace dirs
     workspace,
     join(workspace, "signals"),
-    join(workspace, "hooks"),
     join(workspace, "skills"),
     join(workspace, "routes"),
     join(workspace, "embedding-models"),

package/src/util/pricing.ts

@@ -23,9 +23,9 @@ const PROVIDER_PRICING: Record<string, Record<string, ModelPricing>> = {
   anthropic: {
     "claude-opus-4-7": { inputPer1M: 5, outputPer1M: 25 },
     "claude-opus-4-6": { inputPer1M: 5, outputPer1M: 25 },
-    "claude-opus-4": { inputPer1M: 15, outputPer1M: 75 },
+    "claude-opus-4": { inputPer1M: 5, outputPer1M: 25 },
     "claude-sonnet-4": { inputPer1M: 3, outputPer1M: 15 },
-    "claude-haiku-4": { inputPer1M: 0.8, outputPer1M: 4 },
+    "claude-haiku-4": { inputPer1M: 1, outputPer1M: 5 },
   },
   openai: {
     "gpt-5.4": { inputPer1M: 2.5, outputPer1M: 15 },
@@ -43,17 +43,40 @@ const PROVIDER_PRICING: Record<string, Record<string, ModelPricing>> = {
     "o4-mini": { inputPer1M: 1.1, outputPer1M: 4.4 },
   },
   gemini: {
-    "gemini-3-flash": { inputPer1M: 0.5, outputPer1M: 3 },
-    "gemini-2.5-pro": { inputPer1M: 1.25, outputPer1M: 10 },
     "gemini-2.5-flash": { inputPer1M: 0.15, outputPer1M: 0.6 },
+    "gemini-2.5-flash-lite": { inputPer1M: 0.02, outputPer1M: 0.1 },
+    "gemini-2.5-pro": { inputPer1M: 1.25, outputPer1M: 10 },
     "gemini-2.0-flash": { inputPer1M: 0.1, outputPer1M: 0.4 },
   },
   fireworks: {
     "accounts/fireworks/models/kimi-k2p5": {
       inputPer1M: 0.6,
-      outputPer1M: 3.0,
+      outputPer1M: 2.5,
     },
   },
+  // Non-Anthropic OpenRouter models. Anthropic-on-OpenRouter is handled by a
+  // dedicated branch in resolvePricingForUsage that routes to the Anthropic
+  // catalog (OpenRouter bills those at Anthropic's direct rates). Rates here
+  // mirror the catalog metadata in model-catalog.ts so cost tracking has a
+  // priced value instead of falling back to 'unpriced'.
+  openrouter: {
+    "x-ai/grok-4.20-beta": { inputPer1M: 3, outputPer1M: 15 },
+    "x-ai/grok-4": { inputPer1M: 3, outputPer1M: 15 },
+    "deepseek/deepseek-r1-0528": { inputPer1M: 0.55, outputPer1M: 2.19 },
+    "deepseek/deepseek-chat-v3-0324": { inputPer1M: 0.27, outputPer1M: 1.1 },
+    "qwen/qwen3.5-plus-02-15": { inputPer1M: 0.8, outputPer1M: 2.4 },
+    "qwen/qwen3.5-397b-a17b": { inputPer1M: 0.9, outputPer1M: 2.7 },
+    "qwen/qwen3.5-flash-02-23": { inputPer1M: 0.2, outputPer1M: 0.6 },
+    "qwen/qwen3-coder-next": { inputPer1M: 0.5, outputPer1M: 1.5 },
+    "moonshotai/kimi-k2.6": { inputPer1M: 0.6, outputPer1M: 2.8 },
+    "moonshotai/kimi-k2.5": { inputPer1M: 0.6, outputPer1M: 2.5 },
+    "mistralai/mistral-medium-3": { inputPer1M: 0.4, outputPer1M: 2.0 },
+    "mistralai/mistral-small-2603": { inputPer1M: 0.2, outputPer1M: 0.6 },
+    "mistralai/devstral-2512": { inputPer1M: 0.1, outputPer1M: 0.3 },
+    "meta-llama/llama-4-maverick": { inputPer1M: 0.27, outputPer1M: 0.85 },
+    "meta-llama/llama-4-scout": { inputPer1M: 0.11, outputPer1M: 0.34 },
+    "amazon/nova-pro-v1": { inputPer1M: 0.8, outputPer1M: 3.2 },
+  },
 };
 
 /**
@@ -67,15 +90,25 @@ function isAnthropicModelId(model: string): boolean {
 
 /**
  * Normalize an OpenRouter-style Anthropic model ID for lookup against the
- * Anthropic catalog: strip the `anthropic/` prefix and convert OpenRouter's
+ * Anthropic catalog: strip the `anthropic/` prefix, convert OpenRouter's
  * dot-separated version tokens (`claude-opus-4.6`) to the dash form Anthropic
- * uses natively (`claude-opus-4-6`).
+ * uses natively (`claude-opus-4-6`), and swap OpenRouter's version-first
+ * response form (`claude-4-7-opus-20260416`) into Anthropic's model-first
+ * catalog form (`claude-opus-4-7-20260416`) so the prefix match succeeds.
  */
 function normalizeAnthropicModelId(model: string): string {
   const bare = model.startsWith("anthropic/")
     ? model.slice("anthropic/".length)
     : model;
-  return bare.replace(/\./g, "-");
+  const dashed = bare.replace(/\./g, "-");
+  const versionFirst = dashed.match(
+    /^claude-(\d+(?:-\d+)*)-(opus|sonnet|haiku)(-.+)?$/,
+  );
+  if (versionFirst) {
+    const [, version, family, suffix] = versionFirst;
+    return `claude-${family}-${version}${suffix ?? ""}`;
+  }
+  return dashed;
 }
 
 /**

package/src/watcher/engine.ts

@@ -180,7 +180,7 @@ export async function runWatchersOnce(
         // Do NOT call provider.cleanup() here — auto-disable is reversible.
         // If the watcher is re-enabled later, it must diff against the same
         // baseline to avoid missing events that occurred while disabled.
-        // Cleanup is only correct on true deletion (see tools/watcher/delete.ts).
+        // Cleanup is only correct on true deletion (see watcher delete IPC route).
         log.warn(
           { watcherId: watcher.id, name: watcher.name },
           "Watcher disabled by circuit breaker",

package/src/watcher/providers/google-calendar.ts

@@ -6,15 +6,9 @@
  * Falls back to listing recent upcoming events if the syncToken has expired (410 Gone).
  */
 
-import {
-  CalendarApiError,
-  listEvents,
-} from "../../config/bundled-skills/google-calendar/calendar-client.js";
-import type { CalendarEvent } from "../../config/bundled-skills/google-calendar/types.js";
 import type { OAuthConnection } from "../../oauth/connection.js";
 import { resolveOAuthConnection } from "../../oauth/connection-resolver.js";
-
-const GOOGLE_CALENDAR_BASE_URL = "https://www.googleapis.com/calendar/v3";
+import { wrapUntrustedContent } from "../../security/untrusted-content.js";
 import { getLogger } from "../../util/logger.js";
 import type {
   FetchResult,
@@ -22,6 +16,133 @@ import type {
   WatcherProvider,
 } from "../provider-types.js";
 
+const GOOGLE_CALENDAR_BASE_URL = "https://www.googleapis.com/calendar/v3";
+
+// ---------------------------------------------------------------------------
+// Local types & helpers used by the watcher provider
+// ---------------------------------------------------------------------------
+
+/** Event time - either a dateTime with timezone or a date for all-day events. */
+interface EventDateTime {
+  dateTime?: string;
+  date?: string;
+  timeZone?: string;
+}
+
+/** Calendar event attendee. */
+interface EventAttendee {
+  email: string;
+  displayName?: string;
+  responseStatus?: "needsAction" | "declined" | "tentative" | "accepted";
+  self?: boolean;
+  organizer?: boolean;
+  optional?: boolean;
+}
+
+/** Calendar event organizer. */
+interface EventOrganizer {
+  email?: string;
+  displayName?: string;
+  self?: boolean;
+}
+
+/** A single Google Calendar event. */
+interface CalendarEvent {
+  id: string;
+  status?: "confirmed" | "tentative" | "cancelled";
+  summary?: string;
+  description?: string;
+  location?: string;
+  start?: EventDateTime;
+  end?: EventDateTime;
+  attendees?: EventAttendee[];
+  organizer?: EventOrganizer;
+  htmlLink?: string;
+  created?: string;
+  updated?: string;
+}
+
+/** Events list response. */
+interface CalendarEventsListResponse {
+  items?: CalendarEvent[];
+  nextPageToken?: string;
+  nextSyncToken?: string;
+}
+
+class CalendarApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CalendarApiError";
+  }
+}
+
+/** List events from a calendar. */
+async function listEvents(
+  connection: OAuthConnection,
+  calendarId = "primary",
+  options?: {
+    timeMin?: string;
+    timeMax?: string;
+    maxResults?: number;
+    query?: string;
+    singleEvents?: boolean;
+    orderBy?: "startTime" | "updated";
+    pageToken?: string;
+    syncToken?: string;
+  },
+): Promise<CalendarEventsListResponse> {
+  const query: Record<string, string> = {};
+
+  if (options?.timeMin) query.timeMin = options.timeMin;
+  if (options?.timeMax) query.timeMax = options.timeMax;
+  query.maxResults = String(options?.maxResults ?? 25);
+  if (options?.query) query.q = options.query;
+
+  // Default to expanding recurring events into instances
+  const singleEvents = options?.singleEvents ?? true;
+  query.singleEvents = String(singleEvents);
+
+  if (singleEvents && options?.orderBy) {
+    query.orderBy = options.orderBy;
+  } else if (singleEvents) {
+    query.orderBy = "startTime";
+  }
+
+  if (options?.pageToken) query.pageToken = options.pageToken;
+  if (options?.syncToken) query.syncToken = options.syncToken;
+
+  const resp = await connection.request({
+    method: "GET",
+    path: `/calendars/${encodeURIComponent(calendarId)}/events`,
+    query,
+    baseUrl: GOOGLE_CALENDAR_BASE_URL,
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (resp.status < 200 || resp.status >= 300) {
+    const bodyStr =
+      typeof resp.body === "string"
+        ? resp.body
+        : JSON.stringify(resp.body ?? "");
+    throw new CalendarApiError(
+      resp.status,
+      "",
+      `Calendar API ${resp.status}: ${bodyStr}`,
+    );
+  }
+
+  if (resp.status === 204 || resp.body === undefined) {
+    return undefined as unknown as CalendarEventsListResponse;
+  }
+  return resp.body as CalendarEventsListResponse;
+}
+
 const log = getLogger("watcher:google-calendar");
 
 /** The credential service — calendar shares OAuth tokens with Gmail. */
@@ -44,7 +165,12 @@ function eventToItem(event: CalendarEvent, eventType: string): WatcherItem {
       start,
       end,
       location: event.location ?? "",
-      description: event.description ?? "",
+      description: event.description
+        ? wrapUntrustedContent(event.description, {
+            source: "calendar",
+            maxChars: 5000,
+          })
+        : "",
       status: event.status ?? "confirmed",
       organizer: event.organizer?.email ?? "",
       attendees: