Skip to content

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

16.4 KB
Raw Blame
import { type Doc, type DriveContext, type HostTool, type HostToolIO, Unavailable } from 'harness-world';
import type { ExecOptions, WorkspaceMachine } from './machine.ts';
import { type CallMode, WORKSPACE_TOOL, type WorkspaceRuntime, type WorkspaceToolDef } from './runtime.ts';
import { WORKSPACE_ROOT } from './paths.ts';

/**
 * A workspace runtime on the session's own Vercel Sandbox (`sandbox()`,
 * docs/workspaces.md §5.6): the same `runtime.tool()` tools as on a virtual
 * workspace, their files on the session's Drive at `/workspace` and their
 * commands in the session's VM (`SessionMachine.workspace`, the sandbox
 * tier's `RemoteMachine`), for a kernel harness whose core stays in the
 * Function (Pi).
 *
 * - **Lazy.** The VM is attached on the first call of a drive that reaches
 *   the workspace, so a turn that runs none boots none. The attach is the
 *   kernel's (`attachInDrive`: a `sandbox.attach` fact, with the drive's own
 *   fencing token read inside it, and the `hw.sandbox` record), once per
 *   drive, again after a lost link.
 * - **Pre-intent.** Each tool carries `beforeIntent(ctx)`, which a harness
 *   runs before it writes the call's intent (harness-world-pi does): it
 *   attaches there, so an attach that fails or is busy makes the call
 *   "not run" (`NotRun`, a definite outcome: the model may call again),
 *   never an interrupted call; one that stops the drive (preempted,
 *   superseded, `Unavailable` such as a spent `vmSeconds` budget, a link lost
 *   past its re-attaches) stops it (`ctx.halt`). A harness that doesn't run
 *   the phase gets the same outcomes, the attach inside the call's intent.
 * - **Durable, not transactional.** The Drive keeps what a call wrote, even
 *   a call a crash cut off, so a tool that may change files or run commands
 *   (`mode: 'write'`) is `replay: 'never'`: one cut off comes back
 *   interrupted, "may have taken effect", never run again by itself. Each
 *   write reaches the Drive (`FSYNC`) before its call's outcome is recorded
 *   (the machine flushes each one). A `read` tool is `safe`.
 * - **One call at a time** per drive, each on the attach's machine, its
 *   commands stopped when the call or the drive is.
 * - **Lost files.** When the session's Drive is not the one its log knew,
 *   the first call of the drive that completes says so before its result,
 *   and the record is told it was said, with that call's outcome.
 * - **Closed at the drive's end** (`afterDrive(ctx)`, which the harness
 *   calls), or once no call ran on it for `IDLE_CLOSE_MS` (a harness that
 *   doesn't call it): the machine's commands are killed and its link
 *   closed; the VM and the Drive stay, and a later call attaches again.
 *
 * The sandbox tier (harness-world-sandbox, `@vercel/sandbox`) is the
 * caller's to load (`kernelSandbox`), on the first attach, so this package
 * does not depend on it.
 */

/** What the runtime uses of an attached machine: harness-world-process' `SessionMachine`, structurally. */
export interface AttachedMachine {
  /** The session's `/workspace`, as files and commands. */
  readonly workspace: WorkspaceMachine;
  /** What the model must be told about this attach (the files were lost). */
  readonly notes: readonly string[];
  /** What `notes` describe (the new Drive's id), so the acknowledgement clears exactly them. */
  readonly notesKey?: string;
  /** Aborted when the link to the VM is lost. */
  readonly signal: AbortSignal;
  close(): Promise<void>;
}

export interface SandboxRuntimeOptions {
  /** Attach the session's machine for `ctx`'s drive (the kernel's `attachInDrive`). */
  attach(ctx: DriveContext): Promise<AttachedMachine>;
  /** Inside the effect of the call whose result told the model the machine's notes (`key`, its `notesKey`): tell the record so (`acknowledgeNotes`). */
  told(io: HostToolIO, key: string | undefined): void | Promise<void>;
}

/** The parts of harness-world-sandbox `kernelSandbox` uses (its exports, structurally). */
export interface KernelSandboxTier<Acquire, Record extends object> {
  attachInDrive(ctx: DriveContext, acquire: Acquire): Promise<AttachedMachine>;
  acknowledgeNotes(record: Record, key?: string): Record;
  readonly SANDBOX_DOC: Doc<Record>;
}

/**
 * The runtime options for a kernel drive: `acquire` (the descriptor's
 * `AcquireMachine`) through the kernel's `attachInDrive`, the notes
 * acknowledged on the `hw.sandbox` document. `load` loads the sandbox tier
 * (`() => import('harness-world-sandbox/cli')`, which loads neither the
 * factory nor `@vercel/sandbox`: `acquire` does), on the first attach only.
 */
export function kernelSandbox<Acquire, Record extends object>(acquire: Acquire, load: () => Promise<KernelSandboxTier<Acquire, Record>>): SandboxRuntimeOptions {
  let tier: Promise<KernelSandboxTier<Acquire, Record>> | undefined;
  const loaded = () => {
    const t = (tier ??= load());
    t.catch(() => {
      if (tier === t) tier = undefined;
    });
    return t;
  };
  return {
    attach: async (ctx) => (await loaded()).attachInDrive(ctx, acquire),
    async told(io, key) {
      const { acknowledgeNotes, SANDBOX_DOC } = await loaded();
      io.docs?.update(SANDBOX_DOC, (record) => acknowledgeNotes(record, key));
    },
  };
}

/** The sentence a shell tool's description gets on a sandbox: where it runs, and what a cut-off command means. */
export const SANDBOX_NOTE = "It runs in this session's own sandbox, a Linux VM; a command that was cut off (the session moved, or ran out of time) may have partly run.";

/** The system-prompt snippet for a sandbox. */
export const SANDBOX_INSTRUCTIONS = `Your workspace tools work in this session's own sandbox, a Linux VM, at ${WORKSPACE_ROOT}. Its files are kept with the session: they last across turns. A call that was cut off may have partly run.`;

/** How long a drive's machine stays attached with no call on it, when the harness never says the drive ended (`afterDrive`). */
export const IDLE_CLOSE_MS = 60_000;

/**
 * A call that did not run: the session's sandbox could not be attached for
 * it. Nothing reached the VM. Busy or still starting (`Yield('contended')`:
 * the factory's answer to anything that passes, a 429 or a 5xx included):
 * "not run: the sandbox is starting, try again". Anything else says what
 * failed (a missing project link, a refused credential), so the model is
 * not told to retry what no retry fixes.
 */
export class NotRun extends Error {
  readonly code = 'ENOTRUN';
  constructor(cause?: unknown) {
    const busy = cause === undefined || (cause as { name?: unknown }).name === 'Yield';
    const reason = busy ? '' : String((cause as Error)?.message ?? cause).replace(/\s+/g, ' ').slice(0, 300);
    super(busy ? 'not run: the sandbox is starting, try again' : `not run: the sandbox could not be attached (${reason})`, cause !== undefined ? { cause } : undefined);
    this.name = 'NotRun';
  }
}

/**
 * What a tool of a runtime may carry for the harness that calls it, beside
 * its `HostTool` fields (harness-world-pi runs both):
 *
 * - `beforeIntent(ctx)`: the call's pre-intent phase, before its intent is
 *   written (skipped for a call the log already answers). Resolves with an
 *   error the call fails with at once, without running (`NotRun`), or
 *   nothing; rejects when the drive must stop (it was halted).
 * - `afterDrive(ctx)`: the drive is over (every tool of a runtime shares
 *   one; calling it more than once is harmless).
 */
export interface PhasedTool {
  beforeIntent?(ctx: DriveContext): Promise<Error | undefined>;
  afterDrive?(ctx: DriveContext): Promise<void>;
}

/** The kernel's and the log's stop conditions (by name: two copies of a package agree), which a "not run" outcome would hide. */
const STOPPING = new Set(['Unavailable', 'Fatal', 'Restart', 'LogFenced', 'LogSuperseded', 'InBandSupersededError', 'Parked', 'EffectInterrupted', 'SandboxLost']);

/**
 * Whether an attach failure stops the drive rather than the call: any
 * yield but `contended` (an unfenced drive can't arm a fresh VM:
 * `superseded`; `preempted` writes nothing more), `Unavailable` (no fencing
 * token, the VM-time budget, a CLI downgrade), the log's stop conditions,
 * and a link lost more often than an invocation re-attaches (`SandboxLost`,
 * a transport error: the next delivery takes over).
 */
export function stopsTheDrive(err: unknown): boolean {
  const e = err as { name?: unknown; reason?: unknown } | undefined;
  if (e?.name === 'Yield') return e.reason !== 'contended';
  return typeof e?.name === 'string' && STOPPING.has(e.name);
}

/** One call's view of the attach's machine: its commands also stop when the call or the drive is stopped (`stop`). */
export class CallMachine implements WorkspaceMachine {
  constructor(
    private readonly machine: WorkspaceMachine,
    private readonly stop: AbortSignal
  ) {}
  get root() {
    return this.machine.root;
  }
  get isolation() {
    return this.machine.isolation;
  }
  get lost() {
    return this.machine.lost;
  }
  exec(command: string, options: ExecOptions = {}) {
    return this.machine.exec(command, { ...options, signal: options.signal ? AbortSignal.any([options.signal, this.stop]) : this.stop });
  }
  readFile(path: string) {
    return this.machine.readFile(path);
  }
  writeFile(path: string, content: string | Uint8Array, options?: { mode?: number; append?: boolean }) {
    return this.machine.writeFile(path, content, options);
  }
  stat(path: string) {
    return this.machine.stat(path);
  }
  lstat(path: string) {
    return this.machine.lstat(path);
  }
  list(dir: string) {
    return this.machine.list(dir);
  }
  walk(dir?: string) {
    return this.machine.walk(dir);
  }
  mkdir(path: string, options?: { recursive?: boolean }) {
    return this.machine.mkdir(path, options);
  }
  remove(path: string, options?: { recursive?: boolean; force?: boolean }) {
    return this.machine.remove(path, options);
  }
  rename(from: string, to: string) {
    return this.machine.rename(from, to);
  }
  symlink(target: string, path: string) {
    return this.machine.symlink(target, path);
  }
  readlink(path: string) {
    return this.machine.readlink(path);
  }
  realpath(path: string) {
    return this.machine.realpath(path);
  }
  chmod(path: string, mode: number) {
    return this.machine.chmod(path, mode);
  }
  /** The attach's machine is the drive's to close, never one call's. */
  dispose(): void {}
}

/** One drive's calls on the session's sandbox. */
class SandboxDrive {
  private session: AttachedMachine | undefined;
  private pending: Promise<AttachedMachine> | undefined;
  private queue: Promise<unknown> = Promise.resolve();
  /** Calls queued or running, and the timer that closes an idle machine. */
  private active = 0;
  private idle: ReturnType<typeof setTimeout> | undefined;
  /** The attach's notes reached the model in this drive (and the record was told). */
  private told = false;
  private closed = false;

  constructor(
    private readonly ctx: DriveContext,
    private readonly options: SandboxRuntimeOptions
  ) {}

  /** The attached machine, attaching now if there is none (or its link was lost). One attach at a time. */
  attach(): Promise<AttachedMachine> {
    if (this.closed) return Promise.reject(new Error('harness-world-hands: the drive is over'));
    clearTimeout(this.idle);
    const s = this.session;
    if (s && !s.signal.aborted && !s.workspace.lost) return Promise.resolve(s);
    if (this.pending) return this.pending;
    const pending = (async () => {
      // A lost machine is closed (best effort) before it is replaced.
      this.session = undefined;
      if (s) void s.close().catch(() => {});
      const machine = await this.options.attach(this.ctx);
      if (machine.workspace.root !== WORKSPACE_ROOT) {
        void machine.close().catch(() => {});
        throw new Unavailable(`harness-world-hands: the session's sandbox has its files at ${machine.workspace.root}, not ${WORKSPACE_ROOT}, where its tools work`);
      }
      if (this.closed) {
        void machine.close().catch(() => {});
        throw new Error('harness-world-hands: the drive is over');
      }
      this.session = machine;
      return machine;
    })();
    this.pending = pending;
    const clear = () => {
      if (this.pending === pending) this.pending = undefined;
    };
    pending.then(clear, clear);
    return pending;
  }

  /** Attach, as a call's outcome: `NotRun` for a failure that leaves the drive going; the drive halted (and rejects) for one that stops it. */
  async attachOrNotRun(): Promise<AttachedMachine | NotRun> {
    try {
      return await this.attach();
    } catch (err) {
      if (this.ctx.signal.aborted) throw this.ctx.signal.reason ?? err;
      if (stopsTheDrive(err)) {
        this.ctx.halt?.(err);
        throw err;
      }
      return err instanceof NotRun ? err : new NotRun(err);
    }
  }

  /** A call on the attach's machine, after every earlier call of this drive. */
  run(io: HostToolIO, work: (machine: WorkspaceMachine) => Promise<string>): Promise<string> {
    this.active++;
    clearTimeout(this.idle);
    const call = this.queue.then(async () => {
      const session = await this.attachOrNotRun();
      if (session instanceof NotRun) throw session;
      const stop = AbortSignal.any([io.signal, this.ctx.signal]);
      const note = !this.told && session.notes.length ? session.notes.join('\n') : undefined;
      const text = await work(new CallMachine(session.workspace, stop));
      if (!note) return text;
      // Said with this call's result: the record is told, in the same outcome.
      await this.options.told(io, session.notesKey);
      this.told = true;
      return `${note}\n\n${text}`;
    });
    this.queue = call
      .catch(() => {})
      .finally(() => {
        if (--this.active > 0 || this.closed) return;
        // Nothing ran on it for a while: let the link go (a later call attaches again).
        this.idle = setTimeout(() => {
          const s = this.session;
          this.session = undefined;
          void s?.close().catch(() => {});
        }, IDLE_CLOSE_MS);
        (this.idle as { unref?: () => void }).unref?.();
      });
    return call;
  }

  /** The drive is over: close the attach's machine (its commands are killed; the VM and the Drive stay). */
  async close(): Promise<void> {
    this.closed = true;
    clearTimeout(this.idle);
    const s = this.session;
    this.session = undefined;
    // An attach still pending closes what it gets (`closed`).
    await s?.close().catch(() => {});
  }
}

/**
 * The runtime on the session's sandbox (see the module comment). Its tools
 * are `runtime.tool()`'s, each with `beforeIntent` and `afterDrive`
 * (`PhasedTool`) and the replay a sandbox needs: `never` for a call that may
 * change files or run commands, `safe` for one that only reads.
 */
export function sandboxRuntime(options: SandboxRuntimeOptions): WorkspaceRuntime {
  const drives = new WeakMap<DriveContext, SandboxDrive>();
  const driveOf = (ctx: DriveContext) => {
    let d = drives.get(ctx);
    if (!d) drives.set(ctx, (d = new SandboxDrive(ctx, options)));
    return d;
  };
  const beforeIntent = async (ctx: DriveContext): Promise<Error | undefined> => {
    const r = await driveOf(ctx).attachOrNotRun();
    return r instanceof NotRun ? r : undefined;
  };
  const afterDrive = async (ctx: DriveContext): Promise<void> => {
    const d = drives.get(ctx);
    drives.delete(ctx);
    await d?.close();
  };
  const describe = (description: string, kind: 'shell' | 'file' = 'file') => (kind === 'shell' ? `${description.trimEnd()} ${SANDBOX_NOTE}` : description);
  const run: WorkspaceRuntime['run'] = (io, _mode, work) => driveOf(io.ctx).run(io, work);
  const runtime: WorkspaceRuntime = {
    workspace: { kind: 'sandbox' },
    root: WORKSPACE_ROOT,
    durable: true,
    instructions: SANDBOX_INSTRUCTIONS,
    describe,
    run,
    tool<Input>(def: WorkspaceToolDef<Input>): HostTool<Input> {
      const mode = (input: Input): CallMode => (typeof def.mode === 'function' ? def.mode(input) : def.mode);
      return {
        name: def.name,
        ...(def.label ? { label: def.label } : {}),
        description: def.described ? def.description : describe(def.description, def.kind),
        inputSchema: def.inputSchema,
        // On a Drive a cut-off call may have half-run: only a call that reads is safe to run again.
        replay: def.mode === 'read' ? 'safe' : 'never',
        ...(def.needs ? { needs: def.needs } : {}),
        execute: (input, io) => run(io, mode(input), (machine) => def.run(input, machine, io)),
        beforeIntent,
        afterDrive,
        [WORKSPACE_TOOL]: true,
      } as HostTool<Input> & PhasedTool;
    },
  };
  return runtime;
}