@vellumai/assistant 0.6.2 → 0.6.4

package/src/tts/providers/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Provider adapter factory map.
+ *
+ * Maps every canonical {@link TtsProviderId} from the provider catalog to a
+ * factory function that creates the corresponding {@link TtsProvider} adapter.
+ *
+ * This module is the single place to wire a new provider adapter — adding a
+ * provider to the catalog without a corresponding factory entry here will
+ * cause a startup-time error (enforced by {@link registerBuiltinTtsProviders}).
+ */
+
+import type { TtsProvider, TtsProviderId } from "../types.js";
+import { createDeepgramProvider } from "./deepgram-provider.js";
+import { createElevenLabsProvider } from "./elevenlabs-provider.js";
+import { createFishAudioProvider } from "./fish-audio-provider.js";
+
+// ---------------------------------------------------------------------------
+// Factory type
+// ---------------------------------------------------------------------------
+
+/**
+ * A zero-argument function that constructs a {@link TtsProvider} adapter.
+ */
+export type TtsProviderFactory = () => TtsProvider;
+
+// ---------------------------------------------------------------------------
+// Factory map
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider adapter factories keyed by catalog provider ID.
+ *
+ * When a new provider is added to `provider-catalog.ts`, a matching entry
+ * must be added here. The built-in registration module iterates the catalog
+ * IDs and looks up each one in this map — a missing entry is a fatal error.
+ */
+export const providerFactories: ReadonlyMap<TtsProviderId, TtsProviderFactory> =
+  new Map<TtsProviderId, TtsProviderFactory>([
+    ["elevenlabs", createElevenLabsProvider],
+    ["fish-audio", createFishAudioProvider],
+    ["deepgram", createDeepgramProvider],
+  ]);

package/src/tts/providers/register-builtins.ts

@@ -0,0 +1,130 @@
+/**
+ * Register built-in TTS providers at startup.
+ *
+ * Call {@link registerBuiltinTtsProviders} once during daemon initialization
+ * to make all catalog-declared providers discoverable via the provider
+ * registry. The function iterates {@link listCatalogProviderIds} and looks up
+ * each ID in the {@link providerFactories} map — a missing factory entry
+ * causes a clear startup-time error so that new catalog providers cannot be
+ * added without also wiring an adapter factory.
+ *
+ * Also registers native Twilio voice-spec builders for providers whose
+ * catalog `callMode` is `"native-twilio"`. These builders are consumed by
+ * the call strategy abstraction in `tts-call-strategy.ts`.
+ *
+ * This module is the single entry point for built-in registration — new
+ * providers should be added to the catalog and the factory map so they are
+ * available from first request.
+ */
+
+import {
+  _resetNativeTwilioVoiceSpecRegistry,
+  type NativeTwilioVoiceSpec,
+  registerNativeTwilioVoiceSpec,
+} from "../../calls/tts-call-strategy.js";
+import { buildElevenLabsVoiceSpec } from "../../calls/voice-quality.js";
+import {
+  getCatalogProvider,
+  listCatalogProviderIds,
+} from "../provider-catalog.js";
+import { registerTtsProvider } from "../provider-registry.js";
+import type { TtsProviderId } from "../types.js";
+import { providerFactories } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// Native Twilio voice-spec builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps provider IDs with `callMode: "native-twilio"` to their Twilio
+ * voice-spec builder metadata.
+ *
+ * When onboarding a new native Twilio provider, add an entry here.
+ * Synthesized-play providers do not need an entry — they use a
+ * placeholder TTS provider and empty voice string.
+ */
+const nativeVoiceSpecs = new Map<TtsProviderId, NativeTwilioVoiceSpec>([
+  [
+    "elevenlabs",
+    {
+      twilioProviderName: "ElevenLabs",
+      buildVoiceSpec: (providerConfig) =>
+        buildElevenLabsVoiceSpec(
+          providerConfig as {
+            voiceId: string;
+            voiceModelId?: string;
+            speed?: number;
+            stability?: number;
+            similarityBoost?: number;
+          },
+        ),
+    },
+  ],
+]);
+
+let registered = false;
+
+/**
+ * Register all built-in TTS providers with the global registry.
+ *
+ * Iterates every provider ID declared in the canonical catalog and creates
+ * an adapter via the corresponding factory in {@link providerFactories}.
+ * For providers whose catalog `callMode` is `"native-twilio"`, also
+ * registers the corresponding native Twilio voice-spec builder.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops. This prevents
+ * double-registration when the daemon restarts hot-module paths.
+ *
+ * @throws if any catalog provider ID has no corresponding adapter factory.
+ * @throws if a native-twilio provider has no corresponding voice-spec entry.
+ */
+export function registerBuiltinTtsProviders(): void {
+  if (registered) return;
+
+  const catalogIds = listCatalogProviderIds();
+
+  for (const id of catalogIds) {
+    // Register the TTS provider adapter.
+    const factory = providerFactories.get(id);
+    if (!factory) {
+      throw new Error(
+        `TTS provider "${id}" is declared in the catalog but has no adapter factory. ` +
+          `Add a factory entry for "${id}" in providers/index.ts.`,
+      );
+    }
+    registerTtsProvider(factory());
+
+    // Register the native Twilio voice-spec builder when applicable.
+    const catalogEntry = getCatalogProvider(id);
+    if (catalogEntry.callMode === "native-twilio") {
+      const voiceSpec = nativeVoiceSpecs.get(id);
+      if (!voiceSpec) {
+        throw new Error(
+          `TTS provider "${id}" has callMode "native-twilio" but no native ` +
+            `voice-spec builder. Add an entry in register-builtins.ts nativeVoiceSpecs.`,
+        );
+      }
+      registerNativeTwilioVoiceSpec(id, voiceSpec);
+    }
+  }
+
+  registered = true;
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the registration guard so {@link registerBuiltinTtsProviders} can
+ * re-register providers after a test clears the global registry.
+ *
+ * Also clears the native Twilio voice-spec registry to avoid
+ * duplicate-registration errors on subsequent calls.
+ *
+ * **Test-only** — must not be called in production code.
+ */
+export function _resetBuiltinRegistration(): void {
+  registered = false;
+  _resetNativeTwilioVoiceSpecRegistry();
+}

package/src/tts/synthesize-text.ts

@@ -0,0 +1,110 @@
+/**
+ * Top-level TTS orchestration layer.
+ *
+ * Resolves the globally configured provider via {@link resolveTtsConfig},
+ * looks up the provider adapter in the registry, and delegates synthesis.
+ * Callers supply the pre-sanitized text and a use-case discriminator;
+ * provider selection is always global — per-use-case policy only gates
+ * capabilities (e.g. format checks), never overrides the chosen provider.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import { getTtsProvider } from "./provider-registry.js";
+import { resolveTtsConfig } from "./tts-config-resolver.js";
+import type { TtsSynthesisResult, TtsUseCase } from "./types.js";
+
+const log = getLogger("tts:synthesize");
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SynthesizeTextOptions {
+  /** Pre-sanitized text to speak. */
+  text: string;
+
+  /** Product surface requesting synthesis. */
+  useCase: TtsUseCase;
+
+  /** Optional voice override (provider-specific identifier). */
+  voiceId?: string;
+
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+export type TtsSynthesisErrorCode =
+  | "TTS_PROVIDER_NOT_CONFIGURED"
+  | "TTS_SYNTHESIS_FAILED";
+
+export class TtsSynthesisError extends Error {
+  readonly code: TtsSynthesisErrorCode;
+
+  constructor(code: TtsSynthesisErrorCode, message: string) {
+    super(message);
+    this.name = "TtsSynthesisError";
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Synthesize text to audio using the globally configured TTS provider.
+ *
+ * 1. Resolves the active provider and its config via `tts-config-resolver`.
+ * 2. Looks up the provider adapter in the registry.
+ * 3. Delegates to the adapter's `synthesize` method.
+ *
+ * Throws {@link TtsSynthesisError} when the provider is not registered
+ * or synthesis fails.
+ */
+export async function synthesizeText(
+  options: SynthesizeTextOptions,
+): Promise<TtsSynthesisResult> {
+  const config = getConfig();
+  const { provider: providerId } = resolveTtsConfig(config);
+
+  let provider;
+  try {
+    provider = getTtsProvider(providerId);
+  } catch {
+    throw new TtsSynthesisError(
+      "TTS_PROVIDER_NOT_CONFIGURED",
+      `TTS provider "${providerId}" is not configured or not registered.`,
+    );
+  }
+
+  log.info(
+    {
+      provider: providerId,
+      useCase: options.useCase,
+      textLength: options.text.length,
+    },
+    "Synthesizing text with TTS provider",
+  );
+
+  try {
+    return await provider.synthesize({
+      text: options.text,
+      useCase: options.useCase,
+      voiceId: options.voiceId,
+      signal: options.signal,
+    });
+  } catch (err) {
+    // Re-throw TtsSynthesisError as-is (e.g. from inner adapter errors).
+    if (err instanceof TtsSynthesisError) throw err;
+
+    throw new TtsSynthesisError(
+      "TTS_SYNTHESIS_FAILED",
+      `TTS synthesis failed (provider: ${providerId}): ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/tts/tts-config-resolver.ts

@@ -0,0 +1,78 @@
+/**
+ * Resolves the effective TTS provider and provider-specific configuration
+ * from the canonical `services.tts` config block.
+ *
+ * Reads exclusively from `services.tts.provider` and
+ * `services.tts.providers.<id>`. Migration 032 ensures all workspaces
+ * have canonical fields materialised.
+ */
+
+import type { AssistantConfig } from "../config/types.js";
+import type { TtsProviderId } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Resolved TTS configuration for a single provider. */
+export interface ResolvedTtsConfig {
+  /** The active TTS provider. */
+  provider: TtsProviderId;
+
+  /** Provider-specific settings for the active provider. */
+  providerConfig: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults (must match the schema defaults in tts.ts)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TTS_PROVIDER: TtsProviderId = "elevenlabs";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the effective TTS provider and its configuration from the
+ * assistant config.
+ *
+ * Reads exclusively from `services.tts.provider` and
+ * `services.tts.providers.<id>`. No legacy fallback logic.
+ */
+export function resolveTtsConfig(config: AssistantConfig): ResolvedTtsConfig {
+  const ttsService = config.services.tts;
+
+  const provider: TtsProviderId = ttsService.provider ?? DEFAULT_TTS_PROVIDER;
+
+  // Resolve provider-specific config from the canonical providers map.
+  const providerConfig = resolveProviderConfig(config, provider);
+
+  return { provider, providerConfig };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the provider-specific config object from the canonical
+ * `services.tts.providers.<id>` block.
+ *
+ * Uses a generic lookup against the providers map — no provider-specific
+ * branching. Unknown providers (not in the catalog / schema) receive an
+ * empty config; their adapters are responsible for validating required fields.
+ */
+function resolveProviderConfig(
+  config: AssistantConfig,
+  provider: TtsProviderId,
+): Record<string, unknown> {
+  const ttsProviders = config.services.tts.providers as Record<string, unknown>;
+
+  const providerBlock = ttsProviders[provider];
+  if (providerBlock != null && typeof providerBlock === "object") {
+    return { ...providerBlock } as Record<string, unknown>;
+  }
+
+  return {};
+}

package/src/tts/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Core domain types for the provider-agnostic TTS abstraction.
+ *
+ * These contracts decouple callers (phone calls, message TTS routes, native
+ * clients) from concrete TTS backends (ElevenLabs, Fish Audio, etc.).
+ */
+
+// ---------------------------------------------------------------------------
+// Provider identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Unique identifier for a registered TTS provider.
+ *
+ * Values correspond to the provider names already used in config schemas
+ * (e.g. `"elevenlabs"`, `"fish-audio"`). New providers simply add a new
+ * string to this union — the registry enforces uniqueness at runtime.
+ */
+export type TtsProviderId =
+  | "elevenlabs"
+  | "fish-audio"
+  | "deepgram"
+  | (string & {});
+
+// ---------------------------------------------------------------------------
+// Call-mode discriminator
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes how a TTS provider integrates with the telephony call path.
+ *
+ * - `native-twilio`    — Twilio handles TTS natively via ConversationRelay;
+ *                         text tokens are forwarded to the relay and Twilio
+ *                         synthesises audio using the provider's built-in
+ *                         integration.
+ * - `synthesized-play` — The assistant synthesises audio via the provider's
+ *                         HTTP API and streams chunks to Twilio via `play`
+ *                         messages. Used when the provider is not natively
+ *                         supported by Twilio.
+ */
+export type TtsCallMode = "native-twilio" | "synthesized-play";
+
+// ---------------------------------------------------------------------------
+// Use-case discriminator
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes the product surface that is requesting synthesis so providers
+ * can tailor format, latency, and quality trade-offs.
+ */
+export type TtsUseCase =
+  /** Real-time phone call — prioritize low latency and streaming. */
+  | "phone-call"
+  /** In-app message playback — buffer-oriented, higher quality acceptable. */
+  | "message-playback";
+
+// ---------------------------------------------------------------------------
+// Synthesis request / result
+// ---------------------------------------------------------------------------
+
+/** Input to a TTS synthesis call. */
+export interface TtsSynthesisRequest {
+  /** Pre-sanitized text to synthesize. */
+  text: string;
+
+  /** Product surface requesting synthesis. */
+  useCase: TtsUseCase;
+
+  /**
+   * Optional voice identifier whose format is provider-specific
+   * (e.g. an ElevenLabs voice ID or a Fish Audio reference ID).
+   */
+  voiceId?: string;
+
+  /** Optional abort signal for cancelling in-flight synthesis. */
+  signal?: AbortSignal;
+
+  /**
+   * Optional hint requesting a specific output encoding from the provider.
+   *
+   * - `"pcm"` — Request raw PCM output (e.g. 16-bit signed LE). The
+   *   media-stream transport sets this because its mu-law transcoder
+   *   can handle raw PCM but not compressed formats like mp3/opus.
+   *
+   * Providers that support the requested format should honour the hint;
+   * providers that don't may ignore it and return their default format.
+   * The caller must always check `result.contentType` to determine the
+   * actual format of the returned audio.
+   */
+  outputFormat?: "pcm";
+}
+
+/** Output of a completed TTS synthesis call. */
+export interface TtsSynthesisResult {
+  /** Complete audio buffer. */
+  audio: Buffer;
+
+  /** MIME type of the returned audio (e.g. `"audio/mpeg"`, `"audio/wav"`). */
+  contentType: string;
+}
+
+// ---------------------------------------------------------------------------
+// Provider capabilities
+// ---------------------------------------------------------------------------
+
+/** Advertised capabilities of a TTS provider. */
+export interface TtsProviderCapabilities {
+  /** Whether the provider supports chunk-level streaming via `synthesizeStream`. */
+  supportsStreaming: boolean;
+
+  /** Audio formats the provider can produce (e.g. `["mp3", "wav", "opus"]`). */
+  supportedFormats: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Provider interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Contract that every TTS provider adapter must implement.
+ *
+ * At minimum a provider must support buffer-oriented synthesis. Streaming
+ * synthesis is optional — providers that support it set
+ * `capabilities.supportsStreaming` to `true` and implement
+ * `synthesizeStream`.
+ */
+export interface TtsProvider {
+  /** Unique provider identifier used for registry lookup. */
+  readonly id: TtsProviderId;
+
+  /** Static capability advertisement. */
+  readonly capabilities: TtsProviderCapabilities;
+
+  /**
+   * Synthesize text and return the complete audio buffer.
+   *
+   * This is the universal code-path — every provider must implement it.
+   */
+  synthesize(request: TtsSynthesisRequest): Promise<TtsSynthesisResult>;
+
+  /**
+   * Synthesize text with chunk-level streaming.
+   *
+   * Only required when `capabilities.supportsStreaming` is `true`.
+   * The `onChunk` callback is invoked with each audio chunk as it arrives
+   * from the upstream provider. The returned promise resolves with the
+   * complete concatenated result once all chunks have been delivered.
+   */
+  synthesizeStream?(
+    request: TtsSynthesisRequest,
+    onChunk: (chunk: Uint8Array) => void,
+  ): Promise<TtsSynthesisResult>;
+}

package/src/types/onboarding-context.ts

@@ -0,0 +1,7 @@
+export interface OnboardingContext {
+  tools: string[];
+  tasks: string[];
+  tone: string;
+  userName?: string;
+  assistantName?: string;
+}

package/src/util/abort-reasons.ts

@@ -0,0 +1,58 @@
+/**
+ * Tagged AbortReason objects passed as the `reason` argument to
+ * `AbortController.abort()` for daemon-owned conversation aborts.
+ *
+ * The reason flows through the AbortSignal into provider SDKs (Anthropic,
+ * OpenAI, etc.). When a provider wraps the abort error, the wrapped
+ * `ProviderError` carries the original reason via `ProviderError.abortReason`,
+ * letting `isUserCancellation` distinguish a user-initiated abort from a
+ * genuine provider failure even after wrapping erases the `AbortError` name.
+ */
+
+export type AbortReasonKind =
+  /** User explicitly hit Stop / Esc on the active conversation. */
+  | "user_cancel"
+  /** A new user message arrived for the same conversation, preempting the in-flight turn. */
+  | "preempted_by_new_message"
+  /** The conversation was disposed (eviction, shutdown) while still processing. */
+  | "conversation_disposed"
+  /** A subagent's owning conversation was aborted (parent abort, dispose, or explicit subagent abort). */
+  | "subagent_aborted"
+  /** A signal-file cancel was written by an out-of-process caller (CLI, hook). */
+  | "signal_cancel"
+  /** Voice session bridge aborted the conversation (turn supersession, call end). */
+  | "voice_session_aborted"
+  /** A scheduled work item run was cancelled or its conversation reset. */
+  | "work_item_aborted";
+
+const ABORT_REASON_TAG = "__vellumAbortReason" as const;
+
+export interface AbortReason {
+  readonly [ABORT_REASON_TAG]: true;
+  readonly kind: AbortReasonKind;
+  /** Short identifier of the call site for logging (e.g. "cancelGeneration"). */
+  readonly source: string;
+  readonly conversationId?: string;
+}
+
+export function createAbortReason(
+  kind: AbortReasonKind,
+  source: string,
+  conversationId?: string,
+): AbortReason {
+  return {
+    [ABORT_REASON_TAG]: true,
+    kind,
+    source,
+    ...(conversationId ? { conversationId } : {}),
+  };
+}
+
+export function isAbortReason(value: unknown): value is AbortReason {
+  if (typeof value !== "object" || value === null) return false;
+  return (
+    (value as Record<string, unknown>)[ABORT_REASON_TAG] === true &&
+    typeof (value as Record<string, unknown>).kind === "string" &&
+    typeof (value as Record<string, unknown>).source === "string"
+  );
+}

package/src/util/device-id.ts

@@ -6,11 +6,14 @@
  * extensible for future per-device metadata.
  *
  * Path resolution:
- *   - Containerized (IS_CONTAINERIZED=true): uses /home/assistant (the assistant
- *     user's persistent home dir) so device.json lives on the assistant's own
- *     filesystem rather than the shared data volume.
- *   - Local (single or multi-instance): uses homedir() so all instances on the
- *     same machine share a single device ID.
+ *   - Containerized (IS_CONTAINERIZED=true): `/home/assistant/.vellum/device.json`
+ *     — the assistant user's persistent home dir, kept off the shared data
+ *     volume. Not affected by VELLUM_ENVIRONMENT because the container fs
+ *     has no cross-process contract with the Swift client.
+ *   - Non-containerized production: `~/.vellum/device.json` (legacy, shared
+ *     across all local instances on the same machine).
+ *   - Non-containerized non-production: `$XDG_CONFIG_HOME/vellum-<env>/device.json`,
+ *     matching Swift's `VellumPaths.deviceIdFile`.
  *
  * The value is cached in memory after the first successful read/write.
  * Falls back to a generated UUID if the file cannot be read or written.
@@ -23,25 +26,39 @@ import { join } from "node:path";
 
 import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "./logger.js";
+import { getXdgVellumConfigDirName } from "./platform.js";
 
 const log = getLogger("device-id");
 
 let cached: string | undefined;
 
 /**
- * Resolve the base directory for device.json.
+ * Resolve the directory and file path for `device.json` based on the
+ * runtime environment. See the module docblock for the resolution table.
  *
- * In containerized environments, device.json is stored under /home/assistant
- * (the assistant user's persistent home dir) rather than on the shared data
- * volume. Device ID is assistant-specific state that doesn't need to be shared.
- * In local environments (including multi-instance), homedir() is stable and
- * shared across instances, giving a true per-machine device ID.
+ * Production and containerized modes preserve the legacy `~/.vellum` /
+ * `/home/assistant/.vellum` paths. Non-production, non-containerized
+ * deployments route through `$XDG_CONFIG_HOME/vellum-<env>` to match
+ * the Swift client's `VellumPaths.deviceIdFile`.
  */
-export function getDeviceIdBaseDir(): string {
+function resolveDeviceIdPaths(): { dir: string; file: string } {
   if (getIsContainerized()) {
-    return "/home/assistant";
+    const dir = join("/home/assistant", ".vellum");
+    return { dir, file: join(dir, "device.json") };
   }
-  return homedir();
+
+  const configDirName = getXdgVellumConfigDirName();
+  if (configDirName === "vellum") {
+    // Production: device.json lives at ~/.vellum/device.json, shared
+    // across all local instances on the same machine.
+    const dir = join(homedir(), ".vellum");
+    return { dir, file: join(dir, "device.json") };
+  }
+
+  const configHome =
+    process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+  const dir = join(configHome, configDirName);
+  return { dir, file: join(dir, "device.json") };
 }
 
 /**
@@ -60,8 +77,7 @@ export function getDeviceId(): string {
     return cached;
   }
 
-  const vellumDir = join(getDeviceIdBaseDir(), ".vellum");
-  const filePath = join(vellumDir, "device.json");
+  const { dir: vellumDir, file: filePath } = resolveDeviceIdPaths();
   const generated = randomUUID();
 
   try {