@vellumai/assistant 0.5.4 → 0.5.6

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

@@ -176,6 +176,7 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
 
   // Settings / integrations / identity
   { endpoint: "identity", scopes: ["settings.read"] },
+  { endpoint: "identity/intro", scopes: ["settings.read"] },
   { endpoint: "brain-graph", scopes: ["settings.read"] },
   { endpoint: "brain-graph-ui", scopes: ["settings.read"] },
   { endpoint: "contacts", scopes: ["settings.read"] },
@@ -347,6 +348,10 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "config/embeddings:GET", scopes: ["settings.read"] },
   { endpoint: "config/embeddings:PUT", scopes: ["settings.write"] },
 
+  // Permissions config
+  { endpoint: "config/permissions/skip:GET", scopes: ["settings.read"] },
+  { endpoint: "config/permissions/skip:PUT", scopes: ["settings.write"] },
+
   // Conversation management
   { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
   { endpoint: "conversations/wipe", scopes: ["chat.write"] },
@@ -355,6 +360,9 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   // Conversation search
   { endpoint: "conversations/search", scopes: ["chat.read"] },
 
+  // Conversation starters
+  { endpoint: "conversation-starters", scopes: ["chat.read"] },
+
   // Message content
   { endpoint: "messages/content", scopes: ["chat.read"] },
   { endpoint: "messages/llm-context", scopes: ["chat.read"] },
@@ -498,3 +506,9 @@ for (const endpoint of INTERNAL_ENDPOINTS) {
     allowedPrincipalTypes: ["svc_gateway"],
   });
 }
+
+// Admin control-plane endpoints: gateway-only
+registerPolicy("admin/upgrade-broadcast", {
+  requiredScopes: ["internal.write"],
+  allowedPrincipalTypes: ["svc_gateway"],
+});

package/src/runtime/auth/token-service.ts

@@ -28,6 +28,22 @@ import type { ScopeProfile, TokenAudience, TokenClaims } from "./types.js";
 
 const log = getLogger("token-service");
 
+// ---------------------------------------------------------------------------
+// Bootstrap sentinel error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when the gateway's signing-key bootstrap endpoint returns 403,
+ * indicating that bootstrap has already completed (daemon restart case).
+ * The caller should fall back to loading the key from disk.
+ */
+export class BootstrapAlreadyCompleted extends Error {
+  constructor() {
+    super("Gateway signing key bootstrap already completed");
+    this.name = "BootstrapAlreadyCompleted";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Signing key management
 // ---------------------------------------------------------------------------
@@ -78,6 +94,123 @@ export function loadOrCreateSigningKey(): Buffer {
   return newKey;
 }
 
+/**
+ * Fetch the shared signing key from the gateway's bootstrap endpoint.
+ *
+ * Used in Docker mode where the gateway owns the signing key and the daemon
+ * must fetch it at startup. Retries up to 30 times with 1s intervals to
+ * tolerate gateway startup delays.
+ *
+ * @returns A 32-byte Buffer containing the signing key.
+ * @throws {BootstrapAlreadyCompleted} If the gateway returns 403 (bootstrap
+ *   already completed — daemon restart case). Caller should fall back to
+ *   loading the key from disk.
+ * @throws {Error} If the gateway is unreachable after all retry attempts.
+ */
+export async function fetchSigningKeyFromGateway(): Promise<Buffer> {
+  const gatewayUrl = process.env.GATEWAY_INTERNAL_URL;
+  if (!gatewayUrl) {
+    throw new Error("GATEWAY_INTERNAL_URL not set — cannot fetch signing key");
+  }
+
+  const maxAttempts = 30;
+  const intervalMs = 1000;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    let resp: Response | undefined;
+    try {
+      resp = await fetch(`${gatewayUrl}/internal/signing-key-bootstrap`, {
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch (err) {
+      log.warn(
+        { err, attempt },
+        "Signing key bootstrap: connection failed, retrying",
+      );
+      await Bun.sleep(intervalMs);
+      continue;
+    }
+
+    if (resp.ok) {
+      const body = (await resp.json()) as { key: string };
+      const keyBuf = Buffer.from(body.key, "hex");
+      if (keyBuf.length !== 32) {
+        throw new Error(`Invalid signing key length: ${keyBuf.length}`);
+      }
+      log.info("Signing key fetched from gateway bootstrap endpoint");
+      return keyBuf;
+    }
+
+    if (resp.status === 403) {
+      // Bootstrap already completed — fall through to file-based load.
+      // This happens on daemon restart when the gateway lockfile persists.
+      log.info(
+        "Gateway signing key bootstrap already completed — loading from disk",
+      );
+      throw new BootstrapAlreadyCompleted();
+    }
+
+    log.warn(
+      { status: resp.status, attempt },
+      "Signing key bootstrap: gateway not ready, retrying",
+    );
+
+    await Bun.sleep(intervalMs);
+  }
+
+  throw new Error("Signing key bootstrap: timed out waiting for gateway");
+}
+
+/**
+ * Persist a signing key to disk using an atomic-write pattern.
+ * Used after fetching the key from the gateway so daemon restarts can
+ * load it from disk when the gateway returns 403.
+ */
+function persistSigningKey(key: Buffer): void {
+  const keyPath = getSigningKeyPath();
+  const dir = dirname(keyPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = keyPath + ".tmp." + process.pid;
+  writeFileSync(tmpPath, key, { mode: 0o600 });
+  renameSync(tmpPath, keyPath);
+  chmodSync(keyPath, 0o600);
+}
+
+/**
+ * Resolve the signing key for the current environment.
+ *
+ * In Docker mode (IS_CONTAINERIZED=true + GATEWAY_INTERNAL_URL set), fetches
+ * the key from the gateway's bootstrap endpoint and persists it locally for
+ * restart resilience. On daemon restart (gateway returns 403), falls back to
+ * loading the key from disk.
+ *
+ * In local mode, delegates to the existing file-based loadOrCreateSigningKey().
+ */
+export async function resolveSigningKey(): Promise<Buffer> {
+  const isContainerized = process.env.IS_CONTAINERIZED === "true";
+  const gatewayUrl = process.env.GATEWAY_INTERNAL_URL;
+
+  if (isContainerized && gatewayUrl) {
+    try {
+      const key = await fetchSigningKeyFromGateway();
+      // Persist locally so daemon restarts (where gateway returns 403) load from disk.
+      persistSigningKey(key);
+      return key;
+    } catch (err) {
+      if (err instanceof BootstrapAlreadyCompleted) {
+        // Gateway already bootstrapped (daemon restart) — load from disk.
+        return loadOrCreateSigningKey();
+      }
+      throw err;
+    }
+  }
+
+  // Local mode: use file-based load/create (unchanged behavior).
+  return loadOrCreateSigningKey();
+}
+
 function getSigningKey(): Buffer {
   if (!_authSigningKey) {
     if (process.env.NODE_ENV === "test") {