Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
import type { AgentRunsLink, ChaosSpec, DemoClient, SessionRow, SessionView, WorldName } from 'harness-world-demo-ui';
import { type FxLine, type FxSide, fxBusy, fxLiveEvents, fxPartial, fxProjection } from 'harness-world-demo-ui/fx-view';
import { pendingRows } from './pending.ts';
/**
* "fx (libfx durable)": libfx's own durable sessions on the server's World,
* over the demo app's `/api/fx-durable` routes. Server mode only.
*
* The page follows each session the way the libfx durability doc has a
* browser do it: one subscription to the session's stream, which reconnects
* with the last `cursor` it saw, from whichever server answers. The view,
* the event rows and the live events all come from those lines (plus the
* crash and workspace streams the app keeps beside libfx).
*/
async function json<T>(response: Response): Promise<T> {
if (!response.ok) {
// The routes say why in `error` (fx (libfx durable) off on this server's World, crashes off, a foreign run id).
const error = await response.json().then((body: { error?: unknown }) => body?.error, () => undefined);
throw new Error(typeof error === 'string' ? error : `${response.url.replace(location.origin, '')} ${response.status}`);
}
return response.json() as Promise<T>;
}
const post = (url: string, body: unknown) =>
fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
interface ListResponse {
world: WorldName;
/** On Vercel: where the sessions show in Agent Runs. */
agentRuns?: AgentRunsLink;
chaos: boolean;
sessions: SessionRow[];
}
const LIST = '/api/sessions?harness=fx-durable';
/** A first read waits this long for the stream's first line (a new session has none). */
const FIRST_LINE_MS = 2500;
/** Once lines flow, the stream has caught up when none arrives for this long. */
const QUIET_MS = 250;
/**
* A subscription stops this long after its last listener leaves (`live`'s
* unsubscribe), so a quick re-subscribe (a re-render, a reconnect) reuses it.
*/
const GRACE_MS = 5_000;
/** A subscription only read (`inspect`, `events`), never listened to, stops this long after its last read. */
const IDLE_MS = 120_000;
interface Follow {
lines: FxLine[];
listeners: Set<(line: FxLine) => void>;
caughtUp: Promise<void>;
/** The timer that stops it while nobody listens; `grace` when a listener's leaving armed it. */
parked?: { timer: ReturnType<typeof setTimeout>; grace: boolean };
stop(): void;
}
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
/** Subscribe to one session's stream, reconnecting from the last cursor until stopped. */
function follow(id: string): Follow {
const controller = new AbortController();
let caughtUp!: () => void;
let quiet: ReturnType<typeof setTimeout> | undefined;
const f: Follow = {
lines: [],
listeners: new Set(),
caughtUp: new Promise<void>((resolve) => (caughtUp = resolve)),
stop: () => {
clearTimeout(f.parked?.timer);
f.parked = undefined;
controller.abort();
},
};
const settle = (ms: number) => {
clearTimeout(quiet);
quiet = setTimeout(caughtUp, ms);
};
settle(FIRST_LINE_MS);
void (async () => {
let failures = 0;
while (!controller.signal.aborted) {
try {
const cursor = f.lines.at(-1)?.cursor ?? 0;
// No line yet is -1, so a stream whose first line has cursor 0 keeps it.
const last = f.lines.at(-1)?.cursor ?? -1;
const response = await fetch(`/api/fx-durable/${id}/stream?cursor=${cursor}`, { signal: controller.signal });
if (!response.ok || !response.body) throw new Error(`stream ${response.status}`);
failures = 0;
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffered = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffered += decoder.decode(value, { stream: true });
for (let index = buffered.indexOf('\n'); index >= 0; index = buffered.indexOf('\n')) {
const raw = buffered.slice(0, index);
buffered = buffered.slice(index + 1);
let parsed: Omit<FxLine, 'at'>;
try {
parsed = JSON.parse(raw);
} catch {
continue;
}
if (!Number.isSafeInteger(parsed.cursor) || parsed.cursor <= (f.lines.at(-1)?.cursor ?? last)) continue;
const line: FxLine = { ...parsed, at: Date.now() };
f.lines.push(line);
settle(QUIET_MS);
for (const listener of f.listeners) listener(line);
}
}
} catch {
if (controller.signal.aborted) return;
failures += 1;
}
// The server closes a stream at its function's duration limit: reconnect from the last cursor.
await sleep(Math.min(5000, 250 * 2 ** failures));
}
})();
return f;
}
export async function createClient(): Promise<DemoClient> {
// The runs list can take the World a while: the page is ready on the server's description alone.
let firstList: Promise<SessionRow[]> | undefined = fetch(LIST).then((r) => json<ListResponse>(r)).then((r) => r.sessions);
firstList.catch(() => {});
const first = await fetch(`${LIST}&list=0`).then((r) => json<ListResponse>(r));
const pending = pendingRows();
const follows = new Map<string, Follow>();
const sides = new Map<string, FxSide>();
// Sessions started without a prompt have no World run until their first
// message (libfx creates it then), so a crash armed on one waits here and
// goes with that message.
const unstarted = new Set<string>();
const prearmed = new Map<string, ChaosSpec>();
// What live() attached, so close() can detach it.
const detachers = new Set<() => void>();
let closed = false;
/** Stop `f` after `ms` unless a listener arrives first. */
const park = (id: string, f: Follow, ms: number, grace: boolean) => {
clearTimeout(f.parked?.timer);
const timer = setTimeout(() => {
if (f.listeners.size) return;
f.stop();
if (follows.get(id) === f) follows.delete(id);
}, ms);
f.parked = { timer, grace };
};
const followOf = (id: string): Follow => {
let f = follows.get(id);
if (!f) {
f = follow(id);
follows.set(id, f);
}
// A read with nobody listening keeps it a while; a grace period a
// listener's leaving started runs out as it was (after close, every
// follow gets only that).
if (!f.listeners.size && !f.parked?.grace) park(id, f, closed ? GRACE_MS : IDLE_MS, closed);
return f;
};
const sideOf = async (id: string): Promise<FxSide> => {
const side = await fetch(`/api/fx-durable/${id}/side`).then((r) => json<FxSide>(r));
sides.set(id, side);
return side;
};
const projection = async (id: string) => {
const f = followOf(id);
const [side] = await Promise.all([sideOf(id), f.caughtUp]);
return { f, side, ...fxProjection(id, f.lines, side.chaos, side.workspace) };
};
return {
mode: 'server',
// libfx awaits the prompt and an unsafe tool's intent; its other records trail the turn.
durability: 'run-ahead',
worldName: first.world,
...(first.agentRuns ? { agentRuns: first.agentRuns } : {}),
chaosEnabled: first.chaos,
fxAvailable: true,
async list() {
const listed = firstList ?? fetch(LIST).then((r) => json<ListResponse>(r)).then((r) => r.sessions);
firstList = undefined;
return pending.merge(await listed);
},
async start(_harness, prompt) {
const { sessionId } = await post('/api/fx-durable', prompt ? { prompt, requestId: crypto.randomUUID() } : {}).then((r) => json<{ sessionId: string }>(r));
pending.add(sessionId, 'fx-durable');
if (!prompt) unstarted.add(sessionId);
return sessionId;
},
async send(id, text, kind) {
const chaos = prearmed.get(id);
await post(`/api/fx-durable/${id}/messages`, { text, kind, requestId: crypto.randomUUID(), ...(chaos ? { chaos } : {}) }).then(json);
unstarted.delete(id);
prearmed.delete(id);
},
async inspect(id): Promise<SessionView> {
const { view } = await projection(id);
const armed = prearmed.get(id);
return armed ? { ...view, armedChaos: armed } : view;
},
// Every row, every time: the page skips the ids it has, and a crash row can land between lines it already read.
async events(id) {
const { events } = await projection(id);
return { events, ...(events.length ? { cursor: events.at(-1)!.eventId } : {}) };
},
async event(id, eventId) {
const line = /:line:(\d+)$/.exec(eventId);
if (line) return followOf(id).lines.find((l) => l.cursor === Number(line[1]));
const crash = /:chaos:(\d+)$/.exec(eventId);
if (crash) return (sides.get(id) ?? (await sideOf(id))).chaos[Number(crash[1])];
return undefined;
},
chaos: async (id, spec) => {
if (unstarted.has(id)) prearmed.set(id, spec);
else await post(`/api/fx-durable/${id}/chaos`, spec).then(json);
},
livePushes: true,
/** Stop every subscription this client holds (the compare page closes a column's client with it). */
close() {
closed = true;
for (const detach of [...detachers]) detach();
for (const f of follows.values()) f.stop();
follows.clear();
},
live(id, onEvent) {
const f = followOf(id);
// An attach replays the running model call's text from its start: the page drops what it buffered.
onEvent({ type: 'rewind', reason: 'connect', t: Date.now() });
const partial = fxBusy(f.lines) ? fxPartial(f.lines) : '';
if (partial) onEvent({ type: 'text', delta: partial, t: Date.now() });
let busy = fxBusy(f.lines);
const listener = (line: FxLine) => {
if (line.type === 'turn_start' || line.type === 'turn_resume') busy = true;
else if (line.type === 'turn_end') busy = fxBusy(f.lines);
for (const event of fxLiveEvents(line, busy)) onEvent(event);
};
clearTimeout(f.parked?.timer);
f.parked = undefined;
f.listeners.add(listener);
// Timing marks (model and tool steps), so the page can take the model's
// own time out of each turn. The route replays them from the start, so
// a reconnect skips the ones already passed on.
const marksAbort = new AbortController();
void (async () => {
let passed = 0;
let failures = 0;
while (!marksAbort.signal.aborted) {
try {
const response = await fetch(`/api/fx-durable/${id}/marks`, { signal: marksAbort.signal });
if (!response.ok || !response.body) throw new Error(`marks ${response.status}`);
failures = 0;
const reader = response.body.getReader();
const decoder = new TextDecoder();
let skip = passed;
let buffered = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffered += decoder.decode(value, { stream: true });
for (let index = buffered.indexOf('\n'); index >= 0; index = buffered.indexOf('\n')) {
const raw = buffered.slice(0, index);
buffered = buffered.slice(index + 1);
if (!raw.trim()) continue;
if (skip > 0) {
skip -= 1;
continue;
}
passed += 1;
try {
onEvent(JSON.parse(raw));
} catch {}
}
}
} catch {
if (marksAbort.signal.aborted) return;
failures += 1;
}
await sleep(Math.min(5000, 250 * 2 ** failures));
}
})();
// Crash lines live outside the session's stream: look for new ones while the page follows it.
let crashes = sides.get(id)?.chaos.length;
const poll = setInterval(async () => {
const side = await sideOf(id).catch(() => undefined);
if (!side || side.chaos.length === crashes) return;
crashes = side.chaos.length;
// Not a mark: see fxLiveEvents.
onEvent(side.chaos.at(-1)?.t === 'fired' ? { type: 'chaos', t: Date.now() } : { type: 'armed', t: Date.now() });
}, 2000);
const detach = () => {
if (!detachers.delete(detach)) return;
f.listeners.delete(listener);
marksAbort.abort();
clearInterval(poll);
// The last listener gone: stop following soon, unless one comes back first.
if (!f.listeners.size) park(id, f, GRACE_MS, true);
};
detachers.add(detach);
return detach;
},
};
}