@vellumai/assistant 0.6.1 → 0.6.3

package/src/runtime/routes/identity-routes.ts

@@ -3,12 +3,13 @@
  */
 
 import { existsSync, readFileSync, statfsSync, statSync } from "node:fs";
-import { cpus, totalmem } from "node:os";
+import { availableParallelism, cpus, totalmem } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { z } from "zod";
 
+import { getCpuLimit, getIsPlatform } from "../../config/env-registry.js";
 import { parseIdentityFields } from "../../daemon/handlers/identity.js";
 import { getProfilerRuntimeStatus } from "../../daemon/profiler-run-store.js";
 import { getMaxMigrationVersion } from "../../memory/migrations/registry.js";
@@ -54,10 +55,60 @@ interface MemoryInfo {
   maxMb: number;
 }
 
-// Read the container memory limit from cgroups if available, falling back to host total.
-// cgroups v2: /sys/fs/cgroup/memory.max (returns "max" when unlimited)
-// cgroups v1: /sys/fs/cgroup/memory/memory.limit_in_bytes (large sentinel when unlimited)
+/**
+ * Parse a Kubernetes-style memory string (e.g. "3Gi", "512Mi", "1G") into bytes.
+ * Returns null if the value is not a recognized format.
+ */
+function parseK8sMemoryBytes(value: string): number | null {
+  const match = value
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)\s*(Ki|Mi|Gi|Ti|Pi|Ei|k|M|G|T|P|E|m)?$/);
+  if (!match) return null;
+  const num = parseFloat(match[1]);
+  const unit = match[2] ?? "";
+  const multipliers: Record<string, number> = {
+    "": 1,
+    m: 1e-3,
+    k: 1e3,
+    M: 1e6,
+    G: 1e9,
+    T: 1e12,
+    P: 1e15,
+    E: 1e18,
+    Ki: 1024,
+    Mi: 1024 ** 2,
+    Gi: 1024 ** 3,
+    Ti: 1024 ** 4,
+    Pi: 1024 ** 5,
+    Ei: 1024 ** 6,
+  };
+  const mult = multipliers[unit];
+  if (mult === undefined) return null;
+  const bytes = Math.round(num * mult);
+  return bytes > 0 ? bytes : null;
+}
+
+/**
+ * Read the memory limit from the VELLUM_MEMORY_LIMIT env var (K8s resource format),
+ * then fall back to cgroups, then to os.totalmem().
+ *
+ * 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").
+ */
 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.
   try {
     const v2 = readFileSync("/sys/fs/cgroup/memory.max", "utf-8").trim();
     if (v2 !== "max") {
@@ -67,6 +118,8 @@ function getContainerMemoryLimitBytes(): number | null {
   } catch {
     /* not available */
   }
+
+  // 3. Try cgroups v1.
   try {
     const v1 = readFileSync(
       "/sys/fs/cgroup/memory/memory.limit_in_bytes",
@@ -81,10 +134,56 @@ function getContainerMemoryLimitBytes(): number | null {
   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
+ * `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.
+ */
+function getContainerMemoryUsageBytes(): number | null {
+  // 1. Try cgroups v2.
+  try {
+    const v2 = readFileSync("/sys/fs/cgroup/memory.current", "utf-8").trim();
+    const bytes = parseInt(v2, 10);
+    if (!isNaN(bytes) && bytes > 0) return bytes;
+  } catch {
+    /* not available */
+  }
+
+  // 2. Try cgroups v1.
+  try {
+    const v1 = readFileSync(
+      "/sys/fs/cgroup/memory/memory.usage_in_bytes",
+      "utf-8",
+    ).trim();
+    const bytes = parseInt(v1, 10);
+    if (!isNaN(bytes) && bytes > 0) return bytes;
+  } catch {
+    /* not available */
+  }
+  return null;
+}
+
 function getMemoryInfo(): MemoryInfo {
   const bytesToMb = (b: number) => Math.round((b / (1024 * 1024)) * 100) / 100;
+  // In platform-managed mode the daemon shares its Node process with whatever
+  // the container is doing as a whole; `process.memoryUsage().rss` only sees
+  // this process's resident set, which understates the container footprint
+  // operators care about. Read the cgroup usage file directly so /v1/health
+  // matches what the StatefulSet's memory limit is enforced against.
+  const currentBytes =
+    (getIsPlatform() ? getContainerMemoryUsageBytes() : null) ??
+    process.memoryUsage().rss;
   return {
-    currentMb: bytesToMb(process.memoryUsage().rss),
+    currentMb: bytesToMb(currentBytes),
     maxMb: bytesToMb(getContainerMemoryLimitBytes() ?? totalmem()),
   };
 }
@@ -94,36 +193,180 @@ interface CpuInfo {
   maxCores: number;
 }
 
+/**
+ * Parse a Kubernetes-style CPU string (e.g. "2000m", "1", "500m") into
+ * fractional cores. Returns null if the value is not a recognized format.
+ */
+function parseK8sCpuCores(value: string): number | null {
+  const trimmed = value.trim();
+  const milliMatch = trimmed.match(/^(\d+)m$/);
+  if (milliMatch) {
+    const millis = parseInt(milliMatch[1], 10);
+    return millis > 0 ? millis / 1000 : null;
+  }
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const num = parseFloat(trimmed);
+    return !isNaN(num) && num > 0 ? num : null;
+  }
+  return null;
+}
+
+/**
+ * Read the container's CPU core limit.
+ *
+ * Resolution order:
+ * 1. VELLUM_CPU_LIMIT env var (K8s resource format, e.g. "2000m" or "2").
+ *    In platform mode the container runs under gVisor where cgroup files may
+ *    report the node's CPU count rather than the sandbox limit.
+ * 2. cgroups v2 cpu.max (quota / period → fractional cores).
+ * 3. cgroups v1 cpu.cfs_quota_us / cpu.cfs_period_us.
+ * 4. os.cpus().length as last resort.
+ */
+function getContainerCpuCores(): number {
+  // 1. Prefer the explicit env var set by the platform StatefulSet template.
+  try {
+    const envLimit = getCpuLimit();
+    if (envLimit) {
+      const parsed = parseK8sCpuCores(envLimit);
+      if (parsed !== null) return parsed;
+    }
+  } catch {
+    /* env var parsing failed – fall through */
+  }
+
+  // 2. Try cgroups v2: /sys/fs/cgroup/cpu.max contains "$MAX $PERIOD".
+  try {
+    const raw = readFileSync("/sys/fs/cgroup/cpu.max", "utf-8").trim();
+    if (!raw.startsWith("max")) {
+      const parts = raw.split(/\s+/);
+      const quota = parseInt(parts[0], 10);
+      const period = parseInt(parts[1], 10);
+      if (!isNaN(quota) && !isNaN(period) && period > 0 && quota > 0) {
+        const cores = quota / period;
+        // Sanity check: if the value looks like the node's full CPU count
+        // and we're on a platform pod, it's likely gVisor leaking the host value.
+        if (cores < cpus().length * 0.9 || !getIsPlatform()) {
+          return cores;
+        }
+      }
+    }
+  } catch {
+    /* not available */
+  }
+
+  // 3. Try cgroups v1.
+  try {
+    const quota = parseInt(
+      readFileSync("/sys/fs/cgroup/cpu/cpu.cfs_quota_us", "utf-8").trim(),
+      10,
+    );
+    const period = parseInt(
+      readFileSync("/sys/fs/cgroup/cpu/cpu.cfs_period_us", "utf-8").trim(),
+      10,
+    );
+    if (!isNaN(quota) && !isNaN(period) && period > 0 && quota > 0) {
+      const cores = quota / period;
+      if (cores < cpus().length * 0.9 || !getIsPlatform()) {
+        return cores;
+      }
+    }
+  } catch {
+    /* not available */
+  }
+
+  return cpus().length || availableParallelism();
+}
+
+/**
+ * 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;
+}
+
 // Track CPU usage over a rolling window so /v1/health reports near-real-time
 // utilization instead of a lifetime average (total CPU time / total uptime).
 const CPU_SAMPLE_INTERVAL_MS = 5_000;
-let _lastCpuUsage: NodeJS.CpuUsage = process.cpuUsage();
+let _lastProcessCpuUsage: NodeJS.CpuUsage = process.cpuUsage();
+let _lastCgroupCpuUs: number | null = getContainerCpuUsageUs();
 let _lastCpuTime: number = Date.now();
 let _cachedCpuPercent = 0;
 
 // Kick off the background sampler. unref() so it never prevents process exit.
 setInterval(() => {
   const now = Date.now();
-  const newUsage = process.cpuUsage();
   const elapsedMs = now - _lastCpuTime;
-  if (elapsedMs > 0) {
-    const deltaCpuUs =
-      newUsage.user -
-      _lastCpuUsage.user +
-      (newUsage.system - _lastCpuUsage.system);
-    const deltaCpuMs = deltaCpuUs / 1000;
-    const numCores = cpus().length;
+  if (elapsedMs <= 0) return;
+
+  const numCores = getContainerCpuCores();
+
+  // 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 = process.cpuUsage();
+  const processDeltaUs =
+    newProcessUsage.user -
+    _lastProcessCpuUsage.user +
+    (newProcessUsage.system - _lastProcessCpuUsage.system);
+  _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) {
+      const deltaCpuUs = cgroupUs - _lastCgroupCpuUs;
+      const deltaCpuMs = deltaCpuUs / 1000;
+      _cachedCpuPercent =
+        Math.round((deltaCpuMs / (elapsedMs * numCores)) * 10000) / 100;
+    } else {
+      // cgroup CPU stats unavailable (e.g. gVisor) – fall back to process-level.
+      const deltaCpuMs = processDeltaUs / 1000;
+      _cachedCpuPercent =
+        Math.round((deltaCpuMs / (elapsedMs * numCores)) * 10000) / 100;
+    }
+    _lastCgroupCpuUs = cgroupUs;
+  } else {
+    // Non-platform: use process.cpuUsage() (accurate for single-process mode).
+    const deltaCpuMs = processDeltaUs / 1000;
     _cachedCpuPercent =
       Math.round((deltaCpuMs / (elapsedMs * numCores)) * 10000) / 100;
   }
-  _lastCpuUsage = newUsage;
+
   _lastCpuTime = now;
 }, CPU_SAMPLE_INTERVAL_MS).unref();
 
 function getCpuInfo(): CpuInfo {
   return {
     currentPercent: _cachedCpuPercent,
-    maxCores: cpus().length,
+    maxCores: Math.ceil(getContainerCpuCores()),
   };
 }
 

package/src/runtime/routes/log-export/AGENTS.md

@@ -0,0 +1,104 @@
+# Log Export — Workspace Allowlist Rules
+
+`POST /v1/export` (handled by `log-export-routes.ts`) builds a tar.gz archive
+from audit DB rows, daemon logs under `<workspace>/data/logs/`, and a
+sanitized `config.json` snapshot. This directory
+(`assistant/src/runtime/routes/log-export/`) houses the allowlist module
+that governs which subpaths of the user's workspace directory
+(`~/.vellum/workspace/`) are permitted to flow into that archive.
+
+Workspace contents are **opt-in (allowlist), not opt-out**. The workspace
+contains arbitrary user files — skills, hooks, routes, conversations,
+credentials scaffolding, and other material the user has authored or
+installed locally. Accidentally bundling any of that into a support
+archive would exfiltrate data the user never intended to share. The
+default must therefore be "nothing from the workspace ships" and each
+individual entry that _does_ ship must be justified against the rules
+below.
+
+## Rule 1 — Prefer time-filterable data
+
+Only allowlist a workspace subpath if its contents can be narrowed to the
+`[startTime, endTime]` window carried on the export request.
+
+- When the data is organized as per-record files or per-record
+  directories whose **names encode a timestamp**, filter by parsing the
+  name. The canonical example is the per-conversation directory layout
+  where each directory is named `<ISO-with-dashes>_<conversationId>`
+  (the ISO date comes first so ordinary lexicographic comparison yields
+  chronological order, and colons in the ISO string are replaced with
+  `-` so the name is filesystem-safe). A time filter can be implemented
+  by parsing the prefix and comparing it to `startTime` / `endTime`
+  without reading file contents.
+- When the relevant time information lives **only inside files**, the
+  allowlist entry should err on the side of **not** being included —
+  unless the file is small, rarely changes, and its full contents are
+  acceptable to ship regardless of the requested window.
+
+## Rule 2 — Prefer conversation-filterable data
+
+When the export request carries a `conversationId`, every allowlisted
+subpath should narrow itself to that conversation **if at all possible**.
+
+- Data that is intrinsically global (i.e. not associated with a single
+  conversation) is acceptable to include **only** when Rule 1 alone is
+  sufficient and the request has no `conversationId` filter.
+- When a `conversationId` _is_ set and an entry cannot be scoped to it,
+  prefer omitting the entry for that particular export rather than
+  shipping unrelated conversation data.
+
+The `<ISO-with-dashes>_<conversationId>` directory naming is again the
+motivating example: the suffix lets us select exactly one
+per-conversation directory without scanning file contents.
+
+## Rule 3 — Default deny
+
+Anything in the workspace that is not explicitly added to the allowlist
+module must remain excluded from the export archive. Adding a new entry
+requires, in the same PR:
+
+1. Updating the allowlist module in this directory to teach it about the
+   new subpath (including its time filter, conversation filter, and
+   size cap).
+2. Updating this `AGENTS.md` to record the entry name, which filters it
+   honors, and its size cap under `## Allowlisted entries`.
+
+Review must confirm both updates landed together. A workspace subpath
+that is not mentioned in the registry below is, by definition, not
+allowed in the export archive.
+
+## Rule 4 — Bounded size
+
+Every allowlisted entry must enforce a byte cap so that a misbehaving
+workspace (e.g. a runaway log, a giant attachment, a pathological skill)
+cannot blow up the archive and defeat the export endpoint.
+
+The current convention is **10 MB** across the workspace allowlist,
+mirroring `MAX_LOG_PAYLOAD_BYTES` in `log-export-routes.ts`. Entries
+should track the number of bytes already consumed and stop adding files
+once the cap would be exceeded, preferring to include the newest /
+most-relevant records first.
+
+## Allowlisted entries
+
+- **`conversations/`**
+  - **Path**: `<workspace>/conversations/<ISO-with-dashes>_<conversationId>/`
+  - **Honors filters**: time (union of parsed `createdAt` prefix _and_
+    per-message `ts` inside `messages.jsonl`) and `conversationId`
+    (exact match on the directory-name suffix — no substring matching).
+  - **Time semantics**: A conversation directory is included if EITHER
+    its `createdAt` (parsed from the directory name) falls in the
+    requested window OR `messages.jsonl` contains at least one message
+    whose `ts` falls in the window. The cheap directory-name check runs
+    first; the per-message scan only runs as a fallback when the cheap
+    check failed, so the common in-window case stays IO-free. This is
+    the "support bundle" union — false positives are cheaper than false
+    negatives because the user almost always wants the conversations
+    they were _active in_ during the window, not just the ones they
+    _started_ during it.
+  - **Cap**: shares the 10 MB workspace cap defined by
+    `MAX_WORKSPACE_PAYLOAD_BYTES` in `workspace-allowlist.ts`.
+  - **Notes**: Directory names that don't match the canonical
+    `<ISO-with-dashes>_<conversationId>` format are silently skipped
+    (Rule 3 — default deny). Legacy `<id>_<ISO>` directories are
+    intentionally excluded until they migrate to the canonical format.

package/src/runtime/routes/log-export/__tests__/workspace-allowlist-error-contract.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Regression test for the `result.entries` contract on `collectWorkspaceData`.
+ *
+ * Consumers and telemetry rely on `collectWorkspaceData` always returning at
+ * least one entry summary for the `conversations` allowlist entry — even when
+ * something throws partway through the candidate loop. This file pins that
+ * contract by mocking `parseConversationDirName` to return a malicious object
+ * whose `createdAtMs` getter throws. That throw escapes the inner per-iteration
+ * try/catch (it happens during sort + filter expression evaluation, not inside
+ * the wrapped parser call), bubbles up to the outer try/catch in
+ * `collectWorkspaceData`, and verifies that `result.entries` still contains
+ * exactly one `conversations` entry summary.
+ *
+ * Lives in its own file because `mock.module` is a global module override and
+ * we don't want it bleeding into the rest of the workspace-allowlist tests.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../../../memory/conversation-directories.js", () => ({
+  parseConversationDirName: (_name: string) => {
+    // Return an object whose `createdAtMs` accessor throws. This bypasses the
+    // inner try/catch wrapping `parseConversationDirName(name)` (which only
+    // catches synchronous throws from the call itself, not from later property
+    // accesses) and triggers the unwrapped sort/filter comparisons further
+    // down in `collectConversations`.
+    return {
+      conversationId: "evil",
+      get createdAtMs(): number {
+        throw new Error("simulated parser corruption");
+      },
+    };
+  },
+}));
+
+import { getConversationsDir } from "../../../../util/platform.js";
+import { collectWorkspaceData } from "../workspace-allowlist.js";
+
+let staging: string;
+
+beforeEach(() => {
+  // Fresh staging directory for each test.
+  const conversationsDir = getConversationsDir();
+  rmSync(conversationsDir, { recursive: true, force: true });
+  mkdirSync(conversationsDir, { recursive: true });
+
+  staging = join(
+    process.env.VELLUM_WORKSPACE_DIR ?? "/tmp",
+    "ws-allowlist-error-staging",
+  );
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+
+  // Seed a single canonical-looking dir so the loop has something to chew on.
+  const dirName = "2025-01-15T00-00-00.000Z_conv-jan15";
+  const dir = join(conversationsDir, dirName);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "meta.json"),
+    JSON.stringify({ name: dirName }),
+    "utf-8",
+  );
+});
+
+afterEach(() => {
+  try {
+    rmSync(staging, { recursive: true, force: true });
+  } catch {
+    /* best-effort cleanup */
+  }
+  try {
+    rmSync(getConversationsDir(), { recursive: true, force: true });
+  } catch {
+    /* best-effort cleanup */
+  }
+});
+
+describe("collectWorkspaceData — entry contract on unexpected error", () => {
+  test("synthesizes a conversations entry summary even when the loop throws", () => {
+    // The mocked parser returns a poisoned object whose `createdAtMs` accessor
+    // throws. The first read happens inside the time-filter checks in the
+    // candidate-collection loop, which is NOT wrapped in a per-iteration
+    // try/catch. The throw should propagate up to the outer try/catch in
+    // `collectWorkspaceData`, where it must be swallowed without dropping
+    // the entry summary.
+    const result = collectWorkspaceData({
+      staging,
+      // Force the time-filter branch to read `createdAtMs`.
+      startTime: 0,
+    });
+
+    // Contract: exactly one entry, named "conversations", regardless of error.
+    expect(result.entries).toHaveLength(1);
+    const [entry] = result.entries;
+    expect(entry.entry).toBe("conversations");
+    expect(entry.itemCount).toBe(0);
+    expect(entry.bytes).toBe(0);
+    expect(entry.skippedDueToCap).toBe(0);
+    expect(result.totalBytes).toBe(0);
+  });
+});