Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
import type { JournalRecord, NativeJournal, TranscriptEntry } from 'harness-world-process';
/**
* Claude Code's transcript, mirrored into the run's log.
*
* Claude Code writes its session as an append-only JSONL transcript. The
* Agent SDK mirrors every line it writes to a `SessionStore` (`append`), and a
* resume loads the session back from it (`load`) before the CLI starts. This
* store is that adapter over the drive's `NativeJournal`: each entry is one
* journal record (group-committed with everything else the drive writes),
* deduped by the entry's `uuid`, so the transcript is a fold of the log and
* any machine can resume it.
*
* The entries are opaque: their shape is CLI-internal. Two things are read
* from them: an assistant entry's `tool_use` ids (for the barrier below), and
* the `uuid` of a user message the drive sent (to tell whether a placed
* prompt reached the transcript): a user entry's own `uuid`, or, for a
* message the CLI took in mid-turn (a steer), the `source_uuid` of the
* `queued_command` attachment it became.
*/
/** The SDK's `SessionKey` (structurally; the SDK is a peer dependency). */
export interface SessionKey {
projectKey: string;
sessionId: string;
subpath?: string;
}
/** One transcript line, as the SDK hands it over: JSON with a string `type`. */
export interface TranscriptLine {
type: string;
uuid?: string;
[k: string]: unknown;
}
/** The journal stream of the main transcript. */
export const CLAUDE_STREAM = 'claude';
/** The journal stream of a subagent transcript (`subpath` like `subagents/agent-<id>`). */
export const subStream = (subpath: string) => `${CLAUDE_STREAM}/${subpath}`;
const streamOf = (key: SessionKey) => (key.subpath ? subStream(key.subpath) : CLAUDE_STREAM);
/** The `tool_use` ids an assistant entry carries. */
export function toolUseIds(entry: TranscriptLine | undefined): string[] {
if (entry?.type !== 'assistant') return [];
const content = (entry.message as { content?: unknown } | undefined)?.content;
if (!Array.isArray(content)) return [];
return content.filter((c) => c?.type === 'tool_use' && typeof c.id === 'string').map((c) => c.id as string);
}
export interface JournalSessionStoreOptions {
/** The journal's records as of the drive's start, blobs resolved (`journal.read()`). */
records: JournalRecord[];
/**
* Hold appended entries this long before they go to the journal, so the
* SDK's frames (one `append` per line with eager flushing) ride in fewer
* batches. `barrier` and `flush` send them at once. Default 0.
*/
coalesceMs?: number;
}
/**
* A `SessionStore` (the SDK's `@alpha` mirror interface) whose storage is the
* drive's journal.
*
* - `append` queues the entries on the journal and returns: the journal is
* the durable writer (one batch in flight, the rest in the next), so the
* SDK's own retries and timeouts never come into play. A journal that
* failed has already halted the drive.
* - `load` returns what the log holds, as of the drive's start. Every
* session's key is the run, so `projectKey` (the CLI's cwd, which differs
* from machine to machine) is ignored.
* - `barrier(toolUseId)` resolves once the assistant entry that made that
* call is committed: before a `replay: 'never'` tool runs, the call that
* asked for it is in the log.
*/
export class JournalSessionStore {
private readonly loaded = new Map<string, TranscriptLine[]>();
private readonly calls = new Set<string>();
private readonly users = new Set<string>();
private readonly waiters = new Map<string, (() => void)[]>();
private held: ({ stream: string; entry: TranscriptLine } | { message: TranscriptEntry })[] = [];
private timer: ReturnType<typeof setTimeout> | undefined;
private readonly coalesceMs: number;
/** Entries this drive appended (for tests and diagnostics). */
appended = 0;
constructor(
private readonly journal: NativeJournal,
options: JournalSessionStoreOptions
) {
this.coalesceMs = options.coalesceMs ?? 0;
for (const r of options.records) {
if (r.stream !== CLAUDE_STREAM && !r.stream.startsWith(`${CLAUDE_STREAM}/`)) continue;
const entry = r.data as TranscriptLine | undefined;
// An offloaded entry read without its blob (`journalRecords`, not `journal.read()`): nothing to note.
if (!entry) continue;
const list = this.loaded.get(r.stream) ?? [];
list.push(entry);
this.loaded.set(r.stream, list);
this.note(entry);
}
}
/**
* Whether the log holds a transcript to resume: one with a message in it.
* Lines committed before a crash may be only queue operations, and the CLI
* refuses to resume those ("No conversation found"), every time: such a
* session starts again as a new one, under the same id.
*/
get hasSession(): boolean {
return (this.loaded.get(CLAUDE_STREAM) ?? []).some((e) => (e.type === 'user' || e.type === 'assistant') && !!e.uuid);
}
/**
* Whether the user message sent with this `uuid` is in the transcript (the
* log's, or appended since): as its own user entry, or as the
* `queued_command` attachment a mid-turn message becomes.
*/
hasUser(uuid: string): boolean {
return this.users.has(uuid);
}
/** Whether an assistant entry that made this tool call is in the transcript. */
hasCall(toolUseId: string): boolean {
return this.calls.has(toolUseId);
}
async append(key: SessionKey, entries: TranscriptLine[]): Promise<void> {
const stream = streamOf(key);
for (const entry of entries) {
this.held.push({ stream, entry });
this.appended++;
this.note(entry);
}
if (this.coalesceMs <= 0) this.release();
else this.timer ??= setTimeout(() => this.release(), this.coalesceMs);
}
/** An entry of the normalized transcript, held and committed with the lines around it. */
message(entry: TranscriptEntry): void {
this.held.push({ message: entry });
if (this.coalesceMs <= 0) this.release();
else this.timer ??= setTimeout(() => this.release(), this.coalesceMs);
}
/** Everything appended so far is committed. */
async flush(): Promise<void> {
this.release();
await this.journal.flush();
}
/** Hand the held entries to the journal (which group-commits them). */
private release(): void {
clearTimeout(this.timer);
this.timer = undefined;
for (const item of this.held.splice(0)) {
if ('message' in item) this.journal.message(item.message);
// Entries without a uuid (titles, mode markers, queue operations) are appended as they come.
else this.journal.append(item.stream, item.entry, item.entry.uuid ? { id: item.entry.uuid } : {});
}
}
async load(key: SessionKey): Promise<TranscriptLine[] | null> {
const entries = this.loaded.get(streamOf(key));
return entries?.length ? entries : null;
}
async listSubkeys(_key: { projectKey: string; sessionId: string }): Promise<string[]> {
return [...this.loaded.keys()].filter((s) => s !== CLAUDE_STREAM).map((s) => s.slice(CLAUDE_STREAM.length + 1));
}
/**
* Resolve once the assistant entry that made `toolUseId` is committed. The
* SDK delivers an entry about 100 ms after the CLI wrote it, and the tool
* runs right after the CLI wrote it, so this usually waits for the mirror
* first. Rejects after `timeoutMs` (the caller does not run the tool).
*/
async barrier(toolUseId: string, timeoutMs: number): Promise<void> {
if (!this.calls.has(toolUseId)) {
await new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => {
const list = this.waiters.get(toolUseId)?.filter((w) => w !== done) ?? [];
if (list.length) this.waiters.set(toolUseId, list);
else this.waiters.delete(toolUseId);
reject(new Error(`the transcript entry for tool call ${toolUseId} did not reach the log within ${timeoutMs} ms`));
}, timeoutMs);
const done = () => {
clearTimeout(timer);
resolve();
};
this.waiters.set(toolUseId, [...(this.waiters.get(toolUseId) ?? []), done]);
});
}
await this.flush();
}
private note(entry: TranscriptLine): void {
if (entry.type === 'user' && entry.uuid) this.users.add(entry.uuid);
const attachment = entry.type === 'attachment' ? (entry.attachment as { type?: unknown; source_uuid?: unknown } | undefined) : undefined;
if (attachment?.type === 'queued_command' && typeof attachment.source_uuid === 'string') this.users.add(attachment.source_uuid);
for (const id of toolUseIds(entry)) {
this.calls.add(id);
for (const w of this.waiters.get(id) ?? []) w();
this.waiters.delete(id);
}
}
}