Skip to content

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

3.3 KB
Raw Blame
import type { World } from '@workflow/world';
import { QUEUE_PREFIX } from 'harness-world/queue';

/**
 * The route the kernel's queue is delivered to (app/.well-known/durable-harness/v1/flow),
 * not the Workflow SDK's: world-local and world-postgres send the kernel's
 * prefix there over HTTP once it is registered (on Vercel the route's
 * Function subscribes to the topic instead).
 */
export const FLOW_ROUTE = '/.well-known/durable-harness/v1/flow';

export type WorldName = 'local' | 'postgres' | 'vercel';

export function worldName(): WorldName {
  const name = process.env.HARNESS_WORLD ?? (process.env.VERCEL ? 'vercel' : 'local');
  if (name !== 'local' && name !== 'postgres' && name !== 'vercel') {
    throw new Error(`HARNESS_WORLD must be local, postgres or vercel (got ${name})`);
  }
  return name;
}

/**
 * world-local's data directory: the app's World under HARNESS_WORLD=local,
 * and libfx's too (lib/fx-durable-world.ts). Relative to the server's cwd for
 * both; left unresolved here, since a path.resolve would make the build trace
 * the whole project into every Function.
 */
export const localDataDir = () => process.env.WORKFLOW_LOCAL_DATA_DIR ?? '.workflow-data';

const g = globalThis as { __harnessWorld?: Promise<World> };

/**
 * The process's World. The only line in the app that knows which one it is:
 * everything else is written against the `World` interface.
 */
export function getWorld(): Promise<World> {
  g.__harnessWorld ??= (async () => {
    switch (worldName()) {
      case 'local': {
        const { createWorld } = await import('@workflow/world-local');
        // Its own recovery off: instrumentation.ts re-enqueues the sessions
        // alone (`recoverSessions`), never libfx's runs in the same directory.
        const world = createWorld({ dataDir: localDataDir(), recoverActiveRuns: false });
        world.registerRoute(QUEUE_PREFIX, FLOW_ROUTE);
        return world;
      }
      case 'postgres': {
        const { createWorld } = await import('@workflow/world-postgres');
        const world = createWorld();
        world.registerRoute(QUEUE_PREFIX, FLOW_ROUTE);
        return world;
      }
      case 'vercel': {
        // Event writes go over world-vercel's WebSocket (its default since
        // 5.1.0; HARNESS_EVENTS=http turns it off), but only while the run's
        // channel is open. The flow route's deliveries open one; a drive this
        // process runs itself (the drive route) needs the opener, which
        // harness-world can't import (it doesn't depend on world-vercel), so
        // the app hands over its own. HARNESS_STREAMS=ws also writes streams
        // (live text deltas, marks) over world-vercel's experimental WebSocket
        // stream protocol; off by default, since on beta.52 it hung about 1 in
        // 10 durable fx turns waiting for the first output.
        if (process.env.HARNESS_STREAMS === 'ws') process.env.WORKFLOW_STREAMS_TRANSPORT ??= 'ws';
        const { createWorld, openEventsChannel } = await import('@workflow/world-vercel');
        const { enableVercelWebSockets, setVercelChannelOpener } = await import('harness-world/vercel-channel');
        enableVercelWebSockets();
        setVercelChannelOpener(openEventsChannel);
        return createWorld();
      }
    }
  })();
  return g.__harnessWorld;
}