Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
21.8 KB
Raw Blame
// Ported from the CLI (omnirush-cli src/box/backends/bwrap.js,
// feat/local-box-backends); keep the two in step. Desktop differences: types;
// the one-time admin step is the app's "Allow the sandbox" (setup.ts, pkexec)
// or the CLI's `sudo omnirush sandbox enable`, and the AppArmor reason names
// both; boxrun missing from the sidecars is a reason, not a path.
//
// The bubblewrap backend (Linux; also what runs inside the OmniRush WSL
// distro): no daemon, no root, nothing to install where unprivileged user
// namespaces work. `boxrun` (box/go/cmd/boxrun) pulls the pinned image and
// unpacks it (~/.omnirush/box/bwrap/store), and runs each project's box as
// that root filesystem under a per-project overlay upper layer
// (~/.omnirush/box/bwrap/boxes/<key>), in its own user, mount, PID, IPC and
// UTS namespaces, on the host's network (farm runs: boxd runs the agent's commands in a network of
// their own with only the package registries reachable, box/go/cmd/boxd/egress.go). The upper layer stays on disk, so
// installs survive restarts; boxd is the same helper the containers run.
//
// Ubuntu 23.10+ blocks unprivileged user namespaces through AppArmor
// (kernel.apparmor_restrict_unprivileged_userns=1): the probe says so in one
// line and the next backend (rootless Podman, Docker) is used.

import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
import os from "node:os";
import path from "node:path";

import { GOARCH, RUN_DIR, SHIMS_DIR, containerName, containerRoot, helperPath, newToken, readJson, writeJson, type BoxInstallLog, type BoxRuntime } from "../common.js";
import { REQUIRED_RULES, shadowId, type ShadowPlan } from "../required.js";
import { farmRun } from "../../stock-mode/stock-mode.mjs";
import { runCommand, type RunCommand, type RunOptions } from "../run.js";
import type { RuntimeResult } from "../runtime.js";
import { YOUNG_IMAGE_MS, removableImage, removeTree, staleEntries } from "../retention.mjs";
import { boxshExec, num, parseOut, str } from "./shared.js";
import type { BoxDriver, ListedBox, OpenContext, Opened, PresentImage, Removed } from "./types.js";

export { parseOut } from "./shared.js";

type Env = NodeJS.ProcessEnv;

/** Where `sudo omnirush sandbox enable` (the CLI) puts OmniRush's bwrap (root-owned, profiled). */
export const ENABLED_BWRAP = "/usr/local/lib/omnirush/bwrap";
export const APPARMOR_PROFILE = "/etc/apparmor.d/omnirush-bwrap";
/** boxd exits (and the box with it) after this long with no request. */
export const IDLE_MINUTES = 120;

export function bwrapHome(home: string): string {
  return path.join(home, "bwrap");
}
const storeDir = (home: string) => path.join(bwrapHome(home), "store");
const boxDir = (home: string, key: string) => path.join(bwrapHome(home), "boxes", key);
const metaFile = (home: string, key: string) => path.join(bwrapHome(home), "boxes", `${key}.json`);

/** A box's own record (boxes/<key>.json under the backend's folder). */
export type BoxMeta = {
  v: 1; key: string; root: string; croot: string; image: string; arch: string; ref: string; pull: string; digest: string | null;
  config?: string; stack: string; token: string; instance: string; created_at: string; mounts?: string[];
};

/** boxrun for this machine's architecture (inside a box: linux/<arch>); null when this install has none. */
export function boxrunPath({ env = process.env, arch = process.arch }: { env?: Env; arch?: string } = {}): string | null {
  return helperPath("boxrun", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });
}

/**
 * The bwraps to try, best first ({ path, source }): OMNIRUSH_BOX_BWRAP alone
 * when set; else the root-owned copy `sandbox enable` (or the app's "Allow
 * the sandbox") installed, which AppArmor allows; the system's (a
 * distribution keeps it patched); then the static one shipped with OmniRush
 * (Linux builds: a system without bubblewrap, or whose own cannot start a
 * box). CLI: bwrapCandidates, the same order.
 */
export function bwrapCandidates({ env = process.env, arch = process.arch, exists = existsSync }: { env?: Env; arch?: string; exists?: (file: string) => boolean } = {}): Array<{ path: string; source: "env" | "enabled" | "system" | "bundled" }> {
  const asked = String(env.OMNIRUSH_BOX_BWRAP || "").trim();
  if (asked) return [{ path: asked, source: "env" }];
  const out: Array<{ path: string; source: "env" | "enabled" | "system" | "bundled" }> = [];
  if (exists(ENABLED_BWRAP)) out.push({ path: ENABLED_BWRAP, source: "enabled" });
  const dirs = [...String(env.PATH || "").split(":").filter(Boolean), "/usr/bin", "/usr/local/bin", "/bin"];
  const system = dirs.map((dir) => path.posix.join(dir, "bwrap")).find((file) => file !== ENABLED_BWRAP && exists(file));
  if (system) out.push({ path: system, source: "system" });
  const shipped = helperPath("bwrap", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });
  if (shipped && exists(shipped)) out.push({ path: shipped, source: "bundled" });
  return out;
}

/** The first bwrap to try (null: none here; boxrun looks on PATH). */
export function bwrapPath(options: { env?: Env; arch?: string; exists?: (file: string) => boolean } = {}): string | null {
  return bwrapCandidates(options)[0]?.path ?? null;
}

/** One line for each reason boxrun's probe gives. */
export function explainProbe(out: Record<string, unknown> | null): string {
  const reason = str(out?.reason) || "bubblewrap could not start";
  switch (out?.code) {
    case "apparmor":
      return `${reason}; one-time admin fix: Allow the sandbox (one password prompt), or \`sudo omnirush sandbox enable\` (OmniRush CLI)`;
    case "no_bwrap":
      return `${reason} (\`sudo apt install bubblewrap\` or your system's package)`;
    case "userns_off":
      return `${reason}; an admin can allow them, or use Podman or Docker`;
    case "container":
      return `${reason}; run OmniRush on the host, or give this container a Docker or Podman engine`;
    default:
      return reason;
  }
}

/** Can boxes run here with bubblewrap? A real start (5–20 ms), never a guess from the distro. */
export async function probeBwrap({ env = process.env, boxHome, run = runCommand, timeoutMs = 6_000, arch = process.arch, exists = existsSync, platform = process.platform }: { env?: Env; boxHome: string; run?: RunCommand; timeoutMs?: number; arch?: string; exists?: (file: string) => boolean; platform?: NodeJS.Platform }): Promise<RuntimeResult> {
  const base = { name: "bwrap", backend: "bwrap" };
  if (platform !== "linux") return { ...base, ok: false, reason: "bubblewrap is Linux only" };
  const bin = boxrunPath({ env, arch });
  if (!bin || !exists(bin)) return { ...base, ok: false, ...(bin ? { bin } : {}), reason: "the sandbox helper boxrun is missing from this install" };
  try { mkdirSync(boxHome, { recursive: true }); } catch { /* the probe says */ }
  const candidates = bwrapCandidates({ env, arch, exists });
  const failures: Array<RuntimeResult & { ok: false }> = [];
  // Each bwrap in order until one starts a box; none anywhere: boxrun still looks on PATH and says "not installed".
  for (const candidate of candidates.length ? candidates : [null]) {
    const args = ["probe", "--dir", boxHome];
    if (candidate) args.push("--bwrap", candidate.path);
    const res = await run(bin, args, { env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" }, timeoutMs });
    const out = parseOut(res.stdout);
    if (!out) {
      failures.push({ ...base, ok: false, bin, reason: res.error === "timeout" ? "the bubblewrap probe did not answer in time" : `boxrun probe failed: ${String(res.stderr || "").trim().slice(0, 200)}` });
      continue;
    }
    if (!out.ok) {
      failures.push({ ...base, ok: false, bin, code: str(out.code), reason: explainProbe(out) });
      continue;
    }
    return {
      ...base, ok: true, bin, bwrap: str(out.bwrap) || candidate?.path || null,
      version: str(out.bwrap_version),
      os: "linux", arch: GOARCH[arch] || arch,
      flavor: out.overlay === "fuse" ? "fuse-overlayfs" : "overlayfs",
      idmap: str(out.idmap) || "single", launcher: str(out.launcher) || "bwrap",
      rootless: !out.root, vm: false, kernel: str(out.kernel) || os.release(),
    };
  }
  // AppArmor's answer when that is what blocks them (one admin step fixes it), else the first one's.
  return failures.find((failure) => failure.code === "apparmor") ?? failures[0] ?? { ...base, ok: false, bin, reason: "bubblewrap could not start" };
}

function storeArgs(home: string): string[] {
  return ["--store", storeDir(home)];
}

function presentOf(out: Record<string, unknown> | null): PresentImage | null {
  if (!out?.present) return null;
  return { id: str(out.id), digest: str(out.digest) || null, arch: str(out.arch), config: str(out.config) };
}

async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "" }: { run?: RunCommand; home?: string } = {}): Promise<PresentImage | null> {
  const res = await run(runtime.bin, ["image", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 15_000 });
  return presentOf(parseOut(res.stdout));
}

/** `onLine`: boxrun's output lines as they come (its progress, for a progress line). */
async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "", onLine }: { run?: RunCommand; home?: string; onLine?: RunOptions["onLine"] } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
  const res = await run(runtime.bin, ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 60 * 60_000, ...(onLine ? { onLine } : {}) });
  const out = parseOut(res.stdout);
  return out?.ok ? { ok: true } : { ok: false, error: String(out?.error || res.stderr || `boxrun pull exited ${res.code}`).slice(0, 300) };
}

/**
 * The box's egress: "farm" in farm runs (an asked OMNIRUSH_FARM, stock-mode.mjs farmRun; not an event's stock mode): boxd gives the agent's commands no internet
 * but the package registries (box/go/cmd/boxd/egress.go). null: the box's network as is. CLI: the same.
 */
export function boxEgress(env: Env = process.env): "farm" | null {
  return farmRun(env) ? "farm" : null;
}

/** boxd's environment in a box (what `docker create -e` gives the containers). */
export function boxdEnv({ token, croot, idleMinutes = IDLE_MINUTES, listen = "127.0.0.1:0", egress = null }: { token: string; croot: string; idleMinutes?: number; listen?: string; egress?: string | null }): string[] {
  return [
    `BOXD_TOKEN=${token}`, "BOXD_UID=0", "BOXD_GID=0", "BOXD_HOME=/root", `BOXD_ROOT=${croot}`,
    `BOXD_ENV_FILE=${RUN_DIR}/env`, `BOXD_LISTEN=${listen}`, `BOXD_PORT_FILE=${RUN_DIR}/boxd.port`, `BOXD_IDLE_EXIT=${idleMinutes}`,
    "LANG=C.UTF-8", "DEBIAN_FRONTEND=noninteractive",
    ...(egress ? [`BOXD_EGRESS=${egress}`] : []),
  ];
}

/** The folders boxd may shadow mid-chat (required.json shadows.binds, even_if_absent), with their plain file markers. CLI: the same. */
export function lazyShadowRules(): Array<{ dir: string; markers: string[] }> {
  return REQUIRED_RULES.shadows.binds
    .filter((rule) => rule.even_if_absent)
    .map((rule) => ({ dir: rule.dir, markers: rule.when_any.filter((m) => !/[/@*?[,]/.test(m)) }))
    .filter((rule) => rule.markers.length > 0);
}

/** `boxrun up` arguments for a project's box. */
export function upArgs({ box, store, image, boxd, portFile, root, croot, runFolder, shims = null, pkglog = null, token, bwrap = null, idleMinutes = IDLE_MINUTES, listen, platform = "linux", mapPath = (p: string) => p, shadows = null, shadowStore = null, egress = null }: { box: string; store: string; image: string; boxd: string; portFile: string; root: string; croot: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; bwrap?: string | null; idleMinutes?: number; listen?: string; platform?: NodeJS.Platform; mapPath?: (p: string) => string; shadows?: Pick<ShadowPlan, "binds"> | null; shadowStore?: string | null; egress?: string | null }): string[] {
  const args = ["up", "--box", box, "--store", store, "--image", image, "--boxd", boxd, "--port-file", portFile,
    "--bind", `${mapPath(root)}=${croot}`, "--bind", `${mapPath(runFolder)}=${RUN_DIR}`];
  if (shims) args.push("--ro-bind", `${mapPath(shims)}=${SHIMS_DIR}-src`);
  if (pkglog) args.push("--bind", `${mapPath(pkglog.root)}=${containerRoot(pkglog.root, platform)}`);
  for (const kv of boxdEnv({ token, croot, idleMinutes, egress, ...(listen ? { listen } : {}) })) args.push("--env", kv);
  if (bwrap) args.push("--bwrap", bwrap);
  // The box's own build folders (required.ts shadowPlan; backends whose boxrun runs as root):
  // the per-box store on the backend's own disk, and each folder bound from it (boxrun init Binds).
  if (shadows && shadowStore) {
    args.push("--shadow-store", shadowStore);
    for (const bind of shadows.binds ?? []) args.push("--shadow", `${bind.id ?? shadowId(bind.path)}=${bind.target}`);
    // What boxd may shadow mid-chat (required.json): boxrun removes such a folder after a kill only when it fits these.
    if (shadows.binds?.length) for (const rule of lazyShadowRules()) args.push("--shadow-lazy", `${rule.dir}=${rule.markers.join(",")}`);
  }
  return args;
}

/** A new box's own record. */
export function newMeta({ key, root, croot, present, image }: { key: string; root: string; croot: string; present: PresentImage; image: { ref: string; pull: string; digest: string | null; stack: string } }): BoxMeta {
  return { v: 1, key, root, croot, image: present.id, arch: present.arch, ref: image.ref, pull: image.pull, digest: image.digest || present.digest, ...(present.config ? { config: present.config } : {}), stack: image.stack, token: newToken(), instance: newToken().slice(0, 12), created_at: new Date().toISOString() };
}

async function open(ctx: OpenContext): Promise<Opened> {
  const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling, onLine } = ctx;
  const file = metaFile(home, key);
  let meta = readJson<BoxMeta>(file);
  if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };
  let created = null;
  if (!meta || !existsSync(boxDir(home, key))) {
    let present = await imagePresent(runtime, image, { run, home });
    if (!present) {
      if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };
      onPulling();
      const pulled = await pull(runtime, image, { run, home, onLine });
      if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };
      present = await imagePresent(runtime, image, { run, home });
      if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
    }
    meta = newMeta({ key, root, croot, present, image });
    mkdirSync(path.dirname(file), { recursive: true });
    writeJson(file, meta);
    created = { ref: image.ref, pull: image.pull, digest: meta.digest, id: present.config || present.id, stack: image.stack };
    log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "bwrap" });
  }
  const boxd = helperPath("boxd", { goos: "linux", goarch: GOARCH[meta.arch] || runtime.arch || "amd64", env });
  if (!boxd) return { ok: false, error: "the sandbox helper boxd is missing from this install" };
  const portFile = path.join(runFolder, "boxd.port");
  const idle = Number(env.OMNIRUSH_BOX_IDLE_MIN) > 0 ? Number(env.OMNIRUSH_BOX_IDLE_MIN) : IDLE_MINUTES;
  const args = upArgs({ box: boxDir(home, key), store: storeDir(home), image: meta.image, boxd, portFile, root, croot, runFolder, shims, pkglog, token: meta.token, bwrap: runtime.bwrap ?? null, idleMinutes: idle, egress: boxEgress(env) });
  // OMNIRUSH_BOX_OVERLAY=fuse: fuse-overlayfs only (a kernel without overlayfs in user namespaces, or a test of one).
  if (String(env.OMNIRUSH_BOX_OVERLAY || "").toLowerCase() === "fuse") args.push("--overlay", "fuse");
  const res = await run(runtime.bin, args, { timeoutMs: 45_000, env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" } });
  const out = parseOut(res.stdout);
  const port = num(out?.port);
  if (!out?.ok || !port) return { ok: false, error: `could not start the sandbox: ${String(out?.error || res.stderr || res.error || res.code).slice(0, 300)}` };
  // The folders this running box was started with (a box another session
  // started keeps its own until it stops).
  const mounts = [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root)] : [])];
  if (!out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString(), launcher: out.launcher, idmap: out.idmap, overlay: out.overlay });
  return { ok: true, created, endpoint: { host: "127.0.0.1", port, token: meta.token }, uid: 0, gid: 0, containerId: `bwrap_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: out.reused ? (meta.mounts ?? mounts) : mounts, timing: { ...(num(out.ms) !== null ? { ms: num(out.ms) ?? 0 } : {}), reused: Boolean(out.reused) } };
}

function pidAlive(pid: unknown): boolean {
  if (typeof pid !== "number" || !pid) return false;
  try { process.kill(pid, 0); return true; } catch (error) { return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM"; }
}

async function list(_runtime: BoxRuntime, { home = "" }: { home?: string } = {}): Promise<ListedBox[]> {
  const dir = path.join(bwrapHome(home), "boxes");
  let names: string[] = [];
  try { names = readdirSync(dir).filter((name) => name.endsWith(".json")); } catch { return []; }
  const out: ListedBox[] = [];
  for (const name of names) {
    const meta = readJson<BoxMeta>(path.join(dir, name));
    if (!meta?.key) continue;
    let running = false;
    try { running = pidAlive(JSON.parse(readFileSync(path.join(boxDir(home, meta.key), "state.json"), "utf8")).pid); } catch { /* stopped */ }
    out.push({ key: meta.key, name: containerName(meta.key), root: meta.root, running, image: meta.pull || meta.ref || meta.image, created: meta.created_at || "" });
  }
  return out;
}

export const bwrapDriver: BoxDriver = {
  kind: "bwrap",
  execFallback: false,
  imagePresent,
  pull,
  pullCommand(runtime, image, home) {
    return { bin: runtime.bin, args: ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"] };
  },
  async exists(_runtime, key, { home = "" } = {}) {
    return existsSync(metaFile(home, key)) && existsSync(boxDir(home, key));
  },
  open,
  list,
  async remove(runtime, key, { run = runCommand, home = "" } = {}) {
    const res = await run(runtime.bin, ["rm", "--box", boxDir(home, key), ...(runtime.bwrap ? ["--bwrap", runtime.bwrap] : [])], { timeoutMs: 120_000 });
    const had = existsSync(metaFile(home, key));
    rmSync(metaFile(home, key), { force: true });
    return { removed: had && Boolean(parseOut(res.stdout)?.ok) };
  },
  async stop(runtime, key, { run = runCommand, home = "" } = {}) {
    const res = await run(runtime.bin, ["stop", "--box", boxDir(home, key)], { timeoutMs: 60_000 });
    return { stopped: Boolean(parseOut(res.stdout)?.ok) };
  },
  async gcImages(runtime, { run = runCommand, home = "", current, used, keep = { refs: current, digests: new Set<string>() }, dryRun = false, now = Date.now() }) {
    const removed: Removed[] = [];
    // Downloads a killed pull left in the store (each one can be a whole image).
    for (const item of staleEntries(path.join(storeDir(home), "tmp"), { now })) {
      if (dryRun) removed.push({ kind: "download", name: item.path, reason: "left by a stopped download", dryRun: true });
      else if (removeTree(item.path)) removed.push({ kind: "download", name: item.path, reason: "left by a stopped download" });
    }
    const dir = path.join(storeDir(home), "images");
    let ids: string[] = [];
    try { ids = readdirSync(dir); } catch { return removed; }
    const usedIds = new Set<string>(used);
    for (const box of await list(runtime, { home })) {
      const meta = readJson<BoxMeta>(metaFile(home, box.key));
      if (meta?.image) usedIds.add(meta.image);
    }
    for (const id of ids) {
      const img = readJson<{ ref?: string; digest?: string }>(path.join(dir, id, "image.json"));
      if (!img || !removableImage({ ref: img.ref, digest: img.digest, id }, { keep, used: usedIds })) continue;
      try { if (now - statSync(path.join(dir, id, "image.json")).mtimeMs < YOUNG_IMAGE_MS) continue; } catch { continue; }
      if (dryRun) { removed.push({ kind: "image", name: String(img.ref), reason: "not current", path: path.join(dir, id), dryRun: true }); continue; }
      // boxrun itself also refuses while any box (running or stopped) records this image.
      const res = await run(runtime.bin, ["rmimage", ...storeArgs(home), "--id", id, "--boxes", path.join(bwrapHome(home), "boxes")], { timeoutMs: 120_000 });
      if (parseOut(res.stdout)?.ok) removed.push({ kind: "image", name: String(img.ref), reason: "not current" });
    }
    return removed;
  },
  async upperBytes(runtime, key, { run = runCommand, home = "" } = {}) {
    const res = await run(runtime.bin, ["status", "--box", boxDir(home, key)], { timeoutMs: 60_000 });
    return num(parseOut(res.stdout)?.upper_bytes);
  },
  shellCommand(runtime, { key, croot, home }) {
    return { bin: runtime.bin, args: ["enter", "--box", boxDir(home, key), "--wd", croot, "--", "/bin/bash", "-l"] };
  },
  execCommand: (_runtime, { key, home }) => boxshExec({ key, home }),
};

/** The AppArmor profile `sudo omnirush sandbox enable` (the CLI) installs for OmniRush's own bwrap copy. */
export function apparmorProfile(bwrap = ENABLED_BWRAP): string {
  return `# OmniRush sandbox: lets OmniRush's own bubblewrap copy (root-owned) create
# user namespaces on systems that restrict them (Ubuntu 23.10+). Written by
# \`sudo omnirush sandbox enable\`; \`sudo omnirush sandbox enable --undo\` removes it.
abi <abi/4.0>,
include <tunables/global>

profile omnirush-bwrap ${bwrap} flags=(unconfined) {
  userns,

  include if exists <local/omnirush-bwrap>
}
`;
}