@vellumai/assistant 0.5.3 → 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/auth/route-policy.ts

@@ -128,7 +128,7 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "messages:POST", scopes: ["chat.write"] },
   { endpoint: "btw", scopes: ["chat.write"] },
   { endpoint: "conversations", scopes: ["chat.read"] },
-  { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
+  { endpoint: "conversations:POST", scopes: ["chat.write"] },
   { endpoint: "conversations/fork", scopes: ["chat.write"] },
   { endpoint: "conversations/switch", scopes: ["chat.write"] },
   { endpoint: "conversations/name", scopes: ["chat.write"] },
@@ -348,6 +348,7 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "config/embeddings:PUT", scopes: ["settings.write"] },
 
   // Conversation management
+  { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
   { endpoint: "conversations/wipe", scopes: ["chat.write"] },
   { endpoint: "conversations/reorder", scopes: ["chat.write"] },
 
@@ -470,6 +471,14 @@ for (const { endpoint, scopes } of ACTOR_ENDPOINTS) {
   });
 }
 
+// Clear-all conversations: elevated to settings.write (destructive bulk operation).
+// Uses a distinct key so the single-conversation DELETE (conversations:DELETE)
+// retains the lower chat.write scope.
+registerPolicy("conversations/clear-all", {
+  requiredScopes: ["settings.write"],
+  allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
+});
+
 // Channel inbound: gateway-only
 registerPolicy("channels/inbound", {
   requiredScopes: ["ingress.write"],

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/conversation-management-routes.ts

@@ -1,6 +1,7 @@
 /**
  * Route handlers for conversation management operations.
  *
+ * POST   /v1/conversations                 — create a new conversation
  * POST   /v1/conversations/switch         — switch to an existing conversation
  * POST   /v1/conversations/fork           — fork an existing conversation
  * PATCH  /v1/conversations/:id/name       — rename a conversation
@@ -19,7 +20,9 @@ import {
   PRIVATE_CONVERSATION_FORK_ERROR,
   wipeConversation,
 } from "../../memory/conversation-crud.js";
+import { updateConversationTitle } from "../../memory/conversation-crud.js";
 import {
+  getOrCreateConversation,
   resolveConversationId,
   setConversationKeyIfAbsent,
 } from "../../memory/conversation-key-store.js";
@@ -66,6 +69,44 @@ export function conversationManagementRouteDefinitions(
   deps: ConversationManagementDeps,
 ): RouteDefinition[] {
   return [
+    {
+      endpoint: "conversations",
+      method: "POST",
+      policyKey: "conversations",
+      handler: async ({ req }) => {
+        let body: { conversationKey?: string; conversationType?: string } = {};
+        try {
+          body = (await req.json()) as typeof body;
+        } catch {
+          // Empty or malformed body — fall through with defaults.
+        }
+        const conversationKey = body.conversationKey ?? crypto.randomUUID();
+        const requestedType =
+          body.conversationType === "private" ? "private" : "standard";
+        const result = getOrCreateConversation(conversationKey, {
+          conversationType: requestedType,
+        });
+        if (result.created) {
+          updateConversationTitle(result.conversationId, "New Conversation");
+        }
+        log.info(
+          {
+            conversationId: result.conversationId,
+            conversationKey,
+            created: result.created,
+          },
+          "Created conversation via POST",
+        );
+        return Response.json(
+          {
+            id: result.conversationId,
+            conversationKey,
+            conversationType: result.conversationType,
+          },
+          { status: result.created ? 201 : 200 },
+        );
+      },
+    },
     {
       endpoint: "conversations/fork",
       method: "POST",
@@ -185,8 +226,17 @@ export function conversationManagementRouteDefinitions(
     {
       endpoint: "conversations",
       method: "DELETE",
-      policyKey: "conversations",
-      handler: () => {
+      policyKey: "conversations/clear-all",
+      handler: ({ req }) => {
+        const confirm = req.headers.get("x-confirm-destructive");
+        if (confirm !== "clear-all-conversations") {
+          return httpError(
+            "BAD_REQUEST",
+            "DELETE /v1/conversations permanently deletes ALL conversations, messages, and memory. " +
+              "To confirm, set header X-Confirm-Destructive: clear-all-conversations",
+            400,
+          );
+        }
         deps.clearAllConversations();
         return new Response(null, { status: 204 });
       },
@@ -225,6 +275,24 @@ export function conversationManagementRouteDefinitions(
             targetId: summaryId,
           });
         }
+        for (const obsId of result.deletedObservationIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "observation",
+            targetId: obsId,
+          });
+        }
+        for (const chunkId of result.deletedChunkIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "chunk",
+            targetId: chunkId,
+          });
+        }
+        for (const episodeId of result.deletedEpisodeIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "episode",
+            targetId: episodeId,
+          });
+        }
         log.info(
           {
             conversationId: resolvedId,
@@ -281,6 +349,24 @@ export function conversationManagementRouteDefinitions(
             targetId: summaryId,
           });
         }
+        for (const obsId of deleted.deletedObservationIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "observation",
+            targetId: obsId,
+          });
+        }
+        for (const chunkId of deleted.deletedChunkIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "chunk",
+            targetId: chunkId,
+          });
+        }
+        for (const episodeId of deleted.deletedEpisodeIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "episode",
+            targetId: episodeId,
+          });
+        }
         log.info({ conversationId: resolvedId }, "Deleted conversation");
         return new Response(null, { status: 204 });
       },