Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
import type { World } from '@workflow/world';
import type { WorldCall } from './run-scope.ts';
import {
encodeFrame,
FRAME,
serializeError,
statusForError,
type WireError,
wire,
} from './wire.ts';
/**
* The storage and stream calls a remote World may make, one entry per World
* method. Everything not listed is refused: in particular the queue, which
* stays on each side of the wire (see `createRemoteWorld`).
*/
export const OPS = [
'runs.get',
'runs.list',
'steps.get',
'steps.list',
'hooks.get',
'hooks.getByToken',
'hooks.list',
'events.create',
'events.list',
'events.get',
'events.listByCorrelationId',
'streams.write',
'streams.writeMulti',
'streams.close',
'streams.getChunks',
'streams.getInfo',
'streams.list',
'getDeploymentId',
] as const;
export { mintRunToken, RUN_TOKEN_HEADER, type RunScopeOptions, type RunTokenClaims, runOf, runScope, verifyRunToken, type WorldCall } from './run-scope.ts';
/** `info` (specVersion and friends, read once per client) and the live tail. */
export type Op = (typeof OPS)[number] | 'info' | 'streams.get';
/** What `info` returns: the parts of the fronted World a client mirrors. */
export interface RemoteWorldInfo {
specVersion: number;
deploymentId: string;
capabilities?: {
hookRetention?: { active: boolean };
hookResumeDedup?: boolean;
hookForceClaim?: boolean;
};
}
/** Resume position for a `streams.get` tail after a reconnect. */
export interface StreamResume {
/** Bytes of the stream (from `startIndex`) the client already has. */
skipBytes?: number;
}
export interface WorldHandlerOptions {
/**
* Refuse a call (401) unless this returns true. Called once the request
* is parsed, with the call it carries, so a check can be about the run
* the call touches (`runScope`). Default: allow.
*/
authorize?(req: Request, call: WorldCall): boolean | Promise<boolean>;
/** Restrict the ops this endpoint serves. Default: all of them. */
ops?: readonly Op[];
/**
* Longest one `streams.get` response stays open. The client reconnects
* where it left off, so this only needs to sit under the platform's
* function duration limit. Default 240s.
*/
maxStreamMs?: number;
/**
* Called after an op succeeded, before the response goes out (so a
* client that waits for the response also waits for this). A failure is
* reported through `onError`, never to the client: the op itself is
* committed. The demo sends a server lane's wake here when a tab commits a
* handoff into it (or a submission while the session is in one); a tab
* whose own wake did not land keeps retrying it, and a tab that went away
* is covered by its tether's tab-lost callback.
*/
onCommitted?(op: Op, args: unknown[], value: unknown): void | Promise<void>;
onError?(error: unknown, op: Op): void;
}
// `never[]`: each entry spreads positional args it trusts the client to have
// shaped like the World method's own parameters; the World validates them.
type Call = (world: World, args: never[]) => Promise<unknown>;
const CALLS: Record<Exclude<Op, 'streams.get'>, Call> = {
info: async (world) =>
({
specVersion: world.specVersion,
deploymentId: await world.getDeploymentId(),
capabilities: pickCapabilities(world),
}) satisfies RemoteWorldInfo,
getDeploymentId: (world) => world.getDeploymentId(),
'runs.get': (world, [id, params]) => world.runs.get(id, params),
'runs.list': (world, [params]) => world.runs.list(params),
'steps.get': (world, [runId, stepId, params]) => world.steps.get(runId, stepId, params),
'steps.list': (world, [params]) => world.steps.list(params),
'hooks.get': (world, [hookId, params]) => world.hooks.get(hookId, params),
'hooks.getByToken': (world, [token, params]) => world.hooks.getByToken(token, params),
'hooks.list': (world, [params]) => world.hooks.list(params),
'events.create': (world, [runId, data, params]) => world.events.create(runId, data, params),
'events.list': (world, [params]) => world.events.list(params),
'events.get': (world, [runId, eventId, params]) => world.events.get(runId, eventId, params),
'events.listByCorrelationId': (world, [params]) =>
world.events.listByCorrelationId(params),
'streams.write': (world, [runId, name, chunk]) => world.streams.write(runId, name, chunk),
'streams.writeMulti': async (world, [runId, name, chunks]) => {
const all = chunks as (string | Uint8Array)[];
if (world.streams.writeMulti) return world.streams.writeMulti(runId, name, all);
for (const chunk of all) await world.streams.write(runId, name, chunk);
},
'streams.close': (world, [runId, name]) => world.streams.close(runId, name),
'streams.getChunks': (world, [runId, name, options]) =>
world.streams.getChunks(runId, name, options),
'streams.getInfo': (world, [runId, name]) => world.streams.getInfo(runId, name),
'streams.list': (world, [runId]) => world.streams.list(runId),
};
function pickCapabilities(world: World): RemoteWorldInfo['capabilities'] {
const c = world.capabilities;
if (!c) return undefined;
return {
...(c.hookRetention ? { hookRetention: c.hookRetention } : {}),
...(c.hookResumeDedup !== undefined ? { hookResumeDedup: c.hookResumeDedup } : {}),
...(c.hookForceClaim !== undefined ? { hookForceClaim: c.hookForceClaim } : {}),
};
}
/**
* Front a World over HTTP, for `createRemoteWorld` on the other side.
*
* `POST { op, args }` calls one storage or stream method and answers
* `{ value }` or, with an error status, `{ error }`; bodies use `wire` so
* bytes and dates survive. `streams.get` (POST with `resume`, or
* `GET ?op=streams.get&runId&name&startIndex&skipBytes`) answers a framed,
* long-lived body that tails the stream; see `FRAME`.
*/
export function createWorldHandler(
world: World,
options: WorldHandlerOptions = {}
): (req: Request) => Promise<Response> {
const allowed = new Set<Op>(options.ops ?? [...OPS, 'info', 'streams.get']);
const maxStreamMs = options.maxStreamMs ?? 240_000;
return async (req) => {
let op: string;
let args: unknown[];
let resume: StreamResume = {};
if (req.method === 'GET') {
const q = new URL(req.url).searchParams;
op = q.get('op') ?? '';
const startIndex = q.get('startIndex');
args = [q.get('runId'), q.get('name'), startIndex === null ? undefined : Number(startIndex)];
resume = { skipBytes: Number(q.get('skipBytes') ?? 0) };
} else if (req.method === 'POST') {
let body: { op?: unknown; args?: unknown; resume?: StreamResume };
try {
body = wire.parse(await req.text()) as typeof body;
} catch {
return invalid('body is not valid JSON');
}
if (typeof body?.op !== 'string') return invalid('missing "op"');
if (body.args !== undefined && !Array.isArray(body.args)) return invalid('"args" must be an array');
op = body.op;
args = (body.args as unknown[] | undefined) ?? [];
resume = body.resume ?? {};
} else {
return fail(405, { name: 'WorkflowWorldError', message: `method ${req.method} not allowed` });
}
if (!allowed.has(op as Op)) return invalid(`op "${op}" is not allowed`);
if (options.authorize && !(await options.authorize(req, { op, args }))) {
return fail(401, { name: 'WorkflowWorldError', message: 'unauthorized', code: 'UNAUTHORIZED' });
}
try {
if (op === 'streams.get') {
const [runId, name, startIndex] = args as [string, string, number | undefined];
if (typeof runId !== 'string' || typeof name !== 'string') {
return invalid('streams.get needs runId and name');
}
return await tail(world, runId, name, startIndex, resume, req.signal, maxStreamMs);
}
const value = await CALLS[op as Exclude<Op, 'streams.get'>](world, args as never[]);
if (options.onCommitted) {
try {
await options.onCommitted(op as Op, args, value);
} catch (err) {
options.onError?.(err, op as Op);
}
}
return json(200, { value });
} catch (err) {
const error = serializeError(err);
return fail(statusForError(error), error);
}
};
}
function json(status: number, body: unknown): Response {
return new Response(wire.stringify(body), {
status,
headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
});
}
function fail(status: number, error: WireError): Response {
return json(status, { error });
}
function invalid(message: string): Response {
return fail(400, { name: 'WorkflowWorldError', message, code: 'INVALID_ARGUMENT' });
}
const encoder = new TextEncoder();
/**
* Tail one stream as a framed body. Resumption counts bytes, not chunks,
* because a World's live read need not preserve chunk boundaries
* (world-vercel's is a plain byte stream): the client reconnects with the
* same absolute `startIndex` and the number of bytes it already has.
*/
async function tail(
world: World,
runId: string,
name: string,
startIndex: number | undefined,
resume: StreamResume,
signal: AbortSignal,
maxStreamMs: number
): Promise<Response> {
let start = startIndex ?? 0;
if (start < 0) {
const info = await world.streams.getInfo(runId, name);
start = Math.max(0, info.tailIndex + 1 + start);
}
const upstream = (await world.streams.get(runId, name, start)).getReader();
let skip = Math.max(0, resume.skipBytes ?? 0);
let cut = false;
let finished = false;
const stop = () => {
cut = true;
void upstream.cancel().catch(() => {});
};
const timer = setTimeout(stop, maxStreamMs);
(timer as { unref?: () => void }).unref?.();
signal.addEventListener('abort', stop, { once: true });
const cleanup = () => {
finished = true;
clearTimeout(timer);
signal.removeEventListener('abort', stop);
};
const body = new ReadableStream<Uint8Array>({
async pull(controller) {
if (finished) return;
for (;;) {
let result: ReadableStreamReadResult<Uint8Array>;
try {
result = await upstream.read();
} catch (err) {
cleanup();
if (cut) {
controller.enqueue(encodeFrame(FRAME.reconnect));
} else {
const payload = encoder.encode(wire.stringify(serializeError(err)));
controller.enqueue(encodeFrame(FRAME.error, payload));
}
controller.close();
return;
}
if (result.done) {
cleanup();
// A cancel we caused ends the read as `done` too: not the stream's end.
controller.enqueue(encodeFrame(cut ? FRAME.reconnect : FRAME.end));
controller.close();
return;
}
let chunk = result.value;
if (skip > 0) {
if (skip >= chunk.length) {
skip -= chunk.length;
continue;
}
chunk = chunk.subarray(skip);
skip = 0;
}
if (chunk.length === 0) continue;
controller.enqueue(encodeFrame(FRAME.data, chunk));
return;
}
},
cancel() {
cleanup();
stop();
},
});
return new Response(body, {
status: 200,
headers: {
'content-type': 'application/vnd.harness-world-remote.frames',
// A live tail: nothing between here and the reader may buffer it
// (a compressing proxy holds chunks until its window fills, so
// tokens arrive in bursts).
'cache-control': 'no-store, no-transform',
'content-encoding': 'identity',
'x-accel-buffering': 'no',
// Where the tail began, so a client that asked for a negative
// startIndex can reconnect to the same absolute position.
'x-stream-start': String(start),
},
});
}