Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

13.4 KB
Raw Blame
/**
 * The file tools' sandboxed helper: a Node process the Session's sandbox confines exactly
 * as it confines a command, serving the {@link FsPort} primitives over one JSON line per
 * request on stdin and one per answer on stdout (binary as base64). Every file-system
 * effect of read_file, edit_file and write_file happens inside it when a Session is
 * confined, so the backend that bounds the Session's commands bounds its file tools too —
 * one policy, one enforcer, and nothing for the harness to re-implement.
 *
 * The helper's program travels as a `-e` argument, so no file has to be shipped beside any
 * bundle that inlines core; it uses only builtin modules and syntax an older Node in a
 * sandbox distro understands. One helper serves a Session, started at its first confined
 * file operation and kept for the next ones; it is started over when the confiner's answer
 * changes (the policy was edited), after a crash, and after an abort, which kills it so an
 * operation the sandbox is stalling cannot outlive the call.
 *
 * Paths cross as the host spells them. Inside a Linux distro serving a Windows host (the
 * WSL backend), a drive path is mapped to its `/mnt/<drive>` spelling on the way in and
 * back on the way out, so the tools never see the distro's view.
 */
import { spawn } from "node:child_process";
import type { ChildProcess } from "node:child_process";
import readline from "node:readline";
import type { ConfinedSpawn } from "../../interfaces/index.js";
import type { FsDirent, FsFetchResult, FsStat, ToolFs } from "./fs-port.js";

/**
 * The helper's program (CommonJS, builtin modules only — the same shape a hook script
 * has). Ops answer with JSON-serializable results; buffers travel base64. Windows drive
 * paths are mapped for a Linux distro and unmapped in answers that carry paths.
 */
export const FS_WORKER_SOURCE = String.raw`
const fs = require("node:fs/promises");
const path = require("node:path");
const readline = require("node:readline");
const linux = process.platform !== "win32";
const DRIVE = /^([A-Za-z]):[\\/](.*)$/;
function toLocal(p) {
  const m = linux ? DRIVE.exec(p) : null;
  if (!m) return p;
  const rest = m[2].split(/[\\/]+/).filter(Boolean);
  return ["/mnt/" + m[1].toLowerCase()].concat(rest).join("/");
}
function fromLocal(p, like) {
  if (!linux || !DRIVE.test(like)) return p;
  const m = /^\/mnt\/([a-z])(?:\/(.*))?$/.exec(p);
  if (!m) return p;
  return m[1].toUpperCase() + ":\\" + (m[2] || "").split("/").join("\\");
}
async function writeAtomic(target, content, mode, followSymlinks) {
  let dest = target;
  if (followSymlinks) {
    for (let hop = 0; hop < 40; hop += 1) {
      let link;
      try {
        link = await fs.readlink(dest);
      } catch {
        break;
      }
      dest = path.resolve(path.dirname(dest), link);
    }
  }
  const tmp = path.join(
    path.dirname(dest),
    "." + path.basename(dest) + ".tmp-" + process.pid + "-" + Math.random().toString(36).slice(2, 8),
  );
  try {
    await fs.writeFile(tmp, content, mode === undefined ? { flush: true } : { mode, flush: true });
    if (mode !== undefined) await fs.chmod(tmp, mode);
    await fs.rename(tmp, dest);
  } catch (err) {
    await fs.rm(tmp, { force: true }).catch(() => undefined);
    throw err;
  }
}
const ops = {
  async stat({ p }) {
    const s = await fs.stat(toLocal(p));
    return { isFile: s.isFile(), isDirectory: s.isDirectory(), size: s.size, mode: s.mode };
  },
  async readFile({ p }) {
    return (await fs.readFile(toLocal(p))).toString("base64");
  },
  async readRange({ p, position, length }) {
    const fh = await fs.open(toLocal(p), "r");
    try {
      const buf = Buffer.alloc(length);
      const { bytesRead } = await fh.read(buf, 0, length, position);
      return buf.subarray(0, bytesRead).toString("base64");
    } finally {
      await fh.close();
    }
  },
  async readdir({ p }) {
    const entries = await fs.readdir(toLocal(p), { withFileTypes: true });
    return entries.map((e) => ({ name: e.name, isFile: e.isFile(), isDirectory: e.isDirectory() }));
  },
  async realpath({ p }) {
    return fromLocal(await fs.realpath(toLocal(p)), p);
  },
  async readlink({ p }) {
    return fromLocal(await fs.readlink(toLocal(p)), p);
  },
  async mkdir({ p }) {
    await fs.mkdir(toLocal(p), { recursive: true });
  },
  async writeFileAtomic({ p, content, mode, followSymlinks }) {
    await writeAtomic(toLocal(p), Buffer.from(content, "base64"), mode, followSymlinks === true);
  },
  async fetch({ url, maxBytes }) {
    const res = await fetch(url);
    const declared = Number(res.headers.get("content-length") || "");
    if (Number.isFinite(declared) && declared > maxBytes) {
      throw Object.assign(new Error("response body of " + declared + " bytes exceeds the limit"), { code: "ETOOBIG", size: declared });
    }
    const bytes = Buffer.from(await res.arrayBuffer());
    if (bytes.length > maxBytes) {
      throw Object.assign(new Error("response body of " + bytes.length + " bytes exceeds the limit"), { code: "ETOOBIG", size: bytes.length });
    }
    return { ok: res.ok, status: res.status, contentType: res.headers.get("content-type"), bytes: bytes.toString("base64") };
  },
};
const out = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
readline.createInterface({ input: process.stdin, terminal: false }).on("line", (line) => {
  let req;
  try {
    req = JSON.parse(line);
  } catch {
    return;
  }
  const op = ops[req.op];
  if (!op) {
    out({ id: req.id, ok: false, error: { code: "ENOSYS", message: "unknown op " + req.op } });
    return;
  }
  op(req.args || {}).then(
    (result) => out({ id: req.id, ok: true, result: result === undefined ? null : result }),
    (err) => out({ id: req.id, ok: false, error: { code: err && err.code, message: err && err.message ? err.message : String(err), size: err && err.size } }),
  );
});
process.stdin.on("end", () => process.exit(0));
`;

/** The argv the helper is spawned as, before the confiner rewrites it. */
export function fsWorkerArgv(): string[] {
  return [process.execPath, "-e", FS_WORKER_SOURCE];
}

interface Pending {
  resolve: (value: unknown) => void;
  reject: (err: Error) => void;
}

/** One running helper: the confiner's answer it was started from, its process and the requests in flight. */
interface Worker {
  key: string;
  child: ChildProcess;
  pending: Map<number, Pending>;
  exited: boolean;
}

/**
 * The Session's helper, started on demand and kept until `dispose`. `portFor` answers a
 * port over the helper the confiner's answer describes, starting one when none runs or the
 * running one was started from a different answer.
 */
export class SandboxedFsHost {
  private worker: Worker | null = null;
  private nextId = 1;
  private disposed = false;

  constructor(private readonly spawnWorker: (spawn: ConfinedSpawn) => ChildProcess = start) {}

  /** A port over a helper started from `confined` (the confiner's answer for the helper argv). */
  portFor(confined: ConfinedSpawn): ToolFs {
    const key = JSON.stringify([confined.argv, confined.env ?? null]);
    const request = (op: string, args: Record<string, unknown>, signal?: AbortSignal) =>
      this.request(key, confined, op, args, signal);
    const buffer = async (op: string, args: Record<string, unknown>): Promise<Buffer> =>
      Buffer.from((await request(op, args)) as string, "base64");
    return {
      sandboxed: true,
      stat: (p) => request("stat", { p }) as Promise<FsStat>,
      readFile: (p) => buffer("readFile", { p }),
      readRange: (p, position, length) => buffer("readRange", { p, position, length }),
      readdir: (p) => request("readdir", { p }) as Promise<FsDirent[]>,
      realpath: (p) => request("realpath", { p }) as Promise<string>,
      readlink: (p) => request("readlink", { p }) as Promise<string>,
      mkdir: async (p) => {
        await request("mkdir", { p });
      },
      writeFileAtomic: async (p, content, opts) => {
        await request("writeFileAtomic", {
          p,
          content: content.toString("base64"),
          ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
          ...(opts.followSymlinks !== undefined ? { followSymlinks: opts.followSymlinks } : {}),
        });
      },
      fetch: async (url, opts) => {
        const answer = (await request("fetch", { url, maxBytes: opts.maxBytes }, opts.signal)) as {
          ok: boolean;
          status: number;
          contentType: string | null;
          bytes: string;
        };
        return { ...answer, bytes: Buffer.from(answer.bytes, "base64") } satisfies FsFetchResult;
      },
    };
  }

  /** Whether a helper is running right now (for tests and diagnostics). */
  get running(): boolean {
    return this.worker !== null && !this.worker.exited;
  }

  /** Stops the helper; the next port request starts a fresh one. */
  dispose(): void {
    this.disposed = true;
    this.stop(new Error("the file helper was disposed"));
  }

  private request(
    key: string,
    confined: ConfinedSpawn,
    op: string,
    args: Record<string, unknown>,
    signal?: AbortSignal,
  ): Promise<unknown> {
    if (this.disposed) return Promise.reject(new Error("the file helper was disposed"));
    if (signal?.aborted) return Promise.reject(abortError());
    const worker = this.ensure(key, confined);
    const id = this.nextId++;
    return new Promise<unknown>((resolve, reject) => {
      const onAbort = (): void => {
        // The sandbox may be stalling the operation; the helper goes with the call.
        this.stop(abortError());
      };
      signal?.addEventListener("abort", onAbort, { once: true });
      worker.pending.set(id, {
        resolve: (value) => {
          signal?.removeEventListener("abort", onAbort);
          resolve(value);
        },
        reject: (err) => {
          signal?.removeEventListener("abort", onAbort);
          reject(err);
        },
      });
      worker.child.stdin!.write(`${JSON.stringify({ id, op, args })}\n`, (err) => {
        if (err) this.settle(worker, id, { ok: false, error: { message: err.message } });
      });
    });
  }

  /** The running helper for `key`, or a fresh one — the previous one, started from another answer or exited, is stopped. */
  private ensure(key: string, confined: ConfinedSpawn): Worker {
    if (this.worker !== null && (this.worker.key !== key || this.worker.exited)) {
      this.stop(new Error("the file helper was restarted"));
    }
    if (this.worker !== null) return this.worker;
    const child = this.spawnWorker(confined);
    const worker: Worker = { key, child, pending: new Map(), exited: false };
    let stderr = "";
    child.stderr?.setEncoding("utf8").on("data", (chunk: string) => {
      stderr = (stderr + chunk).slice(-2048);
    });
    readline.createInterface({ input: child.stdout!, terminal: false }).on("line", (line) => {
      let msg: { id?: number; ok?: boolean; result?: unknown; error?: WireError };
      try {
        msg = JSON.parse(line) as typeof msg;
      } catch {
        return;
      }
      if (typeof msg.id === "number") this.settle(worker, msg.id, msg);
    });
    const onGone = (reason: string): void => {
      if (worker.exited) return;
      worker.exited = true;
      const tail = stderr.trim();
      const err = new Error(tail ? `${reason}: ${tail}` : reason);
      for (const p of worker.pending.values()) p.reject(err);
      worker.pending.clear();
      if (this.worker === worker) this.worker = null;
    };
    child.on("error", (err) => onGone(`sandbox: the file helper could not start (${err.message})`));
    child.on("close", (code, signal) =>
      onGone(`sandbox: the file helper exited (${signal ?? `code ${code}`})`),
    );
    child.stdin?.on("error", () => {
      // A helper that died mid-write closes the pipe; `close` above reports it.
    });
    this.worker = worker;
    return worker;
  }

  /** Answers one request from the helper's reply. */
  private settle(
    worker: Worker,
    id: number,
    msg: { ok?: boolean; result?: unknown; error?: WireError },
  ): void {
    const pending = worker.pending.get(id);
    if (!pending) return;
    worker.pending.delete(id);
    if (msg.ok) {
      pending.resolve(msg.result);
      return;
    }
    const error = msg.error ?? {};
    pending.reject(
      Object.assign(new Error(error.message ?? "the file helper failed"), {
        ...(error.code !== undefined && error.code !== null ? { code: error.code } : {}),
        ...(error.size !== undefined && error.size !== null ? { size: error.size } : {}),
      }),
    );
  }

  /** Kills the helper and fails what it still owed. */
  private stop(reason: Error): void {
    const worker = this.worker;
    if (worker === null) return;
    this.worker = null;
    if (!worker.exited) {
      worker.exited = true;
      worker.child.kill("SIGKILL");
    }
    for (const p of worker.pending.values()) p.reject(reason);
    worker.pending.clear();
  }
}

interface WireError {
  code?: string | null;
  message?: string;
  size?: number | null;
}

function abortError(): Error {
  return Object.assign(new Error("aborted"), { name: "AbortError" });
}

/** Spawns the helper from the confiner's answer: the runner's entries over an environment that runs the desktop app's binary as Node. */
function start(confined: ConfinedSpawn): ChildProcess {
  const [program, ...args] = confined.argv;
  if (program === undefined) throw new Error("sandbox: the confiner returned an empty argv");
  return spawn(program, args, {
    stdio: ["pipe", "pipe", "pipe"],
    env: { ...process.env, ELECTRON_RUN_AS_NODE: "1", ...confined.env },
  });
}