@vellumai/assistant 0.5.4 → 0.5.5

package/src/platform/client.test.ts

@@ -0,0 +1,148 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mutable mock state
+// ---------------------------------------------------------------------------
+
+let mockManagedProxyCtx = {
+  enabled: false,
+  platformBaseUrl: "",
+  assistantApiKey: "",
+};
+let mockAssistantId = "";
+
+// ---------------------------------------------------------------------------
+// Module mocks
+// ---------------------------------------------------------------------------
+
+mock.module("../providers/managed-proxy/context.js", () => ({
+  resolveManagedProxyContext: async () => mockManagedProxyCtx,
+}));
+
+mock.module("../config/env.js", () => ({
+  getPlatformAssistantId: () => mockAssistantId,
+}));
+
+// ---------------------------------------------------------------------------
+// Import under test (after mocks)
+// ---------------------------------------------------------------------------
+
+import { VellumPlatformClient } from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("VellumPlatformClient", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    mockManagedProxyCtx = {
+      enabled: true,
+      platformBaseUrl: "https://platform.example.com",
+      assistantApiKey: "sk-test-key",
+    };
+    mockAssistantId = "asst-123";
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  describe("create()", () => {
+    test("returns a client when all prerequisites are met", async () => {
+      const client = await VellumPlatformClient.create();
+      expect(client).not.toBeNull();
+      expect(client!.baseUrl).toBe("https://platform.example.com");
+      expect(client!.assistantApiKey).toBe("sk-test-key");
+      expect(client!.platformAssistantId).toBe("asst-123");
+    });
+
+    test("returns null when managed proxy is not enabled", async () => {
+      mockManagedProxyCtx = {
+        enabled: false,
+        platformBaseUrl: "",
+        assistantApiKey: "",
+      };
+
+      const client = await VellumPlatformClient.create();
+      expect(client).toBeNull();
+    });
+
+    test("returns client with empty assistantId when assistant ID is missing", async () => {
+      mockAssistantId = "";
+
+      const client = await VellumPlatformClient.create();
+      expect(client).not.toBeNull();
+      expect(client!.platformAssistantId).toBe("");
+    });
+
+    test("strips trailing slash from platform base URL", async () => {
+      mockManagedProxyCtx.platformBaseUrl = "https://platform.example.com///";
+
+      const client = await VellumPlatformClient.create();
+      expect(client!.baseUrl).toBe("https://platform.example.com");
+    });
+  });
+
+  describe("fetch()", () => {
+    test("prepends base URL to path", async () => {
+      globalThis.fetch = mock(async (url: string | URL | Request) => {
+        expect(String(url)).toBe(
+          "https://platform.example.com/v1/some/endpoint/",
+        );
+        return new Response("ok", { status: 200 });
+      }) as unknown as typeof globalThis.fetch;
+
+      const client = await VellumPlatformClient.create();
+      await client!.fetch("/v1/some/endpoint/");
+    });
+
+    test("injects Api-Key auth header", async () => {
+      globalThis.fetch = mock(
+        async (_url: string | URL | Request, init?: RequestInit) => {
+          const headers = new Headers(init?.headers);
+          expect(headers.get("Authorization")).toBe("Api-Key sk-test-key");
+          return new Response("ok", { status: 200 });
+        },
+      ) as unknown as typeof globalThis.fetch;
+
+      const client = await VellumPlatformClient.create();
+      await client!.fetch("/v1/test/");
+    });
+
+    test("preserves caller-provided headers", async () => {
+      globalThis.fetch = mock(
+        async (_url: string | URL | Request, init?: RequestInit) => {
+          const headers = new Headers(init?.headers);
+          expect(headers.get("Content-Type")).toBe("application/json");
+          expect(headers.get("Authorization")).toBe("Api-Key sk-test-key");
+          return new Response("ok", { status: 200 });
+        },
+      ) as unknown as typeof globalThis.fetch;
+
+      const client = await VellumPlatformClient.create();
+      await client!.fetch("/v1/test/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    test("passes through request init options", async () => {
+      globalThis.fetch = mock(
+        async (_url: string | URL | Request, init?: RequestInit) => {
+          expect(init?.method).toBe("POST");
+          expect(init?.body).toBe('{"key":"value"}');
+          return new Response("ok", { status: 200 });
+        },
+      ) as unknown as typeof globalThis.fetch;
+
+      const client = await VellumPlatformClient.create();
+      await client!.fetch("/v1/test/", {
+        method: "POST",
+        body: '{"key":"value"}',
+      });
+    });
+  });
+});

package/src/platform/client.ts

@@ -0,0 +1,71 @@
+/**
+ * Centralized platform API client.
+ *
+ * Owns managed proxy context resolution, prerequisite validation, and
+ * authenticated fetch for all platform API calls that use Api-Key auth.
+ */
+
+import { getPlatformAssistantId } from "../config/env.js";
+import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+
+export class VellumPlatformClient {
+  private readonly platformBaseUrl: string;
+  private readonly apiKey: string;
+  private readonly assistantId: string;
+
+  private constructor(
+    platformBaseUrl: string,
+    apiKey: string,
+    assistantId: string,
+  ) {
+    this.platformBaseUrl = platformBaseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.assistantId = assistantId;
+  }
+
+  /**
+   * Create a platform client by resolving managed proxy context.
+   *
+   * Returns `null` when auth prerequisites are missing (not logged in, no API
+   * key). The assistant ID is resolved but not required — callers that need it
+   * should check `platformAssistantId` themselves.
+   */
+  static async create(): Promise<VellumPlatformClient | null> {
+    const ctx = await resolveManagedProxyContext();
+    if (!ctx.enabled) return null;
+
+    const assistantId = getPlatformAssistantId();
+
+    return new VellumPlatformClient(
+      ctx.platformBaseUrl,
+      ctx.assistantApiKey,
+      assistantId,
+    );
+  }
+
+  /**
+   * Authenticated fetch against the platform API.
+   *
+   * Prepends `platformBaseUrl` to `path` and injects the `Api-Key` auth header.
+   * Callers handle response parsing and domain-specific error mapping.
+   */
+  async fetch(path: string, init?: RequestInit): Promise<Response> {
+    const url = `${this.platformBaseUrl}${path}`;
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Api-Key ${this.apiKey}`);
+
+    return fetch(url, { ...init, headers });
+  }
+
+  get baseUrl(): string {
+    return this.platformBaseUrl;
+  }
+
+  get assistantApiKey(): string {
+    return this.apiKey;
+  }
+
+  get platformAssistantId(): string {
+    return this.assistantId;
+  }
+}

package/src/providers/speech-to-text/openai-whisper.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Module mocks (must precede dynamic imports)
+// ---------------------------------------------------------------------------
+
+let mockOpenAIKey: string | undefined;
+
+mock.module("../../security/secure-keys.js", () => ({
+  getProviderKeyAsync: async (provider: string) =>
+    provider === "openai" ? mockOpenAIKey : undefined,
+}));
+
+// Dynamic import so the mock is in effect when resolve.ts loads.
+const { resolveSpeechToTextProvider } = await import("./resolve.js");
+
+import { OpenAIWhisperProvider } from "./openai-whisper.js";
+
+const TEST_API_KEY = "sk-test-key-for-unit-tests";
+
+describe("OpenAIWhisperProvider", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("successful transcription returns text", async () => {
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(JSON.stringify({ text: "  Hello, world!  " }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("fake-audio"),
+      "audio/ogg",
+    );
+
+    expect(result).toEqual({ text: "Hello, world!" });
+  });
+
+  test("API error throws with status and partial body", async () => {
+    const errorBody = JSON.stringify({
+      error: {
+        message: "Invalid API key provided",
+        type: "invalid_request_error",
+      },
+    });
+
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(errorBody, {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+
+    await expect(
+      provider.transcribe(Buffer.from("fake-audio"), "audio/wav"),
+    ).rejects.toThrow("Whisper API error (401)");
+  });
+
+  test("sends correct FormData structure (model=whisper-1, file blob with correct MIME)", async () => {
+    let capturedBody: FormData | undefined;
+    let capturedHeaders: HeadersInit | undefined;
+
+    globalThis.fetch = (async (
+      url: string | URL | Request,
+      init?: RequestInit,
+    ) => {
+      capturedBody = init?.body as FormData;
+      capturedHeaders = init?.headers;
+      expect(url).toBe("https://api.openai.com/v1/audio/transcriptions");
+      expect(init?.method).toBe("POST");
+
+      return new Response(JSON.stringify({ text: "transcribed" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+    await provider.transcribe(Buffer.from("fake-audio"), "audio/mpeg");
+
+    // Verify authorization header
+    expect(capturedHeaders).toEqual({
+      Authorization: `Bearer ${TEST_API_KEY}`,
+    });
+
+    // Verify FormData contents
+    expect(capturedBody).toBeInstanceOf(FormData);
+    const model = capturedBody!.get("model");
+    expect(model).toBe("whisper-1");
+
+    const file = capturedBody!.get("file");
+    expect(file).toBeInstanceOf(Blob);
+    expect((file as Blob).type).toBe("audio/mpeg");
+  });
+
+  test("returns empty text when API returns empty text field", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ text: "" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("returns empty text when API response has no text property", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("error body is truncated to 300 characters", async () => {
+    const longBody = "x".repeat(500);
+
+    globalThis.fetch = (async () => {
+      return new Response(longBody, { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const provider = new OpenAIWhisperProvider(TEST_API_KEY);
+
+    try {
+      await provider.transcribe(Buffer.from("audio"), "audio/wav");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain("Whisper API error (500)");
+      // The body portion should be at most 300 chars
+      const bodyPart = msg.replace("Whisper API error (500): ", "");
+      expect(bodyPart.length).toBeLessThanOrEqual(300);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSpeechToTextProvider
+// ---------------------------------------------------------------------------
+
+describe("resolveSpeechToTextProvider", () => {
+  beforeEach(() => {
+    mockOpenAIKey = undefined;
+  });
+
+  test("returns null when no OpenAI key is configured", async () => {
+    mockOpenAIKey = undefined;
+    const provider = await resolveSpeechToTextProvider();
+    expect(provider).toBeNull();
+  });
+
+  test("returns an OpenAIWhisperProvider when key exists", async () => {
+    mockOpenAIKey = "sk-real-key";
+    const provider = await resolveSpeechToTextProvider();
+    expect(provider).toBeInstanceOf(OpenAIWhisperProvider);
+  });
+});

package/src/providers/speech-to-text/openai-whisper.ts

@@ -0,0 +1,68 @@
+import type { SpeechToTextProvider, SpeechToTextResult } from "./types.js";
+
+const WHISPER_API_URL = "https://api.openai.com/v1/audio/transcriptions";
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Derive a filename extension from a MIME type so the Whisper API can detect
+ * the audio format. Falls back to "audio" when the MIME type is unrecognised.
+ */
+function extensionFromMime(mimeType: string): string {
+  const map: Record<string, string> = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/ogg": "ogg",
+    "audio/opus": "opus",
+    "audio/webm": "webm",
+    "audio/mp4": "m4a",
+    "audio/x-m4a": "m4a",
+    "audio/flac": "flac",
+  };
+  const base = mimeType.split(";")[0].trim().toLowerCase();
+  return map[base] ?? "audio";
+}
+
+export class OpenAIWhisperProvider implements SpeechToTextProvider {
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    audio: Buffer,
+    mimeType: string,
+    signal?: AbortSignal,
+  ): Promise<SpeechToTextResult> {
+    const ext = extensionFromMime(mimeType);
+
+    const formData = new FormData();
+    formData.append(
+      "file",
+      new Blob([new Uint8Array(audio)], { type: mimeType }),
+      `audio.${ext}`,
+    );
+    formData.append("model", "whisper-1");
+
+    const effectiveSignal = signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+
+    const response = await fetch(WHISPER_API_URL, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      body: formData,
+      signal: effectiveSignal,
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        `Whisper API error (${response.status}): ${body.slice(0, 300)}`,
+      );
+    }
+
+    const result = (await response.json()) as { text?: string };
+    return { text: result.text?.trim() ?? "" };
+  }
+}

package/src/providers/speech-to-text/resolve.ts

@@ -0,0 +1,9 @@
+import { getProviderKeyAsync } from "../../security/secure-keys.js";
+import { OpenAIWhisperProvider } from "./openai-whisper.js";
+import type { SpeechToTextProvider } from "./types.js";
+
+export async function resolveSpeechToTextProvider(): Promise<SpeechToTextProvider | null> {
+  const apiKey = await getProviderKeyAsync("openai");
+  if (!apiKey) return null;
+  return new OpenAIWhisperProvider(apiKey);
+}

package/src/providers/speech-to-text/types.ts

@@ -0,0 +1,17 @@
+export interface SpeechToTextResult {
+  text: string;
+}
+
+export interface SpeechToTextProvider {
+  /**
+   * Transcribe audio from a Buffer.
+   * @param audio - Raw audio data (WAV, OGG, MP3, etc.)
+   * @param mimeType - MIME type of the audio data
+   * @param signal - Optional abort signal for cancellation
+   */
+  transcribe(
+    audio: Buffer,
+    mimeType: string,
+    signal?: AbortSignal,
+  ): Promise<SpeechToTextResult>;
+}

package/src/runtime/http-server.ts

@@ -208,8 +208,8 @@ const log = getLogger("runtime-http");
 const DEFAULT_PORT = 7821;
 const DEFAULT_HOSTNAME = "127.0.0.1";
 
-/** Global hard cap on request body size (150 MB — accommodates base64-encoded 100 MB attachments). */
-const MAX_REQUEST_BODY_BYTES = 150 * 1024 * 1024;
+/** Global hard cap on request body size (512 MB — accommodates large .vbundle backup imports). */
+const MAX_REQUEST_BODY_BYTES = 512 * 1024 * 1024;
 
 export class RuntimeHttpServer {
   private server: ReturnType<typeof Bun.serve> | null = null;

package/src/runtime/routes/inbound-message-handler.ts

@@ -44,6 +44,7 @@ import { handleEditIntercept } from "./inbound-stages/edit-intercept.js";
 import { handleEscalationIntercept } from "./inbound-stages/escalation-intercept.js";
 import { handleGuardianReplyIntercept } from "./inbound-stages/guardian-reply-intercept.js";
 import { runSecretIngressCheck } from "./inbound-stages/secret-ingress-check.js";
+import { tryTranscribeAudioAttachments } from "./inbound-stages/transcribe-audio.js";
 import { handleVerificationIntercept } from "./inbound-stages/verification-intercept.js";
 
 const log = getLogger("runtime-http");
@@ -144,7 +145,7 @@ export async function handleChannelInbound(
     return httpError("BAD_REQUEST", "content must be a string", 400);
   }
 
-  const trimmedContent = typeof content === "string" ? content.trim() : "";
+  let trimmedContent = typeof content === "string" ? content.trim() : "";
   const hasAttachments =
     Array.isArray(attachmentIds) && attachmentIds.length > 0;
 
@@ -227,6 +228,29 @@ export async function handleChannelInbound(
     }
   }
 
+  // Auto-transcribe audio attachments from channel messages
+  if (hasAttachments && sourceChannel) {
+    const transcribeResult = await tryTranscribeAudioAttachments(attachmentIds);
+    switch (transcribeResult.status) {
+      case "transcribed":
+        // For voice-only messages (empty content), this becomes the message text.
+        // For audio+caption, both are preserved.
+        trimmedContent =
+          transcribeResult.text +
+          (trimmedContent ? `\n\n${trimmedContent}` : "");
+        break;
+      case "no_provider":
+      case "error":
+        // Inject a hint so the assistant knows the user sent audio and why
+        // transcription failed — it can then guide the user (e.g. set up API key).
+        trimmedContent =
+          `[Voice message received — ${transcribeResult.reason}]` +
+          (trimmedContent ? `\n\n${trimmedContent}` : "");
+        break;
+      // "no_audio", "disabled" — no action needed
+    }
+  }
+
   const sourceMessageId =
     typeof sourceMetadata?.messageId === "string"
       ? sourceMetadata.messageId
@@ -333,7 +357,7 @@ export async function handleChannelInbound(
     externalMessageId,
     conversationId: result.conversationId,
     eventId: result.eventId,
-    content,
+    content: trimmedContent,
     attachmentIds,
     sourceMetadata: body.sourceMetadata,
     actorDisplayName: body.actorDisplayName,
@@ -612,7 +636,7 @@ export async function handleChannelInbound(
       processMessage,
       conversationId: result.conversationId,
       eventId: result.eventId,
-      content: content ?? "",
+      content: trimmedContent,
       attachmentIds: hasAttachments ? attachmentIds : undefined,
       sourceChannel,
       sourceInterface,

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -79,14 +79,29 @@ export interface AclResult {
   guardianVerifyCode: string | undefined;
 }
 
+/**
+ * Strip Slack/Telegram mrkdwn formatting wrappers from a raw message.
+ * When users copy-paste a verification code from the desktop app with
+ * rich-text formatting (e.g. bold), Slack preserves it as `*code*` in
+ * the message text, which would otherwise fail the strict bare-code regex.
+ */
+function stripMrkdwnFormatting(text: string): string {
+  // Bold (*…*), italic (_…_), strikethrough (~…~), inline code (`…`)
+  return text.replace(/^[*_~`]+/, "").replace(/[*_~`]+$/, "");
+}
+
 /**
  * Parse a guardian verification code from message content.
  * Accepts a bare code as the entire message: 6-digit numeric OR 64-char hex
  * (hex is retained for compatibility with unbound inbound/bootstrap sessions
  * that intentionally use high-entropy secrets).
+ *
+ * Strips surrounding mrkdwn formatting characters first so that codes
+ * pasted with bold/italic/code formatting are still recognized.
  */
 function parseGuardianVerifyCode(content: string): string | undefined {
-  const bareMatch = content.match(/^([0-9a-fA-F]{64}|\d{6})$/);
+  const stripped = stripMrkdwnFormatting(content);
+  const bareMatch = stripped.match(/^([0-9a-fA-F]{64}|\d{6})$/);
   if (bareMatch) return bareMatch[1];
 
   return undefined;