Skip to content

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

8.5 KB
Raw Blame
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';

/**
 * The sandbox lane's VCR image (P6): a Vercel Container Registry
 * image with Node 24, the daemon bundle and its compile cache preinstalled
 * under `/opt/harness-image`, tagged with the bundle's content-addressed
 * version. A VM created from it starts its daemon with one detached command:
 * no `writeFiles` of the 5+ MB bundle, no installed-version check.
 *
 * `/opt/harness-image` is never written at runtime, so a VM whose `hostImage`
 * tag names a version is guaranteed to hold that version's bundle there (the
 * classic path installs into `/opt/harness` instead, and both launchers share
 * that directory's pidfile, lock and log, so either replaces the other's
 * daemon).
 */

/** Where the image keeps the bundle (read-only at runtime). */
export const IMAGE_DIR = '/opt/harness-image';
/** The runtime directory both launch paths share: `host.env`, pidfile, lock, log. */
export const HOST_DIR = '/opt/harness';
/** The VM tag recording which bundle version its image holds. */
export const IMAGE_TAG_KEY = 'hostImage';
/** The VCR repository the image is pushed to (in the demo's project). */
export const DEFAULT_IMAGE_REPO = 'harness-host';

/** The bundle version a bundle directory holds (its `manifest.json`), if any. */
export function bundleVersion(dir: string): string | undefined {
  try {
    return (JSON.parse(readFileSync(`${dir}/manifest.json`, 'utf8')) as { version?: string }).version;
  } catch {
    return undefined;
  }
}

/**
 * The provider options for the image (`HARNESS_SANDBOX_IMAGE`: a VCR
 * repository in the project, `1` for `harness-host`; unset or `0` is off):
 * `<repo>:<version>` plus the `hostImage` tag. Empty without a version.
 */
export function imageOptions(
  setting: string | undefined,
  version: string | undefined
): { image?: string; imageTags?: Record<string, string>; imagePrefetch?: string[] } {
  if (!setting || setting === '0' || !version) return {};
  const repo = setting === '1' ? DEFAULT_IMAGE_REPO : setting;
  // A fresh VM reads the image's blocks lazily: the daemon's first start
  // read its bundle cold (~0.8 s vs ~0.4 s warm), so connect warms them.
  return { image: imageRef(repo, version), imageTags: { [IMAGE_TAG_KEY]: imageTag(version) }, imagePrefetch: [IMAGE_DIR, '/usr/local/bin/node'] };
}

let recipe: string | undefined;
/**
 * The image's tag for a bundle version: `<version>-<recipe hash>`. The
 * launcher and the Dockerfile are baked into the image but are not part of
 * the bundle's version, so a change to either names a new image.
 */
export function imageTag(version: string): string {
  recipe ??= createHash('sha256').update(imageLaunchScript()).update(dockerfile()).digest('hex').slice(0, 8);
  return `${version}-${recipe}`;
}

/** `repo:<imageTag>`: the image of one bundle version. */
export function imageRef(repo: string, version: string): string {
  return `${repo}:${imageTag(version)}`;
}

/** Whether a VM's tags say it was created from the image of this bundle version (and this launcher). */
export function hasImageFor(tags: Record<string, string> | undefined, version: string): boolean {
  return tags?.[IMAGE_TAG_KEY] === imageTag(version);
}

/** `[/]opt/harness(-image)?/daemon[.]mjs`: matches either path's daemon, never a pkill's own argv. */
export const DAEMON_PATTERN = '[/]opt/harness(-image)?/daemon[.]mjs';

/** The health check a launcher runs before replacing a daemon: exit 0 if one of this version serves this VM session. */
export const HEALTH_JS =
  "fetch('http://127.0.0.1:'+process.argv[1]+'/health',{signal:AbortSignal.timeout(1500)}).then(r=>r.json()).then(h=>process.exit(h.version===process.argv[2]&&h.sessionId===process.argv[3]?0:1),()=>process.exit(1))";

const q = (v: string) => `'${v.replace(/'/g, `'\\''`)}'`;

export interface ImageLaunchOptions {
  /** `/opt/harness-image` (tests point it elsewhere). */
  image?: string;
  /** `/opt/harness`. */
  dir?: string;
  /** `node`. */
  node?: string;
  /** Skip the root-only steps (tests run it unprivileged). */
  unprivileged?: boolean;
}

/**
 * The image's launcher, baked in at `<image>/launch.sh` and run as root,
 * detached, with everything in its environment (`runCommand({ env })`):
 * `HOST_PORT`, `HOST_VERSION`, `HOST_SANDBOX_SESSION`, `HOST_RUN_AS` and,
 * named by `HOST_ENV_KEYS`, every key the daemon's `host.env` gets. It
 * writes `host.env` (root, 0600) from those, then runs the daemon with
 * those keys removed from its environment, so the secrets live only in the
 * file the daemon deletes once read. Same per-VM start lock and reuse rule as the
 * classic launcher (`launchScript`).
 */
export function imageLaunchScript(o: ImageLaunchOptions = {}): string {
  const img = o.image ?? IMAGE_DIR;
  const dir = o.dir ?? HOST_DIR;
  const node = o.node ?? 'node';
  return [
    '#!/bin/bash',
    'set -e',
    `HD=${q(dir)}; IMG=${q(img)}; NODE=${q(node)}`,
    'PORT="${HOST_PORT:-3000}"; V="${HOST_VERSION:?HOST_VERSION is required}"; S="${HOST_SANDBOX_SESSION:?HOST_SANDBOX_SESSION is required}"; RUN_AS="${HOST_RUN_AS:-harness-run}"',
    'mkdir -p "$HD"',
    'exec 9>"$HD/.start.lock"',
    'if command -v flock >/dev/null 2>&1; then flock -w 60 9; fi',
    `if "$NODE" -e ${q(HEALTH_JS)} "$PORT" "$V" "$S"; then echo "reuse"; exit 0; fi`,
    // The tag said this version; refuse anything else rather than run it.
    'if ! grep -q "\\"version\\": *\\"$V\\"" "$IMG/manifest.json" 2>/dev/null; then echo "image holds another bundle than $V" >> "$HD/daemon.log"; exit 3; fi',
    '( umask 077; : > "$HD/host.env"; for k in ${HOST_ENV_KEYS:-}; do printf \'%s=%s\\n\' "$k" "${!k//$\'\\n\'/}" >> "$HD/host.env"; done )',
    'chmod 600 "$HD/host.env"',
    ...(o.unprivileged
      ? []
      : [
          'if [ "$(id -u)" = 0 ]; then',
          '  chown root:root "$HD/host.env"',
          '  id -u "$RUN_AS" >/dev/null 2>&1 || useradd -m -s /bin/bash "$RUN_AS"',
          '  mkdir -p /workspace /tmp/harness && chown -R "$RUN_AS:$RUN_AS" /workspace && chmod 755 /tmp/harness',
          'fi',
        ]),
    'if [ -f "$HD/daemon.pid" ]; then kill "$(cat "$HD/daemon.pid")" >/dev/null 2>&1 || true; fi',
    `pkill -f ${q(DAEMON_PATTERN)} >/dev/null 2>&1 || true`,
    'echo $$ > "$HD/daemon.pid"',
    'cd "$IMG"',
    // Drop what went into host.env (the secrets live only in the file the
    // daemon deletes once read); keep the rest of the command's environment:
    // the sandbox sets NODE_USE_SYSTEM_CA / NODE_EXTRA_CA_CERTS there, which
    // the daemon needs to trust the egress proxy on intercepted hosts.
    'for k in ${HOST_ENV_KEYS:-}; do unset "$k"; done; unset HOST_ENV_KEYS',
    'export HOST_LOCK_FD=9 NODE_COMPILE_CACHE="$IMG/.compile-cache"',
    'exec "$NODE" "$IMG/daemon.mjs" --env "$HD/host.env" >> "$HD/daemon.log" 2>&1',
    '',
  ].join('\n');
}

/**
 * The image's Dockerfile, built `linux/amd64` with the bundle and
 * `launch.sh` in the context. The managed `vercel/sandbox/*` images are not
 * pullable from VCR, so this rebuilds their open-source base
 * (github.com/vercel/sandbox `images/ubuntu` + `images/node`): Ubuntu 26.04,
 * the `ubuntu` user with passwordless sudo, `HOME=/vercel`, Node 24
 * (`node/` in the context: the official linux-x64 tarball) and git,
 * plus what the launcher and the bash tool need (procps, python3, curl, jq,
 * ripgrep). Then it warms Node's compile cache by loading every module the
 * daemon would (`HOST_WARM=1`).
 */
export function dockerfile(): string {
  return `# syntax=docker/dockerfile:1
FROM ubuntu:26.04 AS base
ENV LANG=C.UTF-8
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && \\
    apt-get install -y --no-install-recommends ca-certificates sudo git libatomic1 procps curl jq ripgrep python3 python-is-python3 && \\
    rm -rf /var/lib/apt/lists/*
RUN printf '%s\\n' 'Defaults always_set_home' 'Defaults !env_reset' 'Defaults !fqdn' 'ubuntu ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/sandbox && \\
    chmod 0440 /etc/sudoers.d/sandbox && \\
    install -d -o ubuntu -g ubuntu /vercel && usermod --home /vercel ubuntu

FROM base
# Node's linux-x64 tarball, unpacked by scripts/image.mjs on the build host
# (tar under amd64 emulation fails on some hosts).
COPY node/ /usr/local/
COPY bundle/ ${IMAGE_DIR}/
COPY launch.sh ${IMAGE_DIR}/launch.sh
RUN chmod 755 ${IMAGE_DIR}/launch.sh && \\
    useradd -m -s /bin/bash harness-run && \\
    mkdir -p ${HOST_DIR} /workspace && chown harness-run:harness-run /workspace && \\
    cd ${IMAGE_DIR} && HOST_WARM=1 NODE_COMPILE_CACHE=${IMAGE_DIR}/.compile-cache node daemon.mjs && \\
    node --version
ENV HOME=/vercel
ENV SHELL=/bin/bash
USER ubuntu
WORKDIR /vercel
`;
}