Skip to content

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

5.7 KB
Raw Blame
import { createServer, type Server } from 'node:http';
import type { AddressInfo } from 'node:net';
import type { World } from '@workflow/world';
import { ulid } from 'ulid';
import { afterEach, describe, expect, it } from 'vitest';
import { durableSessions, QUEUE_PREFIX, recoverSessions } from './index.ts';
import { workflowNameFor } from './names.ts';
import type { DriveContext, Harness } from './types.ts';

/**
 * The kernel's queue on world-postgres, delivered per prefix (vercel/workflow
 * #4835): a job keeps its prefix and the route its producer registered, so a
 * worker in another process, one with no handler for the kernel's prefix
 * (the Workflow SDK's, say), delivers it over HTTP to the kernel's route,
 * never to the Workflow SDK's flow route. Runs when `WORKFLOW_POSTGRES_URL`
 * names a database with the World's migrations applied.
 */

const url = process.env.WORKFLOW_POSTGRES_URL;
const ROUTE = '/.well-known/durable-harness/v1/flow';

const answer: Harness = {
  name: 'pg-answer',
  async drive(ctx: DriveContext) {
    let turn = ctx.state().effectOrder.length;
    for (const s of ctx.pending()) {
      await ctx.effect(`model:${turn++}`, { name: 'model', replay: 'safe', input: s.text, placed: [s.id] }, async () => `re: ${s.text}`);
    }
  },
};

type Routable = World & { registerRoute(prefix: string, path: string): void; close?: () => Promise<void> };

let server: Server | undefined;
const worlds: Routable[] = [];
afterEach(async () => {
  for (const w of worlds.splice(0)) await w.close?.();
  server?.closeAllConnections();
  await new Promise((r) => (server ? server.close(r) : r(undefined)));
  server = undefined;
});

/** An HTTP front for the app: records each request's path, queue name and run, and hands it to `handler`. */
async function front(handler: () => (r: Request) => Promise<Response>) {
  const seen: { path: string; queue: string; runId?: string }[] = [];
  server = createServer(async (req, res) => {
    const chunks: Buffer[] = [];
    for await (const c of req) chunks.push(c as Buffer);
    const headers = new Headers();
    for (const [k, v] of Object.entries(req.headers)) if (typeof v === 'string') headers.set(k, v);
    let runId: string | undefined;
    try {
      runId = (JSON.parse(Buffer.concat(chunks).toString('utf8')) as { runId?: string }).runId;
    } catch {}
    seen.push({ path: String(req.url), queue: headers.get('x-vqs-queue-name') ?? '', ...(runId ? { runId } : {}) });
    const response = String(req.url).startsWith(ROUTE)
      ? await handler()(new Request(`http://127.0.0.1${req.url}`, { method: req.method, headers, ...(chunks.length ? { body: Buffer.concat(chunks) } : {}) }))
      : new Response('Unhandled queue', { status: 400 });
    res.writeHead(response.status, Object.fromEntries(response.headers));
    res.end(Buffer.from(await response.arrayBuffer()));
  });
  await new Promise<void>((r) => server!.listen(0, '127.0.0.1', r));
  return { base: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, seen };
}

async function until<T>(fn: () => Promise<T | undefined>, timeoutMs = 30_000): Promise<T> {
  const start = Date.now();
  for (;;) {
    const value = await fn();
    if (value !== undefined) return value;
    if (Date.now() - start > timeoutMs) throw new Error('timed out');
    await new Promise((r) => setTimeout(r, 100));
  }
}

describe.skipIf(!url)("the kernel's queue on world-postgres", () => {
  it("a job the kernel's World enqueued is delivered by another World's worker to the kernel's route, not the Workflow SDK's", async () => {
    const { createWorld } = await import('@workflow/world-postgres');
    const jobPrefix = `hw_queue_${ulid().toLowerCase()}_`;
    let sessions: ReturnType<typeof durableSessions> | undefined;
    const http = await front(() => sessions!.handler);
    process.env.WORKFLOW_LOCAL_BASE_URL = http.base;
    try {
      // The kernel's World: it registers its route and never starts a worker here.
      const kernel = createWorld({ connectionString: url!, jobPrefix }) as unknown as Routable;
      worlds.push(kernel);
      kernel.registerRoute(QUEUE_PREFIX, ROUTE);
      sessions = durableSessions({ world: kernel, harness: answer });
      // Another World on the database (another process: the Workflow SDK's), whose worker runs, with nothing registered for the kernel's prefix.
      const theirs = createWorld({ connectionString: url!, jobPrefix }) as unknown as Routable;
      worlds.push(theirs);
      await theirs.start?.();

      const { sessionId } = await sessions.start();
      await sessions.send(sessionId, 'hi');
      const state = await until(async () => {
        const s = await sessions!.inspect(sessionId);
        return s.effectOrder.some((e) => e.status === 'completed') ? s : undefined;
      });
      expect(state.effectOrder.map((e) => e.output)).toEqual(['re: hi']);
      // Only this session's deliveries: the other World's start() also re-enqueues every active run on the
      // database (another test's, its own), and with no route of its own those go to the flow route.
      const ours = () => http.seen.filter((d) => d.runId === sessionId);
      expect(ours().length).toBeGreaterThan(0);
      for (const d of ours()) {
        expect(d.path).toBe(ROUTE);
        expect(d.queue.startsWith(QUEUE_PREFIX)).toBe(true);
      }

      // A restart's recovery on the kernel's prefix goes the same way.
      const before = ours().length;
      expect(await recoverSessions(kernel)).toBeGreaterThanOrEqual(1);
      await until(async () => (ours().slice(before).some((d) => d.queue === `${QUEUE_PREFIX}${workflowNameFor('pg-answer')}`) ? true : undefined));
      expect(ours().every((d) => d.path === ROUTE)).toBe(true);
    } finally {
      delete process.env.WORKFLOW_LOCAL_BASE_URL;
    }
  }, 60_000);
});