@vellumai/assistant 0.6.4 → 0.6.6

package/src/security/token-manager.ts

@@ -232,7 +232,8 @@ async function doRefresh(service: string, connId: string): Promise<string> {
       tokenExchangeBodyFormat,
     );
   } catch (err) {
-    circuitBreaker.recordFailure(connId);
+    const credential = isCredentialError(err);
+    circuitBreaker.recordFailure(connId, credential);
     if (circuitBreaker.isOpen(connId)) {
       const state = circuitBreaker.getState(connId)!;
       log.warn(
@@ -244,7 +245,7 @@ async function doRefresh(service: string, connId: string): Promise<string> {
         "Token refresh circuit breaker opened — skipping refresh attempts until cooldown expires",
       );
     }
-    if (isCredentialError(err)) {
+    if (credential) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new TokenExpiredError(
         service,
@@ -269,17 +270,30 @@ async function doRefresh(service: string, connId: string): Promise<string> {
     );
   }
 
-  // Update oauth_connection row with new expiry.
-  try {
-    updateConnection(connId, {
-      expiresAt: persisted.expiresAt,
-      hasRefreshToken: persisted.hasRefreshToken,
-    });
-  } catch (err) {
-    log.warn(
-      { err, service },
-      "Failed to update oauth_connection after refresh",
-    );
+  // Update oauth_connection row with new expiry. Retry once on failure
+  // to reduce the risk of stale expiresAt metadata in SQLite while the
+  // actual token in secure storage is valid.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      updateConnection(connId, {
+        expiresAt: persisted.expiresAt,
+        hasRefreshToken: persisted.hasRefreshToken,
+      });
+      break;
+    } catch (err) {
+      if (attempt === 0) {
+        log.warn(
+          { err, service },
+          "Failed to update oauth_connection after refresh, retrying",
+        );
+      } else {
+        log.error(
+          { err, service, expiresAt: persisted.expiresAt },
+          "Failed to update oauth_connection after refresh — token is valid " +
+            "in secure storage but SQLite expiry metadata is stale",
+        );
+      }
+    }
   }
 
   circuitBreaker.recordSuccess(connId);

package/src/security/untrusted-content.ts

@@ -0,0 +1,102 @@
+/**
+ * Structural defenses against prompt injection from external content.
+ *
+ * All external data (emails, messages, web pages, calendar events, etc.)
+ * should be wrapped via `wrapUntrustedContent()` before entering the LLM
+ * conversation context. The wrapper:
+ *
+ * 1. Delimits external content with `<external_content>` XML boundaries so
+ *    the model can distinguish data from instructions.
+ * 2. Escapes boundary-breaking sequences within the content.
+ * 3. Enforces per-source character budgets to prevent context flooding.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type UntrustedContentSource =
+  | "email"
+  | "slack"
+  | "web"
+  | "calendar"
+  | "webhook"
+  | "search"
+  | "tool_result";
+
+export interface WrapOptions {
+  /** Which external source produced this content. */
+  source: UntrustedContentSource;
+  /** Origin identifier (sender email, URL, etc.). Sanitized before inclusion. */
+  sourceDetail?: string;
+  /** Override the default character budget for this source. */
+  maxChars?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Per-source character budgets
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BUDGETS: Record<UntrustedContentSource, number> = {
+  email: 20_000,
+  slack: 10_000,
+  web: 40_000,
+  calendar: 5_000,
+  webhook: 10_000,
+  search: 15_000,
+  tool_result: 20_000,
+};
+
+// ---------------------------------------------------------------------------
+// Core API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap external content in structural XML boundaries.
+ *
+ * The returned string is safe to include directly in an LLM message - the
+ * model will see it delimited as third-party data.
+ */
+export function wrapUntrustedContent(
+  content: string,
+  options: WrapOptions,
+): string {
+  const budget = options.maxChars ?? DEFAULT_BUDGETS[options.source];
+  const escaped = escapeContentBoundaries(content);
+  const truncated = truncateWithNotice(escaped, budget);
+  const detail = options.sourceDetail
+    ? ` origin="${sanitizeAttr(options.sourceDetail)}"`
+    : "";
+  return `<external_content source="${options.source}"${detail}>\n${truncated}\n</external_content>`;
+}
+
+/**
+ * Escape sequences that could break out of the `<external_content>` wrapper.
+ * Case-insensitive to cover mixed-case evasion attempts.
+ */
+export function escapeContentBoundaries(content: string): string {
+  return content.replace(
+    /<\/external_content/gi,
+    (match) => `&lt;${match.slice(1)}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Sanitize a value for use as an XML attribute (no quotes, angle brackets, newlines). */
+function sanitizeAttr(value: string): string {
+  return value.replace(/[<>"&\r\n]/g, "").slice(0, 200);
+}
+
+/** Truncate content to a character budget, appending a notice if truncated. */
+function truncateWithNotice(content: string, maxChars: number): string {
+  if (content.length <= maxChars) {
+    return content;
+  }
+  return (
+    content.slice(0, maxChars) +
+    `\n[... truncated at ${maxChars.toLocaleString()} characters]`
+  );
+}

package/src/skills/catalog-cache.ts

@@ -12,24 +12,50 @@ const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 let cachedCatalog: CatalogSkill[] | null = null;
 let cacheTimestamp = 0;
 
-/** Resolve the Vellum catalog with in-memory caching. */
+/**
+ * Resolve the Vellum catalog with in-memory caching.
+ *
+ * When a local first-party catalog is available (dev mode or compiled binary
+ * with bundled skills), merge it with the remote catalog so skills published
+ * after the build still show up. Local entries take precedence by id. If the
+ * remote fetch fails and a local catalog exists, fall back to it so listings
+ * keep working offline. Mirrors `resolveCatalog()` in `catalog-install.ts`.
+ */
 export async function getCatalog(): Promise<CatalogSkill[]> {
   if (cachedCatalog && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
     return cachedCatalog;
   }
   const repoSkillsDir = getRepoSkillsDir();
+  const local = repoSkillsDir ? readLocalCatalog(repoSkillsDir) : [];
   let catalog: CatalogSkill[];
-  if (repoSkillsDir) {
-    catalog = readLocalCatalog(repoSkillsDir);
-  } else {
-    try {
-      catalog = await fetchCatalog();
-    } catch (err) {
+  try {
+    const remote = await fetchCatalog();
+    if (local.length > 0) {
+      const localIds = new Set(local.map((s) => s.id));
+      catalog = [...local, ...remote.filter((s) => !localIds.has(s.id))];
+    } else {
+      catalog = remote;
+    }
+  } catch (err) {
+    if (cachedCatalog) {
+      log.warn(
+        { err },
+        "Failed to fetch Vellum catalog, keeping stale merged cache",
+      );
+      // Reset the TTL window so subsequent calls during the outage are served
+      // from cache instead of re-entering fetchCatalog() on every call.
+      cacheTimestamp = Date.now();
+      return cachedCatalog;
+    }
+    if (local.length > 0) {
       log.warn(
         { err },
-        "Failed to fetch Vellum catalog, using stale cache or empty",
+        "Failed to fetch Vellum catalog, falling back to bundled local catalog",
       );
-      return cachedCatalog ?? [];
+      catalog = local;
+    } else {
+      log.warn({ err }, "Failed to fetch Vellum catalog, returning empty");
+      return [];
     }
   }
   cachedCatalog = catalog;

package/src/skills/catalog-install.ts

@@ -52,14 +52,42 @@ export function getSkillsIndexPath(): string {
 }
 
 /**
- * Resolve the repo-level skills/ directory when running in dev mode.
- * Returns the path if VELLUM_DEV is set and the directory exists, or undefined.
+ * Resolve the directory containing a `catalog.json` and first-party skill
+ * sources — either bundled next to a compiled binary (e.g. `Vellum.app`) or
+ * in the dev repo.
+ *
+ * Both `getCatalog()` in `catalog-cache.ts` and `resolveCatalog()` below
+ * merge the local catalog with the remote one so skills published after a
+ * release still show up; the local catalog is used as an offline fallback
+ * when the remote fetch fails.
  */
 export function getRepoSkillsDir(): string | undefined {
+  const importDir = import.meta.dir;
+
+  if (importDir.startsWith("/$bunfs/")) {
+    const execDir = dirname(process.execPath);
+    // macOS .app bundle: binary in Contents/MacOS/, resources in Contents/Resources/
+    const resourcesPath = join(
+      execDir,
+      "..",
+      "Resources",
+      "first-party-skills",
+    );
+    if (existsSync(join(resourcesPath, "catalog.json"))) {
+      return resourcesPath;
+    }
+    // Next to the binary (non-app-bundle compiled deployments)
+    const execDirPath = join(execDir, "first-party-skills");
+    if (existsSync(join(execDirPath, "catalog.json"))) {
+      return execDirPath;
+    }
+    return undefined;
+  }
+
   if (!process.env.VELLUM_DEV) return undefined;
 
   // assistant/src/skills/catalog-install.ts -> ../../../skills/
-  const candidate = join(import.meta.dir, "..", "..", "..", "skills");
+  const candidate = join(importDir, "..", "..", "..", "skills");
   if (existsSync(join(candidate, "catalog.json"))) {
     return candidate;
   }

package/src/skills/skill-cache-store.ts

@@ -0,0 +1,97 @@
+import { randomBytes } from "crypto";
+
+/** Default time-to-live for cache entries: 30 minutes. */
+const DEFAULT_TTL_MS = 30 * 60_000;
+
+/** Default maximum number of entries before LRU eviction kicks in. */
+const DEFAULT_MAX_ENTRIES = 64;
+
+interface CacheEntry {
+  data: unknown;
+  expiresAt: number;
+}
+
+/**
+ * Daemon-process singleton in-memory cache with TTL and LRU eviction.
+ *
+ * - Keys are auto-generated 16-char hex strings unless an explicit key is provided.
+ * - TTL defaults to 30 minutes; per-entry override via `ttlMs`.
+ * - Uses Map insertion order for LRU; `get` refreshes position.
+ * - At capacity, the oldest entry is evicted before a new insert.
+ * - Expired entries are lazily evicted on `get`.
+ */
+const _store = new Map<string, CacheEntry>();
+
+/**
+ * Store a value in the cache.
+ *
+ * If `options.key` is provided, the entry is upserted at that key
+ * (refreshing insertion order and resetting expiry).
+ * Otherwise a random 16-char hex key is generated.
+ */
+export function setCacheEntry(
+  data: unknown,
+  options?: { key?: string; ttlMs?: number },
+): { key: string } {
+  const key = options?.key ?? randomBytes(8).toString("hex");
+  const ttl = options?.ttlMs ?? DEFAULT_TTL_MS;
+
+  // Upsert: delete first so the re-insert moves to the end of the Map
+  // (refreshes LRU position).
+  if (_store.has(key)) {
+    _store.delete(key);
+  }
+
+  // LRU eviction: if at capacity after removing a potential existing key,
+  // drop the oldest entry (first key in Map iteration order).
+  if (_store.size >= DEFAULT_MAX_ENTRIES) {
+    const oldest = _store.keys().next().value;
+    if (oldest !== undefined) _store.delete(oldest);
+  }
+
+  _store.set(key, { data, expiresAt: Date.now() + ttl });
+  return { key };
+}
+
+/**
+ * Retrieve a value from the cache.
+ *
+ * Returns `null` if the key does not exist or the entry has expired.
+ * On a hit, the entry is moved to the end of the Map (LRU refresh).
+ */
+export function getCacheEntry(key: string): { data: unknown } | null {
+  const entry = _store.get(key);
+  if (!entry) return null;
+
+  // Lazy TTL eviction.
+  if (Date.now() >= entry.expiresAt) {
+    _store.delete(key);
+    return null;
+  }
+
+  // LRU refresh: delete + re-set moves the entry to the tail.
+  _store.delete(key);
+  _store.set(key, entry);
+
+  return { data: entry.data };
+}
+
+/**
+ * Remove a cache entry by key. Returns `true` if an entry was deleted,
+ * `false` if the key was not present (idempotent).
+ */
+export function deleteCacheEntry(key: string): boolean {
+  return _store.delete(key);
+}
+
+/** Clear all entries — exposed for test isolation only. */
+export function clearCacheForTests(): void {
+  _store.clear();
+}
+
+/** Visible-for-testing internals. */
+export const _internals = {
+  store: _store,
+  DEFAULT_TTL_MS,
+  DEFAULT_MAX_ENTRIES,
+};

package/src/stt/__tests__/daemon-batch-transcriber.test.ts

@@ -45,6 +45,19 @@ mock.module("../../providers/speech-to-text/google-gemini.js", () => ({
   },
 }));
 
+let mockXAITranscribeResult: { text: string } = { text: "" };
+let mockXAITranscribeError: Error | null = null;
+
+mock.module("../../providers/speech-to-text/xai.js", () => ({
+  XAIProvider: class MockXAIProvider {
+    constructor(_apiKey: string) {}
+    async transcribe(_audio: Buffer, _mimeType: string, _signal?: AbortSignal) {
+      if (mockXAITranscribeError) throw mockXAITranscribeError;
+      return mockXAITranscribeResult;
+    }
+  },
+}));
+
 // Dynamic import so mocks are active when the module loads.
 const { createDaemonBatchTranscriber, normalizeSttError } =
   await import("../daemon-batch-transcriber.js");
@@ -61,6 +74,8 @@ describe("createDaemonBatchTranscriber", () => {
     mockDeepgramTranscribeError = null;
     mockGeminiTranscribeResult = { text: "" };
     mockGeminiTranscribeError = null;
+    mockXAITranscribeResult = { text: "" };
+    mockXAITranscribeError = null;
   });
 
   // -------------------------------------------------------------------------
@@ -305,6 +320,67 @@ describe("createDaemonBatchTranscriber", () => {
     expect(createDaemonBatchTranscriber(null, "google-gemini")).toBeNull();
     expect(createDaemonBatchTranscriber(undefined, "google-gemini")).toBeNull();
   });
+
+  // -------------------------------------------------------------------------
+  // Provider identity — xAI
+  // -------------------------------------------------------------------------
+
+  test("reports providerId as xai when created with xai", () => {
+    const transcriber = createDaemonBatchTranscriber("xai-test-key", "xai");
+    expect(transcriber).not.toBeNull();
+    expect(transcriber!.providerId).toBe("xai");
+  });
+
+  test("reports boundaryId as daemon-batch for xai", () => {
+    const transcriber = createDaemonBatchTranscriber("xai-test-key", "xai");
+    expect(transcriber!.boundaryId).toBe("daemon-batch");
+  });
+
+  // -------------------------------------------------------------------------
+  // Successful transcription — xAI
+  // -------------------------------------------------------------------------
+
+  test("delegates transcription to the xAI provider", async () => {
+    mockXAITranscribeResult = { text: "Hello from xAI" };
+
+    const transcriber = createDaemonBatchTranscriber("xai-test-key", "xai");
+    const result = await transcriber!.transcribe({
+      audio: Buffer.from("fake-audio"),
+      mimeType: "audio/ogg",
+    });
+
+    expect(result).toEqual({ text: "Hello from xAI" });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error propagation — xAI
+  // -------------------------------------------------------------------------
+
+  test("propagates xAI errors unchanged", async () => {
+    const original = new Error("xAI API error (401): Invalid credentials");
+    mockXAITranscribeError = original;
+
+    const transcriber = createDaemonBatchTranscriber("xai-test-key", "xai");
+
+    try {
+      await transcriber!.transcribe({
+        audio: Buffer.from("audio"),
+        mimeType: "audio/wav",
+      });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBe(original);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Null on missing key — xAI
+  // -------------------------------------------------------------------------
+
+  test("returns null for xai when no API key is provided", () => {
+    expect(createDaemonBatchTranscriber(null, "xai")).toBeNull();
+    expect(createDaemonBatchTranscriber(undefined, "xai")).toBeNull();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/stt/daemon-batch-transcriber.ts

@@ -10,6 +10,7 @@
  * - OpenAI Whisper (`openai-whisper`)
  * - Deepgram (`deepgram`)
  * - Google Gemini (`google-gemini`)
+ * - xAI (`xai`)
  */
 
 import type {
@@ -120,6 +121,36 @@ class GoogleGeminiBatchTranscriber implements BatchTranscriber {
   }
 }
 
+// ---------------------------------------------------------------------------
+// xAI adapter — implements BatchTranscriber on top of the xAI audio
+// transcription provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps `XAIProvider` behind the `BatchTranscriber` contract.
+ *
+ * Same error-propagation semantics as WhisperBatchTranscriber: raw provider
+ * errors pass through unchanged.
+ */
+class XAIBatchTranscriber implements BatchTranscriber {
+  readonly providerId = "xai" as const;
+  readonly boundaryId = "daemon-batch" as const;
+
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    request: SttTranscribeRequest,
+  ): Promise<SttTranscribeResult> {
+    const { XAIProvider } = await import("../providers/speech-to-text/xai.js");
+    const provider = new XAIProvider(this.apiKey);
+    return provider.transcribe(request.audio, request.mimeType, request.signal);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Error normalization
 // ---------------------------------------------------------------------------
@@ -185,6 +216,8 @@ export function createDaemonBatchTranscriber(
       return new DeepgramBatchTranscriber(apiKey);
     case "google-gemini":
       return new GoogleGeminiBatchTranscriber(apiKey);
+    case "xai":
+      return new XAIBatchTranscriber(apiKey);
     default: {
       // Exhaustive check — compile error if a new SttProviderId is added
       // without a corresponding case here.

package/src/stt/stt-stream-session.ts

@@ -30,6 +30,10 @@
  *   configurable window.
  */
 
+import {
+  listProviderIds,
+  supportsBoundary,
+} from "../providers/speech-to-text/provider-catalog.js";
 import { getLogger } from "../util/logger.js";
 import type { StreamingTranscriber, SttStreamServerEvent } from "./types.js";
 
@@ -172,10 +176,13 @@ export class SttStreamSession {
           { provider: this.provider },
           "Streaming transcriber unavailable for provider",
         );
+        const streamingProviders = listProviderIds()
+          .filter((id) => supportsBoundary(id, "daemon-streaming"))
+          .join(", ");
         this.sendEvent({
           type: "error",
           category: "provider-error",
-          message: `Streaming transcription is not supported for provider "${this.provider}". Supported providers: deepgram, google-gemini, openai-whisper.`,
+          message: `Streaming transcription is not supported for provider "${this.provider}". Supported providers: ${streamingProviders}.`,
         });
         this.sendEvent({ type: "closed" });
         this.state = "closed";

package/src/stt/types.ts

@@ -20,7 +20,11 @@
  * Canonical provider identifiers for daemon-hosted STT backends.
  * Extend this union as new providers are integrated.
  */
-export type SttProviderId = "openai-whisper" | "deepgram" | "google-gemini";
+export type SttProviderId =
+  | "openai-whisper"
+  | "deepgram"
+  | "google-gemini"
+  | "xai";
 
 /**
  * Telephony-specific STT capability class.