@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/util/container-cpu-sampler.ts

@@ -0,0 +1,250 @@
+/**
+ * Rolling container CPU sampler.
+ *
+ * Tracks CPU usage over a rolling window so consumers (e.g. /v1/health) report
+ * near-real-time utilization instead of a lifetime average (total CPU time /
+ * total uptime). The sampler starts on module import and runs on an unref'd
+ * interval, so it never prevents process exit.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { getIsPlatform } from "../config/env-registry.js";
+import { getContainerCpuCores } from "./cgroup-cpu.js";
+
+/**
+ * Read the container's CPU usage from cgroup accounting files.
+ *
+ * Returns total CPU microseconds consumed by the container since boot.
+ * We use the delta between two samples to compute percentage.
+ */
+function getContainerCpuUsageUs(): number | null {
+  // cgroups v2: cpu.stat has a "usage_usec" line.
+  try {
+    const stat = readFileSync("/sys/fs/cgroup/cpu.stat", "utf-8");
+    for (const line of stat.split("\n")) {
+      if (line.startsWith("usage_usec")) {
+        const val = parseInt(line.split(/\s+/)[1], 10);
+        if (!isNaN(val) && val > 0) {
+          return val;
+        }
+      }
+    }
+  } catch {
+    /* not available */
+  }
+
+  // cgroups v1: cpuacct.usage is in nanoseconds.
+  try {
+    const ns = parseInt(
+      readFileSync("/sys/fs/cgroup/cpuacct/cpuacct.usage", "utf-8").trim(),
+      10,
+    );
+    if (!isNaN(ns) && ns > 0) {
+      return ns / 1000;
+    } // convert ns → µs
+  } catch {
+    /* not available */
+  }
+
+  return null;
+}
+
+const CPU_SAMPLE_INTERVAL_MS = 5_000;
+
+/**
+ * Sample this process's cumulative CPU time, returning null when the
+ * underlying syscall fails.
+ */
+function sampleProcessCpuUsage(): NodeJS.CpuUsage | null {
+  try {
+    return process.cpuUsage();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert a CPU-time delta into a percent of the container's full allocation,
+ * rounded to 2 decimal places. Callers must guard `numCores > 0` and
+ * `elapsedMs > 0`; a zero divisor yields a non-finite result.
+ */
+export function computeCpuPercent(
+  deltaCpuUs: number,
+  elapsedMs: number,
+  numCores: number,
+): number {
+  const deltaCpuMs = deltaCpuUs / 1000;
+  return Math.round((deltaCpuMs / (elapsedMs * numCores)) * 10000) / 100;
+}
+
+// Recent per-tick percents are retained so consumers with a coarser cadence
+// (the resource-pressure guard samples every 30s) can average the 5s windows
+// inside their own interval instead of reading one instantaneous value; a
+// workload that spikes in phase with the coarser cadence would otherwise
+// alias into a sustained-high reading.
+const RECENT_SAMPLE_RETENTION_MS = 5 * 60 * 1000;
+
+let _lastProcessCpuUsage: NodeJS.CpuUsage | null = sampleProcessCpuUsage();
+let _lastCgroupCpuUs: number | null = getContainerCpuUsageUs();
+let _lastCpuTime: number = Date.now();
+let _cachedCpuPercent = 0;
+// Whether the sampler has ever computed a real delta. Until then the cache
+// is a placeholder 0 (still warming up, or neither cgroup counters nor
+// process.cpuUsage() deltas are readable), not a measurement.
+let _hasCpuSample = false;
+let _recentSamples: { at: number; percent: number; elapsedMs: number }[] = [];
+
+function setCachedCpuPercent(
+  percent: number,
+  at: number,
+  elapsedMs: number,
+): void {
+  _cachedCpuPercent = percent;
+  _hasCpuSample = true;
+  _recentSamples.push({ at, percent, elapsedMs });
+  const cutoff = at - RECENT_SAMPLE_RETENTION_MS;
+  while (_recentSamples.length > 0 && _recentSamples[0].at < cutoff) {
+    _recentSamples.shift();
+  }
+}
+
+function runCpuSamplerTick(now: number): void {
+  const elapsedMs = now - _lastCpuTime;
+  if (elapsedMs <= 0) {
+    return;
+  }
+
+  const numCores = getContainerCpuCores();
+  if (numCores <= 0) {
+    _lastCpuTime = now;
+    return;
+  }
+
+  // Always sample process-level CPU so the baseline stays fresh. This
+  // prevents a spike if the platform cgroup path later falls back to
+  // process.cpuUsage() after cgroup stats were previously available.
+  const newProcessUsage = sampleProcessCpuUsage();
+  const processDeltaUs =
+    newProcessUsage !== null && _lastProcessCpuUsage !== null
+      ? newProcessUsage.user -
+        _lastProcessCpuUsage.user +
+        (newProcessUsage.system - _lastProcessCpuUsage.system)
+      : null;
+  if (newProcessUsage !== null) {
+    _lastProcessCpuUsage = newProcessUsage;
+  }
+
+  if (getIsPlatform()) {
+    // In platform mode, prefer cgroup-level CPU usage so we see the full
+    // container footprint, not just this process.
+    const cgroupUs = getContainerCpuUsageUs();
+    if (cgroupUs !== null && _lastCgroupCpuUs !== null) {
+      setCachedCpuPercent(
+        computeCpuPercent(cgroupUs - _lastCgroupCpuUs, elapsedMs, numCores),
+        now,
+        elapsedMs,
+      );
+    } else if (processDeltaUs !== null) {
+      // cgroup CPU stats unavailable (e.g. gVisor) – fall back to process-level.
+      setCachedCpuPercent(
+        computeCpuPercent(processDeltaUs, elapsedMs, numCores),
+        now,
+        elapsedMs,
+      );
+    }
+    _lastCgroupCpuUs = cgroupUs;
+  } else if (processDeltaUs !== null) {
+    // Non-platform: use process.cpuUsage() (accurate for single-process mode).
+    setCachedCpuPercent(
+      computeCpuPercent(processDeltaUs, elapsedMs, numCores),
+      now,
+      elapsedMs,
+    );
+  }
+
+  _lastCpuTime = now;
+}
+
+// Kick off the background sampler. unref() so it never prevents process exit.
+setInterval(() => {
+  runCpuSamplerTick(Date.now());
+}, CPU_SAMPLE_INTERVAL_MS).unref();
+
+/**
+ * Near-real-time CPU utilization as a percent of the container's full
+ * allocation, refreshed every {@link CPU_SAMPLE_INTERVAL_MS}.
+ *
+ * Reports 0 until the sampler computes its first delta; callers that must
+ * distinguish "idle" from "no data yet" use
+ * {@link getCachedContainerCpuPercentOrNull}.
+ */
+export function getCachedContainerCpuPercent(): number {
+  return _cachedCpuPercent;
+}
+
+/**
+ * Like {@link getCachedContainerCpuPercent}, but null until the sampler has
+ * computed at least one real delta, so warm-up and unreadable CPU accounting
+ * read as "signal unavailable" instead of a genuine-looking 0%.
+ */
+export function getCachedContainerCpuPercentOrNull(): number | null {
+  return _hasCpuSample ? _cachedCpuPercent : null;
+}
+
+/**
+ * Duration-weighted mean of per-tick percents over the window starting at
+ * `windowStartMs`. Each tick's percent covers the wall time its delta
+ * spanned (ending at `at`), so a delayed tick must weigh proportionally
+ * more than an on-schedule one, and only the part of a tick's interval
+ * that overlaps the window may contribute: a long delayed tick ending just
+ * inside the window would otherwise import load that predates it.
+ */
+export function computeDurationWeightedMeanPercent(
+  samples: readonly { at: number; percent: number; elapsedMs: number }[],
+  windowStartMs: number,
+): number | null {
+  let weightedSum = 0;
+  let totalOverlapMs = 0;
+  for (const sample of samples) {
+    const intervalStart = sample.at - sample.elapsedMs;
+    const overlapMs = sample.at - Math.max(intervalStart, windowStartMs);
+    if (overlapMs > 0) {
+      weightedSum += sample.percent * overlapMs;
+      totalOverlapMs += overlapMs;
+    }
+  }
+  if (totalOverlapMs <= 0) {
+    return null;
+  }
+  return Math.round((weightedSum / totalOverlapMs) * 100) / 100;
+}
+
+/**
+ * Duration-weighted mean of the per-tick percents recorded within the
+ * trailing `windowMs`, rounded to 2 decimal places, or null when no tick
+ * overlaps the window. Coarser-cadence consumers use this instead of the
+ * instantaneous cache so a short spike aligned with their cadence cannot
+ * read as sustained load.
+ */
+export function getAverageContainerCpuPercentOrNull(
+  windowMs: number,
+): number | null {
+  return computeDurationWeightedMeanPercent(
+    _recentSamples,
+    Date.now() - windowMs,
+  );
+}
+
+export function __resetContainerCpuSamplerForTests(): void {
+  _lastProcessCpuUsage = sampleProcessCpuUsage();
+  _lastCgroupCpuUs = getContainerCpuUsageUs();
+  _lastCpuTime = Date.now();
+  _cachedCpuPercent = 0;
+  _hasCpuSample = false;
+  _recentSamples = [];
+}
+
+export function __runContainerCpuSamplerTickForTests(nowMs: number): void {
+  runCpuSamplerTick(nowMs);
+}

package/src/util/image-conversion.ts

@@ -22,6 +22,7 @@ import {
   readdirSync,
   readFileSync,
   readSync,
+  renameSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -42,26 +43,151 @@ function getCacheDir(): string {
   return join(tmpdir(), "vellum-optimized-images");
 }
 
+/**
+ * Structural completeness check for a JPEG payload: SOI marker (FF D8) at the
+ * head and EOI marker (FF D9) at the tail. Every cache entry and every sips
+ * output is a JPEG, so a payload failing this is truncated or empty (the
+ * signature of a torn cache write) and must never reach a provider, which
+ * rejects it with a 400 that wedges the conversation (the corrupt block is
+ * resent on every subsequent turn).
+ */
+export function isCompleteJpeg(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === 0xff &&
+    bytes[1] === 0xd8 &&
+    bytes[bytes.length - 2] === 0xff &&
+    bytes[bytes.length - 1] === 0xd9
+  );
+}
+
+/**
+ * Structural JPEG truncation check for payloads of arbitrary origin: walk the
+ * marker segments from SOI and report whether a terminal EOI is reached.
+ * Unlike {@link isCompleteJpeg} (exact tail framing, for sips output and
+ * cache entries, which always end on EOI), this tolerates encoders that
+ * append padding or metadata after the EOI.
+ *
+ * A raw byte search for FF D9 is not enough: length-delimited APP/COM
+ * segments (an EXIF thumbnail is itself a complete embedded JPEG) may contain
+ * FF D9, so a truncated file with an intact metadata prefix would pass.
+ * Walking segment boundaries skips those payloads entirely; only an EOI at
+ * the top level of the marker stream counts. Entropy-coded scan data is
+ * traversed byte-wise, where FF is stuffed as FF 00 and restart markers
+ * (D0-D7) continue the scan, so a marker byte there is unambiguous.
+ *
+ * The EOI only counts after at least one frame header (SOF) and one scan
+ * (SOS) have been seen: a degenerate payload such as bare SOI+EOI carries no
+ * image data and providers reject it.
+ */
+export function hasValidJpegStructure(bytes: Uint8Array): boolean {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) {
+    return false;
+  }
+  let sawFrame = false;
+  let sawScan = false;
+  let i = 2;
+  while (i + 1 < bytes.length) {
+    if (bytes[i] !== 0xff) {
+      return false;
+    }
+    // FF fill bytes before a marker are legal padding.
+    let j = i + 1;
+    while (j < bytes.length && bytes[j] === 0xff) {
+      j++;
+    }
+    if (j >= bytes.length) {
+      return false;
+    }
+    const marker = bytes[j];
+    i = j + 1;
+    if (marker === 0xd9) {
+      return sawFrame && sawScan;
+    }
+    // SOF0-SOF15 occupy C0-CF, excluding DHT (C4), JPG (C8), and DAC (CC).
+    if (
+      marker >= 0xc0 &&
+      marker <= 0xcf &&
+      marker !== 0xc4 &&
+      marker !== 0xc8 &&
+      marker !== 0xcc
+    ) {
+      sawFrame = true;
+    }
+    // Standalone markers carry no length field: repeated SOI, TEM, RST0-7.
+    if (
+      marker === 0xd8 ||
+      marker === 0x01 ||
+      (marker >= 0xd0 && marker <= 0xd7)
+    ) {
+      continue;
+    }
+    if (i + 1 >= bytes.length) {
+      return false;
+    }
+    const segmentLength = (bytes[i] << 8) | bytes[i + 1];
+    if (segmentLength < 2) {
+      return false;
+    }
+    i += segmentLength;
+    if (marker === 0xda) {
+      sawScan = true;
+      // SOS: entropy-coded data follows the header. Scan to the next real
+      // marker; FF 00 (stuffed data byte) and FF D0-D7 (restart) stay inside
+      // the scan.
+      while (i + 1 < bytes.length) {
+        if (
+          bytes[i] === 0xff &&
+          bytes[i + 1] !== 0x00 &&
+          !(bytes[i + 1] >= 0xd0 && bytes[i + 1] <= 0xd7)
+        ) {
+          break;
+        }
+        i++;
+      }
+    }
+  }
+  return false;
+}
+
 function readFromCache(key: string): Buffer | null {
+  const cachePath = join(getCacheDir(), `${key}.jpg`);
   try {
-    const cachePath = join(getCacheDir(), `${key}.jpg`);
     if (!existsSync(cachePath)) {
       return null;
     }
-    return readFileSync(cachePath) as Buffer;
+    const bytes = readFileSync(cachePath) as Buffer;
+    if (!isCompleteJpeg(bytes)) {
+      // Poisoned entry (torn write, disk full, etc.): drop it so the caller
+      // re-converts and re-caches.
+      unlinkSync(cachePath);
+      return null;
+    }
+    return bytes;
   } catch {
     return null;
   }
 }
 
 function writeToCache(key: string, convertedBytes: Buffer): void {
+  const dir = getCacheDir();
+  // Write-then-rename so concurrent readers (the cache dir is shared across
+  // daemon processes) never observe a partially written entry; rename within
+  // the same directory is atomic. The pid+uuid suffix keeps concurrent
+  // writers of the same key off each other's temp file.
+  const tmpPath = join(dir, `${key}.${process.pid}-${uuid().slice(0, 8)}.tmp`);
   try {
-    const dir = getCacheDir();
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, `${key}.jpg`), convertedBytes);
+    writeFileSync(tmpPath, convertedBytes);
+    renameSync(tmpPath, join(dir, `${key}.jpg`));
     evictIfNeeded(dir);
   } catch {
     // Cache write failure is non-fatal.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
   }
 }
 
@@ -141,7 +267,14 @@ async function runSips(
     if (proc.exitCode !== 0) {
       return null;
     }
-    return readFileSync(outPath) as Buffer;
+    const out = readFileSync(outPath) as Buffer;
+    // A zero-exit sips can still leave a truncated file (disk full, timeout
+    // kill racing the write). Returning it would poison the cache and every
+    // downstream provider call. Treat it as a failed conversion instead.
+    if (!isCompleteJpeg(out)) {
+      return null;
+    }
+    return out;
   } catch {
     return null;
   } finally {
@@ -206,14 +339,22 @@ const HEIF_FTYP_BRANDS = new Set([
   "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 {
+// Brands whose canonical MIME is `image/heic`; the remaining HEIF brands
+// (`heif`, `mif1`, `msf1`) are `image/heif`.
+const HEIC_FTYP_BRANDS = new Set([
+  "heic",
+  "heix",
+  "hevc",
+  "hevx",
+  "heim",
+  "heis",
+  "hevm",
+  "hevs",
+]);
+
+function heifFtypBrand(bytes: Uint8Array): string | null {
   if (bytes.length < 12) {
-    return false;
+    return null;
   }
   // ISO BMFF layout: bytes 4-8 are "ftyp", bytes 8-12 the major brand.
   if (
@@ -222,7 +363,7 @@ export function isHeifImage(bytes: Uint8Array): boolean {
     bytes[6] !== 0x79 || // y
     bytes[7] !== 0x70 // p
   ) {
-    return false;
+    return null;
   }
   const brand = String.fromCharCode(
     bytes[8]!,
@@ -230,7 +371,30 @@ export function isHeifImage(bytes: Uint8Array): boolean {
     bytes[10]!,
     bytes[11]!,
   );
-  return HEIF_FTYP_BRANDS.has(brand);
+  return HEIF_FTYP_BRANDS.has(brand) ? brand : null;
+}
+
+/**
+ * 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 {
+  return heifFtypBrand(bytes) !== null;
+}
+
+/**
+ * Canonical HEIF MIME type for bytes whose container brand names one, and null
+ * for everything else. For providers that read HEIF directly and key on the
+ * declared media type (Gemini accepts `image/heic` and `image/heif`:
+ * https://ai.google.dev/gemini-api/docs/image-understanding).
+ */
+export function heifImageMimeType(bytes: Uint8Array): string | null {
+  const brand = heifFtypBrand(bytes);
+  if (!brand) {
+    return null;
+  }
+  return HEIC_FTYP_BRANDS.has(brand) ? "image/heic" : "image/heif";
 }
 
 /**

package/src/util/platform.ts

@@ -1,6 +1,6 @@
-import { chmodSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, sep } from "node:path";
 
 import { SEEDS } from "@vellumai/environments";
 
@@ -24,13 +24,17 @@ const VELLUM_ROOT = join(homedir(), ".vellum");
  */
 export function vellumRoot(): string {
   const override = getWorkspaceDirOverride();
+  let root = VELLUM_ROOT;
   if (override) {
     const parent = dirname(override);
     if (parent !== "/") {
-      return parent;
+      root = parent;
     }
   }
-  return VELLUM_ROOT;
+  // Same containment rule as getWorkspaceDir(): root-derived paths (protected
+  // dir, .env) must stay ephemeral in test processes too.
+  assertTestPathIsEphemeral(root);
+  return root;
 }
 
 export function isMacOS(): boolean {
@@ -334,19 +338,98 @@ export function getProcPidPath(name: string): string {
   return join(getProcDir(name), `${name}.pid`);
 }
 
+// --- Live-workspace guard for test processes --------------------------------
+//
+// A test process must never resolve the workspace (or the vellum root) to a
+// real, non-temp directory: production code exercised by a test would then
+// read and destructively write live state. The tmpdir redirection normally
+// comes from the bunfig.toml test preload, but bun only loads bunfig from the
+// cwd, so `bun test` run from any other directory (for example a source
+// checkout inside a deployed container's workspace) skips the preload and
+// inherits the ambient VELLUM_WORKSPACE_DIR. The containment assertion
+// therefore lives here, in production code, where it fires no matter how the
+// test process was launched.
+//
+// Containment logic mirrors src/__tests__/assert-not-live-db.ts, which cannot
+// be imported here (production code must not depend on test machinery).
+
+/** Lazily computed: is this process a `bun test` run? */
+let isTestProcess: boolean | undefined;
+
+/**
+ * Resolve symlinks in the deepest existing ancestor of `p`, then re-append
+ * the not-yet-created tail. This keeps the containment check honest both for
+ * paths under a symlinked temp root (macOS /var/folders) and for symlinks
+ * that point outside it, whether or not the leaf exists yet.
+ */
+function canonicalizeForWorkspaceGuard(p: string): string {
+  let cur = p;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) {
+        return p;
+      }
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function assertTestPathIsEphemeral(dir: string): void {
+  isTestProcess ??=
+    process.env.NODE_ENV === "test" ||
+    process.env.BUN_TEST === "1" ||
+    // `bun test` sets NODE_ENV=test only when unset; Bun.main being the test
+    // file itself is the backstop signal that survives a preset NODE_ENV.
+    (typeof Bun !== "undefined" &&
+      /\.(test|spec)\.[cm]?[jt]sx?$/.test(Bun.main));
+  if (!isTestProcess) {
+    return;
+  }
+  // Escape hatch for the rare intentional run against a real workspace,
+  // shared with assertTestDbIsIsolated() in persistence/db-connection.ts.
+  // Deliberately NOT added to tools/terminal/safe-env.ts: a daemon-level
+  // opt-out must not propagate into agent-spawned shells and disarm the
+  // guard for tests run from there.
+  if (process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS === "1") {
+    return;
+  }
+  const tmpRoot = canonicalizeForWorkspaceGuard(tmpdir());
+  const resolved = canonicalizeForWorkspaceGuard(dir);
+  if (resolved !== tmpRoot && !resolved.startsWith(tmpRoot + sep)) {
+    throw new Error(
+      [
+        `Refusing to use ${dir} (resolves to ${resolved}) in a test process: it is not under the temp directory (${tmpRoot}).`,
+        "",
+        "Tests must only touch an ephemeral workspace; a real one would expose",
+        "live assistant state to destructive test fixtures. This usually means",
+        "`bun test` ran from a cwd without the repo bunfig.toml, so the test",
+        "preload that redirects VELLUM_WORKSPACE_DIR to a tmpdir never loaded.",
+        "Run tests from the assistant package root, or set",
+        "VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS=1 to bypass deliberately.",
+      ].join("\n"),
+    );
+  }
+}
+
 /**
  * Returns the workspace root for user-facing state.
  *
  * When the VELLUM_WORKSPACE_DIR env var is set, returns that value (used in
  * containerized deployments where the workspace is a separate volume).
  * Otherwise falls back to ~/.vellum/workspace.
+ *
+ * In test processes the resolved directory must live under `os.tmpdir()`
+ * (see the live-workspace guard above); anything else throws.
  */
 export function getWorkspaceDir(): string {
-  const override = getWorkspaceDirOverride();
-  if (override) {
-    return override;
-  }
-  return join(VELLUM_ROOT, "workspace");
+  const dir = getWorkspaceDirOverride() ?? join(VELLUM_ROOT, "workspace");
+  assertTestPathIsEphemeral(dir);
+  return dir;
 }
 
 /**