@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/util/__tests__/text-spacing.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import { joinWithSpacing, needsBoundarySpace } from "../text-spacing.js";
+
+describe("needsBoundarySpace", () => {
+  test("true when both sides fuse two non-whitespace characters", () => {
+    expect(needsBoundarySpace("end.", "Next")).toBe(true);
+  });
+
+  test("false when the left side already ends in whitespace", () => {
+    expect(needsBoundarySpace("end. ", "Next")).toBe(false);
+    expect(needsBoundarySpace("end.\n", "Next")).toBe(false);
+    expect(needsBoundarySpace("end.\t", "Next")).toBe(false);
+  });
+
+  test("false when the right side already starts with whitespace", () => {
+    expect(needsBoundarySpace("end.", " Next")).toBe(false);
+    expect(needsBoundarySpace("end.", "\nNext")).toBe(false);
+  });
+
+  test("false when either side is empty", () => {
+    expect(needsBoundarySpace("", "Next")).toBe(false);
+    expect(needsBoundarySpace("end.", "")).toBe(false);
+    expect(needsBoundarySpace("", "")).toBe(false);
+  });
+});
+
+describe("joinWithSpacing", () => {
+  test("inserts a single space between fused segments", () => {
+    expect(joinWithSpacing(["Sentence one.", "Sentence two."])).toBe(
+      "Sentence one. Sentence two.",
+    );
+  });
+
+  test("preserves whitespace the parts already supply", () => {
+    expect(joinWithSpacing(["First half. ", "Second half."])).toBe(
+      "First half. Second half.",
+    );
+    expect(joinWithSpacing(["First.", " Second."])).toBe("First. Second.");
+    expect(joinWithSpacing(["Line one\n", "Line two"])).toBe(
+      "Line one\nLine two",
+    );
+  });
+
+  test("does not alter intra-part spacing", () => {
+    expect(joinWithSpacing(["a b c"])).toBe("a b c");
+  });
+
+  test("skips empty parts without inserting stray spaces", () => {
+    expect(joinWithSpacing(["Done.", "", "More."])).toBe("Done. More.");
+    expect(joinWithSpacing([])).toBe("");
+  });
+});

package/src/util/cgroup-memory.ts

@@ -0,0 +1,142 @@
+/**
+ * Container memory accounting read from cgroup files (and the platform
+ * `VELLUM_MEMORY_LIMIT` override).
+ *
+ * Shared by the `/v1/health` identity handler (which reports current + max) and
+ * the resource monitor (which additionally samples the peak and the
+ * memory.events pressure counters). Keeping the cgroup v2→v1 fallbacks in one
+ * place means a single source of truth for how the assistant reads its own
+ * memory footprint.
+ */
+
+import { readFileSync } from "node:fs";
+import { totalmem } from "node:os";
+
+import { parseK8sMemoryBytes } from "./disk-usage.js";
+
+function readCgroupInt(path: string): number | null {
+  try {
+    const raw = readFileSync(path, "utf-8").trim();
+    if (raw === "max") return null;
+    const bytes = parseInt(raw, 10);
+    return Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the memory limit from the VELLUM_MEMORY_LIMIT env var (K8s resource
+ * format), then fall back to cgroups, then to os.totalmem() at the call site.
+ *
+ * In platform mode the container runs under gVisor where cgroup files may report
+ * the node's memory rather than the container limit. VELLUM_MEMORY_LIMIT is set
+ * by the StatefulSet template to the exact K8s memory limit (e.g. "3Gi").
+ */
+export function getContainerMemoryLimitBytes(): number | null {
+  // 1. Prefer the explicit env var set by the platform StatefulSet template.
+  try {
+    const envLimit = process.env.VELLUM_MEMORY_LIMIT;
+    if (envLimit) {
+      const parsed = parseK8sMemoryBytes(envLimit);
+      if (parsed !== null) return parsed;
+    }
+  } catch {
+    /* env var parsing failed – fall through to cgroups */
+  }
+
+  // 2. Try cgroups v2.
+  const v2 = readCgroupInt("/sys/fs/cgroup/memory.max");
+  if (v2 !== null) return v2;
+
+  // 3. Try cgroups v1.
+  try {
+    const raw = readFileSync(
+      "/sys/fs/cgroup/memory/memory.limit_in_bytes",
+      "utf-8",
+    ).trim();
+    const bytes = parseInt(raw, 10);
+    // cgroups v1 uses a near-INT64_MAX sentinel when no limit is set.
+    if (!isNaN(bytes) && bytes > 0 && bytes < totalmem() * 1.5) return bytes;
+  } catch {
+    /* not available */
+  }
+  return null;
+}
+
+/**
+ * Read the container's current memory usage from cgroup files.
+ *
+ * Tries cgroups v2 (`memory.current`) first, then cgroups v1
+ * (`memory/memory.usage_in_bytes`), mirroring the v2-then-v1 fallback used by
+ * {@link getContainerMemoryLimitBytes}. Returns null if neither file is
+ * available or readable.
+ *
+ * Unlike the limit lookup, no env-var override is needed: the gVisor issue that
+ * motivates VELLUM_MEMORY_LIMIT is specifically about the *limit* files exposing
+ * the host node's memory instead of the sandbox limit. The *usage* files
+ * (memory.current / memory.usage_in_bytes) reflect the sandbox's own accounting
+ * and are accurate under gVisor.
+ */
+export function getContainerMemoryUsageBytes(): number | null {
+  return (
+    readCgroupInt("/sys/fs/cgroup/memory.current") ??
+    readCgroupInt("/sys/fs/cgroup/memory/memory.usage_in_bytes")
+  );
+}
+
+/**
+ * Read the high-water mark of the container's memory usage.
+ *
+ * cgroups v2 (`memory.peak`) first, then cgroups v1
+ * (`memory/memory.max_usage_in_bytes`). Returns null when neither is available
+ * — `memory.peak` in particular only exists on newer kernels, so callers must
+ * tolerate its absence.
+ */
+export function getContainerMemoryPeakBytes(): number | null {
+  return (
+    readCgroupInt("/sys/fs/cgroup/memory.peak") ??
+    readCgroupInt("/sys/fs/cgroup/memory/memory.max_usage_in_bytes")
+  );
+}
+
+/**
+ * Pressure counters from the cgroup v2 `memory.events` file. Each field counts
+ * how many times the cgroup crossed the corresponding boundary since boot; a
+ * rising `max` (usage hit the hard limit and allocation was throttled) or
+ * `oom_kill` (a process was reaped) is the clearest in-VM signal that the
+ * container is being squeezed toward an OOM kill. Returns null on cgroups v1 or
+ * when the file is unreadable.
+ */
+export interface ContainerMemoryEvents {
+  low: number;
+  high: number;
+  max: number;
+  oom: number;
+  oomKill: number;
+}
+
+export function getContainerMemoryEvents(): ContainerMemoryEvents | null {
+  let raw: string;
+  try {
+    raw = readFileSync("/sys/fs/cgroup/memory.events", "utf-8");
+  } catch {
+    return null;
+  }
+
+  const counts: Record<string, number> = {};
+  for (const line of raw.split("\n")) {
+    const [key, value] = line.trim().split(/\s+/);
+    if (!key) continue;
+    const parsed = parseInt(value, 10);
+    if (Number.isFinite(parsed)) counts[key] = parsed;
+  }
+
+  return {
+    low: counts.low ?? 0,
+    high: counts.high ?? 0,
+    max: counts.max ?? 0,
+    oom: counts.oom ?? 0,
+    oomKill: counts.oom_kill ?? 0,
+  };
+}

package/src/util/image-conversion.ts

@@ -0,0 +1,281 @@
+/**
+ * JPEG conversion for images, backed by macOS `sips`.
+ *
+ * Two consumers share this converter:
+ *   - transport optimization (`agent/image-optimize.ts`) downscales large
+ *     images before provider calls;
+ *   - storage normalization (attachment ingress + history hydration) converts
+ *     HEIF/HEIC — which Chromium-based clients cannot decode — to JPEG.
+ *
+ * Conversion runs `sips` (a macOS builtin); on other platforms or on any
+ * failure it returns null and callers keep the original bytes. Results are
+ * cached on disk keyed by content hash + conversion options, so repeated
+ * conversions of the same image (or daemon restarts) skip the sips call.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { v4 as uuid } from "uuid";
+
+const DEFAULT_JPEG_QUALITY = 80;
+
+/** Full-resolution quality for stored attachment masters. */
+const STORAGE_JPEG_QUALITY = 90;
+
+const CACHE_MAX_ENTRIES = 500;
+
+function getCacheDir(): string {
+  return join(tmpdir(), "vellum-optimized-images");
+}
+
+function readFromCache(key: string): Buffer | null {
+  try {
+    const cachePath = join(getCacheDir(), `${key}.jpg`);
+    if (!existsSync(cachePath)) return null;
+    return readFileSync(cachePath) as Buffer;
+  } catch {
+    return null;
+  }
+}
+
+function writeToCache(key: string, convertedBytes: Buffer): void {
+  try {
+    const dir = getCacheDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${key}.jpg`), convertedBytes);
+    evictIfNeeded(dir);
+  } catch {
+    // Cache write failure is non-fatal.
+  }
+}
+
+function evictIfNeeded(dir: string): void {
+  try {
+    const entries = readdirSync(dir)
+      .filter((f) => f.endsWith(".jpg"))
+      .map((f) => {
+        const full = join(dir, f);
+        return { path: full, mtimeMs: statSync(full).mtimeMs };
+      })
+      .sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const excess = entries.length - CACHE_MAX_ENTRIES;
+    for (let i = 0; i < excess; i++) {
+      try {
+        unlinkSync(entries[i]!.path);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+export interface ConvertToJpegOptions {
+  /** Downscale so neither side exceeds this; omit to keep full resolution. */
+  maxDimensionPx?: number;
+  /** JPEG quality 1-100 (default 80). */
+  quality?: number;
+}
+
+function runSips(
+  inputBytes: Uint8Array,
+  options: ConvertToJpegOptions,
+): 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`);
+  try {
+    writeFileSync(srcPath, inputBytes);
+    const args =
+      options.maxDimensionPx != null
+        ? ["--resampleHeightWidthMax", String(options.maxDimensionPx)]
+        : [];
+    args.push(
+      "-s",
+      "format",
+      "jpeg",
+      "-s",
+      "formatOptions",
+      String(options.quality ?? DEFAULT_JPEG_QUALITY),
+      srcPath,
+      "--out",
+      outPath,
+    );
+    execFileSync("sips", args, { stdio: "pipe", timeout: 15_000 });
+    return readFileSync(outPath) as Buffer;
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(srcPath);
+    } catch {
+      /* ignore */
+    }
+    try {
+      unlinkSync(outPath);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Convert an image to JPEG, optionally downscaling. Returns null when
+ * conversion is unavailable (non-macOS) or fails; callers keep the original.
+ */
+export function convertImageToJpeg(
+  bytes: Uint8Array,
+  options: ConvertToJpegOptions = {},
+): Buffer | null {
+  const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+  // Options qualify the key so full-resolution storage conversions and
+  // downscaled transport conversions of the same source never collide.
+  const cacheKey = `${hash}-${options.maxDimensionPx ?? "full"}-q${options.quality ?? DEFAULT_JPEG_QUALITY}`;
+
+  const cached = readFromCache(cacheKey);
+  if (cached) return cached;
+
+  const converted = runSips(bytes, options);
+  if (!converted) return null;
+
+  writeToCache(cacheKey, converted);
+  return converted;
+}
+
+// HEIF container brands (ISO BMFF `ftyp` major brand). AVIF brands are
+// deliberately absent: Chromium decodes AVIF natively, so it needs no
+// normalization.
+const HEIF_FTYP_BRANDS = new Set([
+  "heic",
+  "heix",
+  "hevc",
+  "hevx",
+  "heif",
+  "heim",
+  "heis",
+  "hevm",
+  "hevs",
+  "mif1",
+  "msf1",
+]);
+
+/**
+ * Content-based HEIF/HEIC detection. MIME metadata is unreliable here:
+ * Chromium reports an empty `file.type` for `.heic`, which clients coerce to
+ * `application/octet-stream`.
+ */
+export function isHeifImage(bytes: Uint8Array): boolean {
+  if (bytes.length < 12) return false;
+  // ISO BMFF layout: bytes 4-8 are "ftyp", bytes 8-12 the major brand.
+  if (
+    bytes[4] !== 0x66 || // f
+    bytes[5] !== 0x74 || // t
+    bytes[6] !== 0x79 || // y
+    bytes[7] !== 0x70 // p
+  ) {
+    return false;
+  }
+  const brand = String.fromCharCode(
+    bytes[8]!,
+    bytes[9]!,
+    bytes[10]!,
+    bytes[11]!,
+  );
+  return HEIF_FTYP_BRANDS.has(brand);
+}
+
+const HEIF_FILENAME_RE = /\.(heic|heif)$/i;
+
+/**
+ * Filename-extension HEIF/HEIC detection, for call sites that only hold
+ * attachment metadata (filename + MIME) and want to skip hydrating bytes for
+ * non-candidate rows. Complements {@link isHeifImage}: Chromium reports an
+ * empty MIME for `.heic`, so legacy rows can carry HEIC bytes under
+ * `application/octet-stream` while the extension survives.
+ */
+export function isHeicFilename(filename: string): boolean {
+  return HEIF_FILENAME_RE.test(filename.trim());
+}
+
+/** Rewrites a filename's extension to `.jpg` (e.g. `IMG_5487.HEIC` → `IMG_5487.jpg`). */
+export function jpegFilenameFor(filename: string): string {
+  const fallback = "attachment";
+  const trimmed = filename.trim() || fallback;
+  if (/\.jpe?g$/i.test(trimmed)) return trimmed;
+  const withoutExtension = trimmed.replace(/\.[^./\\]+$/, "") || fallback;
+  return `${withoutExtension}.jpg`;
+}
+
+export interface NormalizedImageBytes {
+  mimeType: string;
+  bytes: Uint8Array;
+  converted: boolean;
+}
+
+/**
+ * Normalize image bytes for storage: HEIF/HEIC becomes a full-resolution JPEG
+ * master; everything else (and any conversion failure) passes through
+ * unchanged. Callers that persist a filename should rewrite it with
+ * {@link jpegFilenameFor} when `converted` is true.
+ */
+export function normalizeImageBytes(
+  mimeType: string,
+  bytes: Uint8Array,
+): NormalizedImageBytes {
+  if (!isHeifImage(bytes)) {
+    return { mimeType, bytes, converted: false };
+  }
+  const converted = convertImageToJpeg(bytes, {
+    quality: STORAGE_JPEG_QUALITY,
+  });
+  if (!converted) {
+    return { mimeType, bytes, converted: false };
+  }
+  return { mimeType: "image/jpeg", bytes: converted, converted: true };
+}
+
+export interface NormalizedImageBase64 {
+  mimeType: string;
+  dataBase64: string;
+  converted: boolean;
+}
+
+/**
+ * Base64 variant of {@link normalizeImageBytes}. Sniffs the decoded head
+ * first so non-HEIF payloads skip the full decode.
+ */
+export function normalizeImageBase64(
+  mimeType: string,
+  dataBase64: string,
+): NormalizedImageBase64 {
+  // 16 base64 chars decode to the 12 bytes the ftyp sniff needs.
+  const head = Buffer.from(dataBase64.slice(0, 16), "base64");
+  if (!isHeifImage(head)) {
+    return { mimeType, dataBase64, converted: false };
+  }
+  const normalized = normalizeImageBytes(
+    mimeType,
+    Buffer.from(dataBase64, "base64"),
+  );
+  if (!normalized.converted) {
+    return { mimeType, dataBase64, converted: false };
+  }
+  return {
+    mimeType: normalized.mimeType,
+    dataBase64: Buffer.from(normalized.bytes).toString("base64"),
+    converted: true,
+  };
+}

package/src/util/phone.ts

@@ -1,17 +1,10 @@
 /**
- * Phone number normalization and validation utilities.
+ * Phone number normalization utilities.
  *
  * Accepts common US and international phone number formats and normalizes
  * them to E.164 before validation, rate-limit lookups, or storage.
  */
 
-/**
- * Basic E.164 phone number validation: starts with +, followed by 10-15 digits.
- */
-export function isValidE164(phone: string): boolean {
-  return /^\+\d{10,15}$/.test(phone);
-}
-
 /**
  * Normalize a phone number string to E.164 format.
  *

package/src/util/platform.ts

@@ -247,6 +247,28 @@ export function getMemoryWorkerPidPath(): string {
   return join(getWorkspaceDir(), "memory-worker.pid");
 }
 
+/** Returns the path to the schedule-worker PID file ($VELLUM_WORKSPACE_DIR/schedule-worker.pid). */
+export function getScheduleWorkerPidPath(): string {
+  return join(getWorkspaceDir(), "schedule-worker.pid");
+}
+
+/**
+ * Returns the directory where the resource monitor persists its forensics
+ * ($VELLUM_WORKSPACE_DIR/data/monitoring). Lives on the workspace volume (the
+ * PVC) so the sample ring buffer and high-memory snapshots survive an OOM
+ * SIGKILL that resets all in-process state. Git-ignored from the workspace
+ * tree (see `data/monitoring/` in git-service.ts) so the assistant's own
+ * telemetry is not auto-committed as user changes.
+ */
+export function getMonitoringDataDir(): string {
+  return join(getDataDir(), "monitoring");
+}
+
+/** Returns the path to the monitoring PID file, under the monitor data dir. */
+export function getMonitoringPidPath(): string {
+  return join(getMonitoringDataDir(), "monitoring.pid");
+}
+
 /**
  * Returns the workspace root for user-facing state.
  *
@@ -331,6 +353,17 @@ export function getWorkspaceRoutesDir(): string {
   return join(getWorkspaceDir(), "routes");
 }
 
+/**
+ * Returns $VELLUM_WORKSPACE_DIR/workflows — saved (named) workflow scripts.
+ *
+ * A file here becomes a saved workflow whose source is executed (in the sandbox,
+ * and unattended when triggered by a schedule), so the file risk classifier
+ * escalates writes under this path to High like `tools/` and `routes/`.
+ */
+export function getWorkspaceWorkflowsDir(): string {
+  return join(getWorkspaceDir(), "workflows");
+}
+
 /** Returns $VELLUM_WORKSPACE_DIR/deprecated — transitional files slated for removal. */
 export function getDeprecatedDir(): string {
   return join(getWorkspaceDir(), "deprecated");

package/src/util/process-tree.ts

@@ -64,7 +64,10 @@ function scriptName(scriptPath: string): string {
  * Derive a readable name from a command line. For interpreter invocations
  * (`bun run /…/jobs/worker.ts`) the script path is far more useful than the
  * interpreter name, so prefer the first script-looking argument and summarize it
- * as `<parent-dir>-<filename>` (e.g. `jobs-worker`). Plain binaries
+ * as `<parent-dir>-<filename>` (e.g. `jobs-worker`). When an interpreter is run
+ * without a script file (`bun run dev`, `bun x prettier`, `bun repl`) the bare
+ * interpreter name says nothing about what is running, so surface the arguments
+ * — what was actually run — alongside it (e.g. `bun run dev`). Plain binaries
  * (`/…/vellum-qdrant`) keep their bare executable name.
  */
 export function deriveName(command: string): string {
@@ -73,8 +76,13 @@ export function deriveName(command: string): string {
 
   const argv0 = basename(tokens[0]);
   if (RUNTIMES.has(argv0)) {
-    const script = tokens.slice(1).find((t) => SCRIPT_EXT_RE.test(t));
+    const args = tokens.slice(1);
+    const script = args.find((t) => SCRIPT_EXT_RE.test(t));
     if (script) return scriptName(script);
+    // No script to summarize: show the non-flag arguments so the entry reads as
+    // "what was run" rather than an opaque `bun`. Flags are dropped as noise.
+    const meaningful = args.filter((t) => !t.startsWith("-"));
+    if (meaningful.length > 0) return `${argv0} ${meaningful.join(" ")}`;
   }
   return argv0;
 }

package/src/util/text-spacing.ts

@@ -0,0 +1,53 @@
+/**
+ * Boundary-aware text joining.
+ *
+ * A single assistant turn is emitted as a sequence of text blocks split by
+ * tool-call and message boundaries. The model frequently ends one block with a
+ * sentence-final period and no trailing whitespace, then opens the next block
+ * with a capital letter and no leading whitespace — because from the model's
+ * point of view each block is its own response. Concatenating those blocks raw
+ * fuses the boundary into `...end.Next...` with the space missing.
+ *
+ * These helpers insert a single separating space at such a boundary, and only
+ * there: when both sides carry a character at the join and neither is already
+ * whitespace. Blocks that already supply a boundary space (or are empty) join
+ * verbatim, so intra-block token streams — where the model's own spacing is
+ * authoritative — are never altered.
+ */
+
+/** Whitespace characters that count as an existing join boundary. */
+function isJoinWhitespace(ch: string | undefined): boolean {
+  return ch === " " || ch === "\n" || ch === "\t";
+}
+
+/**
+ * Whether concatenating `left` + `right` needs a single separating space:
+ * true only when both sides have a character at the join and neither of those
+ * characters is already whitespace. Returns `false` when either side is empty.
+ */
+export function needsBoundarySpace(left: string, right: string): boolean {
+  const prev = left[left.length - 1];
+  const next = right[0];
+  return (
+    prev !== undefined &&
+    next !== undefined &&
+    !isJoinWhitespace(prev) &&
+    !isJoinWhitespace(next)
+  );
+}
+
+/**
+ * Join text parts, inserting a single space between adjacent parts only when
+ * the boundary would otherwise fuse two non-whitespace characters. Parts that
+ * already carry a boundary space (or are empty) are joined verbatim.
+ */
+export function joinWithSpacing(parts: string[]): string {
+  let result = parts[0] ?? "";
+  for (let i = 1; i < parts.length; i++) {
+    if (needsBoundarySpace(result, parts[i])) {
+      result += " ";
+    }
+    result += parts[i];
+  }
+  return result;
+}