Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

6.5 KB
Raw Blame
import { readFileSync } from 'node:fs';
import { describe, expect, it } from 'vitest';
import { blobHashes, eventName, isTerminal, type OpenCodeEvent, statusOf, TranscriptBuilder } from './records.ts';

/**
 * The pure readers, on events recorded from real OpenCode 2.0.22 turns
 * through this harness (`test/fixtures/`): `turn.json` is one turn with two
 * tool calls; `crash.json` is a turn whose process was SIGKILLed during
 * `unsafe_make_payment` (seq 0-9) and the recovery that finished it on
 * another session root (seq 10-21).
 */

interface Fixture {
  runId: string;
  events: OpenCodeEvent[];
  blobs: { hash: string; value: unknown }[];
}
const fixture = (name: string) => JSON.parse(readFileSync(new URL(`../test/fixtures/${name}.json`, import.meta.url), 'utf8')) as Fixture;
const turn = fixture('turn');
const crash = fixture('crash');
const upTo = (f: Fixture, seq: number) => f.events.filter((e) => e.seq <= seq);
const msgId = (f: Fixture) => String(f.events.find((e) => eventName(e) === 'session.inbox.enqueued')!.data.inboxID);

describe('statusOf', () => {
  it('a finished turn: no claim, nothing undelivered', () => {
    const s = statusOf(turn.events);
    expect(s).toMatchObject({ lastSeq: 28, claimHeld: false, executing: false, restarts: 0 });
    expect([...s.enqueued]).toEqual([msgId(turn)]);
    expect(s.undelivered.size).toBe(0);
  });

  it('a turn cut off mid tool: the claim is held, the prompt admitted', () => {
    const s = statusOf(upTo(crash, 9));
    expect(s).toMatchObject({ lastSeq: 9, claimHeld: true, executing: true, restarts: 0 });
    expect(s.enqueued.has(msgId(crash))).toBe(true);
    expect(s.undelivered.size).toBe(0);
  });

  it('counts restart notices until a terminal event resets them', () => {
    // seq 10: our recovery note (inbox), 11: OpenCode's restart notice, 12: the resumed execution.
    expect(statusOf(upTo(crash, 12))).toMatchObject({ claimHeld: true, restarts: 1 });
    expect(statusOf(upTo(crash, 10)).undelivered.size).toBe(1);
    expect(statusOf(crash.events)).toMatchObject({ claimHeld: false, executing: false, restarts: 0 });
  });

  it('an interruption for shutdown keeps the claim; any other ends the turn', () => {
    const base = upTo(crash, 9);
    const at = (data: object) => ({ id: 'evt_x', seq: 10, created: 0, type: 'session.execution.interrupted.1', data: { sessionID: 's', ...data } });
    expect(isTerminal(at({ reason: 'shutdown' }))).toBe(false);
    expect(statusOf([...base, at({ reason: 'shutdown' })])).toMatchObject({ claimHeld: true, executing: false });
    expect(isTerminal(at({ reason: 'user' }))).toBe(true);
    expect(statusOf([...base, at({ reason: 'user' })])).toMatchObject({ claimHeld: false });
  });
});

describe('TranscriptBuilder', () => {
  it('a message and the call it made are one entry; a turn ends at the execution’s end', () => {
    const b = new TranscriptBuilder();
    const entries = turn.events.flatMap((e) => b.push(e));
    expect(entries.map((e) => (e.type === 'turn' ? `turn:${e.status}` : `${e.role}:${e.type === 'message' && 'toolCalls' in e ? e.toolCalls?.map((c) => c.name).join(',') : ''}`))).toEqual([
      'assistant:write_file',
      'assistant:read_file',
      'assistant:',
      'turn:completed',
    ]);
    const [first, , last] = entries as { text: string; toolCalls?: { id: string }[] }[];
    expect(first!.text).toContain('haiku');
    // The call id is OpenCode's own: the tool's effect key is `tool:<id>`.
    expect(first!.toolCalls![0]!.id).toBe(turn.events.find((e) => eventName(e) === 'session.tool.called')!.data.id);
    expect(last!.text.length).toBeGreaterThan(0);
  });

  it('primed with the journal, it writes only what new events complete', () => {
    const b = new TranscriptBuilder(upTo(crash, 9));
    const entries = crash.events.filter((e) => e.seq > 9).flatMap((e) => b.push(e));
    expect(entries.map((e) => e.type)).toEqual(['message', 'turn']);
    expect(entries[0]).toMatchObject({ role: 'assistant', text: expect.stringContaining('payment') });
    expect(entries[1]).toEqual({ type: 'turn', status: 'completed' });
  });

  it('names a call id an earlier assistant message used by its own message; the first use, or a re-issue in the same message, keeps the plain id', () => {
    const ev = (seq: number, type: string, data: object) => ({ id: `evt_${seq}`, seq, created: 0, type: `${type}.1`, data: { sessionID: 's', ...data } });
    const id = 'functions.bash:0';
    const b = new TranscriptBuilder([ev(0, 'session.tool.called', { id, assistantMessageID: 'msg_1' })]);
    expect(b.callId(id)).toBe(id);
    b.push(ev(1, 'session.tool.called', { id, assistantMessageID: 'msg_1' }));
    expect(b.callId(id)).toBe(id);
    const [entry] = b.push(ev(2, 'session.tool.called', { id, assistantMessageID: 'msg_2' }));
    expect(b.callId(id)).toBe(`${id}@msg_2`);
    expect(entry).toMatchObject({ toolCalls: [{ id: `${id}@msg_2` }] });
    // A builder primed with the same events (the next drive) derives the same names.
    expect(new TranscriptBuilder([ev(0, 'session.tool.called', { id, assistantMessageID: 'msg_1' }), ev(2, 'session.tool.called', { id, assistantMessageID: 'msg_2' })]).callId(id)).toBe(`${id}@msg_2`);
    expect(b.callId('never-called')).toBe('never-called');
  });

  it('text a crash cut off before its step ended is written when the step settles', () => {
    const textEnded = { id: 'evt_t', seq: 6, created: 0, type: 'session.text.ended.1', data: { sessionID: 's', text: 'half a thought' } };
    const b = new TranscriptBuilder([textEnded]);
    expect(b.push({ id: 'evt_f', seq: 7, created: 0, type: 'session.step.failed.1', data: { sessionID: 's' } })).toEqual([
      { type: 'message', role: 'assistant', text: 'half a thought' },
    ]);
  });
});

describe('blobHashes', () => {
  it('names the instruction blobs an instructions update references, and they were journaled', () => {
    const update = turn.events.find((e) => eventName(e) === 'session.instructions.updated')!;
    const hashes = blobHashes(update);
    expect(hashes.length).toBeGreaterThan(0);
    expect(hashes.every((h) => turn.blobs.some((b) => b.hash === h))).toBe(true);
    expect(blobHashes(turn.events[0]!)).toEqual([]);
  });

  it('a recovery on another machine re-observes its environment: a new blob, journaled too', () => {
    const updates = crash.events.filter((e) => eventName(e) === 'session.instructions.updated');
    expect(updates).toHaveLength(2);
    const second = blobHashes(updates[1]!);
    expect(second.every((h) => crash.blobs.some((b) => b.hash === h))).toBe(true);
  });
});