@vellumai/assistant 0.12.0 → 0.12.1-dev.202609141913.5e16607

package/src/i18n/__tests__/i18n.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  DEFAULT_LOCALE,
+  isMessageKey,
+  localeFromAcceptLanguage,
+  MESSAGE_CATALOGS,
+  MESSAGE_KEYS,
+  negotiateLocale,
+  resolveConversationTitle,
+  SUPPORTED_LOCALES,
+  t,
+} from "../index.js";
+
+describe("negotiateLocale", () => {
+  test("matches a full shipped tag", () => {
+    expect(negotiateLocale(["es"])).toBe("es");
+    expect(negotiateLocale(["zh-TW"])).toBe("zh-TW");
+  });
+
+  test("falls back from a regional tag to the primary language", () => {
+    expect(negotiateLocale(["es-MX", "en"])).toBe("es");
+  });
+
+  test("maps Traditional Chinese tags to zh-TW", () => {
+    expect(negotiateLocale(["zh-Hant"])).toBe("zh-TW");
+    expect(negotiateLocale(["zh-HK"])).toBe("zh-TW");
+  });
+
+  test("defaults when nothing matches", () => {
+    expect(negotiateLocale([])).toBe(DEFAULT_LOCALE);
+    expect(negotiateLocale(["xx"])).toBe(DEFAULT_LOCALE);
+  });
+});
+
+describe("localeFromAcceptLanguage", () => {
+  test("honors quality values", () => {
+    expect(localeFromAcceptLanguage("fr;q=0.8, es;q=0.9, en;q=0.5")).toBe(
+      "es",
+    );
+  });
+
+  test("defaults on missing or empty", () => {
+    expect(localeFromAcceptLanguage(null)).toBe(DEFAULT_LOCALE);
+    expect(localeFromAcceptLanguage("")).toBe(DEFAULT_LOCALE);
+  });
+});
+
+describe("catalog completeness", () => {
+  test("every locale has every key", () => {
+    const keys = Object.values(MESSAGE_KEYS);
+    for (const locale of SUPPORTED_LOCALES) {
+      for (const key of keys) {
+        expect(MESSAGE_CATALOGS[locale][key].length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe("t", () => {
+  test("resolves generating and untitled per locale", () => {
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING, "en")).toBe(
+      "Generating title...",
+    );
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED, "en")).toBe(
+      "Untitled Conversation",
+    );
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED, "es")).toBe(
+      "Sin título",
+    );
+  });
+});
+
+describe("resolveConversationTitle", () => {
+  test("resolves a stored key and an empty title", () => {
+    expect(
+      resolveConversationTitle(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING, "zh"),
+    ).toBe("标题生成中...");
+    expect(resolveConversationTitle(null, "es")).toBe("Sin título");
+    expect(resolveConversationTitle("")).toBe("Untitled Conversation");
+  });
+
+  test("passes stored display strings through, including English placeholders", () => {
+    expect(resolveConversationTitle("Untitled Conversation", "es")).toBe(
+      "Untitled Conversation",
+    );
+    expect(resolveConversationTitle("Generating title...", "zh")).toBe(
+      "Generating title...",
+    );
+    expect(resolveConversationTitle("Auth Middleware Rewrite", "es")).toBe(
+      "Auth Middleware Rewrite",
+    );
+  });
+
+  test("defaults locale inside the helper", () => {
+    expect(
+      resolveConversationTitle(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING),
+    ).toBe("Generating title...");
+  });
+});
+
+describe("isMessageKey", () => {
+  test("recognizes catalog keys only", () => {
+    expect(isMessageKey(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED)).toBe(true);
+    expect(isMessageKey("Untitled Conversation")).toBe(false);
+    expect(isMessageKey("Untitled")).toBe(false);
+  });
+});

package/src/i18n/index.ts

@@ -0,0 +1,16 @@
+export {
+  DEFAULT_LOCALE,
+  isSupportedLocale,
+  localeFromAcceptLanguage,
+  negotiateLocale,
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "./locales.js";
+export {
+  isMessageKey,
+  MESSAGE_CATALOGS,
+  MESSAGE_KEYS,
+  type MessageKey,
+  t,
+} from "./messages.js";
+export { resolveConversationTitle } from "./title.js";

package/src/i18n/locales.ts

@@ -0,0 +1,93 @@
+/**
+ * Locales the daemon can resolve user-facing copy into.
+ *
+ * Keep this set aligned with `clients/web/src/i18n/supported-locales.ts`.
+ * A locale that exists only here cannot be requested by the web app; a
+ * locale that exists only there cannot be resolved for CLI or HTTP
+ * consumers that go through this module.
+ */
+
+export const DEFAULT_LOCALE = "en";
+
+export const SUPPORTED_LOCALES = ["en", "es", "ru", "zh", "zh-TW"] as const;
+
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+
+export function isSupportedLocale(value: unknown): value is SupportedLocale {
+  return (
+    typeof value === "string" &&
+    (SUPPORTED_LOCALES as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Pick the best shipped locale for an ordered list of preferred BCP 47 tags.
+ *
+ * Full tag first, then the primary language subtag, so `es-MX` resolves to
+ * `es`. `zh-Hant` / `zh-HK` / `zh-MO` map to `zh-TW`.
+ */
+export function negotiateLocale(preferred: readonly string[]): SupportedLocale {
+  for (const tag of preferred) {
+    const normalized = tag.trim();
+    if (normalized === "") {
+      continue;
+    }
+    const exact = SUPPORTED_LOCALES.find(
+      (locale) => locale.toLowerCase() === normalized.toLowerCase(),
+    );
+    if (exact) {
+      return exact;
+    }
+    const lower = normalized.toLowerCase();
+    if (
+      lower === "zh-hant" ||
+      lower.startsWith("zh-hant-") ||
+      lower === "zh-hk" ||
+      lower === "zh-mo"
+    ) {
+      return "zh-TW";
+    }
+    const base = normalized.split("-")[0]?.toLowerCase();
+    const baseMatched = SUPPORTED_LOCALES.find(
+      (locale) => locale.toLowerCase() === base,
+    );
+    if (baseMatched) {
+      return baseMatched;
+    }
+  }
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * Parse an `Accept-Language` header into preference order and negotiate.
+ *
+ * Quality values are honored; the header is a hint, not a required input.
+ * Missing or empty headers resolve to {@link DEFAULT_LOCALE}.
+ */
+export function localeFromAcceptLanguage(
+  header: string | null | undefined,
+): SupportedLocale {
+  if (header == null || header.trim() === "") {
+    return DEFAULT_LOCALE;
+  }
+  const tags = header
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      let quality = 1;
+      for (const param of params) {
+        const [name, value] = param.trim().split("=");
+        if (name === "q" && value !== undefined) {
+          const parsed = Number.parseFloat(value);
+          if (Number.isFinite(parsed)) {
+            quality = parsed;
+          }
+        }
+      }
+      return { tag: tag?.trim() ?? "", quality };
+    })
+    .filter((entry) => entry.tag.length > 0)
+    .sort((a, b) => b.quality - a.quality)
+    .map((entry) => entry.tag);
+  return negotiateLocale(tags);
+}

package/src/i18n/messages.ts

@@ -0,0 +1,61 @@
+/**
+ * Daemon message catalog.
+ *
+ * Keys are the stable identity of a hardcoded constant. English is the
+ * source language. Add a key here, then add the same key to every locale
+ * catalog. A key present in a translated catalog but missing from English
+ * is a test failure.
+ *
+ * Persist the key when a column holds a system constant. Never persist a
+ * translated string, and never treat a stored display string as a key:
+ * a user title may be in any language.
+ */
+
+import {
+  DEFAULT_LOCALE,
+  type SupportedLocale,
+} from "./locales.js";
+
+export const MESSAGE_KEYS = {
+  CONVERSATION_TITLE_GENERATING: "conversation.title.generating",
+  CONVERSATION_TITLE_UNTITLED: "conversation.title.untitled",
+} as const;
+
+export type MessageKey = (typeof MESSAGE_KEYS)[keyof typeof MESSAGE_KEYS];
+
+export const MESSAGE_CATALOGS: Record<
+  SupportedLocale,
+  Record<MessageKey, string>
+> = {
+  en: {
+    "conversation.title.generating": "Generating title...",
+    "conversation.title.untitled": "Untitled Conversation",
+  },
+  es: {
+    "conversation.title.generating": "Generando título...",
+    "conversation.title.untitled": "Sin título",
+  },
+  ru: {
+    "conversation.title.generating": "Создание названия...",
+    "conversation.title.untitled": "Без названия",
+  },
+  zh: {
+    "conversation.title.generating": "标题生成中...",
+    "conversation.title.untitled": "无标题",
+  },
+  "zh-TW": {
+    "conversation.title.generating": "標題產生中...",
+    "conversation.title.untitled": "未命名",
+  },
+};
+
+export function t(
+  key: MessageKey,
+  locale: SupportedLocale = DEFAULT_LOCALE,
+): string {
+  return MESSAGE_CATALOGS[locale][key] ?? MESSAGE_CATALOGS[DEFAULT_LOCALE][key];
+}
+
+export function isMessageKey(value: string): value is MessageKey {
+  return (Object.values(MESSAGE_KEYS) as string[]).includes(value);
+}

package/src/i18n/title.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve a conversation title for a locale.
+ *
+ * A stored message key (or an empty title) is a hardcoded constant and
+ * resolves through the catalog. Any other stored string is user or model
+ * copy and passes through, including English placeholders written before
+ * keys were persisted.
+ */
+
+import { DEFAULT_LOCALE, type SupportedLocale } from "./locales.js";
+import { isMessageKey, MESSAGE_KEYS, t } from "./messages.js";
+
+export function resolveConversationTitle(
+  title: string | null | undefined,
+  locale: SupportedLocale = DEFAULT_LOCALE,
+): string {
+  const trimmed = title?.trim() ?? "";
+  if (trimmed === "") {
+    return t(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED, locale);
+  }
+  if (isMessageKey(trimmed)) {
+    return t(trimmed, locale);
+  }
+  return trimmed;
+}

package/src/inbound/platform-callback-registration.ts

@@ -18,9 +18,10 @@
  * the platform can register a route that points at this instance.
  */
 
-import { getPlatformAssistantId, getPlatformBaseUrl } from "../config/env.js";
+import { getPlatformBaseUrl } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
+import { resolvePlatformAssistantId } from "../config/platform-identity.js";
 import { ipcRegisterWebhookRoute } from "../ipc/gateway-client.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -45,11 +46,11 @@ export interface PlatformCallbackRegistrationContext {
 
 export async function resolvePlatformCallbackRegistrationContext(): Promise<PlatformCallbackRegistrationContext> {
   const platform = getIsPlatform();
-  const [storedBaseUrlRaw, storedAssistantIdRaw, storedAssistantApiKeyRaw] =
+  const [storedBaseUrlRaw, storedAssistantApiKeyRaw, assistantId] =
     await Promise.all([
       getSecureKeyAsync(credentialKey("vellum", "platform_base_url")),
-      getSecureKeyAsync(credentialKey("vellum", "platform_assistant_id")),
       getSecureKeyAsync(credentialKey("vellum", "assistant_api_key")),
+      resolvePlatformAssistantId(),
     ]);
 
   const storedBaseUrl = storedBaseUrlRaw?.trim();
@@ -57,8 +58,6 @@ export async function resolvePlatformCallbackRegistrationContext(): Promise<Plat
     /\/+$/,
     "",
   );
-  const assistantId =
-    getPlatformAssistantId().trim() || storedAssistantIdRaw?.trim() || "";
   const envAssistantCredential = process.env.ASSISTANT_API_KEY?.trim();
   const assistantCredential =
     storedAssistantApiKeyRaw?.trim() || envAssistantCredential || undefined;

package/src/live-voice/__tests__/live-voice-metrics.test.ts

@@ -329,7 +329,6 @@ describe("LiveVoiceMetricsCollector", () => {
       endpointHoldCount: 0,
       endpointDecisionMaxLatencyMs: 95,
     });
-    expect(completed).not.toHaveProperty("ackSpoken");
   });
 
   test("decisions without a source are attributed to the front door", () => {
@@ -435,7 +434,6 @@ describe("LiveVoiceMetricsCollector", () => {
     expect(completed).not.toHaveProperty("endpointHoldCount");
     expect(completed).not.toHaveProperty("endpointDecisionMaxLatencyMs");
     expect(completed).not.toHaveProperty("endpointDecisionSource");
-    expect(completed).not.toHaveProperty("ackSpoken");
     expect(completed).not.toHaveProperty("progressUpdatesSpoken");
 
     const aggregateFields = getLiveVoiceMetricsAggregateFields(
@@ -446,7 +444,6 @@ describe("LiveVoiceMetricsCollector", () => {
     expect(aggregateFields).not.toHaveProperty("endpointHoldCount");
     expect(aggregateFields).not.toHaveProperty("endpointDecisionMaxLatencyMs");
     expect(aggregateFields).not.toHaveProperty("endpointDecisionSource");
-    expect(aggregateFields).not.toHaveProperty("ackSpoken");
     expect(aggregateFields).not.toHaveProperty("progressUpdatesSpoken");
   });
 

package/src/live-voice/__tests__/live-voice-progress.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, mock, test } from "bun:test";
 
+import type {
+  VoiceProgressNarrator,
+  VoiceProgressTextInput,
+} from "../../calls/progress-narration.js";
+import {
+  pickProgressPhrase,
+  PROGRESS_FALLBACK_PHRASES,
+  PROGRESS_FALLBACK_PHRASES_BY_LANGUAGE,
+} from "../../calls/progress-phrases.js";
 import { sanitizeForTts } from "../../calls/tts-text-sanitizer.js";
 import type {
   VoiceTurnCallbacks,
@@ -7,9 +16,9 @@ import type {
 } from "../../calls/voice-session-bridge.js";
 import { loadRawConfig, saveRawConfig } from "../../config/loader.js";
 import type {
-  LiveVoiceFrontModelConfig,
-  LiveVoiceProgressConfig,
-} from "../../config/schemas/live-voice.js";
+  VoiceFrontModelConfig,
+  VoiceProgressConfig,
+} from "../../config/schemas/voice.js";
 import type {
   StreamingTranscriber,
   SttStreamServerEvent,
@@ -21,15 +30,6 @@ import {
 } from "../live-voice-session.js";
 import type { LiveVoiceSessionFactoryContext } from "../live-voice-session-manager.js";
 import type { LiveVoiceTtsOptions } from "../live-voice-tts.js";
-import type {
-  VoiceProgressNarrator,
-  VoiceProgressTextInput,
-} from "../progress-narration.js";
-import {
-  pickProgressPhrase,
-  PROGRESS_FALLBACK_PHRASES,
-  PROGRESS_FALLBACK_PHRASES_BY_LANGUAGE,
-} from "../progress-phrases.js";
 import {
   createLiveVoiceServerFrameSequencer,
   type LiveVoiceClientStartFrame,
@@ -142,8 +142,8 @@ function makeProgressNarrator(
 }
 
 function progressConfig(
-  overrides: Partial<LiveVoiceProgressConfig> = {},
-): Partial<LiveVoiceFrontModelConfig> {
+  overrides: Partial<VoiceProgressConfig> = {},
+): Partial<VoiceFrontModelConfig> {
   const idleIntervalMs = overrides.idleIntervalMs ?? 60_000;
   return {
     progress: {
@@ -163,7 +163,7 @@ function progressConfig(
 }
 
 function createProgressHarness(options: {
-  frontModelConfig: Partial<LiveVoiceFrontModelConfig>;
+  frontModelConfig: Partial<VoiceFrontModelConfig>;
   progressNarrator: VoiceProgressNarrator;
   emitMetrics?: boolean;
   gateTtsText?: (text: string) => Promise<void> | null;

package/src/live-voice/__tests__/live-voice-vad.test.ts

@@ -12,7 +12,7 @@ import {
   loadRawConfig,
   saveRawConfig,
 } from "../../config/loader.js";
-import type { LiveVoiceFrontModelConfig } from "../../config/schemas/live-voice.js";
+import type { VoiceFrontModelConfig } from "../../config/schemas/voice.js";
 import type {
   StreamingTranscriber,
   SttStreamServerEvent,
@@ -183,7 +183,7 @@ function createHarness(options: {
   echoBargeInMargin?: number;
   echoEmaHalfLifeMs?: number;
   echoDrainSlackMs?: number;
-  frontModelConfig?: Partial<LiveVoiceFrontModelConfig>;
+  frontModelConfig?: Partial<VoiceFrontModelConfig>;
   emitMetrics?: boolean;
   metricsClock?: () => number;
   // Return a promise to hold a frame's transport write open (a backed-up

package/src/live-voice/__tests__/runtime-websocket-shell.test.ts

@@ -92,36 +92,17 @@ mock.module("../live-voice-credential-preflight.js", () => ({
       : realPreflightModule.resolveLiveVoiceCredentialReadiness(),
 }));
 
-import { CURRENT_POLICY_EPOCH } from "../../runtime/auth/policy.js";
-import { mintToken } from "../../runtime/auth/token-service.js";
+import {
+  mintActorToken,
+  mintGatewayToken,
+  requireHttpAuth,
+  upgradeHeaders,
+  waitForClose,
+} from "../../runtime/__tests__/runtime-ws-test-utils.js";
 import { RuntimeHttpServer } from "../../runtime/http-server.js";
 
 type JsonFrame = Record<string, unknown>;
 
-const savedAuthEnv = {
-  DISABLE_HTTP_AUTH: process.env.DISABLE_HTTP_AUTH,
-};
-
-function mintGatewayToken(): string {
-  return mintToken({
-    aud: "vellum-daemon",
-    sub: "svc:gateway:self",
-    scope_profile: "gateway_ingress_v1",
-    policy_epoch: CURRENT_POLICY_EPOCH,
-    ttlSeconds: 3600,
-  });
-}
-
-function mintActorToken(): string {
-  return mintToken({
-    aud: "vellum-daemon",
-    sub: "actor:self:user-123",
-    scope_profile: "actor_client_v1",
-    policy_epoch: CURRENT_POLICY_EPOCH,
-    ttlSeconds: 3600,
-  });
-}
-
 function startFrame(conversationId = "conversation-123"): string {
   return JSON.stringify({
     type: "start",
@@ -161,33 +142,6 @@ async function waitForOpen(ws: WebSocket, timeoutMs = 2000): Promise<void> {
   });
 }
 
-async function waitForClose(ws: WebSocket, timeoutMs = 2000): Promise<void> {
-  if (ws.readyState === WebSocket.CLOSED) {
-    return;
-  }
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      cleanup();
-      reject(new Error("Timed out waiting for WebSocket close"));
-    }, timeoutMs);
-    const cleanup = () => {
-      clearTimeout(timer);
-      ws.removeEventListener("close", onClose);
-      ws.removeEventListener("error", onError);
-    };
-    const onClose = () => {
-      cleanup();
-      resolve();
-    };
-    const onError = () => {
-      cleanup();
-      reject(new Error("WebSocket close failed"));
-    };
-    ws.addEventListener("close", onClose);
-    ws.addEventListener("error", onError);
-  });
-}
-
 async function waitForJsonFrame(
   ws: WebSocket,
   timeoutMs = 2000,
@@ -241,6 +195,7 @@ describe("RuntimeHttpServer live voice WebSocket shell", () => {
   let baseUrl: string;
   let wsBaseUrl: string;
   let clients: WebSocket[];
+  let restoreAuthEnv: () => void;
 
   beforeAll(() => {
     shellMocksActive = true;
@@ -251,7 +206,7 @@ describe("RuntimeHttpServer live voice WebSocket shell", () => {
   });
 
   beforeEach(async () => {
-    delete process.env.DISABLE_HTTP_AUTH;
+    restoreAuthEnv = requireHttpAuth();
     resolveStreamingTranscriberImpl = async () => createResolvedTranscriber();
     resolveStreamingTranscriberMock.mockClear();
     resolvedTranscribers.length = 0;
@@ -268,11 +223,7 @@ describe("RuntimeHttpServer live voice WebSocket shell", () => {
       closeClient(client);
     }
     await server.stop();
-    if (savedAuthEnv.DISABLE_HTTP_AUTH === undefined) {
-      delete process.env.DISABLE_HTTP_AUTH;
-    } else {
-      process.env.DISABLE_HTTP_AUTH = savedAuthEnv.DISABLE_HTTP_AUTH;
-    }
+    restoreAuthEnv();
   });
 
   function openLiveVoiceClient(token = mintGatewayToken()): WebSocket {
@@ -284,21 +235,14 @@ describe("RuntimeHttpServer live voice WebSocket shell", () => {
   }
 
   test("rejects unauthorized upgrades before creating a WebSocket", async () => {
-    const baseHeaders = {
-      Upgrade: "websocket",
-      Connection: "Upgrade",
-      "Sec-WebSocket-Key": "dGhlIHNhbXBsZSBub25jZQ==",
-      "Sec-WebSocket-Version": "13",
-    };
-
     const missingToken = await fetch(`${baseUrl}/v1/live-voice`, {
-      headers: baseHeaders,
+      headers: upgradeHeaders,
     });
     expect(missingToken.status).toBe(401);
 
     const actorToken = await fetch(
       `${baseUrl}/v1/live-voice?token=${mintActorToken()}`,
-      { headers: baseHeaders },
+      { headers: upgradeHeaders },
     );
     expect(actorToken.status).toBe(401);
 
@@ -306,7 +250,7 @@ describe("RuntimeHttpServer live voice WebSocket shell", () => {
       `${baseUrl}/v1/live-voice?token=${mintGatewayToken()}`,
       {
         headers: {
-          ...baseHeaders,
+          ...upgradeHeaders,
           Origin: "https://external.example.com",
         },
       },