Skip to content

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

6.6 KB
Raw Blame
/**
 * The sandbox stand-in for OpenCode's tests (docs/workspaces.md §5.8, §11.4
 * B7): harness-sandbox's private fake Sandbox API (each "VM" a local relay
 * child over temp dirs, `localMachine()`'s relay; each "Drive" a temp dir
 * that outlives the VMs mounted on it), behind the real session factory
 * (`sandboxSession`: the Drive and VM lifecycle, the arm with the drive's
 * fencing token, the branded machine and its `RemoteMachine` over the
 * relay's helper).
 *
 * One thing differs from a VM, and `atWorkspace` covers it: a VM's Drive is
 * mounted at `/workspace`, the stand-in's is a temp dir, so each machine's
 * workspace is seen at `/workspace` here (paths in, and paths in what comes
 * back). Commands still run in the stand-in's temp dir, so a test's shell
 * commands use paths relative to the workspace.
 *
 * Test helpers only: guarded like the stand-in (`DH_TEST_LOCAL_SANDBOX=1`,
 * a test runner, not on Vercel, not in production).
 */
import { realpathSync, rmSync } from 'node:fs';
import type { DirEntry, ExecOptions, ExecResult, PathStat, WalkEntry, WorkspaceMachine } from 'harness-world-hands/runtime';
import type { AcquireMachine, SessionMachine } from 'harness-world-process';
import { type SandboxSessionOptions, sandboxSession, type SandboxSpec } from 'harness-world-sandbox';
import { FakeSandboxApi, type FakeApiOptions } from '../../harness-sandbox/test/fake-api.ts';

export { FakeSandboxApi };
export { relayBundle } from '../../harness-sandbox/test/local-machine.ts';

/** What `sandbox()` resolves to, as the stand-in's tests need it (the factory reads these fields). */
export const SPEC: SandboxSpec = { vcpus: 2, network: 'allow-all', idleMs: 60_000, driveSize: 10 * 1024 ** 3, budget: { vmSeconds: Infinity }, image: 'stand-in' };

/** The project the fake Sandbox API reports: a session's sandbox and Drive are named from it. */
export const STAND_IN_PROJECT = 'prj_stand_in';

const WS = '/workspace';

/** A machine's workspace seen at `/workspace` (see the module comment). */
export class AtWorkspace implements WorkspaceMachine {
  readonly root = WS;
  private readonly roots: string[];

  constructor(private readonly machine: WorkspaceMachine) {
    let real = machine.root;
    try {
      real = realpathSync(machine.root);
    } catch {}
    // The longer form first: macOS's temp dirs are under /private.
    this.roots = [...new Set([real, machine.root])].sort((a, b) => b.length - a.length);
  }

  get isolation() {
    return this.machine.isolation;
  }
  get lost() {
    return this.machine.lost;
  }

  /** A path as the stand-in has it. */
  private in(p: string): string {
    if (p === WS) return this.machine.root;
    if (p.startsWith(`${WS}/`)) return this.machine.root + p.slice(WS.length);
    return p;
  }
  /** A path as a VM would report it. */
  private out(p: string): string {
    for (const r of this.roots) {
      if (p === r) return WS;
      if (p.startsWith(`${r}/`)) return WS + p.slice(r.length);
    }
    return p;
  }
  private text(t: string): string {
    for (const r of this.roots) t = t.split(r).join(WS);
    return t;
  }

  async exec(command: string, options: ExecOptions = {}): Promise<ExecResult> {
    const r = await this.machine.exec(command, { ...options, ...(options.cwd ? { cwd: this.in(options.cwd) } : {}), ...(options.args ? { args: options.args.map((a) => this.in(a)) } : {}) });
    return { ...r, stdout: this.text(r.stdout), stderr: this.text(r.stderr) };
  }
  readFile(path: string): Promise<Uint8Array> {
    return this.machine.readFile(this.in(path));
  }
  writeFile(path: string, content: string | Uint8Array, options?: { mode?: number; append?: boolean }): Promise<void> {
    return this.machine.writeFile(this.in(path), content, options);
  }
  stat(path: string): Promise<PathStat | undefined> {
    return this.machine.stat(this.in(path));
  }
  lstat(path: string): Promise<PathStat | undefined> {
    return this.machine.lstat(this.in(path));
  }
  list(dir: string): Promise<DirEntry[]> {
    return this.machine.list(this.in(dir));
  }
  async walk(dir?: string): Promise<WalkEntry[]> {
    return (await this.machine.walk(dir === undefined ? undefined : this.in(dir))).map((e) => ({ ...e, path: this.out(e.path) }));
  }
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
    return this.machine.mkdir(this.in(path), options);
  }
  remove(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void> {
    return this.machine.remove(this.in(path), options);
  }
  rename(from: string, to: string): Promise<void> {
    return this.machine.rename(this.in(from), this.in(to));
  }
  symlink(target: string, path: string): Promise<void> {
    return this.machine.symlink(this.in(target), this.in(path));
  }
  async readlink(path: string): Promise<string> {
    return this.out(await this.machine.readlink(this.in(path)));
  }
  async realpath(path: string): Promise<string> {
    return this.out(await this.machine.realpath(this.in(path)));
  }
  chmod(path: string, mode: number): Promise<void> {
    return this.machine.chmod(this.in(path), mode);
  }
  dispose(): void {
    this.machine.dispose();
  }
}

/** The session factory's machines, each with its workspace at `/workspace` (`AtWorkspace`). */
export function atWorkspace(acquire: AcquireMachine): AcquireMachine {
  return async (request) => {
    const m = await acquire(request);
    const workspace = new AtWorkspace(m.workspace);
    return Object.freeze({ ...m, workspace }) as SessionMachine;
  };
}

/** A fake Sandbox API and the session factory over it, as OpenCode's resolved `sandbox()` workspace. */
export function standIn(options: { api?: FakeSandboxApi; apiOptions?: FakeApiOptions; factory?: Omit<SandboxSessionOptions, 'spec' | 'test'>; name?: (projectId: string, sessionId: string) => string } = {}) {
  const api = options.api ?? new FakeSandboxApi(options.apiOptions);
  const acquire = sandboxSession({ spec: SPEC, ...options.factory, test: { api, allowDegraded: true, ...(options.name ? { name: options.name } : {}) } });
  return { api, workspace: { kind: 'sandbox' as const, acquire: atWorkspace(acquire) } };
}

/**
 * A stand-in whose session sandbox has a fixed name and an existing Drive
 * (`dir`, `driveId`): for a test whose app runs in another process (each
 * process has its own fake Sandbox API, over the same Drive dir).
 */
export function seededStandIn(drive: { name: string; dir: string; driveId: string }) {
  const api = new FakeSandboxApi();
  const d = api.addDrive(drive.name);
  rmSync(d.dir, { recursive: true, force: true });
  d.dir = drive.dir;
  d.info.driveId = drive.driveId;
  return standIn({ api, name: () => drive.name });
}