Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
19.3 KB
Raw Blame
/**
 * Write check of a project folder, before the agent's first turn there.
 *
 * A folder the engine cannot write to (Windows Controlled folder access, a
 * OneDrive folder whose files are online-only, a read-only drive or mount, a
 * system folder, a macOS privacy-protected folder) let the agent run whole
 * turns, spending tokens, without changing a file. This check creates,
 * writes, fsyncs, renames and deletes a temporary file in the folder, run by
 * the engine binary itself (BUN_BE_BUN=1: the same executable, so the same
 * Defender and macOS privacy decisions as the engine's own writes), and
 * names the reason and the fix when it fails.
 *
 * Kept in step with the CLI (omnirush-cli src/folder-write-check.js).
 */
import { execFile, spawn } from "node:child_process";
import { chmodSync, closeSync, fsyncSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { isReleaseBuild, releaseEngineBinary } from "./release-guard.js";

export type FolderWriteReason =
  | "missing"
  | "not_a_folder"
  | "read_only_volume"
  | "read_only_attribute"
  | "permission"
  | "protected_folder"
  | "cloud_files"
  | "system_folder"
  | "network_folder"
  | "macos_privacy"
  | "disk_full"
  | "unknown";

export type FolderProbeOutcome =
  | { ok: true }
  | { ok: false; step: string; code: string | null; errno: number | null; message: string };

export type FolderWriteResult =
  | { ok: true; via: "engine" | "server" | "skipped" }
  | {
      ok: false;
      via: "engine" | "server";
      reason: FolderWriteReason;
      code: string | null;
      step: string;
      /** "OmniRush can't write to <folder>: <why>." */
      message: string;
      /** How to fix it, for this platform. */
      hint: string;
    };

export const FOLDER_NOT_WRITABLE = "workspace_not_writable";

/**
 * The probe the engine binary runs (`BUN_BE_BUN=1 <engine> -e <script>`).
 * Prints one JSON line; never throws.
 */
export const PROBE_SCRIPT = [
  'const fs=require("node:fs"),p=require("node:path");',
  "const d=process.env.OMNIRUSH_WRITE_CHECK_DIR;",
  'const n=".omnirush-write-check-"+process.pid+"-"+Date.now().toString(36);',
  'const a=p.join(d,n+".tmp"),b=p.join(d,n);let step="create",fd;',
  'try{fd=fs.openSync(a,"wx");step="write";fs.writeSync(fd,"omnirush write check\\n");step="fsync";fs.fsyncSync(fd);fs.closeSync(fd);fd=undefined;',
  'step="rename";fs.renameSync(a,b);step="delete";fs.unlinkSync(b);process.stdout.write(JSON.stringify({ok:true}))}',
  "catch(e){if(fd!==undefined)try{fs.closeSync(fd)}catch{}for(const f of[a,b])try{fs.unlinkSync(f)}catch{}",
  "process.stdout.write(JSON.stringify({ok:false,step,code:e&&e.code||null,errno:e&&typeof e.errno===\"number\"?e.errno:null,message:String(e&&e.message||e).slice(0,300)}))}",
].join("");

/** The same steps in this process (no engine binary, or it could not run). */
export function probeInProcess(dir: string): FolderProbeOutcome {
  const name = `.omnirush-write-check-${process.pid}-${Date.now().toString(36)}`;
  const a = path.join(dir, `${name}.tmp`);
  const b = path.join(dir, name);
  let step = "create";
  let fd: number | undefined;
  try {
    fd = openSync(a, "wx");
    step = "write";
    writeSync(fd, "omnirush write check\n");
    step = "fsync";
    fsyncSync(fd);
    closeSync(fd);
    fd = undefined;
    step = "rename";
    renameSync(a, b);
    step = "delete";
    unlinkSync(b);
    return { ok: true };
  } catch (error) {
    if (fd !== undefined) try { closeSync(fd); } catch { /* closed */ }
    for (const file of [a, b]) try { unlinkSync(file); } catch { /* not there */ }
    const e = error as NodeJS.ErrnoException;
    return { ok: false, step, code: e?.code ?? null, errno: typeof e?.errno === "number" ? e.errno : null, message: String(e?.message ?? e).slice(0, 300) };
  }
}

/**
 * The engine binary run as bun reads a bunfig.toml (its `preload` runs code)
 * and a .env from its working folder. The probe runs in a fresh private
 * folder of its own (under the app's user data folder, else the temporary
 * folder; 0700), with an empty bunfig the app writes there named on the
 * command line and no .env file, so no other folder (a shared temporary
 * folder, a project) adds anything to it. The same options as the CLI's
 * helper runtime.
 */
export function isolatedBunArgs(folder: string): string[] {
  return ["--no-env-file", `--config=${path.join(folder, "bunfig.toml")}`];
}

function isolatedBunFolder(env: NodeJS.ProcessEnv = process.env): string | null {
  try {
    const userData = env.OMNIRUSH_DESKTOP_USER_DATA_DIR?.trim();
    const parent = userData ? path.join(userData, "write-check") : os.tmpdir();
    if (userData) mkdirSync(parent, { recursive: true, mode: 0o700 });
    const folder = mkdtempSync(path.join(parent, "probe-"));
    chmodSync(folder, 0o700);
    writeFileSync(path.join(folder, "bunfig.toml"), "", { mode: 0o600 });
    return folder;
  } catch {
    return null;
  }
}

/** The probe run by the engine binary; null when it could not run or said nothing usable. */
export async function probeWithEngine(dir: string, engineBin: string, timeoutMs = 15_000): Promise<FolderProbeOutcome | null> {
  // A release build runs only the engine it bundles (release-guard.ts); another binary is not run.
  if (isReleaseBuild() && !(await releaseEngineBinary(engineBin).then(() => true, () => false))) return null;
  const folder = isolatedBunFolder();
  if (!folder) return Promise.resolve(null);
  let exited: Promise<void> = Promise.resolve();
  return probeIn(folder, dir, engineBin, timeoutMs, (closed) => { exited = closed; }).finally(async () => {
    // A probe that timed out was killed: its folder goes once the process has ended (at most a few seconds).
    await Promise.race([exited, new Promise<void>((resolveWait) => setTimeout(resolveWait, 5_000).unref?.())]);
    try { rmSync(folder, { recursive: true, force: true }); } catch { /* best effort */ }
  });
}

function probeIn(folder: string, dir: string, engineBin: string, timeoutMs: number, onSpawn: (closed: Promise<void>) => void): Promise<FolderProbeOutcome | null> {
  return new Promise((resolve) => {
    let out = "";
    let done = false;
    const finish = (value: FolderProbeOutcome | null) => {
      if (done) return;
      done = true;
      clearTimeout(timer);
      resolve(value);
    };
    let child: ReturnType<typeof spawn>;
    try {
      const env: NodeJS.ProcessEnv = { ...process.env, BUN_BE_BUN: "1", OMNIRUSH_WRITE_CHECK_DIR: dir };
      // Extra command-line options bun would take from the environment.
      delete env.BUN_OPTIONS;
      child = spawn(engineBin, [...isolatedBunArgs(folder), "-e", PROBE_SCRIPT], {
        cwd: folder,
        env,
        stdio: ["ignore", "pipe", "ignore"],
        windowsHide: true,
      });
    } catch {
      resolve(null);
      return;
    }
    onSpawn(new Promise<void>((resolveClosed) => {
      child.once("close", () => resolveClosed());
      child.once("error", () => resolveClosed());
    }));
    const timer = setTimeout(() => {
      try { child.kill(); } catch { /* gone */ }
      finish(null);
    }, timeoutMs);
    child.stdout?.on("data", (chunk: Buffer) => { out += chunk.toString("utf8"); });
    child.on("error", () => finish(null));
    child.on("close", () => {
      try {
        const parsed = JSON.parse(out.trim().split("\n").pop() ?? "");
        if (parsed && typeof parsed.ok === "boolean") return finish(parsed as FolderProbeOutcome);
      } catch { /* not JSON */ }
      finish(null);
    });
  });
}

/** Whether Windows Security's Controlled folder access is on (block mode). */
export function controlledFolderAccessOn(run: (args: string[]) => Promise<string> = regQuery): Promise<boolean> {
  const keys = [
    "HKLM\\SOFTWARE\\Microsoft\\Windows Defender\\Windows Defender Exploit Guard\\Controlled Folder Access",
    "HKLM\\SOFTWARE\\Policies\\Microsoft\\Windows Defender\\Windows Defender Exploit Guard\\Controlled Folder Access",
  ];
  return Promise.all(keys.map((key) => run(["query", key, "/v", "EnableControlledFolderAccess"]).catch(() => "")))
    .then((outs) => outs.some((text) => /EnableControlledFolderAccess\s+REG_DWORD\s+0x0*1\b/i.test(text)));
}

function regQuery(args: string[]): Promise<string> {
  return new Promise((resolve, reject) => {
    execFile("reg", args, { timeout: 3_000, windowsHide: true }, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
  });
}

export type ClassifyContext = {
  platform: NodeJS.Platform;
  dir: string;
  env?: NodeJS.ProcessEnv;
  home?: string;
  /** Windows: Controlled folder access is on. */
  cfaOn?: boolean;
  /** The folder's mode lacks the owner write bit (Windows: the read-only attribute). */
  readOnlyMode?: boolean;
  /** The folder is there (a create that fails with ENOENT is then not a missing folder). */
  folderExists?: boolean;
  /** The executable to allow (Controlled folder access). */
  engineBin?: string | null;
};

function under(child: string, parent: string | undefined, win: boolean): boolean {
  if (!parent) return false;
  const norm = (value: string) => {
    const resolved = (win ? path.win32 : path.posix).resolve(value);
    return win ? resolved.toLowerCase() : resolved;
  };
  const c = norm(child);
  const p = norm(parent);
  const sep = win ? "\\" : "/";
  return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
}

const CLOUD_TEXT = /cloud (?:file|operation|provider)|0x8007016a|0x80070185|0x8007018[0-9a-f]/i;

/** The reason a failed probe names. */
export function classifyFailure(outcome: Extract<FolderProbeOutcome, { ok: false }>, ctx: ClassifyContext): FolderWriteReason {
  const env = ctx.env ?? {};
  const code = outcome.code ?? "";
  const win = ctx.platform === "win32";
  if (code === "ENOENT" && outcome.step === "create" && !ctx.folderExists) return "missing";
  if (code === "ENOTDIR") return "not_a_folder";
  if (code === "ENOSPC" || code === "EDQUOT") return "disk_full";
  if (code === "EROFS") return "read_only_volume";
  if (win) {
    if (/^\\\\/.test(ctx.dir) || /^\/\//.test(ctx.dir)) return "network_folder";
    const oneDrive = [env.OneDrive, env.OneDriveConsumer, env.OneDriveCommercial].some((root) => under(ctx.dir, root, true));
    if (CLOUD_TEXT.test(outcome.message) || (oneDrive && !["EPERM", "EACCES"].includes(code) )) return "cloud_files";
    // Controlled folder access refuses a create with ERROR_FILE_NOT_FOUND (ENOENT) in a folder that is there.
    if (code === "EPERM" || code === "EACCES" || (code === "ENOENT" && ctx.folderExists)) {
      const parsed = path.win32.parse(path.win32.resolve(ctx.dir));
      const system = [env.ProgramFiles, env["ProgramFiles(x86)"], env.ProgramW6432, env.SystemRoot, env.windir, env.ProgramData]
        .some((root) => under(ctx.dir, root, true));
      if (system || parsed.root.toLowerCase() === path.win32.resolve(ctx.dir).toLowerCase()) return "system_folder";
      if (ctx.cfaOn) return "protected_folder";
      if (ctx.readOnlyMode) return "read_only_attribute";
      if (oneDrive) return "cloud_files";
      return "permission";
    }
    return oneDrive ? "cloud_files" : "unknown";
  }
  if (ctx.platform === "darwin" && code === "EPERM") {
    const home = ctx.home ?? os.homedir();
    const tcc = ["Desktop", "Documents", "Downloads", "Library/Mobile Documents", "Library/CloudStorage"].map((name) => path.posix.join(home, name));
    if (tcc.some((root) => under(ctx.dir, root, false)) || under(ctx.dir, "/Volumes", false)) return "macos_privacy";
  }
  if (code === "EACCES" || code === "EPERM") return "permission";
  return "unknown";
}

const WHY: Record<FolderWriteReason, string> = {
  missing: "the folder does not exist any more",
  not_a_folder: "it is not a folder",
  read_only_volume: "the drive or mount is read-only",
  read_only_attribute: "the folder is marked read-only",
  permission: "permission denied",
  protected_folder: "Windows Security's Controlled folder access blocks the change",
  cloud_files: "it is a OneDrive folder whose files are not available on this device",
  system_folder: "it is a system folder that needs administrator rights",
  network_folder: "the network folder refused the write or cannot be reached",
  macos_privacy: "macOS privacy settings do not allow OmniRush to change files there",
  disk_full: "the disk is full",
  unknown: "a test file could not be written",
};

/** How to fix it, for this platform. */
export function fixHint(reason: FolderWriteReason, platform: NodeJS.Platform, engineBin?: string | null): string {
  const elsewhere = (where: string) => `Or choose another folder ${where}.`;
  const other = "Or choose another folder.";
  switch (reason) {
    case "missing":
    case "not_a_folder":
      return "Choose another folder.";
    case "read_only_volume":
      return platform === "darwin"
        ? `The volume is mounted read-only (a disk image, a locked card, a read-only share). Copy the project into your home folder. ${other}`
        : platform === "win32"
          ? `Copy the project to a folder on a writable drive (for example C:\\Users\\<you>\\Projects). ${other}`
          : `Remount it read-write (for example: sudo mount -o remount,rw <mount point>), or copy the project into your home folder. ${other}`;
    case "read_only_attribute":
      return `Open the folder's Properties, clear "Read-only" and apply it to all files and subfolders. ${other}`;
    case "permission":
      return platform === "win32"
        ? `Check the folder's Properties → Security permissions for your account, or use a folder under C:\\Users\\<you>. If Controlled folder access is on, allow OmniRush in Windows Security. ${other}`
        : `Make your user the owner (for example: sudo chown -R "$USER" <folder>) or give it write permission (chmod -R u+w <folder>). ${other}`;
    case "protected_folder":
      return `Open Windows Security → Virus & threat protection → Ransomware protection → Allow an app through Controlled folder access, and add ${engineBin ? `"${engineBin}"` : "OmniRush's engine"}. ${elsewhere("outside Documents, Desktop, Pictures, Music and Videos")}`;
    case "cloud_files":
      return `Make sure OneDrive is running and signed in, then right-click the folder → "Always keep on this device". ${elsewhere("on this device, outside OneDrive (for example C:\\Users\\<you>\\Projects)")}`;
    case "system_folder":
      return "Choose a folder in your user folder, for example C:\\Users\\<you>\\Projects. Running OmniRush as administrator is not needed.";
    case "network_folder":
      return `Check the network connection and your write access to the share, or copy the project to a local folder. ${other}`;
    case "macos_privacy":
      return `Open System Settings → Privacy & Security → Files and Folders (or Full Disk Access) and allow OmniRush, then try again. ${elsewhere("outside Desktop, Documents and Downloads")}`;
    case "disk_full":
      return `Free some disk space, then try again. ${other}`;
    default:
      return `Check that you can create files there, then try again. ${other}`;
  }
}

export type CheckOptions = {
  platform?: NodeJS.Platform;
  env?: NodeJS.ProcessEnv;
  engineBin?: string | null;
  probeEngine?: typeof probeWithEngine;
  probeLocal?: typeof probeInProcess;
  cfa?: () => Promise<boolean>;
  stat?: (dir: string) => { isDirectory(): boolean; mode: number };
};

/** Run the write check on a folder. Fails open (ok) only when no probe could run at all. */
export async function checkFolderWritable(folder: string, options: CheckOptions = {}): Promise<FolderWriteResult> {
  // The engine probe runs elsewhere (cwd: a private folder of its own): the folder goes to it absolute.
  const platform = options.platform ?? process.platform;
  const dir = (platform === "win32" ? path.win32 : path.posix).resolve(folder);
  const env = options.env ?? process.env;
  const engineBin = options.engineBin?.trim() || null;
  let outcome: FolderProbeOutcome | null = null;
  let via: "engine" | "server" = "engine";
  if (engineBin) outcome = await (options.probeEngine ?? probeWithEngine)(dir, engineBin);
  if (!outcome) {
    via = "server";
    outcome = (options.probeLocal ?? probeInProcess)(dir);
  }
  if (outcome.ok) return { ok: true, via };
  let readOnlyMode = false;
  let folderExists = false;
  try {
    const info = (options.stat ?? statSync)(dir);
    if (!info.isDirectory()) outcome = { ...outcome, code: "ENOTDIR" };
    folderExists = info.isDirectory();
    readOnlyMode = (info.mode & 0o200) === 0;
  } catch { /* classified from the probe */ }
  const code = outcome.code ?? "";
  const cfaOn = platform === "win32" && (code === "EPERM" || code === "EACCES" || (code === "ENOENT" && folderExists))
    ? await (options.cfa ?? (() => controlledFolderAccessOn()))().catch(() => false)
    : false;
  const reason = classifyFailure(outcome, { platform, dir, env, cfaOn, readOnlyMode, folderExists, engineBin });
  const codeText = outcome.code ? ` (${outcome.code})` : "";
  return {
    ok: false,
    via,
    reason,
    code: outcome.code,
    step: outcome.step,
    message: `OmniRush can't write to ${dir}: ${WHY[reason]}${codeText}.`,
    hint: fixHint(reason, platform, engineBin),
  };
}

// --- the gate: once per chat and folder, before its first turn ---------------------

let engineBinary: string | null = null;
/** The engine binary the server starts (embedded.ts); the probe runs it. */
export function setWriteCheckEngine(bin: string | null | undefined): void {
  engineBinary = bin?.trim() || null;
}

const SUCCESS_TTL_MS = 60_000;
const checkedChats = new Set<string>();
const recentOk = new Map<string, number>();
const inFlight = new Map<string, Promise<FolderWriteResult>>();

export function writeCheckDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
  return /^(?:0|off|false|no)$/i.test((env.OMNIRUSH_WRITE_CHECK ?? "").trim());
}

/** A prompt for the read-only plan agent edits nothing: it is never held back. */
export function readOnlyPrompt(body: unknown): boolean {
  return Boolean(body && typeof body === "object" && (body as { agent?: unknown }).agent === "plan");
}

/**
 * The check for a chat's prompt in a folder: null to go on, else the failed
 * result. A chat that passed in a folder is not checked again there; a failed
 * folder is checked again at every prompt (the person fixed it, or not).
 */
export async function folderWriteGate(sessionId: string, dir: string, options: CheckOptions & { now?: () => number } = {}): Promise<Extract<FolderWriteResult, { ok: false }> | null> {
  if (writeCheckDisabled(options.env)) return null;
  const key = `${sessionId}\0${dir}`;
  if (checkedChats.has(key)) return null;
  const now = (options.now ?? Date.now)();
  const recent = recentOk.get(dir);
  if (recent !== undefined && now - recent < SUCCESS_TTL_MS) {
    checkedChats.add(key);
    return null;
  }
  let pending = inFlight.get(dir);
  if (!pending) {
    // Chats run on the 2.x engine (the 1.x one no longer ships): its binary runs the probe.
    const env = options.env ?? process.env;
    pending = checkFolderWritable(dir, { engineBin: env.OMNIRUSH_OPENCODE2_BIN?.trim() || engineBinary || env.OMNIRUSH_OPENCODE_BIN?.trim() || null, ...options })
      .finally(() => inFlight.delete(dir));
    inFlight.set(dir, pending);
  }
  const result = await pending;
  if (result.ok) {
    if (checkedChats.size >= 10_000) checkedChats.clear();
    recentOk.set(dir, now);
    checkedChats.add(key);
    return null;
  }
  recentOk.delete(dir);
  return result;
}

export function resetFolderWriteGate(): void {
  checkedChats.clear();
  recentOk.clear();
  inFlight.clear();
}