@vellumai/assistant 0.6.3 → 0.6.5

package/src/tts/types.ts

@@ -0,0 +1,199 @@
+/**
+ * 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"
+  | "xai"
+  | (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;
+}
+
+// ---------------------------------------------------------------------------
+// Alignment / viseme events
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-phoneme alignment event emitted by TTS providers that expose
+ * character- or phoneme-level alignment metadata alongside the audio
+ * stream (e.g. ElevenLabs Turbo with alignment).
+ *
+ * Consumers (e.g. the Meet avatar lip-sync path) map these events to
+ * blendshape weights at the rendered timestamp. Providers that do not
+ * expose alignment metadata simply never invoke the callback; the
+ * caller is expected to fall back to an amplitude-envelope approximation
+ * derived from the PCM stream.
+ */
+export interface TtsAlignmentEvent {
+  /**
+   * Phoneme label or character — free-form string that the consumer maps
+   * to renderer-specific blendshape weights. Providers typically emit
+   * IPA-style phoneme labels, viseme codes, or individual characters
+   * depending on their alignment granularity.
+   */
+  phoneme: string;
+  /** Normalized intensity in the range [0, 1]. */
+  weight: number;
+  /** Milliseconds from the start of the synthesized utterance. */
+  timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// 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[];
+
+  /**
+   * Whether the provider can emit {@link TtsAlignmentEvent}s via the optional
+   * `onAlignment` callback of `synthesizeStream`. Consumers use this to pick
+   * between a viseme-driven lip-sync path and an RMS-amplitude fallback.
+   *
+   * Optional for backwards compatibility — treat `undefined` as `false`.
+   */
+  alignment?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+   *
+   * Providers that advertise `capabilities.alignment === true` also invoke
+   * the optional `onAlignment` callback with per-phoneme alignment events
+   * interleaved with the audio chunks. Providers that don't support
+   * alignment simply never call it; callers must tolerate a silent
+   * channel and fall back to amplitude-based heuristics.
+   */
+  synthesizeStream?(
+    request: TtsSynthesisRequest,
+    onChunk: (chunk: Uint8Array) => void,
+    onAlignment?: (event: TtsAlignmentEvent) => 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/types/tar-stream.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Minimal ambient types for `tar-stream` v3, which ships no type definitions.
+ *
+ * We only declare the surface used by `runtime/migrations/vbundle-tar-stream.ts`
+ * (the `extract()` factory and its `"entry"` event shape). If additional usage
+ * is needed later, extend this file rather than adding `@types/tar-stream` —
+ * the DT types target v2 and do not match v3's streamx-based extractor.
+ */
+declare module "tar-stream" {
+  import type { Readable, Writable } from "node:stream";
+
+  export interface TarHeader {
+    name: string;
+    size: number;
+    type:
+      | "file"
+      | "link"
+      | "symlink"
+      | "character-device"
+      | "block-device"
+      | "directory"
+      | "fifo"
+      | "contiguous-file"
+      | "pax-header"
+      | "pax-global-header"
+      | "gnu-long-path"
+      | "gnu-long-link-path"
+      | "other"
+      | string;
+    linkname?: string | null;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    mtime?: Date;
+    pax?: Record<string, string> | null;
+  }
+
+  export interface ExtractOptions {
+    filenameEncoding?: string;
+    allowUnknownFormat?: boolean;
+  }
+
+  export type EntryCallback = (err?: Error | null) => void;
+
+  export interface Extract extends Writable {
+    on(
+      event: "entry",
+      listener: (
+        header: TarHeader,
+        stream: Readable,
+        next: EntryCallback,
+      ) => void,
+    ): this;
+    on(event: "finish", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+    on(event: "close", listener: () => void): this;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    destroy(err?: Error): void;
+  }
+
+  export function extract(opts?: ExtractOptions): Extract;
+
+  // `pack` exists but is unused by the runtime migrations code; declare it
+  // permissively so importers that reach for it still type-check.
+  export function pack(opts?: unknown): Writable;
+}

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 {

package/src/util/errors.ts

@@ -102,16 +102,24 @@ export class AssistantError extends VellumError {
 export class ProviderError extends AssistantError {
   /** Delay (in ms) suggested by the server's Retry-After header, if present. */
   public readonly retryAfterMs?: number;
+  /**
+   * Tagged daemon-owned abort reason carried over from the AbortSignal that
+   * triggered this error. Untyped here to avoid a daemon→util import cycle;
+   * `AbortReason` from `util/abort-reasons.ts` is the only producer and
+   * `isAbortReason` is the canonical type guard for consumers.
+   */
+  public readonly abortReason?: unknown;
 
   constructor(
     message: string,
     public readonly provider: string,
     public readonly statusCode?: number,
-    options?: { cause?: unknown; retryAfterMs?: number },
+    options?: { cause?: unknown; retryAfterMs?: number; abortReason?: unknown },
   ) {
     super(message, ErrorCode.PROVIDER_ERROR, options);
     this.name = "ProviderError";
     this.retryAfterMs = options?.retryAfterMs;
+    this.abortReason = options?.abortReason;
   }
 }
 

package/src/util/json.ts

@@ -8,3 +8,20 @@ export function parseJsonSafe<T = unknown>(text: string): T | null {
     return null;
   }
 }
+
+/** Tolerant JSON parse that returns `{}` for invalid or non-object payloads. */
+export function safeParseRecord(raw: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}

package/src/util/platform.ts

@@ -45,13 +45,24 @@ export function normalizeAssistantId(assistantId: string): string {
 }
 
 /**
- * Compute the root ~/.vellum directory path.
+ * The daemon's per-instance root data directory. Resolution order:
  *
- * This is a simple inline computation — not a shared function — so each
- * helper is self-contained and the module has no hidden coupling to
- * env-var indirection.
+ *   1. `BASE_DATA_DIR` env var — set by the CLI when spawning the daemon
+ *      for a specific assistant (see `cli/src/lib/local.ts`). Points at the
+ *      per-assistant instanceDir; we append `.vellum` to get the daemon's
+ *      root so root-level state (PID, credentials, runtime-port, workspace)
+ *      is isolated per instance.
+ *   2. Fallback: `join(homedir(), ".vellum")`. Used when the daemon runs
+ *      outside the CLI-spawn lifecycle (containerized deployments, manual
+ *      test invocations).
+ *
+ * Docker mode relocates the workspace via `VELLUM_WORKSPACE_DIR` rather
+ * than `BASE_DATA_DIR`, so honoring `BASE_DATA_DIR` here does not affect
+ * containerized deployments.
  */
 function vellumRoot(): string {
+  const baseDataDir = process.env.BASE_DATA_DIR?.trim();
+  if (baseDataDir) return join(baseDataDir, ".vellum");
   return join(homedir(), ".vellum");
 }
 
@@ -143,15 +154,47 @@ export function getTCPHost(): string {
   return "127.0.0.1";
 }
 
+// Kept in sync with `cli/src/lib/environments/seeds.ts` and
+// `clients/chrome-extension/native-host/src/lockfile.ts`. Drift between
+// these three sites is caught at test time by
+// `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
+// list into a `packages/environments` package so all three sites import
+// from one place.
+const KNOWN_ENVIRONMENTS: ReadonlySet<string> = new Set([
+  "production",
+  "staging",
+  "test",
+  "dev",
+  "local",
+]);
+
+/**
+ * Returns the env-scoped XDG config subdirectory name for Vellum
+ * (`vellum` in production, `vellum-<env>` otherwise). Mirrors the Swift
+ * side's `VellumPaths.configDir` and the CLI's
+ * `environments/paths.ts:getConfigDir` so the daemon resolves to the
+ * same on-disk location as every other writer of these files.
+ *
+ * Unknown environment names fall back to production to preserve the
+ * legacy path for any unrecognized value.
+ */
+export function getXdgVellumConfigDirName(): string {
+  const raw = process.env.VELLUM_ENVIRONMENT?.trim();
+  if (!raw || raw === "production") return "vellum";
+  if (!KNOWN_ENVIRONMENTS.has(raw)) return "vellum";
+  return `vellum-${raw}`;
+}
+
 /**
- * Returns the XDG-compliant path for the platform API token
- * (~/.config/vellum/platform-token). This is the canonical location
- * shared by the CLI and desktop app.
+ * Returns the XDG-compliant path for the platform API token. Resolves to
+ * `$XDG_CONFIG_HOME/vellum/platform-token` in production and
+ * `$XDG_CONFIG_HOME/vellum-<env>/platform-token` otherwise, matching the
+ * Swift client and CLI.
  */
-function getXdgPlatformTokenPath(): string {
+export function getXdgPlatformTokenPath(): string {
   const configHome =
     process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-  return join(configHome, "vellum", "platform-token");
+  return join(configHome, getXdgVellumConfigDirName(), "platform-token");
 }
 
 /**
@@ -281,8 +324,8 @@ export function getWorkspaceDir(): string {
  * so paths stay concise and portable across machines.
  *
  * Examples:
- *   /Users/sidd/.vellum/workspace → ~/.vellum/workspace
- *   /data/.vellum/workspace       → /data/.vellum/workspace
+ *   /Users/alice/.vellum/workspace → ~/.vellum/workspace
+ *   /data/.vellum/workspace        → /data/.vellum/workspace
  */
 export function getWorkspaceDirDisplay(): string {
   const abs = getWorkspaceDir();
@@ -323,7 +366,7 @@ export function getConversationsDir(): string {
   return join(getWorkspaceDir(), "conversations");
 }
 
-/** Returns the workspace path for a prompt file (e.g. IDENTITY.md, SOUL.md, USER.md). */
+/** Returns the workspace path for a prompt file (e.g. IDENTITY.md, SOUL.md). */
 export function getWorkspacePromptPath(file: string): string {
   return join(getWorkspaceDir(), file);
 }
@@ -383,6 +426,7 @@ export function ensureDataDir(): void {
     join(wsData, "memory"),
     join(wsData, "memory", "knowledge"),
     join(wsData, "apps"),
+    join(wsData, "attachments"),
     join(wsData, "interfaces"),
     join(wsData, "sounds"),
   ];