Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

18.2 KB
Raw Blame
/**
 * The machine a workspace's tools run on: a filesystem and a shell, where
 * every command and file the model picks goes. Never the disk, the processes
 * or the environment of the machine that drives the session.
 *
 * `WorkspaceMachine` is what a harness's tool code uses (each harness's own
 * tools, written against it). Two implementations of it here, both just-bash
 * on an in-memory filesystem, with an explicit command list
 * (`VIRTUAL_COMMANDS`):
 *
 * - in a worker thread leased to one session, with an empty environment
 *   (the default on Node, worker.ts): the shell runs in a realm of its own,
 *   so just-bash's defense-in-depth can be on there (it patches the globals
 *   of the realm it runs in, which the realm that serves requests cannot
 *   afford), and a long command holds that thread, not the one serving every
 *   other session. just-bash's `normal` profile for counts (a loop, a
 *   script's commands), its `hardened` sizes (output, strings, input): a
 *   command's time is bounded by its deadline, at which the worker ends;
 * - in this realm (browsers, Cloudflare Workers, and Node when a worker
 *   cannot start), with defense-in-depth off and the `hardened` profile:
 *   nothing can stop a command that never yields here, so its counts are
 *   capped too.
 *
 * A Sandbox can implement the same interface (exec and files over its API).
 */

/** What a command printed and how it exited. */
export interface ExecResult {
  exitCode: number;
  stdout: string;
  stderr: string;
}

export interface ExecOptions {
  /** Working directory (virtual); default the workspace root. */
  cwd?: string;
  /** Variables for this command only (nothing of the host's environment is ever there). */
  env?: Record<string, string>;
  /** Argv entries appended to the first command, past shell parsing (like `spawn(cmd, args)`). */
  args?: string[];
  /** Standard input. */
  stdin?: string;
  signal?: AbortSignal;
  /** Stop the command after this long (as `signal` would): exit code 124, like `timeout`. */
  timeoutMs?: number;
}

export type PathType = 'file' | 'directory' | 'symlink';

export interface PathStat {
  type: PathType;
  size: number;
  /** Permission bits (`0o644`, `0o755`). */
  mode: number;
  mtimeMs: number;
}

export interface DirEntry {
  name: string;
  type: PathType;
}

/** One path under a directory (`walk`): its type with links followed, and whether it is a link. */
export interface WalkEntry extends PathStat {
  path: string;
  /** The path itself is a symbolic link (`type` is its target's; a dangling link is left out). */
  link?: true;
}

/**
 * A filesystem and a shell. Paths are absolute virtual paths (a relative
 * path is taken from the root). Methods reject on failure with an Error
 * whose `code` is the POSIX one when there is one (`ENOENT`, `EISDIR`, ...).
 */
export interface WorkspaceMachine {
  /** The workspace root: `/workspace`. */
  readonly root: string;
  /** Where commands run: `worker` (an isolated thread), `process` (this realm), or a Sandbox's own. */
  readonly isolation: string;
  /** Its files are gone (the thread it ran in was restarted): make a new one. */
  readonly lost: boolean;
  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
  readFile(path: string): Promise<Uint8Array>;
  /** Write a file, creating its parent directories. An existing file keeps its mode unless `mode` is given. */
  writeFile(path: string, content: string | Uint8Array, options?: { mode?: number; append?: boolean }): Promise<void>;
  /** With links followed; undefined when nothing is there. */
  stat(path: string): Promise<PathStat | undefined>;
  /** The path itself (a link is a link); undefined when nothing is there. */
  lstat(path: string): Promise<PathStat | undefined>;
  /** A directory's entries, sorted by name. */
  list(dir: string): Promise<DirEntry[]>;
  /** Every path under `dir` (default the root), recursively, sorted. */
  walk(dir?: string): Promise<WalkEntry[]>;
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
  remove(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
  rename(from: string, to: string): Promise<void>;
  symlink(target: string, path: string): Promise<void>;
  readlink(path: string): Promise<string>;
  realpath(path: string): Promise<string>;
  chmod(path: string, mode: number): Promise<void>;
  /** Free it (its files are gone). Also done when it is garbage-collected. */
  dispose(): void;
}

/** A file's bytes and mode, as the transaction operations move them. */
export type FileBytes = [path: string, bytes: Uint8Array, mode: number];

/**
 * The operations both machines run, on just-bash. Self-contained (it refers
 * to nothing outside itself, not even a helper of a bundler), because the
 * worker runs its source text (`machineOps.toString()`): the same code runs
 * in this realm and in the worker.
 *
 * Besides the filesystem and the shell, the transaction operations the
 * document-backed workspace needs, done where the files are so a call moves
 * only what changed: `apply` (make files hold given contents), `checkpoint`
 * (remember the files under the root), `diff` (what changed since, after
 * making links copies: the manifest holds no links), `rollback`, `release`.
 */
export function machineOps(jb: any, config: { defenseInDepth: unknown; profile: 'normal' | 'hardened'; limits?: Record<string, number> }) {
  const machines = new Map<string, any>();
  const encoder = new TextEncoder();
  const bytesOf = (c: string | Uint8Array): Uint8Array => (typeof c === 'string' ? encoder.encode(c) : c);
  const sameBytes = (a: Uint8Array, b: Uint8Array): boolean => {
    if (a.length !== b.length) return false;
    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
    return true;
  };
  const get = (id: string) => {
    const m = machines.get(id);
    if (!m) throw Object.assign(new Error('this workspace is gone'), { code: 'EGONE' });
    return m;
  };
  const abs = (m: any, path: string): string => {
    const p = path.startsWith('/') ? path : `${m.root}/${path}`;
    const out: string[] = [];
    for (const seg of p.split('/')) {
      if (seg === '' || seg === '.') continue;
      if (seg === '..') out.pop();
      else out.push(seg);
    }
    return `/${out.join('/')}`;
  };
  const parent = (p: string) => p.slice(0, p.lastIndexOf('/')) || '/';
  /** A full filesystem or a file over the cap, as an error that says so (undefined for any other error). */
  const capError = (err: unknown): Error | undefined => {
    const message = String((err as Error)?.message ?? err);
    if (message.startsWith('ENOSPC')) return Object.assign(new Error(`${message}: the workspace is full. Delete files to make room.`), { code: 'ENOSPC' });
    if (message.startsWith('EFBIG')) return Object.assign(new Error(message), { code: 'EFBIG' });
    return undefined;
  };
  /** Run `fn` with the file size cap off: the machine is made to hold what a record has. */
  const restoring = async <T>(m: any, fn: () => Promise<T>): Promise<T> => {
    m.fs.uncapped = true;
    try {
      return await fn();
    } finally {
      m.fs.uncapped = false;
    }
  };
  /** Run a write, its cap errors saying what they are. */
  const capped = async <T>(fn: () => Promise<T>): Promise<T> => {
    try {
      return await fn();
    } catch (err) {
      throw capError(err) ?? err;
    }
  };
  const typeOf = (s: any) => (s.isSymbolicLink ? 'symlink' : s.isDirectory ? 'directory' : 'file');
  const statOf = (s: any) => ({ type: typeOf(s), size: s.size, mode: s.mode & 0o7777, mtimeMs: s.mtime instanceof Date ? s.mtime.getTime() : 0 });
  const under = (m: any, p: string) => p.startsWith(`${m.root}/`);
  /** Regular files under the root, links followed: path to bytes and mode. */
  const files = async (m: any): Promise<Map<string, { bytes: Uint8Array; mode: number }>> => {
    const out = new Map();
    for (const p of m.fs.getAllPaths()) {
      if (!under(m, p)) continue;
      const s = await m.fs.stat(p).catch(() => undefined);
      if (!s?.isFile) continue;
      out.set(p, { bytes: await m.fs.readFileBuffer(p), mode: s.mode & 0o7777 });
    }
    return out;
  };
  const put = async (m: any, p: string, bytes: Uint8Array, mode: number) => {
    await m.fs.mkdir(parent(p), { recursive: true });
    await m.fs.writeFile(p, bytes);
    // just-bash leaves a written file at 0o644, whatever it was: set the mode after the write.
    await m.fs.chmod(p, mode);
  };
  /** Make every link under the root a copy of the file it names, or nothing (a dangling link, a link to a directory). */
  const unlink = async (m: any) => {
    for (const p of m.fs.getAllPaths()) {
      if (!under(m, p)) continue;
      if (!(await m.fs.lstat(p).catch(() => undefined))?.isSymbolicLink) continue;
      const target = await m.fs.stat(p).catch(() => undefined);
      const file = target?.isFile ? { bytes: await m.fs.readFileBuffer(p), mode: target.mode & 0o7777 } : undefined;
      await m.fs.rm(p, { force: true });
      if (file) await put(m, p, file.bytes, file.mode);
    }
  };
  return {
    async create(id: string, options: { root: string; maxBytes: number; maxFileBytes: number; timeoutMs: number; commands: readonly string[] }) {
      const { maxFileBytes } = options;
      const sizeOf = (c: string | Uint8Array, o: unknown) => {
        if (typeof c !== 'string') return c.length;
        const enc = typeof o === 'string' ? o : (o as { encoding?: string } | undefined)?.encoding;
        return enc && enc !== 'utf8' && enc !== 'utf-8' ? c.length : encoder.encode(c).length;
      };
      const tooLarge = (p: string) =>
        Object.assign(new Error(`EFBIG: ${p} would be over the workspace's largest file size (${maxFileBytes} bytes)`), { code: 'EFBIG' });
      // Every write goes through writeFileSync (writeFile calls it) or appendFile: the file size cap is
      // there. Off while the machine is made to hold what a record has (`apply`, `rollback`).
      // (No class fields: this function's source runs as written in the worker, whatever transpiled it.)
      const Base: new (files: unknown, options: { maxTotalBytes: number }) => any = jb.InMemoryFs;
      class CappedFs extends Base {
        writeFileSync(p: string, c: string | Uint8Array, o?: unknown, meta?: unknown) {
          if (!this.uncapped && sizeOf(c, o) > maxFileBytes) throw tooLarge(p);
          return super.writeFileSync(p, c, o, meta);
        }
        async appendFile(p: string, c: string | Uint8Array, o?: unknown) {
          const before = await this.stat(p).then((s: { size: number }) => s.size, () => 0);
          if (!this.uncapped && before + sizeOf(c, o) > maxFileBytes) throw tooLarge(p);
          return super.appendFile(p, c, o);
        }
      }
      const fs = new CappedFs(undefined, { maxTotalBytes: options.maxBytes });
      await fs.mkdir(options.root, { recursive: true });
      const bash = new jb.Bash({
        fs,
        cwd: options.root,
        commands: [...options.commands],
        executionLimitProfile: config.profile,
        // The command's own deadline; a worker that runs past it anyway is ended (worker.ts).
        executionLimits: { ...config.limits, maxExecutionTimeMs: options.timeoutMs },
        defenseInDepth: config.defenseInDepth,
      });
      machines.set(id, { fs, bash, root: options.root, checkpoint: undefined });
    },
    dispose(id: string) {
      machines.delete(id);
    },
    async exec(id: string, command: string, options: { cwd?: string; env?: Record<string, string>; args?: string[]; stdin?: string } = {}, signal?: AbortSignal) {
      const m = get(id);
      try {
        const r = await m.bash.exec(command, {
          ...(options.cwd ? { cwd: abs(m, options.cwd) } : {}),
          ...(options.env ? { env: options.env } : {}),
          ...(options.args ? { args: options.args } : {}),
          ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
          ...(signal ? { signal } : {}),
        });
        // just-bash stopped it at the machine's time limit: it says so, last on stderr, and exits 124. (Its
        // deadline fires from a timer as well as from its own checks, and a timer can fire early, so how
        // long the command took cannot tell this from a command that exits 124 itself. A command that
        // prints that line itself and exits 124 is taken at its word: it fails the same way.)
        const limited = r.exitCode === 124 && /(?:^|\n)bash: [^\n]* exceeded (?:its execution deadline|execution deadline \(\d+ms\))\n$/.test(r.stderr);
        return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, ...(limited ? { limited: true } : {}) };
      } catch (err) {
        // A full workspace (or a file over the size cap) can escape just-bash as a thrown error: it is the command's failure.
        const full = capError(err);
        if (!full) throw err;
        return { exitCode: 1, stdout: '', stderr: `${full.message}\n` };
      }
    },
    async readFile(id: string, path: string) {
      const m = get(id);
      return m.fs.readFileBuffer(abs(m, path));
    },
    async writeFile(id: string, path: string, content: string | Uint8Array, options: { mode?: number; append?: boolean } = {}) {
      const m = get(id);
      const p = abs(m, path);
      const before = await m.fs.stat(p).catch(() => undefined);
      await m.fs.mkdir(parent(p), { recursive: true });
      await capped(() => (options.append ? m.fs.appendFile(p, bytesOf(content)) : m.fs.writeFile(p, bytesOf(content))));
      const mode = options.mode ?? (before?.isFile ? before.mode & 0o7777 : undefined);
      if (mode !== undefined) await m.fs.chmod(p, mode);
    },
    async stat(id: string, path: string) {
      const m = get(id);
      const s = await m.fs.stat(abs(m, path)).catch(() => undefined);
      return s ? statOf(s) : undefined;
    },
    async lstat(id: string, path: string) {
      const m = get(id);
      const s = await m.fs.lstat(abs(m, path)).catch(() => undefined);
      return s ? statOf(s) : undefined;
    },
    async list(id: string, dir: string) {
      const m = get(id);
      const p = abs(m, dir);
      const out = [];
      for (const name of [...(await m.fs.readdir(p))].sort()) {
        const s = await m.fs.lstat(`${p === '/' ? '' : p}/${name}`).catch(() => undefined);
        if (s) out.push({ name, type: typeOf(s) });
      }
      return out;
    },
    async walk(id: string, dir?: string) {
      const m = get(id);
      const root = abs(m, dir ?? m.root);
      const prefix = root === '/' ? '/' : `${root}/`;
      const out = [];
      for (const p of [...m.fs.getAllPaths()].sort()) {
        if (!p.startsWith(prefix) || p === root) continue;
        const l = await m.fs.lstat(p).catch(() => undefined);
        if (!l) continue;
        const s = l.isSymbolicLink ? await m.fs.stat(p).catch(() => undefined) : l;
        if (!s) continue;
        out.push({ path: p, ...statOf(s), ...(l.isSymbolicLink ? { link: true } : {}) });
      }
      return out;
    },
    async mkdir(id: string, path: string, options: { recursive?: boolean } = {}) {
      const m = get(id);
      await m.fs.mkdir(abs(m, path), { recursive: options.recursive ?? false });
    },
    async remove(id: string, path: string, options: { recursive?: boolean; force?: boolean } = {}) {
      const m = get(id);
      await m.fs.rm(abs(m, path), options);
    },
    async rename(id: string, from: string, to: string) {
      const m = get(id);
      await m.fs.mv(abs(m, from), abs(m, to));
    },
    async symlink(id: string, target: string, path: string) {
      const m = get(id);
      await m.fs.symlink(target, abs(m, path));
    },
    async readlink(id: string, path: string) {
      const m = get(id);
      return m.fs.readlink(abs(m, path));
    },
    async realpath(id: string, path: string) {
      const m = get(id);
      return m.fs.realpath(abs(m, path));
    },
    async chmod(id: string, path: string, mode: number) {
      const m = get(id);
      await m.fs.chmod(abs(m, path), mode);
    },
    /** Every regular file under the root. */
    async snapshot(id: string) {
      const out = [];
      for (const [p, f] of await files(get(id))) out.push([p, f.bytes, f.mode]);
      return out;
    },
    /** Remove `removes`, write `writes` (bytes and mode), and set `chmods` (mode only). */
    async apply(id: string, writes: [string, Uint8Array, number][], removes: string[], chmods: [string, number][] = []) {
      const m = get(id);
      await restoring(m, async () => {
        for (const p of removes) await m.fs.rm(p, { force: true });
        for (const [p, bytes, mode] of writes) await capped(() => put(m, p, bytes, mode));
        for (const [p, mode] of chmods) await m.fs.chmod(p, mode);
      });
    },
    async checkpoint(id: string) {
      const m = get(id);
      m.checkpoint = await files(m);
    },
    /** What changed under the root since the checkpoint (`null`: removed); with `unlink`, links become copies first. */
    async diff(id: string, options: { unlink?: boolean } = {}) {
      const m = get(id);
      if (!m.checkpoint) throw new Error('diff without a checkpoint');
      if (options.unlink) await unlink(m);
      const after = await files(m);
      const out = [];
      for (const [p, f] of after) {
        const b = m.checkpoint.get(p);
        if (!b || b.mode !== f.mode || !sameBytes(b.bytes, f.bytes)) out.push([p, f.bytes, f.mode]);
      }
      for (const p of m.checkpoint.keys()) if (!after.has(p)) out.push([p, null, 0]);
      return out;
    },
    /** Put the files under the root back to the checkpoint (links a call made go first: a checkpoint holds none). */
    async rollback(id: string) {
      const m = get(id);
      const before = m.checkpoint;
      if (!before) return;
      await restoring(m, async () => {
        for (const p of m.fs.getAllPaths()) {
          if (under(m, p) && (await m.fs.lstat(p).catch(() => undefined))?.isSymbolicLink) await m.fs.rm(p, { force: true });
        }
        const now = await files(m);
        for (const p of now.keys()) if (!before.has(p)) await m.fs.rm(p, { force: true });
        for (const [p, f] of before) {
          const n = now.get(p);
          if (!n || n.mode !== f.mode || !sameBytes(n.bytes, f.bytes)) await put(m, p, f.bytes, f.mode);
        }
      });
    },
    async release(id: string) {
      get(id).checkpoint = undefined;
    },
  };
}

export type MachineOps = ReturnType<typeof machineOps>;
export type MachineOp = keyof MachineOps;