Skip to content

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

10.7 KB
Raw Blame
import type { World } from '@workflow/world';
import {
  createDriveRoute,
  currentLane,
  type DurableSessions,
  durableSessions,
  type Harness,
  hostAnchors,
  hostOf,
  type Lane,
  type LaneOptions,
  laneAvailable,
  serveHostDrive,
  SessionLog,
} from 'harness-world';
import { hybridTools, sandboxOwnerPolicy } from 'harness-world-hybrid';
import type { LocalSandboxProvider } from './local-sandbox.ts';
import { tokenExpired } from './token.ts';

/** What one daemon is. */
export interface HostIdentity {
  /** The VM's sandbox name. */
  vm: string;
  /** The VM session (`Sandbox` sessionId): a stop and resume is a new one. */
  sessionId: string;
  /** One per daemon start. */
  bootId: string;
  /** The bundle's content hash (`HOST_VERSION`). */
  version: string;
  /** `production` / `preview` / … : the daemon refuses sessions of another environment. */
  environment?: string;
}

export interface HostOptions extends HostIdentity {
  /** The session log (and streams): world-vercel straight from the VM, with a local queue. */
  world: World;
  /** Builds the hybrid harnesses for this lane (`hybridTools({ lane: 'sandbox', sandbox })`). */
  harnesses(tools: ReturnType<typeof hybridTools>, lanes: LaneOptions): Harness[];
  sandbox: LocalSandboxProvider;
  /** `Authorization: Bearer <secret>` on every control call. */
  secret: string;
  /**
   * Wake the function lane: POST `${appOrigin}/api/hybrid/drive`.
   * Unset: no app (tests).
   */
  appOrigin?: string;
  /** Headers for calls to the app (the scoped bypass is injected by the VM's egress proxy, so normally none). */
  appHeaders?: Record<string, string>;
  /** Replace the OIDC token every World and Gateway call reads (`POST /token`). */
  setToken?(token: string): void;
  /** When the current token expires (unix seconds), for `/health`. */
  tokenExp?(): number | undefined;
  /** `POST /bench/raw`: a raw (no World) busy period in the VM, the `/api/bench/raw` protocol (NDJSON). */
  benchRaw?(request: Request): Promise<Response>;
  /** Extra `/health` fields (fx readiness, …). */
  health?(): Record<string, unknown>;
  /**
   * Honor armed crashes (default on, like the app): Kill Function kills this
   * daemon, Kill Sandbox VM stops its VM (through the app), Kill Command
   * kills the command.
   */
  chaos?: boolean;
  openChannel?: (runId: string) => (() => void) | undefined;
  fetch?: typeof fetch;
  log?: (message: string, fields?: Record<string, unknown>) => void;
}

export interface Host {
  readonly sessions: Promise<DurableSessions>;
  /** The control API (Web `Request` → `Response`), mounted by `daemon.ts` on port 3000. */
  handle(request: Request): Promise<Response>;
  /** Sessions attached to this daemon. */
  readonly attached: ReadonlySet<string>;
  /** Wait for the drives in flight (tests). */
  idle(): Promise<void>;
}

const json = (body: unknown, status = 200) =>
  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });

/**
 * The in-VM host: a normal durable driver serving the
 * `sandbox` lane, with the session's machine tools on this VM, model calls
 * straight to AI Gateway and the log straight to world-vercel. Nothing in
 * the kernel is VM-specific: the same driver, epochs and fencing.
 *
 * Its drives hold no queue message: they run under this boot's anchor
 * (`hostAnchors`), and the app's tether stands behind them, a flow-route
 * delivery that holds its own message while it holds `POST /drive` open
 * here (harness-world's tether.ts). The daemon writes nothing about its own
 * liveness: a VM that dies resets that connection, and the tether takes the
 * session to a function.
 */
export function createHost(options: HostOptions): Host {
  const say = options.log ?? (() => {});
  const doFetch = options.fetch ?? fetch;
  const attached = new Set<string>();
  const inflight = new Set<Promise<void>>();
  const startedAt = Date.now();
  let lastDrive: number | undefined;

  const lanes: LaneOptions = {
    serves: ['sandbox'],
    settle: 'browser',
    available: (lane, state) => laneAvailable(state, lane),
    async wake(runId, to, handoff) {
      if (to === 'sandbox') {
        drive(runId, 'self');
        return;
      }
      // The tab watches its session's log and hints: nothing to send.
      if (to === 'browser') return;
      if (!options.appOrigin) throw new Error('no app to wake the function lane on');
      // The HTTP drive route drives the function lane in that invocation; it
      // sends the delayed queue companion itself.
      let lastError: unknown;
      for (let attempt = 0; attempt < 3; attempt++) {
        try {
          const response = await doFetch(`${options.appOrigin}/api/hybrid/drive`, {
            method: 'POST',
            headers: { 'content-type': 'application/json', ...(options.appHeaders ?? {}) },
            body: JSON.stringify({ runId, lane: to, from: 'sandbox', reason: handoff.reason }),
            signal: AbortSignal.timeout(5000),
          });
          if (response.ok) return;
          lastError = new Error(`POST /api/hybrid/drive answered ${response.status}`);
        } catch (err) {
          lastError = err;
        }
        await new Promise((r) => setTimeout(r, 200 * (attempt + 1)));
      }
      throw lastError;
    },
  };

  // run_on_machine waits for its command inside the call (on this machine).
  const tools = hybridTools({ lane: 'sandbox', sandbox: options.sandbox });

  const sessions = (async () =>
    durableSessions({
      world: options.world,
      harness: options.harnesses(tools, lanes),
      lanes,
      owners: [sandboxOwnerPolicy({ provider: options.sandbox })],
      // A drive here is anchored to this daemon's boot; its tether is its backstop.
      anchors: hostAnchors({ boot: options.bootId }),
      chaos: options.chaos ?? true,
      ...(options.openChannel ? { openChannel: options.openChannel } : {}),
      log: (message, fields) => say(message, fields),
    }))();

  const route = createDriveRoute({
    after: (work) => {
      const p = work().catch((err) => say('drive failed', { error: String(err) }));
      inflight.add(p);
      void p.finally(() => inflight.delete(p));
    },
    drive: async (runId, meta) => {
      lastDrive = Date.now();
      return (await sessions).drive(runId, meta);
    },
    log: say,
  });

  function drive(runId: string, why: string) {
    route.drive(runId, { why });
  }

  async function attach(runId: string): Promise<Response> {
    const log = new SessionLog(options.world, runId);
    await log.refresh();
    const env = (log.state.config as { environment?: string } | undefined)?.environment;
    if (env && options.environment && env !== options.environment) {
      return json({ error: `session is in ${env}, this host serves ${options.environment}` }, 409);
    }
    attached.add(runId);
    options.openChannel?.(runId);
    const host = hostOf(log.state);
    return json({ attached: true, lane: currentLane(log.state), host: host?.bootId === options.bootId });
  }

  async function handle(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    if (request.method === 'OPTIONS') return new Response(null, { status: 204 });
    if (path === '/health' && request.method === 'GET') {
      return json({
        ok: true,
        vm: options.vm,
        bootId: options.bootId,
        sessionId: options.sessionId,
        version: options.version,
        environment: options.environment,
        attached: [...attached],
        driving: [...attached].filter((r) => route.driving(r)),
        tokenExp: options.tokenExp?.(),
        lastDrive,
        uptimeMs: Date.now() - startedAt,
        ...(options.health?.() ?? {}),
      });
    }
    const auth = request.headers.get('authorization') ?? `Bearer ${url.searchParams.get('secret') ?? ''}`;
    if (auth !== `Bearer ${options.secret}`) return json({ error: 'unauthorized' }, 401);
    const body = request.method === 'POST' ? ((await request.json().catch(() => ({}))) as Record<string, unknown>) : {};
    const runId = typeof body.runId === 'string' ? body.runId : url.searchParams.get('runId') ?? undefined;
    switch (path) {
      case '/attach':
        if (!runId?.startsWith('wrun_')) return json({ error: 'expected { runId }' }, 400);
        return attach(runId);
      case '/wake': {
        if (!runId?.startsWith('wrun_')) return json({ error: 'expected { runId }' }, 400);
        // Only sessions attached to this boot (`/attach`, after which the app
        // commits the host fact): a wake for anything else is refused, so the
        // caller hands the session to a function instead of trusting this daemon.
        if (!attached.has(runId)) return json({ error: 'session not attached to this host', bootId: options.bootId }, 409);
        // An expired token: every World write and Gateway call would fail, so
        // say so (the caller pushes a fresh token, or hands off at once).
        const tokenExp = options.tokenExp?.();
        if (tokenExpired(tokenExp)) return json({ error: 'token expired', tokenExp, bootId: options.bootId }, 503);
        // Answer at once: the caller's liveness probe needs a 202 in 500 ms.
        drive(runId, typeof body.why === 'string' ? body.why : 'wake');
        return json({ accepted: true, bootId: options.bootId, ...(tokenExp !== undefined ? { tokenExp } : {}) }, 202);
      }
      case '/drive': {
        // A tether (the app's flow route): a stream that stays open while this
        // daemon drives the session, and ends with an end line when it lets go.
        if (!runId?.startsWith('wrun_')) return json({ error: 'expected { runId }' }, 400);
        if (!attached.has(runId)) return json({ error: 'session not attached to this host', bootId: options.bootId }, 409);
        const tokenExp = options.tokenExp?.();
        if (tokenExpired(tokenExp)) return json({ error: 'token expired', tokenExp, bootId: options.bootId }, 503);
        lastDrive = Date.now();
        return serveHostDrive(options.world, runId, async () => (await sessions).drive(runId));
      }
      case '/token': {
        if (typeof body.token !== 'string' || !options.setToken) return json({ error: 'expected { token }' }, 400);
        options.setToken(body.token);
        return json({ ok: true, tokenExp: options.tokenExp?.() });
      }
      case '/bench/raw':
        if (!options.benchRaw) return json({ error: 'no raw baseline here' }, 404);
        return options.benchRaw(new Request(request.url, { method: 'POST', headers: request.headers, body: JSON.stringify(body) }));
      default:
        return json({ error: 'not found' }, 404);
    }
  }

  return {
    sessions,
    handle,
    attached,
    async idle() {
      while (inflight.size > 0) await Promise.all([...inflight]);
    },
  };
}

export type { Lane };