Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
import { batchTranscript } from 'harness-world-process/records';
import { type ReactNode, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
import { CrashGlyph, preloaded } from './bits.tsx';
import { armedText, prearmedText } from './copy.ts';
import { type CrashInfo, cite, type LogIndex, modelText, modelToolCalls } from './lanes.ts';
import type { RowCtx } from './Rows.tsx';
import type { ChaosSpec, EffectView, Lane, LedgerEntry, SessionView } from './view.ts';
// The row components and the Markdown renderer arrive together, with the
// page, in their own chunk. They are held in a module variable rather than
// React.lazy: a lazy component suspends on its first render even when its
// chunk is already here, and the fallback it swaps out moves the rows. The
// page shows transcript rows once they're ready (`useRowsReady`).
const rows = preloaded(() => import('./Rows.tsx'));
export const useRowsReady = () => !!rows.use();
export type Item =
| { t: 'user'; key: string; subId?: string; text: string; steer: boolean; queued: boolean; withdrawn: boolean; lane?: Lane }
| { t: 'model'; key: string; effect: EffectView; lane?: Lane }
/** `model`: the call that asked for it, when that call said nothing else (its row folds into this one). */
| { t: 'tool'; key: string; effect: EffectView; lane?: Lane; crashed?: boolean; model?: EffectView }
| { t: 'handoff'; key: string; effect: EffectView; from: Lane; to: Lane; reason: string }
/** `told`: what the harness was told after it (a process harness's recovery note, folded in). */
| { t: 'crash'; key: string; effect: EffectView; crash?: CrashInfo; told?: string }
| { t: 'fs'; key: string; effect: EffectView; paths: string[]; lane?: Lane }
| { t: 'checkpoint'; key: string; effect: EffectView; lane?: Lane }
/** A process harness's assistant message (a `transcript` journal entry); `calls` are its tool effects' keys. */
| { t: 'message'; key: string; effect: EffectView; text: string; calls: string[]; lane?: Lane }
/** A message a process harness sent its model itself (a recovery note). */
| { t: 'note'; key: string; effect: EffectView; text: string; synthetic: string; lane?: Lane };
/** The transcript is a fold of the log: one item per effect, plus the inbox. */
export function buildItems(view: SessionView, lanes: Map<string, Lane>, crashList: CrashInfo[]): Item[] {
const subs = new Map(view.submissions.map((s) => [s.id, s]));
const shown = new Set<string>();
const items: Item[] = [];
/** A process harness's session (harness-world-process: its turns end with a transcript entry). */
const processSession = view.turnOpen !== undefined;
const pushSub = (id: string, lane?: Lane) => {
const s = subs.get(id);
if (!s || shown.has(id) || s.kind === 'chaos' || s.kind === 'withdraw') return;
shown.add(id);
items.push({ t: 'user', key: `sub:${id}`, subId: id, text: s.text ?? '', steer: s.kind === 'steer', queued: false, withdrawn: false, lane });
};
for (const e of view.effects) {
const lane = lanes.get(e.key);
const placed: string[] = e.placed.length
? e.placed
: e.name === 'turn' && Array.isArray(e.input?.submissions)
? e.input.submissions.map((s: any) => s.id)
: [];
for (const id of placed) pushSub(id, lane);
if (!placed.length && e.name === 'steer' && typeof e.input?.text === 'string')
items.push({ t: 'user', key: e.key, text: e.input.text, steer: true, queued: false, withdrawn: false, lane });
if (!placed.length && e.name === 'model' && Array.isArray(e.input?.appended)) {
e.input.appended.forEach((m: any, i: number) => {
if (m?.role !== 'user') return;
const text = typeof m.content === 'string' ? m.content : (m.content ?? []).map((c: any) => c.text ?? '').join('');
items.push({ t: 'user', key: `${e.key}:u${i}`, text, steer: false, queued: false, withdrawn: false, lane });
});
}
if (e.name === 'model') {
// A process harness's model step (written only around a crash drill) has no text of
// its own: its messages are journal entries, and its live text streams in a row of its own.
if (!processSession) items.push({ t: 'model', key: e.key, effect: e, lane });
} else if (e.name.startsWith('tool.')) items.push({ t: 'tool', key: e.key, effect: e, lane });
else if (e.name === 'handoff') {
const h = e.output ?? e.input ?? {};
items.push({ t: 'handoff', key: e.key, effect: e, from: h.from, to: h.to, reason: String(h.reason ?? '') });
} else if (e.name === 'chaos' && e.status === 'completed')
items.push({ t: 'crash', key: e.key, effect: e, crash: crashList.find((c) => c.key === e.key) });
else if (e.name === 'fs') items.push({ t: 'fs', key: e.key, effect: e, paths: e.input?.paths ?? Object.keys(e.output?.files ?? {}), lane });
// A sandbox command's settlement carries the files it changed: shown like an fs step.
else if (e.name === 'settle' && Array.isArray(e.input?.paths) && e.input.paths.length)
items.push({ t: 'fs', key: e.key, effect: e, paths: e.input.paths, lane });
else if (e.name === 'checkpoint') items.push({ t: 'checkpoint', key: e.key, effect: e, lane });
// A process harness's normalized transcript (harness-world-process), one row per entry.
else if (e.name === 'journal' && e.status === 'completed') {
batchTranscript(e.input).forEach((entry, i) => {
const key = `${e.key}:${i}`;
if (entry.type !== 'message') return;
if (entry.role === 'user') items.push({ t: 'note', key, effect: e, text: entry.text, synthetic: entry.synthetic, lane });
else if (entry.text || !entry.toolCalls?.length)
items.push({ t: 'message', key, effect: e, text: entry.text, calls: (entry.toolCalls ?? []).map((c) => `tool:${c.id}`), lane });
});
}
}
// A message comes before the tool calls it made, even when its batch
// landed after a replay-safe call (only a never call waits for it).
// Codex's rows stay in log order: its message after a call is its own.
if (view.harness !== 'codex')
for (const m of items.filter((i): i is Extract<Item, { t: 'message' }> => i.t === 'message' && i.calls.length > 0)) {
const first = items.findIndex((i) => i.t === 'tool' && m.calls.includes(i.effect.key));
const at = items.indexOf(m);
if (first >= 0 && first < at) {
items.splice(at, 1);
items.splice(first, 0, m);
}
}
for (const s of view.submissions) {
if (shown.has(s.id) || s.kind === 'chaos' || s.kind === 'withdraw') continue;
items.push({
t: 'user',
key: `sub:${s.id}`,
subId: s.id,
text: s.text ?? '',
steer: s.kind === 'steer',
queued: !s.placed && !s.withdrawn,
withdrawn: s.withdrawn,
});
}
// A process harness's notes to itself: the environment note stays in the
// log; a recovery note folds into the crash row it follows (in its turn).
for (let i = items.length - 1; i >= 0; i--) {
const it = items[i]!;
if (it.t !== 'note') continue;
if (it.synthetic !== 'recovery') {
items.splice(i, 1);
continue;
}
for (let j = i - 1; j >= 0; j--) {
const prev = items[j]!;
if (prev.t === 'user' && !prev.steer) break;
if (prev.t === 'crash') {
if (!prev.told) items[j] = { ...prev, told: it.text };
items.splice(i, 1);
break;
}
}
}
// A model call that said nothing but which tools to call is the tool row's
// ("model 0.9 s"), not a row of its own. Not a call a crash killed: its row
// is where the crash row goes.
const killed = new Set(crashList.map((c) => c.killedKey));
for (let i = items.length - 1; i >= 0; i--) {
const it = items[i]!;
if (it.t !== 'model' || it.effect.status !== 'completed' || killed.has(it.effect.key)) continue;
if (modelText(it.effect)) continue;
const next = items[i + 1];
if (next?.t !== 'tool' || next.model) continue;
// Its tool calls, or (a view that keeps them apart: fx (libfx durable)) the tool row right after it.
items[i + 1] = { ...next, model: it.effect };
items.splice(i, 1);
}
// A crash reads as a child of the step it killed. A step it killed that
// was run again shows the rerun: the crash row goes before it, so the
// recovered output follows the crash. A step left interrupted: after it.
for (const crash of items.filter((i): i is Extract<Item, { t: 'crash' }> => i.t === 'crash')) {
const killedKey = crash.crash?.killedKey ?? crash.effect.output?.crashedDuring;
const at = items.findIndex((i) => i.t !== 'user' && i.t !== 'crash' && i.effect.key === killedKey);
if (at < 0) continue;
const victim = items[at]!;
if (victim.t === 'tool' && crash.crash?.state !== 'replayed') items[at] = { ...victim, crashed: true };
items.splice(items.indexOf(crash), 1);
const before = crash.crash?.state === 'replayed';
let to = items.findIndex((i) => i.key === victim.key) + (before ? 0 : 1);
if (!before) while (items[to]?.t === 'crash') to++;
items.splice(to, 0, crash);
}
return items;
}
/**
* The kind column's width, in the row's `ch`: the longest label it shows
* (the harness's name, or a tool's such as `update_todos`), so none is cut
* off, up to a limit past which a long tool name ellipsizes. A tool name is
* set in 12 px Geist Mono, about 0.8 of the row's `ch` per character.
*/
export function kindWidth(harnessName: string, items: Item[]): number {
let w = Math.max(5, harnessName.length);
for (const i of items) if (i.t === 'tool') w = Math.max(w, Math.ceil((i.effect.name.length - 'tool.'.length) * 0.8));
return Math.min(w, 18);
}
/** Log positions an item cites. */
export function itemIndexes(item: Item, index: LogIndex): number[] {
if (item.t === 'user') return item.subId ? [index.byEvent.get(item.subId)].filter((n): n is number => n !== undefined) : [];
return index.byStep.get(item.effect.stepId) ?? [];
}
/** Step ids an item's events belong to (for highlighting log rows). */
export function itemSteps(item: Item): string[] {
return item.t === 'user' ? [] : [item.effect.stepId];
}
export interface TranscriptProps extends Omit<RowCtx, 'selectedKey' | 'tabKey' | 'ledger'> {
/** The session's side effects (the unsafe tools' ledger): a payment row says how many times it ran. */
ledger?: LedgerEntry[];
items: Item[];
/** A process harness is generating: show its live text in a row of its own (its model call is a step only around a crash drill, and has no text). */
streaming?: boolean;
armed?: ChaosSpec;
/** The armed crash is for the next session started (none is open). */
prearmed?: boolean;
/** The armed crash has fired: the process is gone. */
armedFired?: boolean;
selectedKey?: string;
/** Changes when the open session changes: reset scroll. */
sessionKey: string;
/** Bumped when the user moves the session on (send, steer, Try): follow the newest row again. */
followKey: number;
notes: { tone?: 'error'; text: ReactNode; key: string }[];
empty?: ReactNode;
scrollTo?: { key: string; n: number; pin?: boolean };
/** Shown right after the row with this key (each finished turn's caption). */
captions?: Map<string, ReactNode>;
}
const flash = (el: HTMLElement) => {
el.classList.remove('flash');
void el.offsetWidth;
el.classList.add('flash');
};
/**
* Scrolling, explicitly (`overflow-anchor: none`):
* - follow: stick to the newest row while the reader is at the bottom;
* - pin: when a crash resolves, hold its row (and the step it killed) near
* the top, however much the model writes after it, until the reader
* scrolls or moves the session on;
* - otherwise stay put and count the rows that landed below the fold.
*/
export function Transcript(props: TranscriptProps) {
const { items, armed, notes, empty, sessionKey, scrollTo, followKey } = props;
const scroller = useRef<HTMLDivElement>(null);
const inner = useRef<HTMLDivElement>(null);
const follow = useRef(true);
const pin = useRef<string | undefined>(undefined);
const [unseen, setUnseen] = useState(0);
const Rows = rows.use();
const tabKey = items.some((i) => i.key === props.selectedKey) ? props.selectedKey : items[0]?.key;
const ctx: RowCtx = {
mode: props.mode,
world: props.world,
harnessName: props.harnessName,
times: props.times,
index: props.index,
live: props.live,
frozenAt: props.frozenAt,
selectedKey: props.selectedKey,
tabKey,
onSelect: props.onSelect,
onHover: props.onHover,
onCite: props.onCite,
onOpenFile: props.onOpenFile,
...(props.ledger ? { ledger: props.ledger } : {}),
};
/** Rows whose top is below the visible area. */
const countBelow = useCallback(() => {
const el = scroller.current;
const box = inner.current;
if (!el || !box) return;
const bottom = el.scrollTop + el.clientHeight;
let n = 0;
for (let c = box.lastElementChild as HTMLElement | null; c; c = c.previousElementSibling as HTMLElement | null) {
if (c.offsetTop < bottom - 4) break;
if (c.dataset.key) n++;
}
setUnseen((prev) => (prev === n ? prev : n));
}, []);
const applyPin = useCallback(() => {
const el = scroller.current;
const key = pin.current;
if (!el || !key) return false;
const row = inner.current?.querySelector<HTMLElement>(`:scope > [data-key="${CSS.escape(key)}"]`);
if (!row) return false;
// Show the killed step above the crash row when both fit.
const prev = row.previousElementSibling as HTMLElement | null;
const both = prev?.dataset.key ? row.offsetTop + row.offsetHeight - prev.offsetTop : Number.POSITIVE_INFINITY;
const top = both <= el.clientHeight * 0.7 ? prev!.offsetTop : row.offsetTop;
el.scrollTop = Math.max(0, top - 16);
return true;
}, []);
const settle = useCallback(() => {
const el = scroller.current;
if (!el) return;
if (pin.current) applyPin();
else if (follow.current) el.scrollTop = el.scrollHeight;
countBelow();
}, [applyPin, countBelow]);
const toLatest = useCallback(() => {
pin.current = undefined;
follow.current = true;
settle();
}, [settle]);
useLayoutEffect(() => {
pin.current = undefined;
follow.current = true;
const el = scroller.current;
if (el) el.scrollTop = el.scrollHeight;
setUnseen(0);
}, [sessionKey]);
// The user moved the session on: show what happens next.
const lastFollowKey = useRef(followKey);
useLayoutEffect(() => {
if (lastFollowKey.current === followKey) return;
lastFollowKey.current = followKey;
toLatest();
}, [followKey, toLatest]);
// New rows. A crash that just resolved pins its row; a crash or note that
// just appeared is news, so it releases a pin and follows.
const seen = useRef<{ session: string; crashes: Map<string, string>; notes: Set<string> }>({ session: '', crashes: new Map(), notes: new Set() });
useLayoutEffect(() => {
const prev = seen.current;
const fresh = prev.session !== sessionKey;
const crashes = new Map<string, string>();
let resolved: string | undefined;
let appeared = false;
for (const it of items) {
if (it.t !== 'crash') continue;
const st = it.crash?.state ?? 'waiting';
crashes.set(it.key, st);
const was = prev.crashes.get(it.key);
if (fresh) continue;
if (was === undefined) appeared = true;
if (st !== 'waiting' && was !== st) resolved = it.key;
}
const noteKeys = new Set(notes.map((n) => n.key));
if (!fresh) for (const k of noteKeys) if (!prev.notes.has(k)) appeared = true;
// Only once the session's first rows are in does "new" mean new.
seen.current = { session: items.length || notes.length ? sessionKey : '', crashes, notes: noteKeys };
if (resolved) {
pin.current = resolved;
follow.current = false;
const row = inner.current?.querySelector<HTMLElement>(`:scope > [data-key="${CSS.escape(resolved)}"]`);
if (row) flash(row);
} else if (appeared) {
pin.current = undefined;
follow.current = true;
}
settle();
}, [items, armed, notes, sessionKey, settle]);
// Streaming text, Markdown and expanded output change heights: keep the
// pin (or the bottom) where it was.
useEffect(() => {
const el = inner.current;
if (!el || typeof ResizeObserver === 'undefined') return;
const ro = new ResizeObserver(() => settle());
ro.observe(el);
return () => ro.disconnect();
}, [settle]);
useEffect(() => {
if (!scrollTo) return;
const el = inner.current?.querySelector<HTMLElement>(`:scope > [data-key="${CSS.escape(scrollTo.key)}"]`);
if (!el) return;
if (scrollTo.pin) {
pin.current = scrollTo.key;
follow.current = false;
settle();
} else {
pin.current = undefined;
el.scrollIntoView({ block: 'nearest' });
}
flash(el);
}, [scrollTo, settle]);
// Anything the reader does to scroll ends a pin.
const release = () => {
pin.current = undefined;
};
const onScroll = () => {
const el = scroller.current;
if (!el) return;
if (!pin.current) follow.current = el.scrollHeight - el.scrollTop - el.clientHeight < 48;
countBelow();
};
return (
<div className="t-frame" style={{ position: 'relative', minHeight: 0, display: 'grid' }}>
<div
className="scroll transcript"
// The kind column fits the longest label it shows: the harness's name, or a tool's (up to a limit).
style={{ '--kind-w': `${kindWidth(props.harnessName, props.items)}ch` } as React.CSSProperties}
ref={scroller}
onScroll={onScroll}
onWheel={release}
onTouchMove={release}
onPointerDown={(ev) => {
// A drag on the scrollbar (the pointer lands outside the content).
if (ev.target === ev.currentTarget) release();
}}
onKeyDown={(ev) => {
if (['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '].includes(ev.key)) release();
}}
role="log"
aria-label="Transcript"
>
<div ref={inner}>
{empty}
{Rows &&
items.map((item) => {
const t = item.t === 'user' ? undefined : ctx.times.get(item.effect.stepId);
const chip = props.captions?.get(item.key);
const row = (
<Rows.Row
key={item.key}
item={item}
ctx={ctx}
sig={Rows.rowSig(item)}
cites={cite(itemIndexes(item, ctx.index))}
started={t?.started}
ended={t?.ended}
selected={ctx.selectedKey === item.key}
tab={tabKey === item.key}
ledger={props.ledger?.length ?? 0}
/>
);
return chip ? [row, chip] : row;
})}
{Rows && props.streaming && <Rows.StreamRow ctx={ctx} />}
{armed && (
// The crash as one object: armed here, then the crash row (killed, then back).
<div className="t-crash" data-state={props.armedFired ? 'fired' : 'armed'} data-key="crash:armed">
<div className="t-kind">
<CrashGlyph armed={!props.armedFired} />
</div>
<div className="t-content">
<p className="crash-text">
{props.armedFired ? 'Crash fired: waiting for the process to come back.' : props.prearmed ? prearmedText(armed) : armedText(armed)}
</p>
</div>
</div>
)}
{notes.map((n) => (
<div key={n.key} className="note" data-tone={n.tone}>
{n.text}
</div>
))}
</div>
</div>
{unseen > 0 && (
<button type="button" className="btn float jump" onClick={toLatest}>
Jump to Latest ({unseen})
</button>
)}
</div>
);
}