Skip to content

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

12.4 KB
Raw Blame
import type { World } from '@workflow/world';
import type { Hands } from 'harness-world-demo-ui';
import {
  type ChaosDriveOptions,
  type DurableSessions,
  durableSessions,
  type Harness,
  type HostTool,
  type LaneOptions,
  laneAvailable,
  type OwnerPolicy,
} from 'harness-world';
import { virtual } from 'durable-harness';
import { vercelChannel } from 'harness-world/vercel-channel';
import type { VercelSandboxProvider } from 'harness-world-hybrid/sandbox';
import { byHands, checkUpFront, demoSandbox, type UpFront, upFrontFields } from './hands';
import { wakeLane } from './hybrid';
import { getSandboxProvider, providerFrom } from './sandbox-provider';
import { Todos } from './docs';
import { processKernelHarnesses } from './harnesses';
import { gatewayKey, instructionsFor, MODEL } from './model';
import { handleWake, isPiDurableQueue, isPiWake } from './pi-durable';
import { getWorld } from './world';

/**
 * The harness packages (pi-ai, libfx, the sandbox SDK, the tools) are
 * imported on first use, not with this module. Every API route of the app
 * shares one function, and a new instance pays its first request for
 * whatever the routes import at load; here that was most of the ~2s a turn
 * on a fresh instance cost. `getSessions()` starts loading them at once, so
 * the load overlaps the session's first log read and write.
 */
async function loadHeavy() {
  const [piAi, gw, fxMod, hands, handsFx, hybridMod, sandbox, piMod, libfx] = await Promise.all([
    import('@earendil-works/pi-ai'),
    import('@earendil-works/pi-ai/providers/vercel-ai-gateway'),
    import('harness-world-fx'),
    import('harness-world-hands'),
    import('harness-world-hands/fx'),
    import('harness-world-hybrid'),
    import('harness-world-hybrid/sandbox'),
    import('durable-harness/pi'),
    import('libfx'),
  ]);
  return { piAi, gw, fxMod, hands, handsFx, hybridMod, sandbox, piMod, libfx };
}
type Heavy = Awaited<ReturnType<typeof loadHeavy>>;
const gh = globalThis as { __harnessHeavy?: Promise<Heavy> };
const heavy = (): Promise<Heavy> => (gh.__harnessHeavy ??= loadHeavy());

/** Start loading the harness packages (idempotent; for routes about to drive). */
export function preloadHarnesses(): void {
  heavy().catch(() => {});
}

/** A harness whose implementation is built on its first drive. `name` and `upFront` are known up front. */
function lazyHarness(name: string, upFront: UpFront, make: (h: Heavy) => Harness): Harness {
  let built: Promise<Harness> | undefined;
  return {
    name,
    ...upFrontFields(upFront),
    async drive(ctx) {
      const ready = (built ??= heavy().then((h) => checkUpFront(name, upFront, make(h))));
      return (await ready).drive(ctx);
    },
  };
}

export { MODEL };

/** The plain Pi and fx harnesses (not hybrid), for the durable server lane and the raw baseline. */
export function plainHarnesses() {
  return [pi(), fx()];
}

/**
 * The harness's own workspace tools for a session's hands (the demo's Hands
 * axis): none; on `virtual()` (its files in the log; with durability off,
 * the raw baseline, in memory for the turn); on `virtual({ durable: false })`;
 * on `virtual()` with `run_on_machine` next to them; or on the session's
 * `sandbox()`, which Pi's `createCodingTools` refuses until its sandbox
 * support lands (the page and the sessions route offer it to neither yet).
 */
async function handsTools(h: Heavy, hands: Hands, onWorkspace: (workspace: Parameters<Heavy['piMod']['createCodingTools']>[0]) => HostTool[]): Promise<HostTool[]> {
  switch (hands) {
    case 'none':
      return [];
    case 'ephemeral':
      return onWorkspace(virtual({ durable: false }));
    case 'machine':
      return [...onWorkspace(virtual()), h.hybridMod.runOnMachineTool({ lane: 'function', sandbox: sandboxProvider(h) })];
    case 'sandbox':
      return onWorkspace(await demoSandbox());
    default:
      return onWorkspace(virtual());
  }
}

function pi() {
  return byHands('pi', { modelCalls: 'self' }, async (hands) => {
    const h = await heavy();
    const { piAi, gw, piMod } = h;
    const models = piAi.createModels();
    models.setProvider(gw.vercelAIGatewayProvider());
    const model = models.getModel('vercel-ai-gateway', MODEL);
    if (!model) throw new Error(`pi-ai does not know ${MODEL}`);
    return piMod.piHarness({
      model,
      streamFn: models.streamSimple.bind(models),
      getApiKey: () => gatewayKey(),
      systemPrompt: instructionsFor(hands),
      // Pi's own coding tools (read, bash, edit, write) on the session's hands.
      tools: [...(await handsTools(h, hands, (ws) => piMod.createCodingTools(ws))), ...h.hands.unsafeTools(), ...h.hands.docTools([Todos])],
    });
  });
}

function fx() {
  return byHands('fx', { modelCalls: 'self' }, async (hands) => {
    const h = await heavy();
    const { fxMod, handsFx, libfx } = h;
    return fxMod.fxHarness({
      createFxEngine: libfx.createFxEngine,
      apiKey: gatewayKey,
      model: MODEL,
      instructions: instructionsFor(hands),
      // libfx's kernel tools (read_file, glob_files, grep_files, edit_file,
      // write_file, shell) on the session's hands; a sandbox() has no fx
      // kernel tools yet (the page and the sessions route offer it to neither).
      tools: [
        ...(await handsTools(h, hands, (ws) => {
          if (ws.kind !== 'virtual') throw new TypeError('fx on sandbox() is not available yet: its kernel tools run on virtual() only');
          return handsFx.fxHostTools(ws);
        })),
        ...h.hands.unsafeTools(),
        ...h.hands.docTools([Todos]),
      ],
    });
  });
}

/**
 * The server's lane of a hybrid session: this process drives `function` (a
 * backend secret; `run_on_machine` reaches the session's own VM through the
 * Sandbox API and waits for its command inside the call). The `sandbox`
 * lane (the retired brain-in-VM lane) is never available, even to an older
 * session whose log still has a host fact. Idle sessions settle to their
 * home lane. Carried on the hybrid harnesses only, so plain Pi/fx sessions
 * never move.
 */
function serverLanes(world: World): LaneOptions {
  return {
    serves: ['function'],
    settle: 'browser',
    available: (lane, state) => lane !== 'sandbox' && laneAvailable(state, lane),
    async wake(runId, to, _handoff, opts) {
      const result = await wakeLane(world, runId, to, { key: opts?.idempotencyKey });
      console.log('[harness] wake lane', { runId, to, ...result });
    },
  };
}

const chaosOn = process.env.HARNESS_CHAOS !== '0';

// The hybrid harness names (harness-world-hybrid's HYBRID_HARNESS and
// HYBRID_FX_HARNESS), spelled here so naming a harness loads nothing.
const HYBRID_HARNESS = 'hybrid';
const HYBRID_FX_HARNESS = 'hybrid-fx';

export { getSandboxProvider };

function sandboxProvider({ sandbox }: Heavy): VercelSandboxProvider {
  return providerFrom(sandbox);
}

/** The sandbox owner policy (parked commands), built on its first check. */
function sandboxOwners(): OwnerPolicy {
  let built: Promise<OwnerPolicy> | undefined;
  const policy = () => (built ??= heavy().then((h: Heavy) => h.hybridMod.sandboxOwnerPolicy({ provider: sandboxProvider(h), chaos: chaosOn })));
  return {
    kind: 'sandbox',
    check: async (c) => (await policy()).check(c),
    fireChaos: async (c) => {
      const p = await policy();
      if (!p.fireChaos) throw new Error('harness: the sandbox owner policy cannot fire crashes');
      return p.fireChaos(c);
    },
  };
}

/** The hybrid Pi session, server half: the tools for each session's hands (`config.hands`), the same list as the tab's. */
function hybrid(world: World) {
  const lanes = serverLanes(world);
  return lazyHarness(HYBRID_HARNESS, { lanes, modelCalls: 'self' }, (h) => {
    const { model, streamFn } = h.hybridMod.createGatewayModel(undefined, MODEL);
    return h.hybridMod.hybridHarness({
      lane: 'function',
      model,
      streamFn,
      getApiKey: () => gatewayKey(),
      tools: (hands) => h.hybridMod.hybridTools({ lane: 'function', sandbox: sandboxProvider(h), hands }),
      lanes,
    });
  });
}

/**
 * The hybrid fx session, server half: libfx's native addon here, its Wasm
 * build in the tab, one tape. Same model, prompt and tools as the tab's
 * (the tape digests the request body and checks the model id).
 */
function hybridFx(world: World) {
  const lanes = serverLanes(world);
  return lazyHarness(HYBRID_FX_HARNESS, { lanes, modelCalls: 'self' }, (h) =>
    h.hybridMod.hybridFxHarness({
      lane: 'function',
      createFxEngine: h.libfx.createFxEngine,
      apiKey: gatewayKey,
      model: MODEL,
      tools: (hands) => h.hybridMod.hybridTools({ lane: 'function', sandbox: sandboxProvider(h), hands }),
      lanes,
    })
  );
}

/**
 * What a tab needs to drive hybrid sessions the way this server replays
 * them: the model every lane calls, and the hash of this server's fx
 * configuration (a tab from another deployment compares it with its own
 * and hands fx turns to the server when they differ).
 */
export async function hybridConfig(): Promise<{ model: string; fxConfig: string }> {
  const { hybridMod } = await heavy();
  return { model: MODEL, fxConfig: await hybridMod.hybridFxConfigHash({ lane: 'sandbox', model: MODEL }) };
}

const g = globalThis as { __harnessSessions?: Promise<DurableSessions>; __harnessDrillSessions?: Promise<DurableSessions> };

/**
 * Whether crash drills run in a Function of their own (`/api/drill`). On
 * Vercel a Function instance serves many requests at once (Fluid compute),
 * and a drill's kill (SIGKILL) takes every one of them down: other
 * sessions' drives, their live tails. So on Vercel the turn of a session
 * with an armed crash is sent to the drill route, the only handle here that
 * fires a crash armed before its drive began; every other handle fires
 * only a crash armed while its drive runs (arming mid-turn). Locally there
 * is one process anyway: every handle fires. `HARNESS_DRILL_ROUTE=0` turns
 * the route off.
 */
export const drillRoute = () => !!process.env.VERCEL && process.env.HARNESS_DRILL_ROUTE !== '0';

/** The process's sessions, for every route but the drill route. */
export function getSessions(): Promise<DurableSessions> {
  preloadHarnesses();
  g.__harnessSessions ??= buildSessions(chaosOn ? (drillRoute() ? { fire: 'armed-in-drive' } : true) : false);
  return g.__harnessSessions;
}

/** The drill route's sessions (`/api/drill`): every armed crash fires here. */
export function getDrillSessions(): Promise<DurableSessions> {
  preloadHarnesses();
  g.__harnessDrillSessions ??= buildSessions(chaosOn);
  return g.__harnessDrillSessions;
}

async function buildSessions(chaos: boolean | ChaosDriveOptions): Promise<DurableSessions> {
  return durableSessions({
      world: await getWorld(),
      // Writes made outside a queue delivery (the drive route, direct
      // drives) share one WebSocket per session; a no-op off world-vercel.
      openChannel: vercelChannel(),
      // Process harnesses (Claude Code, Codex, ...) come from lib/harnesses.
      harness: [pi(), fx(), hybrid(await getWorld()), hybridFx(await getWorld()), ...processKernelHarnesses()],
      log: (message, fields) => console.log(`[harness] ${message}`, fields ?? ''),
      // The UI's Crash button arms a real crash: the function driving the
      // session exits mid-step and the queue redrives it. Under `next dev`
      // that exits the dev server; start it again to watch recovery. Which
      // crashes this handle fires: see `drillRoute`.
      chaos,
      // Parked sandbox commands (the detached sandbox_exec of older hybrid
      // sessions; run_on_machine never parks) are policed through the
      // Sandbox API by owner checks.
      owners: [sandboxOwners()],
      // Nothing beats: each drive runs under its queue message (or, on the
      // drive route, a deadline with a companion message behind it), and a
      // redelivery takes over at once (harness-world's anchor.ts). A tab's
      // drives are covered by its tether (/api/hybrid/tether).
      // pi-durable sessions (lib/pi-durable.ts) share this queue and flow
      // route: their wakes and continuations go to the opener that lane
      // registered with durable-harness/pi-durable's `resumeWith`.
      // So do a restart's recovery deliveries for their runs
      // (instrumentation.ts: `__harness_wkf_workflow_<workflowName>`).
      route: (message, meta) => {
        const runId = (message as { runId?: unknown })?.runId;
        return isPiWake(message) || (typeof runId === 'string' && isPiDurableQueue(meta.queueName)) ? handleWake(message, meta) : undefined;
      },
    });
}