Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
import { currentLane, SessionLog, stepNameFor } from 'harness-world';
import { createWorldHandler, runOf, runScope } from 'harness-world-remote/server';
import { wakeLane } from './hybrid';
import { admitTabCall, tabSecret } from './run-tokens';
import { getWorld } from './world';
const g = globalThis as { __harnessWorldHandler?: Promise<(req: Request) => Promise<Response>> };
const HANDOFF_STEP = stepNameFor('handoff');
/**
* The server's World for `createRemoteWorld` in a browser tab: the handler
* `/api/world` mounts over HTTP and `/api/session-host` serves over one
* WebSocket. Storage and streams only: the tab keeps its own queue, and
* server lanes are woken through /api/hybrid/drive (or /api/hybrid/wake), so
* a hybrid session has exactly one log (world-vercel in production)
* whichever lane is writing to it.
*
* Scoped to the tab's session: a call about a run is served only with that
* run's token (`x-harness-run-token`, from `/api/hybrid/session-token`),
* and never one that spans runs (`runs.list`, a hook by id); a run it
* creates must be a hybrid session, and the streams only the server writes
* stay the server's (lib/run-tokens.ts). Without a secret on the deployment
* only the World's own description is served.
*
* A tab's commit that leaves work for a server lane (a handoff into it, or
* a submission while the session is in one) also sends that lane's wake
* from here, keyed by its cause: the tab's own wake may not land, and a tab
* that went away is covered by its tether (tab-lost) instead. Nothing here
* is a backstop chain: each wake is one message, for one cause.
*/
export function worldHandler(): Promise<(req: Request) => Promise<Response>> {
g.__harnessWorldHandler ??= getWorld().then((world) =>
createWorldHandler(world, {
maxStreamMs: 240_000,
authorize: authorizeTab(),
async onCommitted(op, args, value) {
if (op !== 'events.create') return;
const [runId, request] = args as [string, { eventType?: string; correlationId?: string; eventData?: { stepName?: string } }];
const submission = request?.eventType === 'hook_received';
const handoff = request?.eventType === 'step_completed' && request.eventData?.stepName === HANDOFF_STEP;
if (!submission && !handoff) return;
const log = new SessionLog(world, runId);
await log.refresh();
const lane = currentLane(log.state);
if (log.state.status !== 'running' || lane === 'browser') return;
const eventId = (value as { event?: { eventId?: string } } | undefined)?.event?.eventId;
await wakeLane(world, runId, lane, { log, key: submission ? `submission:${eventId ?? request.correlationId ?? 'unknown'}` : 'handoff' });
},
onError: (error, op) => console.log('[harness] /api/world hook failed', { op, error: String(error) }),
})
);
return g.__harnessWorldHandler;
}
/** The tab's World access: its own run's, with its token (fail closed without a secret). */
function authorizeTab() {
const secret = tabSecret();
if (!secret) {
console.log('[harness] /api/world: no HARNESS_TAB_SECRET (or other server secret): every call about a run is refused');
return (_req: Request, call: { op: string; args: readonly unknown[] }) => runOf(call.op, call.args) === null;
}
return runScope({ secret, admit: admitTabCall });
}