vellum 0.2.13 → 0.3.2

package/src/tools/terminal/backends/docker.ts

@@ -1,372 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import { existsSync, realpathSync } from 'node:fs';
-import { dirname, resolve, relative, posix } from 'node:path';
-import { ToolError } from '../../../util/errors.js';
-import { getLogger } from '../../../util/logger.js';
-import type { DockerConfig } from '../../../config/types.js';
-import type { SandboxBackend, SandboxResult, WrapOptions } from './types.js';
-
-const log = getLogger('docker-sandbox');
-
-export const DEFAULT_SANDBOX_IMAGE = 'vellum-sandbox:latest';
-
-/**
- * Fallback defaults when DockerBackend is constructed without explicit config.
- * Must stay in sync with DockerConfigSchema defaults in config/schema.ts.
- */
-const DEFAULTS: Required<DockerConfig> = {
-  image: DEFAULT_SANDBOX_IMAGE,
-  shell: 'bash',
-  cpus: 1,
-  memoryMb: 512,
-  pidsLimit: 256,
-  network: 'none',
-};
-
-/**
- * Characters that are dangerous in Docker mount arguments or shell commands.
- * Commas are included because Docker's --mount flag uses them as field
- * delimiters — a path containing a comma could inject extra key=value pairs
- * (e.g. overriding dst= or src=) into the mount specification.
- */
-const UNSAFE_PATH_CHARS = /[\x00\n\r,]/;
-
-/**
- * Cache positive preflight results only, matching the bwrap pattern in native.ts.
- * Negative results are not cached so that installing/starting Docker after the
- * daemon starts takes effect without a restart.
- */
-let dockerCliAvailable = false;
-let dockerDaemonReachable = false;
-const imageAvailableCache = new Set<string>();
-const mountProbeCache = new Set<string>();
-/** Maps image → resolved shell path (e.g. 'bash' → 'bash', or fell back to 'sh'). */
-const shellResolvedCache = new Map<string, string>();
-
-/** Exported for tests to reset cached state between runs. */
-export function _resetDockerChecks(): void {
-  dockerCliAvailable = false;
-  dockerDaemonReachable = false;
-  imageAvailableCache.clear();
-  mountProbeCache.clear();
-  shellResolvedCache.clear();
-}
-
-function checkDockerCli(): void {
-  if (dockerCliAvailable) return;
-  try {
-    execFileSync('docker', ['--version'], { stdio: 'ignore', timeout: 5000 });
-    dockerCliAvailable = true;
-  } catch {
-    throw new ToolError(
-      'Docker CLI is not installed or not in PATH. Install Docker: https://docs.docker.com/get-docker/',
-      'bash',
-    );
-  }
-}
-
-function checkDockerDaemon(): void {
-  if (dockerDaemonReachable) return;
-  try {
-    execFileSync('docker', ['info'], { stdio: 'ignore', timeout: 10000 });
-    dockerDaemonReachable = true;
-  } catch {
-    throw new ToolError(
-      'Docker daemon is not running. Start Docker Desktop or run "sudo systemctl start docker".',
-      'bash',
-    );
-  }
-}
-
-/**
- * Resolve the path to Dockerfile.sandbox relative to this source file.
- * Works in both development (source layout) and bundled environments.
- *
- * In compiled Bun binaries, import.meta.dirname resolves into the virtual
- * $bunfs filesystem, so the Dockerfile won't exist there. Fall back to
- * looking next to the compiled binary (process.execPath) in that case.
- */
-function getSandboxDockerfilePath(): string {
-  const dir = import.meta.dirname ?? __dirname;
-  const sourcePath = resolve(dir, '../../../../Dockerfile.sandbox');
-
-  // In compiled Bun binaries, dir points into /$bunfs/ which is virtual.
-  // Fall back to looking next to the compiled binary itself.
-  if (!existsSync(sourcePath) && dir.startsWith('/$bunfs/')) {
-    return resolve(dirname(process.execPath), 'Dockerfile.sandbox');
-  }
-
-  return sourcePath;
-}
-
-function checkImageAvailable(image: string): void {
-  if (imageAvailableCache.has(image)) return;
-  try {
-    // Use execFileSync to avoid shell interpolation of the image name.
-    execFileSync('docker', ['image', 'inspect', image], { stdio: 'ignore', timeout: 10000 });
-    imageAvailableCache.add(image);
-    return;
-  } catch {
-    // Image not available locally — try to build or pull it.
-  }
-
-  // For the default sandbox image, build from Dockerfile.sandbox instead of pulling.
-  if (image === DEFAULT_SANDBOX_IMAGE) {
-    const dockerfile = getSandboxDockerfilePath();
-    if (existsSync(dockerfile)) {
-      log.info(`Building sandbox image "${image}" from ${dockerfile}...`);
-      try {
-        // --no-cache avoids stale apt-get layers with expired GPG signatures.
-        execFileSync('docker', ['build', '--no-cache', '-t', image, '-f', dockerfile, '.'], {
-          stdio: ['ignore', 'ignore', 'pipe'],
-          timeout: 120000,
-          cwd: resolve(dockerfile, '..'),
-        });
-        imageAvailableCache.add(image);
-        return;
-      } catch (err: unknown) {
-        const stderr = err instanceof Error && 'stderr' in err
-          ? String((err as { stderr: unknown }).stderr).trim()
-          : '';
-        const detail = stderr ? `\n\nBuild output:\n${stderr}` : '';
-        throw new ToolError(
-          `Failed to build sandbox image "${image}" from ${dockerfile}. ` +
-          'Check Docker is running and try building manually: ' +
-          `docker build --no-cache -t ${image} -f ${dockerfile} ${resolve(dockerfile, '..')}` +
-          detail,
-          'bash',
-        );
-      }
-    }
-
-    // Dockerfile not found — can't build the local-only image and pulling won't work.
-    throw new ToolError(
-      `Cannot find Dockerfile.sandbox to build "${image}". ` +
-      'This image is built locally and is not available from a registry. ' +
-      'If you have the Vellum source tree, build it manually:\n' +
-      '  docker build --no-cache -t vellum-sandbox:latest -f assistant/Dockerfile.sandbox assistant\n' +
-      'Or set sandbox.docker.image to a different image in your config.',
-      'bash',
-    );
-  }
-
-  log.info(`Docker image "${image}" not found locally, pulling...`);
-  try {
-    execFileSync('docker', ['pull', image], { stdio: 'ignore', timeout: 120000 });
-    imageAvailableCache.add(image);
-  } catch {
-    throw new ToolError(
-      `Failed to pull Docker image "${image}". Check your network connection or pull it manually: docker pull ${image}`,
-      'bash',
-    );
-  }
-}
-
-function checkMountProbe(sandboxRoot: string, image: string): void {
-  const cacheKey = `${sandboxRoot}\0${image}`;
-  if (mountProbeCache.has(cacheKey)) return;
-  try {
-    execFileSync(
-      'docker',
-      [
-        'run', '--rm',
-        '--mount', `type=bind,src=${sandboxRoot},dst=/workspace`,
-        image, 'test', '-w', '/workspace',
-      ],
-      { stdio: 'ignore', timeout: 15000 },
-    );
-    mountProbeCache.add(cacheKey);
-  } catch {
-    throw new ToolError(
-      'Cannot bind-mount the sandbox root into a Docker container or /workspace is not writable. ' +
-      'If using Docker Desktop, enable file sharing for this path in Settings > Resources > File Sharing.',
-      'bash',
-    );
-  }
-}
-
-/**
- * Verify the configured shell exists in the image.  If the requested shell
- * (e.g. 'bash') is missing, fall back to 'sh' which is available on virtually
- * every Linux image.  If neither exists the image is too minimal to use.
- */
-function resolveShell(image: string, shell: string): string {
-  const cacheKey = `${image}\0${shell}`;
-  const cached = shellResolvedCache.get(cacheKey);
-  if (cached) return cached;
-
-  // Try the configured shell first.
-  try {
-    execFileSync('docker', ['run', '--rm', image, shell, '-c', 'true'], {
-      stdio: 'ignore',
-      timeout: 15000,
-    });
-    shellResolvedCache.set(cacheKey, shell);
-    return shell;
-  } catch {
-    // configured shell not available — try sh fallback
-  }
-
-  if (shell === 'sh') {
-    throw new ToolError(
-      `Shell "sh" is not available in Docker image "${image}". The image may be too minimal for sandbox use.`,
-      'bash',
-    );
-  }
-
-  try {
-    execFileSync('docker', ['run', '--rm', image, 'sh', '-c', 'true'], {
-      stdio: 'ignore',
-      timeout: 15000,
-    });
-    log.warn(`Shell "${shell}" not found in image "${image}", falling back to "sh"`);
-    shellResolvedCache.set(cacheKey, 'sh');
-    return 'sh';
-  } catch {
-    throw new ToolError(
-      `Neither "${shell}" nor "sh" is available in Docker image "${image}". ` +
-      'Choose a different image or set sandbox.docker.shell to a shell that exists in the image.',
-      'bash',
-    );
-  }
-}
-
-/**
- * Validate that a path is safe to use in Docker mount arguments.
- * Rejects paths containing null bytes, newlines, or carriage returns which
- * could cause argument injection or parsing issues.
- */
-function validatePathSafety(path: string, label: string): void {
-  if (UNSAFE_PATH_CHARS.test(path)) {
-    throw new ToolError(
-      `${label} contains characters that are unsafe for Docker mount arguments. ` +
-      'Refusing to execute. Remove null bytes, newlines, carriage returns, or commas from the path.',
-      'bash',
-    );
-  }
-}
-
-/**
- * Docker sandbox backend that wraps commands in ephemeral containers.
- *
- * Each invocation produces a single `docker run --rm` command — no long-lived
- * container state. The sandbox filesystem root is bind-mounted to /workspace
- * and the host UID:GID is forwarded to prevent permission drift.
- *
- * On first use, runs preflight checks (CLI, daemon, image, mount probe) and
- * fails closed with actionable error messages if any check fails.
- */
-export class DockerBackend implements SandboxBackend {
-  private readonly sandboxRoot: string;
-  private readonly config: Required<DockerConfig>;
-  private readonly uid: number;
-  private readonly gid: number;
-
-  constructor(
-    sandboxRoot: string,
-    config?: Partial<Required<DockerConfig>>,
-    uid?: number,
-    gid?: number,
-  ) {
-    // Resolve to an absolute path first, then follow symlinks.
-    // This prevents path traversal via ../.. or symlink tricks.
-    const resolved = resolve(sandboxRoot);
-    this.sandboxRoot = realpathSync(resolved);
-    validatePathSafety(this.sandboxRoot, 'Sandbox root');
-    this.config = { ...DEFAULTS, ...config };
-    if (uid != null) {
-      this.uid = uid;
-    } else if (process.getuid) {
-      this.uid = process.getuid();
-    } else {
-      throw new ToolError(
-        'Docker sandbox requires POSIX UID/GID APIs (process.getuid/getgid) which are not available on this platform.',
-        'bash',
-      );
-    }
-    this.gid = gid ?? (process.getgid ? process.getgid() : this.uid);
-  }
-
-  /**
-   * Run preflight checks in dependency order. Each check is cached
-   * on success; failures re-check on every call.  Returns the resolved
-   * shell (may differ from config if the configured shell is missing).
-   */
-  preflight(): string {
-    checkDockerCli();
-    checkDockerDaemon();
-    checkImageAvailable(this.config.image);
-    checkMountProbe(this.sandboxRoot, this.config.image);
-    return resolveShell(this.config.image, this.config.shell);
-  }
-
-  wrap(command: string, workingDir: string, options?: WrapOptions): SandboxResult {
-    // Preflight: fail closed if Docker is not usable.
-    const shell = this.preflight();
-
-    // Resolve + follow symlinks for the working directory.
-    const resolved = resolve(workingDir);
-    const realWorkDir = realpathSync(resolved);
-    const realRoot = this.sandboxRoot;
-
-    // Validate path safety for mount/workdir args.
-    validatePathSafety(realWorkDir, 'Working directory');
-
-    // Fail closed: working dir must be inside sandbox root.
-    if (!realWorkDir.startsWith(realRoot + '/') && realWorkDir !== realRoot) {
-      log.error(
-        'Working directory is outside sandbox root — refusing to execute',
-      );
-      throw new ToolError(
-        'Working directory is outside the sandbox root. Refusing to execute.',
-        'bash',
-      );
-    }
-
-    // Map host working dir to container path under /workspace.
-    const relPath = relative(realRoot, realWorkDir);
-    const containerWorkDir =
-      relPath === '' ? '/workspace' : posix.join('/workspace', relPath);
-
-    const { image, cpus, memoryMb, pidsLimit, network } = this.config;
-
-    // Per-invocation network override: proxied mode needs bridge networking
-    // so the container can reach the proxy on the host. Default ('off' or
-    // undefined) preserves the config-level network setting.
-    const effectiveNetwork =
-      options?.networkMode === 'proxied' ? 'bridge' : network;
-
-    // Every flag is a separate argv segment — no shell interpolation occurs.
-    const args: string[] = [
-      'run',
-      '--rm',
-      `--network=${effectiveNetwork}`,
-      // When proxied, map host.docker.internal to the host machine so the
-      // container can reach the proxy daemon listening on the host loopback.
-      ...(options?.networkMode === 'proxied'
-        ? ['--add-host=host.docker.internal:host-gateway']
-        : []),
-      `--cpus=${cpus}`,
-      `--memory=${memoryMb}m`,
-      `--pids-limit=${pidsLimit}`,
-      '--cap-drop=ALL',
-      '--security-opt=no-new-privileges',
-      // Read-only container root prevents writes outside explicit mounts.
-      '--read-only',
-      // Writable tmpfs for /tmp — required for shell behavior, temp files, etc.
-      '--tmpfs', '/tmp:rw,nosuid,nodev,noexec',
-      '--mount',
-      `type=bind,src=${realRoot},dst=/workspace`,
-      '--workdir',
-      containerWorkDir,
-      '--user',
-      `${this.uid}:${this.gid}`,
-      image,
-      shell,
-      '-c',
-      command,
-    ];
-
-    return { command: 'docker', args, sandboxed: true };
-  }
-}

package/src/tools/terminal/backends/native.ts

@@ -1,190 +0,0 @@
-import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { execSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { join } from 'node:path';
-import { isMacOS, isLinux } from '../../../util/platform.js';
-import { ToolError } from '../../../util/errors.js';
-import { getLogger } from '../../../util/logger.js';
-import type { SandboxBackend, SandboxResult } from './types.js';
-
-const log = getLogger('sandbox');
-
-const HASH_DISPLAY_LENGTH = 12;
-
-/**
- * macOS sandbox-exec profile that restricts shell commands:
- * - Denies all by default
- * - Allows read access to most of the filesystem (needed for toolchains)
- * - Allows write access only to the working directory and temp dirs
- * - Blocks outbound network access
- * - Blocks process debugging (ptrace)
- *
- * The WORKING_DIR placeholder is replaced at runtime with the actual
- * working directory path.
- */
-const SANDBOX_PROFILE = `
-(version 1)
-(deny default)
-
-;; Allow read access to the filesystem (tools, libraries, etc.)
-(allow file-read*)
-
-;; Allow write access to the working directory and its children
-(allow file-write*
-  (subpath "__WORKING_DIR__")
-  (subpath "/private/tmp")
-  (subpath "/tmp")
-  (subpath "/var/folders"))
-
-;; Allow process execution (needed to run commands)
-(allow process-exec*)
-(allow process-fork)
-
-;; Allow signal delivery between parent and child
-(allow signal (target others))
-
-;; Allow sysctl reads (needed by many tools)
-(allow sysctl-read)
-
-;; Allow mach lookups (IPC, needed for basic process operation)
-(allow mach-lookup)
-(allow mach-register)
-
-;; Allow IOKit (needed for some system calls)
-(allow iokit-open)
-
-;; Block network access
-(deny network*)
-
-;; Block process debugging
-(deny process-info-pidinfo (target others))
-`.trim();
-
-/** Characters that are meaningful in SBPL syntax and must not appear in paths. */
-const SBPL_UNSAFE = /["()\\;\n\r]/;
-
-/**
- * Validate that a path is safe to embed in an SBPL profile string.
- * Returns true if the path contains no SBPL metacharacters.
- */
-function isSafeForSBPL(path: string): boolean {
-  return !SBPL_UNSAFE.test(path);
-}
-
-/**
- * Get the path to the sandbox profile file, creating it if needed.
- *
- * Each distinct working directory gets its own profile file (keyed by
- * a hash of the path) to avoid race conditions when concurrent commands
- * use different working directories.
- */
-function getProfilePath(workingDir: string): string {
-  const dir = join(process.env.HOME ?? '/tmp', '.vellum');
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const hash = createHash('sha256').update(workingDir).digest('hex').slice(0, HASH_DISPLAY_LENGTH);
-  const path = join(dir, `sandbox-profile-${hash}.sb`);
-
-  const profile = SANDBOX_PROFILE.replace(/__WORKING_DIR__/g, workingDir);
-  writeFileSync(path, profile + '\n');
-  return path;
-}
-
-/**
- * Cache positive bwrap results only. Negative results are not cached so that
- * installing bwrap after the daemon starts takes effect without a restart.
- */
-let bwrapAvailable = false;
-
-/**
- * Check whether bwrap is installed AND functional (can create namespaces).
- *
- * Just testing `bwrap --version` is not enough — the binary may exist but
- * namespace creation can be blocked by the kernel (e.g. inside containers
- * or when user namespaces are disabled). We run a minimal sandbox that
- * exercises all namespace types used by buildBwrapArgs() (mount, network,
- * PID) to verify end-to-end functionality.
- *
- * Only positive results are cached — if bwrap is unavailable, we re-check
- * on every call so that a mid-session install is picked up immediately.
- */
-function isBwrapAvailable(): boolean {
-  if (bwrapAvailable) return true;
-  try {
-    execSync('bwrap --ro-bind / / --unshare-net --unshare-pid true', { stdio: 'ignore', timeout: 5000 });
-    bwrapAvailable = true;
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Build bwrap arguments for Linux sandboxing.
- *
- * Strategy mirrors the macOS sandbox-exec profile:
- * - Read-only bind-mount of the root filesystem (toolchains, libs, etc.)
- * - Read-write bind-mount of the working directory
- * - Read-write tmpfs for /tmp
- * - /proc mounted for basic process operation
- * - /dev bind-mounted for device access (needed by many tools)
- * - Network access blocked (--unshare-net)
- * - PID namespace isolated (--unshare-pid)
- */
-function buildBwrapArgs(workingDir: string, command: string): string[] {
-  return [
-    // Filesystem: read-only root, writable working dir and temp
-    '--ro-bind', '/', '/',
-    '--bind', workingDir, workingDir,
-    '--bind', '/tmp', '/tmp',
-    '--dev', '/dev',
-    '--proc', '/proc',
-    // Isolation
-    '--unshare-net',
-    '--unshare-pid',
-    // Run bash inside the sandbox
-    'bash', '-c', '--', command,
-  ];
-}
-
-/**
- * Native sandbox backend using OS-level sandboxing:
- * macOS sandbox-exec (SBPL profiles) and Linux bwrap (bubblewrap).
- */
-export class NativeBackend implements SandboxBackend {
-  wrap(command: string, workingDir: string, _options?: import('./types.js').WrapOptions): SandboxResult {
-    if (isMacOS()) {
-      if (!isSafeForSBPL(workingDir)) {
-        throw new ToolError(
-          `Sandbox is enabled but the working directory contains characters unsafe for the sandbox profile (SBPL metacharacters). ` +
-          `Refusing to execute unsandboxed. Change to a directory without special characters in its path, or disable sandboxing.`,
-          'bash',
-        );
-      }
-      const profile = getProfilePath(workingDir);
-      return {
-        command: 'sandbox-exec',
-        args: ['-f', profile, 'bash', '-c', '--', command],
-        sandboxed: true,
-      };
-    }
-
-    if (isLinux()) {
-      if (!isBwrapAvailable()) {
-        const msg = 'Sandbox is enabled but bwrap is not available or cannot create namespaces. Refusing to execute unsandboxed. Install bubblewrap (for example: apt install bubblewrap), or disable sandboxing.';
-        log.error(msg);
-        throw new ToolError(msg, 'bash');
-      }
-      return {
-        command: 'bwrap',
-        args: buildBwrapArgs(workingDir, command),
-        sandboxed: true,
-      };
-    }
-
-    const msg = `Sandbox is enabled but not supported on this platform (${process.platform}). Refusing to execute unsandboxed. Disable sandboxing to run shell commands.`;
-    log.error(msg);
-    throw new ToolError(msg, 'bash');
-  }
-}

package/src/tools/terminal/backends/types.ts

@@ -1,26 +0,0 @@
-export interface SandboxResult {
-  /** The command/args to use for spawning. */
-  command: string;
-  args: string[];
-  /** Whether sandboxing was applied. */
-  sandboxed: boolean;
-}
-
-/** Per-invocation options that override backend defaults. */
-export interface WrapOptions {
-  /**
-   * Network mode for this invocation.
-   * - 'off': no container network (--network=none). This is the default.
-   * - 'proxied': bridge network so the container can reach a host proxy (--network=bridge).
-   */
-  networkMode?: 'off' | 'proxied';
-}
-
-/**
- * A sandbox backend knows how to wrap a shell command so it runs
- * inside an OS-level sandbox (macOS sandbox-exec, Linux bwrap, Docker, etc.).
- */
-export interface SandboxBackend {
-  /** Wrap a command for sandboxed execution in the given working directory. */
-  wrap(command: string, workingDir: string, options?: WrapOptions): SandboxResult;
-}