@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/util/__tests__/language-subtag.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+
+import { baseLanguageSubtag, localizedOrDefault } from "../language-subtag.js";
+
+describe("baseLanguageSubtag", () => {
+  test("lowercases a bare tag", () => {
+    expect(baseLanguageSubtag("EN")).toBe("en");
+  });
+
+  test("strips a hyphenated region", () => {
+    expect(baseLanguageSubtag("en-US")).toBe("en");
+    expect(baseLanguageSubtag("PT-br")).toBe("pt");
+  });
+
+  test("strips an underscore-separated region", () => {
+    expect(baseLanguageSubtag("hi_IN")).toBe("hi");
+    expect(baseLanguageSubtag("es_419")).toBe("es");
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(baseLanguageSubtag("  hi ")).toBe("hi");
+    expect(baseLanguageSubtag(" pt-BR ")).toBe("pt");
+  });
+
+  test("returns undefined for undefined and blank input", () => {
+    expect(baseLanguageSubtag(undefined)).toBeUndefined();
+    expect(baseLanguageSubtag("")).toBeUndefined();
+    expect(baseLanguageSubtag("   ")).toBeUndefined();
+  });
+});
+
+describe("localizedOrDefault", () => {
+  const table: Readonly<Record<string, string>> = { en: "hello", es: "hola" };
+
+  test("selects by the language's base subtag", () => {
+    expect(localizedOrDefault(table, "es", "hello")).toBe("hola");
+    expect(localizedOrDefault(table, "ES-mx", "hello")).toBe("hola");
+    expect(localizedOrDefault(table, "en_GB", "fallback")).toBe("hello");
+  });
+
+  test("falls back for unset, blank, and unknown languages", () => {
+    expect(localizedOrDefault(table, undefined, "fallback")).toBe("fallback");
+    expect(localizedOrDefault(table, "", "fallback")).toBe("fallback");
+    expect(localizedOrDefault(table, "ko", "fallback")).toBe("fallback");
+  });
+
+  test("never resolves prototype keys as entries", () => {
+    expect(localizedOrDefault(table, "constructor", "fallback")).toBe(
+      "fallback",
+    );
+    expect(localizedOrDefault(table, "toString", "fallback")).toBe("fallback");
+    expect(localizedOrDefault(table, "__proto__", "fallback")).toBe("fallback");
+  });
+});

package/src/util/__tests__/sqlite-retry.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Tests for `withSqliteRetry()`, the shared retry wrapper for transient
+ * SQLite write contention (`SQLITE_BUSY*` / `SQLITE_IOERR*`).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { isRetryableSqliteError, withSqliteRetry } from "../sqlite-retry.js";
+
+function sqliteError(code: string): Error {
+  const err = new Error(code);
+  (err as Error & { code: string }).code = code;
+  return err;
+}
+
+describe("isRetryableSqliteError", () => {
+  test("matches the SQLITE_BUSY and SQLITE_IOERR families", () => {
+    expect(isRetryableSqliteError(sqliteError("SQLITE_BUSY"))).toBe(true);
+    expect(isRetryableSqliteError(sqliteError("SQLITE_BUSY_SNAPSHOT"))).toBe(
+      true,
+    );
+    expect(isRetryableSqliteError(sqliteError("SQLITE_IOERR"))).toBe(true);
+    expect(isRetryableSqliteError(sqliteError("SQLITE_IOERR_SHORT_READ"))).toBe(
+      true,
+    );
+  });
+
+  test("rejects non-transient errors", () => {
+    expect(isRetryableSqliteError(sqliteError("SQLITE_CONSTRAINT"))).toBe(
+      false,
+    );
+    expect(isRetryableSqliteError(new Error("database is locked"))).toBe(false);
+    expect(isRetryableSqliteError(null)).toBe(false);
+    expect(isRetryableSqliteError(undefined)).toBe(false);
+  });
+});
+
+describe("withSqliteRetry", () => {
+  test("returns the wrapped value on first success", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      () => {
+        calls += 1;
+        return "ok";
+      },
+      { op: "test-op" },
+    );
+    expect(result).toBe("ok");
+    expect(calls).toBe(1);
+  });
+
+  test("retries transient contention and returns the eventual success", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      () => {
+        calls += 1;
+        if (calls <= 2) {
+          throw sqliteError("SQLITE_BUSY");
+        }
+        return "recovered";
+      },
+      { op: "test-op", baseDelayMs: 1 },
+    );
+    expect(result).toBe("recovered");
+    expect(calls).toBe(3);
+  });
+
+  test("awaits an async wrapped function", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      async () => {
+        calls += 1;
+        if (calls === 1) {
+          throw sqliteError("SQLITE_IOERR");
+        }
+        return 42;
+      },
+      { op: "test-op", baseDelayMs: 1 },
+    );
+    expect(result).toBe(42);
+    expect(calls).toBe(2);
+  });
+
+  test("throws immediately on a non-retryable error", async () => {
+    let calls = 0;
+    await expect(
+      withSqliteRetry(
+        () => {
+          calls += 1;
+          throw sqliteError("SQLITE_CONSTRAINT_PRIMARYKEY");
+        },
+        { op: "test-op", baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow("SQLITE_CONSTRAINT_PRIMARYKEY");
+    expect(calls).toBe(1);
+  });
+
+  test("rethrows after exhausting maxRetries", async () => {
+    let calls = 0;
+    await expect(
+      withSqliteRetry(
+        () => {
+          calls += 1;
+          throw sqliteError("SQLITE_BUSY");
+        },
+        { op: "test-op", maxRetries: 2, baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow("SQLITE_BUSY");
+    // Initial attempt + 2 retries.
+    expect(calls).toBe(3);
+  });
+});

package/src/util/abort-reasons.ts

@@ -46,6 +46,22 @@ export function createAbortReason(
   };
 }
 
+/**
+ * True when the abort came from a person stopping the turn they are watching
+ * (the Stop button, Esc, or the CLI's cancel signal file) rather than from the
+ * conversation going away or another subsystem seizing it.
+ *
+ * The distinction matters for the message queue. A user interrupt ends the
+ * turn in flight; it says nothing about the messages the same user queued
+ * behind it, so those survive the abort and run on the interrupted turn's
+ * drain. Every other kind (dispose, eviction, voice supersession, subagent
+ * teardown) is the conversation or its owner disappearing, where a queued
+ * message has nothing left to run on and is discarded.
+ */
+export function isUserInterruptAbort(reason: AbortReason | undefined): boolean {
+  return reason?.kind === "user_cancel" || reason?.kind === "signal_cancel";
+}
+
 export function isAbortReason(value: unknown): value is AbortReason {
   if (typeof value !== "object" || value === null) {
     return false;

package/src/util/ansi.ts

@@ -0,0 +1,44 @@
+/**
+ * Stripping of terminal escape sequences and control characters from
+ * untrusted strings before they reach a terminal or notification copy.
+ *
+ * One pattern serves every call site so coverage cannot drift between
+ * hand-rolled copies. CSI sequences carry the full parameter and
+ * intermediate byte ranges; OSC sequences match through their BEL/ST
+ * terminator, with the terminator optional so an unterminated sequence
+ * cannot smuggle its body past the strip.
+ */
+
+/**
+ * Well-formed ANSI escape sequences: CSI (`ESC [ params intermediates final`,
+ * covering colors, cursor moves, erase) and OSC (`ESC ] payload BEL|ST`,
+ * covering window-title writes and hyperlinks).
+ */
+const ANSI_SEQUENCE_RE =
+  /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g;
+
+/**
+ * Runs of C0/C1 control characters, including DEL and any bare ESC left by a
+ * malformed sequence. `\r` and `\n` are C0, so this also flattens newlines.
+ */
+const CONTROL_CHAR_RUN_RE = /[\u0000-\u001f\u007f-\u009f]+/g;
+
+/**
+ * Remove ANSI CSI/OSC escape sequences, leaving other control characters
+ * (newlines, tabs) intact. For multi-line text whose line structure matters.
+ */
+export function stripAnsiSequences(value: string): string {
+  return value.replace(ANSI_SEQUENCE_RE, "");
+}
+
+/**
+ * Remove ANSI CSI/OSC escape sequences, then replace every remaining run of
+ * C0/C1 control characters with `replacement` (removed by default). For
+ * single-line rendering where no control character may survive.
+ */
+export function stripAnsiAndControlChars(
+  value: string,
+  replacement = "",
+): string {
+  return stripAnsiSequences(value).replace(CONTROL_CHAR_RUN_RE, replacement);
+}

package/src/util/disk-usage.ts

@@ -1,5 +1,6 @@
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { existsSync, statfsSync } from "node:fs";
+import { promisify } from "node:util";
 
 import {
   getIsContainerized,
@@ -8,6 +9,8 @@ import {
 } from "../config/env-registry.js";
 import { getWorkspaceDir } from "./platform.js";
 
+const execFileAsync = promisify(execFile);
+
 export interface DiskUsageInfo {
   path: string;
   totalMb: number;
@@ -19,21 +22,17 @@ export interface DiskUsageInfo {
  * Measure the on-disk usage of one or more directory paths using `du -sb`.
  * Returns the sum of all paths in bytes, or null on failure.
  */
-function getDirectorySizeBytes(paths: string[]): number | null {
+async function getDirectorySizeBytes(paths: string[]): Promise<number | null> {
   try {
     const existing = paths.filter((p) => existsSync(p));
     if (existing.length === 0) {
       return null;
     }
-    const result = spawnSync("du", ["-sb", ...existing], {
-      encoding: "utf-8",
+    const { stdout } = await execFileAsync("du", ["-sb", ...existing], {
       timeout: 30_000,
     });
-    if (result.status !== 0) {
-      return null;
-    }
     let total = 0;
-    for (const line of result.stdout.trim().split("\n")) {
+    for (const line of stdout.trim().split("\n")) {
       const size = parseInt(line.split("\t")[0], 10);
       if (!isNaN(size) && size > 0) {
         total += size;
@@ -46,14 +45,19 @@ function getDirectorySizeBytes(paths: string[]): number | null {
 }
 
 const DU_CACHE_TTL_MS = 60_000;
-let duCacheValue: number | null = null;
+// Caches the in-flight promise so concurrent callers share one `du` run.
+let duCacheValue: Promise<number | null> | null = null;
 let duCacheTime = 0;
 let duCachePaths: string | null = null;
 
-function getCachedDirectorySizeBytes(paths: string[]): number | null {
+function getCachedDirectorySizeBytes(paths: string[]): Promise<number | null> {
   const key = paths.join("\0");
   const now = Date.now();
-  if (duCachePaths === key && now - duCacheTime < DU_CACHE_TTL_MS) {
+  if (
+    duCacheValue !== null &&
+    duCachePaths === key &&
+    now - duCacheTime < DU_CACHE_TTL_MS
+  ) {
     return duCacheValue;
   }
   duCacheValue = getDirectorySizeBytes(paths);
@@ -119,7 +123,7 @@ function classifyWorkspaceVolume(
   return { kind: "none" };
 }
 
-export function getDiskUsageInfo(): DiskUsageInfo | null {
+export async function getDiskUsageInfo(): Promise<DiskUsageInfo | null> {
   try {
     const wsDir = getWorkspaceDir();
     const diskPath = existsSync(wsDir) ? wsDir : "/";
@@ -135,7 +139,7 @@ export function getDiskUsageInfo(): DiskUsageInfo | null {
       if (diskPath !== "/data" && existsSync("/data")) {
         volumePaths.push("/data");
       }
-      const usedBytes = getCachedDirectorySizeBytes(volumePaths);
+      const usedBytes = await getCachedDirectorySizeBytes(volumePaths);
       if (usedBytes !== null) {
         const totalBytes =
           reporting.kind === "fixed-cap"

package/src/util/image-conversion.ts

@@ -13,7 +13,6 @@
  * conversions of the same image (or daemon restarts) skip the sips call.
  */
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   closeSync,
@@ -101,10 +100,10 @@ export interface ConvertToJpegOptions {
   quality?: number;
 }
 
-function runSips(
+async function runSips(
   inputBytes: Uint8Array,
   options: ConvertToJpegOptions,
-): Buffer | null {
+): Promise<Buffer | null> {
   const stamp = `${Date.now()}-${uuid().slice(0, 8)}`;
   const srcPath = join(tmpdir(), `vellum-img-opt-${stamp}-src`);
   const outPath = join(tmpdir(), `vellum-img-opt-${stamp}-out.jpg`);
@@ -133,7 +132,15 @@ function runSips(
       "--out",
       outPath,
     );
-    execFileSync("sips", args, { stdio: "pipe", timeout: 15_000 });
+    const proc = Bun.spawn(["sips", ...args], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: 15_000,
+    });
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+      return null;
+    }
     return readFileSync(outPath) as Buffer;
   } catch {
     return null;
@@ -155,10 +162,10 @@ function runSips(
  * Convert an image to JPEG, optionally downscaling. Returns null when
  * conversion is unavailable (non-macOS) or fails; callers keep the original.
  */
-export function convertImageToJpeg(
+export async function convertImageToJpeg(
   bytes: Uint8Array,
   options: ConvertToJpegOptions = {},
-): Buffer | null {
+): Promise<Buffer | null> {
   const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
   // Options qualify the key so full-resolution storage conversions and
   // resized transport conversions of the same source never collide.
@@ -173,7 +180,7 @@ export function convertImageToJpeg(
     return cached;
   }
 
-  const converted = runSips(bytes, options);
+  const converted = await runSips(bytes, options);
   if (!converted) {
     return null;
   }
@@ -346,12 +353,12 @@ export interface NormalizedImageBytes {
  * {@link jpegFilenameFor} when `converted` is true — a MIME-only correction
  * sets `converted: false` and keeps the filename.
  */
-export function normalizeImageBytes(
+export async function normalizeImageBytes(
   mimeType: string,
   bytes: Uint8Array,
-): NormalizedImageBytes {
+): Promise<NormalizedImageBytes> {
   if (isHeifImage(bytes)) {
-    const converted = convertImageToJpeg(bytes, {
+    const converted = await convertImageToJpeg(bytes, {
       quality: STORAGE_JPEG_QUALITY,
     });
     if (!converted) {
@@ -376,14 +383,14 @@ export interface NormalizedImageBase64 {
  * Base64 variant of {@link normalizeImageBytes}. Sniffs the decoded head
  * first so non-HEIF payloads skip the full decode.
  */
-export function normalizeImageBase64(
+export async function normalizeImageBase64(
   mimeType: string,
   dataBase64: string,
-): NormalizedImageBase64 {
+): Promise<NormalizedImageBase64> {
   // 16 base64 chars decode to the 12 bytes the ftyp/signature sniffs need.
   const head = Buffer.from(dataBase64.slice(0, 16), "base64");
   if (isHeifImage(head)) {
-    const normalized = normalizeImageBytes(
+    const normalized = await normalizeImageBytes(
       mimeType,
       Buffer.from(dataBase64, "base64"),
     );

package/src/util/language-subtag.ts

@@ -0,0 +1,43 @@
+/**
+ * The lowercased primary subtag of a BCP 47 (or underscore-separated)
+ * language tag: "pt-BR" -> "pt", "es_419" -> "es", "  EN-us " -> "en".
+ * Undefined for undefined or blank input. The one language-tag
+ * normalizer in the daemon: every language comparison, table lookup, and
+ * prompt interpolation goes through this so a regional variant can never
+ * slip past a base-subtag consumer.
+ */
+export function baseLanguageSubtag(language?: string): string | undefined {
+  const base = language?.trim().toLowerCase().split(/[-_]/)[0];
+  return base ? base : undefined;
+}
+
+/**
+ * Whether the table carries its own entry for the language, keyed by
+ * lowercased base subtag. False for unset languages and for prototype keys
+ * ("constructor", "toString") rather than table entries. When this is
+ * false, {@link localizedOrDefault} returns the fallback, so callers whose
+ * fallback is English text can label the result as English (e.g. for a TTS
+ * language hint) instead of the requested language.
+ */
+export function hasLocalizedEntry(
+  table: Readonly<Record<string, unknown>>,
+  language: string | undefined,
+): boolean {
+  const base = baseLanguageSubtag(language);
+  return base !== undefined && Object.hasOwn(table, base);
+}
+
+/**
+ * Look up a per-language value in a plain-record table keyed by lowercase
+ * base subtags, falling back when the language is unset, unknown, or a
+ * prototype key ("constructor", "toString") rather than a table entry.
+ */
+export function localizedOrDefault<T>(
+  table: Readonly<Record<string, T>>,
+  language: string | undefined,
+  fallback: T,
+): T {
+  return hasLocalizedEntry(table, language)
+    ? (table[baseLanguageSubtag(language)!] as T)
+    : fallback;
+}

package/src/util/schedule-source-key.ts

@@ -0,0 +1,23 @@
+/**
+ * Plugin-declared schedules record their provenance in the `source_key`
+ * column as `plugin:<pluginName>/<scheduleName>`. The format is minted by
+ * `pluginScheduleSourceKey` in schedule/plugin-schedule-declarations.ts;
+ * this leaf parser lets display surfaces (CLI tables, tool output) derive
+ * the owning plugin without importing the daemon's schedule modules.
+ */
+
+const PLUGIN_SOURCE_KEY_RE = /^plugin:([^/]+)\//;
+
+/**
+ * Display attribution for a schedule row: the owning plugin's name, the raw
+ * key when it does not match the format so provenance is never silently
+ * dropped, or null when the row is imperative.
+ */
+export function describeScheduleSource(
+  sourceKey: string | null | undefined,
+): string | null {
+  if (!sourceKey) {
+    return null;
+  }
+  return PLUGIN_SOURCE_KEY_RE.exec(sourceKey)?.[1] ?? sourceKey;
+}

package/src/util/unicode.ts

@@ -20,7 +20,7 @@ export function isHighSurrogate(code: number): boolean {
   return code >= HIGH_SURROGATE_START && code <= HIGH_SURROGATE_END;
 }
 
-function isLowSurrogate(code: number): boolean {
+export function isLowSurrogate(code: number): boolean {
   return code >= LOW_SURROGATE_START && code <= LOW_SURROGATE_END;
 }
 

package/src/util/worker-process.ts

@@ -17,6 +17,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { getCurrentLogFilePath } from "./logger.js";
 import { workerMemoryEnv } from "./worker-memory.js";
@@ -209,8 +210,13 @@ export async function spawnWorkerProcess(args: {
 
   // Workers are latency-insensitive, so run them in bun's small-heap mode
   // with a RAM-size hint sized to the container — see worker-memory.ts.
+  //
+  // `fileURLToPath`, not `.pathname`: a URL's pathname is percent-encoded, so
+  // an install path containing a space (every macOS desktop install lives
+  // under "Application Support") would reach bun as "Application%20Support"
+  // and the entry would not be found.
   const child = Bun.spawn({
-    cmd: ["bun", "--smol", "run", args.entry.pathname],
+    cmd: ["bun", "--smol", "run", fileURLToPath(args.entry)],
     env: workerMemoryEnv(),
     stdio: ["ignore", "ignore", stderrFd],
     detached,

package/src/workspace/git-service.ts

@@ -1,4 +1,4 @@
-import { execFile, spawn, spawnSync } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import {
   chmodSync,
   existsSync,
@@ -413,18 +413,19 @@ export class WorkspaceGitService {
    * open, we leave it alone. If no process holds it, it's stale (crashed
    * process) and safe to remove.
    */
-  private cleanStaleLockFile(): void {
+  private async cleanStaleLockFile(): Promise<void> {
     const lockPath = join(this.workspaceDir, ".git", "index.lock");
     if (!existsSync(lockPath)) {
       return;
     }
 
     try {
-      const result = spawnSync("lsof", ["-t", lockPath], {
+      // lsof exits non-zero when no process holds the file, which rejects the
+      // promise and falls through to removal below.
+      const { stdout } = await execFileAsync("lsof", ["-t", lockPath], {
         timeout: 3000,
-        stdio: ["ignore", "pipe", "ignore"],
       });
-      if (result.status === 0 && result.stdout?.length > 0) {
+      if (stdout.length > 0) {
         log.debug("index.lock held by an active process, skipping removal");
         return;
       }
@@ -490,7 +491,7 @@ export class WorkspaceGitService {
 
           // Clean up stale lock files before any git operations.
           if (existsSync(gitDir)) {
-            this.cleanStaleLockFile();
+            await this.cleanStaleLockFile();
           }
 
           if (existsSync(gitDir)) {
@@ -657,7 +658,7 @@ export class WorkspaceGitService {
     await this.ensureInitialized();
 
     await this.mutex.withLock(async () => {
-      this.cleanStaleLockFile();
+      await this.cleanStaleLockFile();
 
       // Stage all changes (minus oversized files)
       await this.stageAllLocked();
@@ -734,7 +735,7 @@ export class WorkspaceGitService {
 
     try {
       const result = await this.mutex.withLock(async () => {
-        this.cleanStaleLockFile();
+        await this.cleanStaleLockFile();
 
         // Re-check breaker under lock: a queued call that started before the
         // breaker opened should not proceed with expensive git work now that
@@ -1991,6 +1992,29 @@ export class WorkspaceGitService {
     return this.execGit(args);
   }
 
+  /**
+   * Run a read-only git command WITHOUT initializing the repository.
+   *
+   * `runReadOnlyGit` is read-only in the sense that its git command does not
+   * write, but it still awaits `ensureInitialized()`, which will create the
+   * repository, write `.gitignore` and the hooks directory, make the initial
+   * commit, and schedule a history compaction when the workspace is not yet a
+   * repo. That makes it unusable from an HTTP GET, which
+   * `src/runtime/AGENTS.md` requires to be side-effect-free.
+   *
+   * This variant skips initialization entirely and throws when the workspace
+   * is not a repository, so a caller that merely wants to *observe* history
+   * can degrade instead of bringing a repo into existence.
+   */
+  async runReadOnlyGitWithoutInit(
+    args: string[],
+  ): Promise<{ stdout: string; stderr: string }> {
+    if (!existsSync(join(this.workspaceDir, ".git"))) {
+      throw new Error("Workspace is not a git repository");
+    }
+    return this.execGit(args);
+  }
+
   /**
    * Run a sequence of git commands atomically under the workspace mutex.
    * Use this for write operations that need serialization with other
@@ -2003,7 +2027,7 @@ export class WorkspaceGitService {
   ): Promise<void> {
     await this.ensureInitialized();
     await this.mutex.withLock(async () => {
-      this.cleanStaleLockFile();
+      await this.cleanStaleLockFile();
       await fn((args) => {
         // Intercept commit commands to enforce hook hardening.
         if (args[0] === "commit") {