Skip to content

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

20.2 KB
Raw Blame
import type { ChaosKind, Drill, DrillTarget, DriveFence } from 'harness-world';
import type { WorkspaceMachine } from 'harness-world-hands/runtime';

/**
 * Where a process harness's CLI runs, as types (docs/workspaces.md §3.1,
 * §4.1, §5.4). Shared by the harness packages, which can't import
 * durable-harness, and by the sandbox tier that implements them; nothing
 * here runs a process.
 *
 * - `SessionMachine`: one session's VM, as the driver holds it for one
 *   invocation: spawn the CLI on it, upload and wipe its cache files, tail a
 *   file the CLI writes, flush the Drive, and its `/workspace` as a
 *   `WorkspaceMachine` (files and commands, for a Function-tier runtime's
 *   tools). Implemented by the sandbox tier's session factory over the in-VM
 *   relay, and branded and frozen there (`harness-world-process/machine-brand`),
 *   so a harness that must run only in a sandbox (Claude Code, Codex) can
 *   refuse a hand-written one by provenance, not by shape.
 * - `AcquireMachine`: how a runtime gets one, with the fencing token it
 *   arms the relay with (the kernel's `DriveContext.fence`; pi-durable and
 *   libfx supply their own).
 * - `LineChannel`: a child's stdio as line-oriented harness code uses it
 *   (Codex's app-server client, the reference harness): a `HostedProcess`
 *   on this machine and a `SessionProcess` in a VM are both one.
 * - `ProcessHostLike`: what a process harness asks of its host, so the host
 *   can be `ProcessHost` (this machine: the reference harness, tests) or
 *   one in a VM.
 * - `GatewayHandler`: the driver's side of the VM's model port: a relayed
 *   model request in, the Gateway's response out (§5.5).
 *
 * The files and commands a Function-tier harness's tools use are
 * harness-world-hands' `WorkspaceMachine` (its `/runtime` entry), not these.
 */

// ---------------------------------------------------------------------------
// Fencing

/**
 * A token that only rises across the owners of a session, and stays the
 * same for one owner: a newer owner's is higher, and no two owners hold the
 * same one. The relay records the highest it was armed with, refuses a
 * lower one, and lets a higher one kill the session's processes (§5.4).
 * The kernel's is `DriveContext.fence` (the count of the drive's first
 * accepted in-band write); a runtime with its own log supplies its own
 * (pi-world `WorldStorage`'s fence, libfx's lease). `fenced: false` says the
 * owner's own writes are no longer fenced (see `DriveFence.fenced`).
 */
export type FenceToken = DriveFence;

// ---------------------------------------------------------------------------
// A child's stdio

/** How a child exited (`signal` is the signal's name). */
export interface ChannelExit {
  code: number | null;
  signal: string | null;
}

/** A child's stdio, line by line: what line-oriented harness code reads and writes. */
export interface LineChannel {
  /** Write one line to the child's stdin (a value is sent as JSON). False once stdin is closed. */
  send(line: unknown): boolean;
  /** Close the child's stdin. */
  end(): void;
  /** The child's stdout, line by line. One reader per process. */
  lines(): AsyncIterable<string>;
  /** Resolves when the child exits (never rejects). */
  readonly exited: Promise<ChannelExit>;
  /** The last few KB of stderr. */
  stderrTail(): string;
}

/** The signals a harness may send a child (the ones the relay's `KILL` accepts). */
export type KillSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT';

/** A running child, wherever it runs: its stdio, and a way to stop it with everything it started. */
export interface ProcessLike extends LineChannel {
  /** Whether it is still running. */
  alive(): boolean;
  /** Kill it and everything it started (its process group here; the session's cgroup in a VM). Default `SIGTERM`. */
  kill(signal?: KillSignal): void;
}

// ---------------------------------------------------------------------------
// The host a process harness runs its child on

/** What a process harness spawns. */
export interface ProcessSpawn {
  command: string;
  args?: string[];
  /** The child's whole environment, on top of what the host sets itself: nothing else is inherited. */
  env?: Record<string, string | undefined>;
  /** Default: the host's directory for the session. */
  cwd?: string;
  /** Kill the child when this aborts. */
  signal?: AbortSignal;
  /**
   * Runs with the session claimed, after a child a previous drive left is
   * killed and before this one starts: rebuild the harness's native session
   * files here (from the journal), so no other drive of this host starts a
   * child, and no stale one writes, in between. On a host over a
   * `SessionMachine` that is `files.upload` before the `SPAWN`, and the
   * claim is the relay's fence (the arm this driver holds).
   */
  prepare?: () => Promise<void> | void;
}

/**
 * What a process harness asks of the host its child runs on. `ProcessHost`
 * (this machine) is one; a host the sandbox tier builds over a branded
 * `SessionMachine` is another. The session is claimed for one child at a
 * time: a spawn while another drive of this host runs the session's child
 * throws `Yield('contended')`. stderr is always kept as a tail
 * (`stderrTail()`), as the relay keeps it.
 *
 * Not interchangeable for callers: a ProcessHostLike carries no brand, so
 * Claude Code and Codex never take one from their options (that would let
 * a host `child_process` in). They take a branded `SessionMachine` and build
 * their host from it internally. `ProcessHost` is for the reference
 * harness, the relay and tests only (docs/workspaces.md §6 rules 1 and 3).
 */
export interface ProcessHostLike {
  /** Start the session's child (after killing one a previous drive left running). */
  spawn(runId: string, options: ProcessSpawn): Promise<ProcessLike>;
  /** Whether a drive of this host runs (or is starting) the session's child. */
  busy(runId: string): boolean;
  /** Kill a child (and what it started) a previous drive left running, before a resume. Returns what it killed. */
  killStale(runId: string): Promise<unknown>;
  /** Kill what the session's tools started that is still running (at the drive's end). Returns what it killed. */
  killGroups(runId: string): Promise<unknown>;
}

// ---------------------------------------------------------------------------
// A session's VM

/** The per-session cache directories in the VM, wiped before every spawn (§5.2): HOME, the CLIs' config homes, TMPDIR, XDG caches. */
export type CacheDir = 'home' | 'config' | 'codex-home' | 'tmp' | 'cache';

/** One file to upload into a cache directory, at a path relative to it (no `..`, not absolute). */
export interface CacheFile {
  path: string;
  bytes: Uint8Array;
  /** Default 0o600. */
  mode?: number;
}

/** What a harness spawns on a `SessionMachine`. The relay rebuilds the child's environment from its own allowlist plus `env`. */
export interface MachineSpawn {
  command: string;
  args?: string[];
  /**
   * Variables for the child, on top of the relay's allowlist: the one
   * channel through which a credential could reach the VM (decision 6).
   * The relay can't judge a secret, so the session factory checks every
   * spawn's `env` in the Function before it is sent: §3.1's name and value
   * rules (`sandbox({ env })`'s), and no value equal to a `process.env`
   * value of 16 or more characters. A failing key is a `TypeError` naming
   * the key, never the value. Every harness inherits the check (A3 tests
   * it once).
   */
  env?: Record<string, string>;
  /** Default the workspace root (`/workspace`). */
  cwd?: string;
  /** Kill the session's processes when this aborts. */
  signal?: AbortSignal;
  /**
   * The child's own commands run in a pid namespace of their own (Claude
   * Code's sandbox), or it runs none (its built-ins off). The model port
   * admits a CLI that can be traced from the VM only when this is set: a
   * command beside a traceable CLI could read its key from its environ, or
   * take its model socket (§5.5). Codex needs no claim: its binary is
   * installed execute-only, so the process is not dumpable.
   */
  isolatedCommands?: boolean;
}

/** A child on a `SessionMachine`: its stdio over the relay. `kill` always takes the session's whole cgroup. */
export interface SessionProcess extends ProcessLike {}

/**
 * A line-complete tail of a file the CLI appends to under its cache
 * directory (a Codex rollout), served in the VM by the unprivileged helper.
 * The same shape as `FileTail`: `read()` returns what has arrived since.
 */
export interface MachineTail {
  /** Byte offset consumed so far. */
  readonly offset: number;
  /** The complete lines that arrived since the last read. Throws once the file shrank or was replaced. */
  read(): string[];
  /** Wait until every line the file holds now has arrived (`SYNC`). */
  sync(): Promise<void>;
  close(): void;
}

/**
 * One session's VM, for one driver: what a process harness spawns its CLI
 * on. Every byte it returns came from an untrusted VM: callers bound and
 * parse it strictly, and never use a path it reports on their own fs.
 */
export interface SessionMachine {
  /** Provenance: set only by the sandbox tier's session factory (`machineBrand`); checked with `isBrandedMachine`. */
  readonly brand: MachineBrand;
  /** The session (`runId`). */
  readonly sessionId: string;
  /**
   * The token the relay was armed with for this attach, read once when the
   * runtime owned the session and reused for every arm and re-arm of it
   * (a dropped socket, a relay restart), so the relay sees one token per
   * owner. Undefined: none (a World without the in-band fence).
   */
  readonly fence: FenceToken | undefined;
  /** The workspace root: `/workspace`, the Drive. */
  readonly root: string;
  /**
   * The session's `/workspace` as files and commands (`RemoteMachine`: the
   * relay's helper over `ENV_CALL`, as the unprivileged user, rooted at
   * `/workspace`): what a Function-tier runtime's tools run on in a sandbox,
   * the same interface as `virtual()`'s.
   */
  readonly workspace: WorkspaceMachine;
  /** The cache directories, as paths in the VM. */
  readonly dirs: Readonly<Record<CacheDir, string>>;
  /** Aborted when the link to the VM is lost (a socket dropped, the relay superseded or gone): re-attach. */
  readonly signal: AbortSignal;
  /**
   * The model port in the VM, as the CLI's base URL (`http://127.0.0.1:4100`):
   * every request the CLI sends there is relayed over `/model` to the
   * `GatewayHandler` the acquire passed (§5.5).
   */
  readonly modelUrl: string;
  /**
   * The CLI's model key `P` for this attach (§5.5): give it to the CLI as its
   * API key (`ANTHROPIC_AUTH_TOKEN`, Codex's `env_key`). The relay admits a
   * model request only with it, and only from a process this attach spawned,
   * so it is a placeholder, not a credential: it authorizes nothing outside
   * this VM's model port. The spawn env check lets its variable name through
   * only with exactly this value.
   */
  readonly modelKey: string;
  /**
   * What the model must be told about this attach (§5.7): today only that
   * the session's files were lost (a new Drive). Frozen; empty when nothing
   * changed. Every machine of the invocation carries it, and every later
   * attach does too until the runtime acknowledges it in the turn that
   * told the model (the record's `filesLost`; the kernel's harness clears it
   * with `acknowledgeNotes` on the `hw.sandbox` document), so a turn that
   * failed before the model saw it shows it again.
   */
  readonly notes: readonly string[];
  /**
   * What `notes` describe (the new Drive's id while the "files lost" note is
   * shown), for the runtime to acknowledge exactly them: an acknowledgement
   * of an older key leaves a loss recorded since in place. Undefined when
   * there are no notes.
   */
  readonly notesKey?: string;
  /** Start a process in the session's cgroup, as the unprivileged user. Rejects with a `TypeError` for an `env` the checks refuse (`MachineSpawn.env`). */
  spawn(options: MachineSpawn): Promise<SessionProcess>;
  /** The session's cache files (`FILES`, `WIPE`). */
  readonly files: {
    /** Unpack `files` into `dir` (freshly wiped), as the unprivileged user. */
    upload(dir: CacheDir, files: readonly CacheFile[]): Promise<void>;
    /** Delete every cache directory and make them again, empty. */
    wipe(): Promise<void>;
  };
  /** Follow a file under `dir` from `offset` (default 0): `path` is relative to it, and the helper refuses anything outside. */
  tail(dir: CacheDir, path: string, options?: { offset?: number }): Promise<MachineTail>;
  /** Flush the Drive's writes (`sync -f /workspace`): before a mutating call's outcome is recorded. */
  fsync(): Promise<void>;
  /** Kill the session's processes and close the link. The VM and the Drive stay. */
  close(): Promise<void>;
}

/**
 * What a runtime keeps about its session's sandbox (docs/workspaces.md §5.7;
 * the kernel's is the `hw.sandbox` document). The Drive is the record: its
 * name comes from the session, and it carries its own region and size, so
 * this exists only to notice change. A `driveId` other than the stored one
 * means the files were lost: `filesLost` keeps the new id until the runtime
 * acknowledges the note (`SessionMachine.notes`); `versions` only move
 * forward (a newer recorded CLI than the image's is
 * `Unavailable('cli_version')`), and hold only versions the driver pins
 * itself, never one a VM merely reported; `vmSeconds` is the VM time granted
 * so far, against `sandbox({ budget: { vmSeconds } })`, written as soon as it
 * is granted (before the arm), so a delivery that fails after a grant still
 * counts it. The rest is for diagnosis.
 */
export interface MachineRecord {
  readonly sandboxName?: string;
  readonly driveName?: string;
  readonly driveId?: string;
  readonly region?: string;
  readonly driveSize?: number;
  readonly image?: string;
  readonly versions?: Readonly<Record<string, string>>;
  readonly vmSeconds?: number;
  /** The `driveId` of a Drive the model has not been told is new yet (the "files lost" note is in `notes` while it is set). */
  readonly filesLost?: string;
}

/** Where a runtime reads and writes its `MachineRecord`, in a document it already has (the kernel: `hw.sandbox`, in the attach fact's body). */
export interface MachineRecordStore {
  read(): MachineRecord | undefined | Promise<MachineRecord | undefined>;
  write(record: MachineRecord): void | Promise<void>;
}

/** How a runtime gets its session's machine. */
export interface AcquireMachineRequest {
  sessionId: string;
  /**
   * The runtime's fencing token, read once per acquire, after the runtime
   * owns the session (for the kernel: inside the body of the `sandbox.attach`
   * fact, `DriveContext.fence`), and reused for every arm and re-arm of
   * that acquire (`SessionMachine.fence`). Within one invocation its count
   * stays the same; a later read may only narrow it (`fenced` turned false),
   * and the session factory then stops every machine of the invocation from
   * mutating the VM.
   *
   * Undefined (no token: a World without the in-band fence) or not
   * `fenced`: the token never preempts a recorded one, and is admitted only
   * once the old sockets are dead (the relay refuses a second driver at the
   * same token instead of letting it preempt). A token that is not `fenced`
   * also gets no fresh VM armed, and no `WIPE`, `FILES` or mutating
   * `SPAWN`/`ENV_CALL` from the session factory: on a fresh VM the World's
   * fence is the only guard, and that drive is no longer behind it.
   */
  fence: () => FenceToken | undefined;
  /**
   * The invocation's own signal: the session factory keeps one attach per
   * session per signal, so an acquire after a loss within the same
   * invocation re-attaches with the count it read the first time; when the
   * signal aborts, the invocation's links close.
   */
  signal: AbortSignal;
  /**
   * The session's config as its log recorded it (its `run_created`'s:
   * the kernel's `DriveContext.config`, pi-world's `WorldStorage.config`),
   * for the factory's admission checks: durable-harness's `sandbox()`
   * refuses a session a public chat route started without its opt-in
   * before any VM boots. Every runtime passes it, `undefined` when the
   * session recorded none; durable-harness's acquire refuses a request
   * without the key at all (a runtime that forgot it fails closed).
   */
  config?: unknown;
  /**
   * Where the session's `MachineRecord` lives. Without one, a lost Drive is
   * never noticed; the session factory refuses (a `TypeError`) to go without
   * one when `budget.vmSeconds` is finite, since the budget would then hold
   * per invocation only. pi-durable and libfx pass a store backed by a
   * document they already have.
   */
  record?: MachineRecordStore;
  /**
   * Serves the CLI's model calls (`/model`, §5.5): the harness's
   * `gatewayHandler`, with its steps and budget. Without one, every model
   * call fails `internal`. A re-acquire within the invocation that passes
   * another handler rebinds the link to it.
   */
  model?: GatewayHandler;
  /** When this invocation ends (epoch ms), so the VM stays up at least that long plus `idleMs`. Default: 800 s from now (the longest Function). */
  deadline?: number;
  /**
   * The drive's drills on the session's sandbox (docs/workspaces.md §8
   * "Drills"; for the kernel: `attachInDrive` builds it from the attach
   * fact's `io.drill` and the drive's `ctx.drills`). Absent: the runtime runs
   * no drills, and the session factory carries none out.
   */
  drills?: AcquireDrills;
}

/** What a session factory needs to carry out the drills armed for a session (`AcquireMachineRequest.drills`). */
export interface AcquireDrills {
  /**
   * Claim, now, an armed attach drill of one of `kinds` (`sandbox-new-vm`,
   * `sandbox-zombie`): its chaos step is committed against the attach. The
   * drill, for the factory to carry out before it attaches; undefined when
   * none is armed.
   */
  claim(kinds: readonly ChaosKind[]): Promise<Drill | undefined>;
  /** Register what carries out the mid-step drills (`sandbox-vm` at a tool, `relay-drop`) for the drive: once per drive, however often it re-attaches. */
  register(target: DrillTarget): void;
}

/** The sandbox tier's machine acquisition (docs/workspaces.md §4.1), for runtimes with and without the kernel. */
export type AcquireMachine = (request: AcquireMachineRequest) => Promise<SessionMachine>;

// ---------------------------------------------------------------------------
// The brand

declare const brandType: unique symbol;

/**
 * An opaque provenance mark (`SessionMachine.brand`). Only the minter in
 * `harness-world-process/machine-brand` makes one; `isBrandedMachine`
 * checks it.
 */
export interface MachineBrand {
  readonly [brandType]: true;
}

// ---------------------------------------------------------------------------
// The model port

/**
 * One model request the CLI sent to its loopback port, relayed by the VM
 * (`/model`). `method` and `path` are VM-chosen text: the handler only
 * matches them against its fixed table, never joins them into a URL.
 */
export interface RelayedModelRequest {
  method: string;
  /** Pathname and query, as the CLI sent them. */
  path: string;
  headers: Readonly<Record<string, string>>;
  body: Uint8Array;
}

/** The handler's answer: allowlisted headers, and the body as it streams from the Gateway. */
export interface RelayedModelResponse {
  status: number;
  headers: Readonly<Record<string, string>>;
  body: AsyncIterable<Uint8Array>;
}

/**
 * Why the handler refused or failed a request. Fixed codes: the details go
 * to the Function's log, never to the VM. `budget` is a spend cap (the turn
 * or the session is out of money: no retry helps), `busy` the concurrency
 * cap (a retry soon may pass); the relay answers them 403 and 429.
 */
export type GatewayErrorCode = 'bad_request' | 'forbidden' | 'budget' | 'busy' | 'upstream' | 'internal';

/**
 * The driver's side of the model port (§5.5): match the request against the
 * harness's fixed table, validate its body, model and budget, call the
 * Gateway at a fixed URL with the credential, and record the step. A
 * request it refuses rejects with an error whose `code` is a
 * `GatewayErrorCode`. `signal` aborts the upstream call (`/model` closed).
 */
export type GatewayHandler = (request: RelayedModelRequest, signal: AbortSignal) => Promise<RelayedModelResponse>;