@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/util/platform.ts

@@ -1,6 +1,6 @@
-import { chmodSync, existsSync, mkdirSync, realpathSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, sep } from "node:path";
 
 import {
   AVATAR_IMAGE_FILENAME,
@@ -8,6 +8,7 @@ import {
   resolveAvatarDir,
 } from "@vellumai/avatar-manifest";
 import { SEEDS } from "@vellumai/environments";
+import { assertTestPathIsEphemeral as assertEphemeralInTests } from "@vellumai/environments/test-path-guard";
 
 import { getWorkspaceDirOverride } from "../config/env-registry.js";
 
@@ -54,6 +55,62 @@ export function isWindows(): boolean {
   return process.platform === "win32";
 }
 
+/**
+ * Per-user application data root: `~/Library/Application Support` on macOS,
+ * `%APPDATA%` on Windows, `$XDG_DATA_HOME` (default `~/.local/share`) elsewhere.
+ */
+export function getUserAppDataDir(): string {
+  if (isMacOS()) {
+    return join(homedir(), "Library", "Application Support");
+  }
+  if (isWindows()) {
+    return process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+  }
+  return process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+}
+
+/**
+ * Extra directories to prepend to PATH so daemon-spawned tools are found
+ * even when launched from a minimal environment (macOS .app bundle). Empty
+ * on Windows, where PATH already carries the installer-managed entries.
+ */
+export function getExtraToolPathDirs(): string[] {
+  if (isWindows()) {
+    return [];
+  }
+  return [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    join(homedir(), ".local", "bin"),
+  ];
+}
+
+/**
+ * Add missing `dirs` to the PATH entry of `env` in place, using the platform
+ * delimiter. Windows keys the variable as `Path`, so the existing key is
+ * matched case-insensitively rather than assuming `PATH`.
+ */
+export function addToPathEnv(
+  env: Record<string, string | undefined>,
+  dirs: string[],
+  position: "front" | "back" = "front",
+): void {
+  if (dirs.length === 0) {
+    return;
+  }
+  const key =
+    Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+  const entries = (env[key] ?? "").split(delimiter).filter(Boolean);
+  const missing = dirs.filter((d) => !entries.includes(d));
+  if (missing.length === 0) {
+    return;
+  }
+  env[key] =
+    position === "front"
+      ? [...missing, ...entries].join(delimiter)
+      : [...entries, ...missing].join(delimiter);
+}
+
 /**
  * Returns the raw platform string from Node.js (e.g. 'darwin', 'linux', 'win32').
  * Prefer this over accessing process.platform directly so all platform
@@ -341,78 +398,17 @@ export function getProcPidPath(name: string): string {
 //
 // 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;
-    }
-  }
-}
+// read and destructively write live state. The containment assertion is
+// shared with the gateway via @vellumai/environments/test-path-guard;
+// src/__tests__/assert-not-live-db.ts keeps its own containment check
+// because test machinery must not import production dependencies.
 
 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"),
-    );
-  }
+  assertEphemeralInTests(dir, {
+    // Shared with assertTestDbIsIsolated() in persistence/db-connection.ts.
+    allowEnvVar: "VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS",
+    runHint: "Run tests from the assistant package root.",
+  });
 }
 
 /**

package/src/util/process-table.ts

@@ -157,6 +157,7 @@ function runProcessTableCommand(
     cmd: command,
     stdout: "pipe",
     stderr: "ignore",
+    windowsHide: true,
   });
   if (result.exitCode !== 0) {
     throw new Error(
@@ -173,6 +174,7 @@ async function runProcessTableCommandAsync(
   const { stdout } = await execFileAsync(command[0], command.slice(1), {
     encoding: "utf8",
     maxBuffer: 8 * 1024 * 1024,
+    windowsHide: true,
   });
   return parser(stdout);
 }
@@ -229,6 +231,19 @@ export async function listProcessTableAsync(
   );
 }
 
+/**
+ * The process-table row for `pid`, or null when the process is gone or the
+ * table cannot be read. Callers get `ppid` alongside the command line, so
+ * ownership and identity can be decided from a single snapshot.
+ */
+function findProcessRow(pid: number): ProcessTableRow | null {
+  try {
+    return listProcessTable().find((row) => row.pid === pid) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export function readRawProcessCommand(pid: number): string | null {
   if (process.platform === "linux") {
     try {
@@ -241,9 +256,5 @@ export function readRawProcessCommand(pid: number): string | null {
     }
   }
 
-  try {
-    return listProcessTable().find((row) => row.pid === pid)?.command ?? null;
-  } catch {
-    return null;
-  }
+  return findProcessRow(pid)?.command ?? null;
 }

package/src/util/read-stdin.ts

@@ -25,3 +25,8 @@ export const STDIN_FD = 0;
 export function readStdinSync(encoding: BufferEncoding = "utf-8"): string {
   return readFileSync(STDIN_FD, encoding);
 }
+
+/** Read all data currently available on stdin as raw bytes. */
+export function readStdinBytesSync(): Buffer {
+  return readFileSync(STDIN_FD);
+}

package/src/util/spawn.ts

@@ -29,6 +29,7 @@ export function spawnWithTimeout(
     const proc = Bun.spawn(cmd, {
       stdout: "pipe",
       stderr: "pipe",
+      windowsHide: true,
       env: {
         ...process.env,
         PATH: [

package/src/util/sqlite3-runtime.ts

@@ -21,6 +21,10 @@
  */
 
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { isWindows } from "./platform.js";
 
 let cachedSqlite3Path: string | undefined | null;
 
@@ -37,11 +41,27 @@ export function findSqlite3(): string | undefined {
   // 1. Common install locations. We check these before `Bun.which` so we
   //    pick a deterministic, predictable binary even when PATH is
   //    unusual (e.g. a daemon launched with a stripped env).
-  for (const p of [
-    "/usr/bin/sqlite3",
-    "/usr/local/bin/sqlite3",
-    "/opt/homebrew/bin/sqlite3",
-  ]) {
+  const candidates = isWindows()
+    ? [
+        join(
+          process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"),
+          "Programs",
+          "sqlite",
+          "sqlite3.exe",
+        ),
+        join(
+          process.env.ProgramFiles ?? "C:\\Program Files",
+          "SQLite",
+          "sqlite3.exe",
+        ),
+        "C:\\sqlite\\sqlite3.exe",
+      ]
+    : [
+        "/usr/bin/sqlite3",
+        "/usr/local/bin/sqlite3",
+        "/opt/homebrew/bin/sqlite3",
+      ];
+  for (const p of candidates) {
     if (existsSync(p)) {
       cachedSqlite3Path = p;
       return p;

package/src/util/worker-ownership.ts

@@ -0,0 +1,193 @@
+/**
+ * Process-tree ownership for background worker processes.
+ *
+ * A worker's parent IS its owner. The process table is therefore the
+ * authoritative answer to "whose worker is this": unlike a PID file it
+ * survives a crash, and a second owner cannot overwrite it.
+ *
+ * Nothing here is specific to one worker kind. `listWorkerProcesses` matches
+ * on the absolute worker path the caller passes, and `classifyWorkerOwnership`
+ * takes injected liveness and PID-1 predicates, so any worker whose spawner
+ * knows its own PID can use both.
+ */
+
+import { listProcessTable, readRawProcessCommand } from "./process-table.js";
+
+export interface WorkerProcess {
+  pid: number;
+  ppid: number;
+}
+
+/**
+ * What this process may do with a worker it found in the process table.
+ *
+ * - `reclaim`: parented to us, a worker we started and lost track of. Reaping
+ *   it is what enforces one live worker per owning process.
+ * - `orphan`: reparented to init, or its owner is gone. Nobody else will ever
+ *   clean it up.
+ * - `foreign`: owned by another live process. The memory-worker process runs
+ *   its own backend against this same workspace and is entitled to its own
+ *   worker; signalling it is what made the two replace each other in a loop.
+ *
+ * A parent of PID 1 is ambiguous, and resolving it wrongly in either direction
+ * costs something real. `docker-entrypoint.sh` execs the daemon, so PID 1 can
+ * BE the daemon and its child a healthy sibling's worker. Under `docker run
+ * --init`, and on any host, PID 1 is an init process instead, so the same
+ * parentage means the owner died and the worker needs reclaiming. Callers
+ * therefore pass what PID 1 actually is rather than inferring it from whether
+ * the deployment is containerized, which is true in both container shapes.
+ */
+export type WorkerOwnership = "reclaim" | "orphan" | "foreign";
+
+export function classifyWorkerOwnership(
+  worker: WorkerProcess,
+  selfPid: number,
+  isOwnerAlive: (pid: number) => boolean,
+  pid1OwnsWorkers: boolean,
+): WorkerOwnership {
+  if (worker.ppid === selfPid) {
+    return "reclaim";
+  }
+  if (worker.ppid <= 1) {
+    return pid1OwnsWorkers ? "foreign" : "orphan";
+  }
+  if (!isOwnerAlive(worker.ppid)) {
+    return "orphan";
+  }
+  return "foreign";
+}
+
+/** The packaged daemon binary, with or without a Windows extension. */
+const PACKAGED_DAEMON_ARGV0 = /^vellum-daemon(\.exe)?$/i;
+
+/** The runtime the source daemon is launched under. */
+const BUN_ARGV0 = /^bun(\.exe)?$/i;
+
+/** The daemon entry script, as a whole trailing path segment pair. */
+const DAEMON_ENTRY_ARG = /(^|\/)daemon\/main\.(ts|js)$/;
+
+/**
+ * Split a command line into argv, keeping quoted paths whole.
+ *
+ * Splitting on whitespace first would shred the ordinary Windows install path
+ * `"C:\\Program Files\\Vellum\\...\\vellum-daemon.exe"` into `"C:\\Program` and
+ * make the packaged daemon unrecognisable, which is the very install this
+ * recovery path exists for. Separators are normalised per token so a caller
+ * can take a basename either way.
+ */
+function tokenizeCommandLine(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: string | null = null;
+  let started = false;
+
+  for (const ch of command) {
+    if (quote !== null) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (started) {
+        tokens.push(current);
+        current = "";
+        started = false;
+      }
+      continue;
+    }
+    current += ch;
+    started = true;
+  }
+  if (started) {
+    tokens.push(current);
+  }
+  return tokens.map((token) => token.replaceAll("\\", "/"));
+}
+
+/**
+ * Whether a command line is an assistant daemon, judged by argv shape rather
+ * than by substring.
+ *
+ * Two accepted shapes: the packaged binary as argv0 (which also covers the
+ * source daemon once `process.title` rewrites its argv), or bun as argv0 with
+ * the daemon entry script among its arguments.
+ *
+ * The shape matters because this authorises an irreversible signal. A
+ * substring test would accept any command line that merely mentions a
+ * `daemon/main` path, so an unrelated service, an editor, or a test runner
+ * holding a recycled PID would qualify. `cli/src/lib/orphan-detection.test.ts`
+ * already pins that exact collision (`node /opt/unrelated-service/daemon/main.ts`)
+ * as something we must not claim.
+ */
+export function isDaemonCommand(command: string | null): boolean {
+  if (command == null) {
+    return false;
+  }
+  const tokens = tokenizeCommandLine(command);
+  const argv0 = tokens[0]?.split("/").pop() ?? "";
+  if (PACKAGED_DAEMON_ARGV0.test(argv0)) {
+    return true;
+  }
+  if (!BUN_ARGV0.test(argv0)) {
+    return false;
+  }
+  return tokens.slice(1).some((token) => DAEMON_ENTRY_ARG.test(token));
+}
+
+/**
+ * Whether PID 1 is an assistant daemon rather than an init process.
+ *
+ * True only where the daemon was exec'd as PID 1 (`docker-entrypoint.sh`),
+ * which is what makes a worker parented to 1 a live sibling's rather than an
+ * orphan. Under `docker run --init` PID 1 is docker-init and under launchd or
+ * systemd it is the system init, so both answer false and PID-1 orphans stay
+ * reclaimable. Unreadable means false, which keeps the reclaiming behaviour.
+ *
+ * Callers that already hold a process-table snapshot pass PID 1's command line
+ * so this does not read the table a second time.
+ */
+export function pid1OwnsWorkers(pid1Command?: string | null): boolean {
+  if (process.pid === 1) {
+    return true;
+  }
+  return isDaemonCommand(
+    pid1Command === undefined ? readRawProcessCommand(1) : pid1Command,
+  );
+}
+
+/**
+ * Live worker processes matching `workerPath`, as `(pid, ppid)` pairs.
+ *
+ * `workerPath` is an absolute path unique to one worker of one install, so a
+ * sibling instance's workers never match. `model`, when given, must appear as
+ * a whole argv token rather than a substring, so a backend for `bge-small`
+ * cannot reclaim a live `bge-small-v2` worker.
+ *
+ * Raw command lines are read for matching only, never stored or logged:
+ * process arguments can carry secrets (see the redaction note in
+ * `util/process-tree.ts`).
+ */
+export function listWorkerProcesses(
+  workerPath: string,
+  model?: string,
+): WorkerProcess[] {
+  try {
+    return listProcessTable()
+      .filter(
+        (row) =>
+          row.command.includes(workerPath) &&
+          (!model || row.command.split(/\s+/).includes(model)),
+      )
+      .map(({ pid, ppid }) => ({ pid, ppid }));
+  } catch {
+    return [];
+  }
+}