Skip to content

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

40.6 KB
Raw Blame
import { existsSync, mkdirSync } from 'node:fs';
import { mkdtemp } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { createWorld, type LocalWorld } from '@workflow/world-local';
import { type DriveContext, durableSessions, QUEUE_PREFIX, type SessionState, Yield } from 'harness-world';
import { filesFromState, readLedger, unsafeTools, workspaceTools } from 'harness-world-hands';
import { journalRecords, transcriptOf, WORKSPACE_STREAM } from 'harness-world-process';
import { RESET_NOTE, workspaceRuntime } from 'harness-world-hands/runtime';
import { type FakeModel, fakeModel, streamFromModel } from 'harness-world-process/reference/fake-model';
import { afterEach, describe, expect, it } from 'vitest';
import { OPENCODE_TOOLS } from './environment.ts';
import { type HostConnection, opencodeHarness } from './harness.ts';
import { type FromHost, type HostInit, pipePair, type ToHost } from './protocol.ts';
import { EVENTS, type OpenCodeEvent } from './records.ts';

/**
 * The drive's side, against a scripted host (no OpenCode, no network): what
 * it mirrors into the log, how it maps OpenCode's tool calls onto the tool
 * bridge, the model barrier, recovery, and stopping the host when a write
 * is refused. `host.test.ts` covers OpenCode's side; `test/e2e.test.ts` runs
 * both for real.
 */

const worlds: LocalWorld[] = [];
const models: FakeModel[] = [];
afterEach(async () => {
  for (const w of worlds.splice(0)) await w.close?.();
  for (const m of models.splice(0)) await m.close();
});

async function until<T>(fn: () => Promise<T | undefined> | T | undefined, timeoutMs = 20_000): Promise<T> {
  const start = Date.now();
  for (;;) {
    const v = await fn();
    if (v !== undefined) return v;
    if (Date.now() - start > timeoutMs) throw new Error('timed out');
    await new Promise((r) => setTimeout(r, 25));
  }
}

/** A scripted OpenCode host: the test writes the events it commits and the requests it makes. */
class FakeHost {
  seq: number;
  readonly sent: OpenCodeEvent[] = [];
  readonly inbound: ToHost[] = [];
  ended = false;
  private next = 0;
  private wakers: (() => void)[] = [];
  readonly conn: HostConnection;
  /** Set by a script: what it still does after the drive closes it, before its channel ends (a real host's shutdown). */
  linger: Promise<void> | undefined;
  private readonly out: (m: FromHost) => void;
  constructor(
    readonly ctx: DriveContext,
    readonly init: HostInit
  ) {
    this.seq = init.events.at(-1)?.seq ?? -1;
    const { left, right } = pipePair<FromHost, ToHost>();
    this.out = (m) => right.send(m);
    void (async () => {
      for await (const m of right.messages) {
        this.inbound.push(m);
        this.wake();
      }
      this.ended = true;
      this.wake();
    })();
    this.conn = {
      send: (m) => left.send(m),
      messages: left.messages,
      close: async () => {
        left.send({ type: 'close' });
        await this.linger;
        right.close();
      },
      kill: () => {
        left.close();
        right.close();
      },
      tail: () => '',
      exited: Promise.resolve(),
    };
  }
  private wake() {
    for (const w of this.wakers.splice(0)) w();
  }
  /** The next message from the drive of this type. */
  async take<T extends ToHost['type']>(type: T): Promise<Extract<ToHost, { type: T }>> {
    for (;;) {
      const at = this.inbound.findIndex((m) => m.type === type);
      if (at >= 0) return this.inbound.splice(at, 1)[0] as Extract<ToHost, { type: T }>;
      if (this.ended) throw new Error(`the drive closed before sending ${type}`);
      await new Promise<void>((r) => this.wakers.push(r));
    }
  }
  /** Commit (and ship) events. */
  commit(...events: [string, Record<string, unknown>?][]) {
    const out = events.map(([type, data]) => ({
      id: `evt_${this.seq + 1}`,
      seq: ++this.seq,
      created: Date.now(),
      type: `${type}.1`,
      data: { sessionID: this.init.sessionId, ...data },
    }));
    this.sent.push(...out);
    this.out({ type: 'events', events: out, blobs: [] });
  }
  send(m: FromHost) {
    this.out(m);
  }
  /** A request (barrier or tool) and the drive's reply. */
  async request(
    m:
      | { type: 'barrier'; kind: string }
      | { type: 'tool'; callId: string; name: string; input: unknown }
      | { type: 'builtin'; phase: 'begin'; callId: string; name: string; input: unknown }
      | { type: 'builtin'; phase: 'end'; callId: string; name: string; text: string; isError: boolean }
  ) {
    const id = ++this.next + 1000;
    this.out({ ...m, id } as FromHost);
    for (;;) {
      const at = this.inbound.findIndex((x) => x.type === 'reply' && x.id === id);
      if (at >= 0) return this.inbound.splice(at, 1)[0] as Extract<ToHost, { type: 'reply' }>;
      if (this.ended) throw new Error('the drive closed before replying');
      await new Promise<void>((r) => this.wakers.push(r));
    }
  }
}

type Script = (h: FakeHost) => Promise<void>;

async function session(
  dataDir: string,
  scripts: Script[],
  opts: { chaos?: boolean; crash?: () => void; recover?: boolean; contended?: () => boolean; gatewayUrl?: string; confirmMs?: number; builtins?: boolean; durable?: boolean } = {}
) {
  const world = createWorld({ dataDir, recoverActiveRuns: opts.recover ?? false });
  worlds.push(world);
  const hosts: FakeHost[] = [];
  /** What the scripts threw (their expectations included). */
  const errors: unknown[] = [];
  const harness = opencodeHarness({
    // Built-ins: OpenCode's own tools, on a virtual workspace.
    ...(opts.builtins ? { workspace: { kind: 'virtual' as const, runtime: workspaceRuntime({ kind: 'virtual', durable: opts.durable ?? true }) } } : {}),
    tools: opts.builtins ? unsafeTools({ confirmMs: opts.confirmMs ?? 3000 }) : workspaceTools({ confirmMs: opts.confirmMs ?? 3000 }),
    root: await mkdtemp(join(tmpdir(), 'oc-fake-root-')),
    // The scripted host's model requests (if it makes any) go to a fake model, with no real credential.
    ...(opts.gatewayUrl ? { gatewayUrl: opts.gatewayUrl, credential: async () => 'test-key' } : {}),
    connect: async (ctx, init) => {
      if (opts.contended?.()) throw new Yield('contended', 1);
      const h = new FakeHost(ctx, init);
      hosts.push(h);
      const script = scripts[hosts.length - 1];
      if (!script) throw new Error(`no script for drive ${hosts.length}`);
      void script(h).catch((err) => errors.push(err));
      return h.conn;
    },
  });
  const sessions = durableSessions({
    world,
    harness,
    ...(opts.chaos ? { chaos: true, crash: opts.crash ?? (() => {}) } : {}),
  });
  world.registerHandler(QUEUE_PREFIX, sessions.handler);
  await world.start?.();
  return { world, sessions, harness, hosts, errors };
}

/** A new session: `session.created`, then ready. */
function open(h: FakeHost) {
  if (h.init.events.length === 0) h.commit(['session.created', { location: { directory: h.init.directory }, projectID: 'p' }]);
  h.send({ type: 'ready', seq: h.seq });
}

/** Admit the next prompt and start its execution (OpenCode's order). */
async function admit(h: FakeHost) {
  const p = await h.take('prompt');
  h.send({ type: 'reply', id: p.id, ok: true });
  h.commit(['session.inbox.enqueued', { inboxID: p.messageId, item: { type: 'user', payload: { text: p.text } } }], ['session.execution.started'], [
    'session.inbox.delivered',
    { inboxID: p.messageId },
  ]);
  return p;
}

const turnsEnded = (s: SessionState) => transcriptOf(s).filter((r) => r.data.type === 'turn').length;
const waitTurns = (sessions: Awaited<ReturnType<typeof session>>['sessions'], id: string, n: number) =>
  until(async () => {
    const s = await sessions.inspect(id);
    return turnsEnded(s) >= n ? s : undefined;
  });

describe('the OpenCode drive', () => {
  it('mirrors what OpenCode commits, maps its tool calls onto the bridge, and holds model requests for the log', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    const seen: { placedBeforeSend?: boolean; journaledAtBarrier?: number[]; sentAtBarrier?: number[]; init?: HostInit[] } = { init: [] };
    const turn: Script = async (h) => {
      seen.init!.push(h.init);
      open(h);
      const p = await admit(h);
      const sub = h.ctx.state().submissions.find((s) => `msg_${s.id}` === p.messageId)!;
      seen.placedBeforeSend ??= h.ctx.state().placed.has(sub.id);
      const b1 = await h.request({ type: 'barrier', kind: 'primary' });
      expect(b1.ok).toBe(true);
      // Everything shipped before the barrier is in the drive's log once it is answered.
      seen.sentAtBarrier ??= h.sent.map((e) => e.seq);
      seen.journaledAtBarrier ??= journalRecords<OpenCodeEvent>(h.ctx.state(), EVENTS).map((r) => r.data.seq);
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Writing it.' }], ['session.tool.input.started', { id: 'toolu_1', name: 'write_file' }]);
      h.commit(['session.tool.called', { id: 'toolu_1', input: { path: 'a.txt', content: 'hi' } }]);
      h.send({ type: 'text', delta: 'Writing it.' });
      const r = await h.request({ type: 'tool', callId: 'toolu_1', name: 'write_file', input: { path: 'a.txt', content: 'hi' } });
      expect(r).toMatchObject({ ok: true, isError: false, text: expect.stringContaining('wrote 2 bytes') });
      h.commit(['session.tool.success', { id: 'toolu_1', content: [{ type: 'text', text: r.ok ? r.text : '' }] }], ['session.step.ended']);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Done.' }], ['session.step.ended'], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [turn, turn]);
    const { sessionId } = await a.sessions.start({ prompt: 'write a.txt' });
    let state = await waitTurns(a.sessions, sessionId, 1);

    // The call ran once, as a kernel effect keyed by OpenCode's call id.
    expect(state.effects.get('tool:toolu_1')).toMatchObject({ name: 'tool.write_file', status: 'completed' });
    expect(filesFromState(state)).toEqual({ '/workspace/a.txt': 'hi' });
    // The journal is OpenCode's events, in order, one record each.
    const host1 = a.hosts[0]!;
    expect(journalRecords<OpenCodeEvent>(state, EVENTS).map((r) => [r.id, r.data])).toEqual(host1.sent.map((e) => [`seq:${e.seq}`, e]));
    // The normalized transcript.
    expect(transcriptOf(state).map((r) => r.data)).toEqual([
      { type: 'message', role: 'assistant', text: 'Writing it.', toolCalls: [{ id: 'toolu_1', name: 'write_file' }] },
      { type: 'message', role: 'assistant', text: 'Done.' },
      { type: 'turn', status: 'completed' },
    ]);
    // Placed before OpenCode saw it; the barrier answered only once the log had it all.
    expect(seen.placedBeforeSend).toBe(true);
    expect(seen.journaledAtBarrier).toEqual(seen.sentAtBarrier);
    expect(seen.init![0]).toMatchObject({ events: [], claim: false, restarts: 0, sessionId: `ses_${sessionId}`, model: 'vercel/anthropic/claude-haiku-4.5' });
    expect(seen.init![0]!.tools.map((t) => t.name)).toEqual(workspaceTools().map((t) => t.name));

    // The next drive rebuilds OpenCode from exactly what was journaled.
    await a.sessions.send(sessionId, 'again');
    state = await waitTurns(a.sessions, sessionId, 2);
    expect(seen.init![1]!.events).toEqual(host1.sent);
    expect(seen.init![1]).toMatchObject({ claim: false, restarts: 0 });
    // A call id OpenCode reuses (it never does) would answer from the log, not run again.
    expect(state.effectOrder.filter((e) => e.name === 'tool.write_file')).toHaveLength(1);
    expect(a.errors).toEqual([]);
  });

  it('an execution OpenCode fails before it delivers the prompt ends the turn, failed, with its error', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    const failing: Script = async (h) => {
      open(h);
      const p = await h.take('prompt');
      h.send({ type: 'reply', id: p.id, ok: true });
      // OpenCode's order when its drain fails at once: admitted, started, failed, the prompt still in its inbox.
      h.commit(['session.inbox.enqueued', { inboxID: p.messageId, item: { type: 'user', payload: { text: p.text } } }], ['session.execution.started'], [
        'session.execution.failed',
        { error: { type: 'unknown', message: 'the provider failed' } },
      ]);
      await h.take('close');
      closed = Date.now();
    };
    let closed: number | undefined;
    const a = await session(dataDir, [failing]);
    const started = Date.now();
    const { sessionId } = await a.sessions.start({ prompt: 'hi' });
    const state = await waitTurns(a.sessions, sessionId, 1);
    // The drive is over at once: it does not wait for the prompt OpenCode never delivered.
    expect((await until(() => closed, 10_000)) - started).toBeLessThan(10_000);
    expect(transcriptOf(state).at(-1)?.data).toMatchObject({ type: 'turn', status: 'failed', error: expect.stringContaining('the provider failed') });
    expect(a.errors).toEqual([]);
  });

  it('a crash mid never-tool: the next drive restores the claim and resumes with a recovery note; the side effect happened once', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let crashed!: () => void;
    const died = new Promise<void>((r) => (crashed = r));
    const pay = { to: '[email protected]', amount_usd: 5, memo: 'order 7' };
    const first: Script = async (h) => {
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.send({ type: 'text', delta: 'Paying acme now.' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Paying acme now.' }], ['session.tool.input.started', { id: 'toolu_pay', name: 'unsafe_make_payment' }], ['session.tool.called', { id: 'toolu_pay', input: pay }]);
      await h.request({ type: 'tool', callId: 'toolu_pay', name: 'unsafe_make_payment', input: pay });
    };
    let note = '';
    let resumedInit: HostInit | undefined;
    const second: Script = async (h) => {
      resumedInit = h.init;
      open(h);
      const r = await h.take('recover');
      note = r.note;
      h.send({ type: 'reply', id: r.id, ok: true });
      h.commit(
        ['session.synthetic', { text: 'The server restarted while you were working.', metadata: { notice: 'restart' } }],
        ['session.tool.failed', { id: 'toolu_pay', error: { type: 'aborted', message: 'Tool execution interrupted: unsafe_make_payment' } }]
      );
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'The payment may have gone through; not repeating it.' }], ['session.step.ended'], [
        'session.execution.succeeded',
      ]);
      await h.take('close');
    };
    const a = await session(dataDir, [first], { chaos: true, crash: () => crashed() });
    const { sessionId } = await a.sessions.start();
    await a.sessions.chaos(sessionId, { at: 'tool', afterMs: 300 });
    await a.sessions.send(sessionId, 'pay acme $5 once');
    await died;
    await a.world.close?.();

    const b = await session(dataDir, [second], { chaos: true, recover: true });
    const state = await waitTurns(b.sessions, sessionId, 1);
    expect(state.effects.get('tool:toolu_pay')).toMatchObject({ name: 'tool.unsafe_make_payment', status: 'failed', error: { interrupted: true } });
    expect((await readLedger(b.world, sessionId)).map((l) => l.callKey)).toEqual(['tool:toolu_pay']);
    // The host was rebuilt with OpenCode's claim held, then told to resume with the note.
    expect(resumedInit).toMatchObject({ claim: true, restarts: 0 });
    expect(resumedInit!.events.map((e) => e.type)).toContain('session.tool.called.1');
    expect(note).toContain('[Recovery]');
    expect(note).toContain('unsafe_make_payment');
    expect(note).toContain('may have taken effect');
    const entries = transcriptOf(state).map((r) => r.data);
    expect(entries).toContainEqual({ type: 'message', role: 'user', text: note, synthetic: 'recovery' });
    expect(entries.at(-1)).toEqual({ type: 'turn', status: 'completed' });
    // The live stream: the first drive's text, then `restart` with what the log kept of the turn, before the resumed reply.
    const abort = new AbortController();
    const live: { type?: string; text?: string; delta?: string }[] = [];
    for await (const ev of b.sessions.live(sessionId, { signal: abort.signal }) as AsyncIterable<{ type?: string }>) {
      live.push(ev);
      if (ev.type === 'idle' && live.some((e) => e.type === 'restart')) abort.abort();
    }
    expect(live.filter((e) => e.type === 'text' || e.type === 'restart')).toEqual([
      { type: 'text', delta: 'Paying acme now.' },
      { type: 'restart', text: 'Paying acme now.', parts: ['Paying acme now.'] },
    ]);
    expect(b.errors).toEqual([]);
  });

  it('a crash while the model streams, after a never tool: the chaos step kills the model step, the resumed turn makes the call again, the email went out once', async () => {
    // The model behind the drive's proxy types the reply to the tool's result slowly: the stream the crash cuts.
    const model = await fakeModel({ pieceMs: (text) => (text.startsWith('unsafe_send_email returned') ? 150 : 5) });
    models.push(model);
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let crashed!: () => void;
    // A real crash takes the process's OpenCode host with it: the stand-in host stops sending at the crash.
    let dead = false;
    const died = new Promise<void>((r) => (crashed = () => ((dead = true), r())));
    const mail = { to: '[email protected]', subject: 'hi', body: 'x' };
    /** OpenCode's model request: through the drive's proxy (`gatewayBaseURL`), after the barrier. */
    const ask = async (h: FakeHost, text: string, alive = () => true) => {
      await h.request({ type: 'barrier', kind: 'primary' });
      await streamFromModel(`${h.init.gatewayBaseURL}/language-model`, text, (delta) => alive() && h.send({ type: 'text', delta }), { authorization: `Bearer ${h.init.gatewayKey}` });
    };
    const before = () => !dead;
    const first: Script = async (h) => {
      open(h);
      await admit(h);
      await ask(h, 'Sending it.', before);
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Sending it.' }], ['session.tool.input.started', { id: 'toolu_mail', name: 'unsafe_send_email' }], [
        'session.tool.called',
        { id: 'toolu_mail', input: mail },
      ]);
      const r = await h.request({ type: 'tool', callId: 'toolu_mail', name: 'unsafe_send_email', input: mail });
      h.commit(['session.tool.success', { id: 'toolu_mail', content: [{ type: 'text', text: r.ok ? r.text : '' }] }], ['session.step.ended']);
      await ask(h, `unsafe_send_email returned: ${r.ok ? r.text : ''}`, before);
    };
    let note = '';
    const second: Script = async (h) => {
      open(h);
      const r = await h.take('recover');
      note = r.note;
      h.send({ type: 'reply', id: r.id, ok: true });
      h.commit(['session.synthetic', { text: 'The server restarted while you were working.', metadata: { notice: 'restart' } }]);
      await ask(h, 'Recovered from the log: the email went out.');
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Recovered from the log: the email went out.' }], ['session.step.ended'], [
        'session.execution.succeeded',
      ]);
      await h.take('close');
    };
    const a = await session(dataDir, [first], { chaos: true, crash: () => crashed(), gatewayUrl: model.url, confirmMs: 500 });
    const { sessionId } = await a.sessions.start();
    await a.sessions.chaos(sessionId, { at: 'model', afterMs: 400 });
    await a.sessions.send(sessionId, 'email [email protected] once');
    await died;
    let state = await a.sessions.inspect(sessionId);
    // "Sending it." streamed in under 400 ms; the crash fired in the reply's model step.
    const steps = state.effectOrder.filter((e) => e.name === 'model');
    expect(steps.map((e) => e.status)).toEqual(['completed', 'running']);
    expect(steps[0]!.input).toEqual({ method: 'POST', path: '/v3/ai/language-model' });
    expect(state.effectOrder.find((e) => e.name === 'chaos')).toMatchObject({ output: { effect: 'model', crashedDuring: steps[1]!.key } });
    expect(state.effects.get('tool:toolu_mail')).toMatchObject({ status: 'completed' });
    await a.world.close?.();

    const b = await session(dataDir, [second], { chaos: true, recover: true, gatewayUrl: model.url });
    state = await waitTurns(b.sessions, sessionId, 1);
    expect(state.effects.get(steps[1]!.key)).toMatchObject({ status: 'completed', attempt: 2 });
    expect(state.effectOrder.filter((e) => e.status === 'running' || e.status === 'pending')).toEqual([]);
    expect(state.effectOrder.filter((e) => e.name === 'tool.unsafe_send_email')).toHaveLength(1);
    expect((await readLedger(b.world, sessionId)).map((l) => l.callKey)).toEqual(['tool:toolu_mail']);
    expect(note).toContain('call toolu_mail: completed');
    const entries = transcriptOf(state).map((r) => r.data);
    expect(entries).toContainEqual({ type: 'message', role: 'user', text: note, synthetic: 'recovery' });
    expect(entries.at(-1)).toEqual({ type: 'turn', status: 'completed' });
    // The cut-off reply streamed live and was never in the log: `restart` keeps only "Sending it.", then the resumed reply streams.
    const abort = new AbortController();
    const live: { type?: string; text?: string; delta?: string }[] = [];
    for await (const ev of b.sessions.live(sessionId, { signal: abort.signal }) as AsyncIterable<{ type?: string }>) {
      live.push(ev);
      if (ev.type === 'idle' && live.some((e) => e.type === 'restart')) abort.abort();
    }
    const restart = live.findIndex((e) => e.type === 'restart');
    expect(live[restart]).toEqual({ type: 'restart', text: 'Sending it.', parts: ['Sending it.'] });
    const text = (from: number, to: number) => live.slice(from, to).flatMap((e) => (e.type === 'text' ? [e.delta] : [])).join('');
    expect(text(0, restart)).toMatch(/^Sending it\..+/);
    expect(text(restart + 1, live.length)).toBe('Recovered from the log: the email went out.');
    expect(b.errors).toEqual([]);
  });

  it('admits a steer into the running turn', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let steered: Extract<ToHost, { type: 'prompt' }> | undefined;
    let first!: () => void;
    const admitted = new Promise<void>((r) => (first = r));
    const script: Script = async (h) => {
      open(h);
      await admit(h);
      first();
      // The turn runs until the steer arrives: OpenCode delivers it at its next step.
      steered = await h.take('prompt');
      h.send({ type: 'reply', id: steered.id, ok: true });
      h.commit(['session.inbox.enqueued', { inboxID: steered.messageId, item: { type: 'user', payload: { text: steered.text } } }], [
        'session.inbox.delivered',
        { inboxID: steered.messageId },
      ]);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Both done.' }], ['session.step.ended'], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [script]);
    const { sessionId } = await a.sessions.start({ prompt: 'do one thing' });
    await admitted;
    const steerId = await a.sessions.send(sessionId, 'and another', 'steer');
    const state = await waitTurns(a.sessions, sessionId, 1);
    expect(steered).toMatchObject({ delivery: 'steer', text: 'and another', messageId: `msg_${steerId}` });
    expect(state.placed.has(steerId)).toBe(true);
    expect(transcriptOf(state).map((r) => r.data)).toEqual([
      { type: 'message', role: 'assistant', text: 'Both done.' },
      { type: 'turn', status: 'completed' },
    ]);
    expect(a.errors).toEqual([]);
  });

  it('a refused journal write halts the drive and stops the host', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let host!: FakeHost;
    const script: Script = async (h) => {
      host = h;
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' }).catch(() => {});
    };
    const a = await session(dataDir, [script]);
    const { sessionId } = await a.sessions.start();
    await a.sessions.send(sessionId, 'hello', 'prompt', { wake: 'backstop' });
    const create = a.world.events.create.bind(a.world.events);
    const refused = new Error('the World refused the write');
    a.world.events.create = (async (runId: string, request: any, params?: any) => {
      if (request?.eventType === 'step_started' && String(request.eventData?.stepName).endsWith('//journal')) throw refused;
      return create(runId, request, params);
    }) as typeof a.world.events.create;
    await expect(a.sessions.drive(sessionId)).rejects.toBe(refused);
    // OpenCode's input ended: the host stops, and nothing it committed is in the log.
    await until(() => (host.ended ? true : undefined), 5000);
    const state = await a.sessions.inspect(sessionId);
    expect(state.effectOrder.some((e) => e.name === 'journal')).toBe(false);
  });
  it('a call id OpenCode reuses in a later step is a new call: it runs, keyed by its message; re-issued in its own message, it answers from the log', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    const replies: string[] = [];
    // Kimi-style ids: `functions.write_file:0` in every step.
    const id = 'functions.write_file:0';
    const call = (message: string, input: { path: string; content: string }): Script => async (h) => {
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started', { assistantMessageID: message }], ['session.tool.input.started', { assistantMessageID: message, id, name: 'write_file' }], [
        'session.tool.called',
        { assistantMessageID: message, id, input },
      ]);
      const r = await h.request({ type: 'tool', callId: id, name: 'write_file', input });
      replies.push(r.ok ? (r.text ?? '') : `error: ${r.error}`);
      // OpenCode re-issuing the same call (same message): the log's answer, no second run.
      const again = await h.request({ type: 'tool', callId: id, name: 'write_file', input });
      replies.push(again.ok ? (again.text ?? '') : `error: ${again.error}`);
      h.commit(['session.tool.success', { assistantMessageID: message, id }], ['session.step.ended', { assistantMessageID: message }], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [call('msg_a1', { path: 'a.txt', content: 'one' }), call('msg_a2', { path: 'b.txt', content: 'two' })]);
    const { sessionId } = await a.sessions.start({ prompt: 'write a.txt' });
    await waitTurns(a.sessions, sessionId, 1);
    await a.sessions.send(sessionId, 'now b.txt');
    const state = await waitTurns(a.sessions, sessionId, 2);
    expect(filesFromState(state)).toEqual({ '/workspace/a.txt': 'one', '/workspace/b.txt': 'two' });
    expect(state.effectOrder.filter((e) => e.name === 'tool.write_file').map((e) => [e.key, e.status])).toEqual([
      [`tool:${id}`, 'completed'],
      [`tool:${id}@msg_a2`, 'completed'],
    ]);
    expect(replies[0]).toBe(replies[1]);
    expect(replies[2]).toBe(replies[3]);
    // The transcript names the calls as the log keys them.
    const calls = transcriptOf(state).flatMap((r) => (r.data.type === 'message' && 'toolCalls' in r.data ? (r.data.toolCalls ?? []) : []));
    expect(calls.map((c) => c.id)).toEqual([id, `${id}@msg_a2`]);
    expect(a.errors).toEqual([]);
  });

  it('a drive that lost the race to start a host leaves the drive that runs it its files', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let second: unknown;
    let presentAfter: boolean | undefined;
    const harness = () => a.harness;
    const script: Script = async (h) => {
      mkdirSync(dirname(h.init.dbPath), { recursive: true });
      open(h);
      await admit(h);
      // Another drive of the session on this machine, while this one runs: it cannot start a host.
      second = await harness()
        .drive(h.ctx)
        .then(() => 'returned', (err) => err);
      presentAfter = existsSync(dirname(h.init.dbPath));
      h.commit(['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [script]);
    const { sessionId } = await a.sessions.start({ prompt: 'one thing' });
    await waitTurns(a.sessions, sessionId, 1);
    expect(second).toBeInstanceOf(Yield);
    expect(presentAfter).toBe(true);
    expect(a.errors).toEqual([]);
  });

  it('once the drive is over, nothing the host still sends reaches the log, and its tool calls are refused', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let late: Extract<ToHost, { type: 'reply' }> | undefined;
    let journaledAtEnd = 0;
    const script: Script = async (h) => {
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Done.' }], ['session.step.ended'], ['session.execution.succeeded']);
      // Its shutdown: an event committed and a tool called after the drive closed it.
      h.linger = (async () => {
        await h.take('close');
        journaledAtEnd = journalRecords(h.ctx.state(), EVENTS).length;
        h.commit(['session.step.started']);
        late = await h.request({ type: 'tool', callId: 'toolu_late', name: 'write_file', input: { path: 'late.txt', content: 'x' } });
      })();
      await h.linger;
    };
    const a = await session(dataDir, [script]);
    const { sessionId } = await a.sessions.start({ prompt: 'hi' });
    await waitTurns(a.sessions, sessionId, 1);
    await until(() => late);
    await new Promise((r) => setTimeout(r, 300));
    const state = await a.sessions.inspect(sessionId);
    expect(late).toMatchObject({ ok: false });
    expect(state.effects.has('tool:toolu_late')).toBe(false);
    expect(filesFromState(state)).toEqual({});
    expect(journalRecords(state, EVENTS)).toHaveLength(journaledAtEnd);
    expect(a.errors).toEqual([]);
  });
});

describe('the OpenCode drive, built-ins on', () => {
  it("records OpenCode's own tool calls: each one's intent before it runs (after its event is in the log), its outcome after", async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    const seen: { init?: HostInit; begin?: Extract<ToHost, { type: 'reply' }>; intentBeforeReply?: boolean; eventFirst?: boolean } = {};
    const turn: Script = async (h) => {
      seen.init = h.init;
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.tool.input.started', { id: 'call_sh', name: 'shell' }], ['session.tool.called', { id: 'call_sh', input: { command: 'date > d.txt' } }]);
      seen.begin = await h.request({ type: 'builtin', phase: 'begin', callId: 'call_sh', name: 'shell', input: { command: 'date > d.txt' } });
      const state = h.ctx.state();
      seen.intentBeforeReply = state.effects.get('tool:call_sh')?.status === 'running';
      // OpenCode's record of the call was in the log before the call's intent.
      const event = journalRecords<OpenCodeEvent>(state, EVENTS).find((r) => r.data.type === 'session.tool.called.1')!;
      seen.eventFirst = event.at < state.effectOrder.indexOf(state.effects.get('tool:call_sh')!);
      await h.request({ type: 'builtin', phase: 'end', callId: 'call_sh', name: 'shell', text: 'ok', isError: false });
      h.commit(['session.tool.succeeded', { id: 'call_sh', result: 'ok' }]);
      // A read: replay-safe.
      h.commit(['session.tool.input.started', { id: 'call_rd', name: 'read' }], ['session.tool.called', { id: 'call_rd', input: { path: 'd.txt' } }]);
      await h.request({ type: 'builtin', phase: 'begin', callId: 'call_rd', name: 'read', input: { path: 'd.txt' } });
      await h.request({ type: 'builtin', phase: 'end', callId: 'call_rd', name: 'read', text: 'ENOENT', isError: true });
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.text.ended', { text: 'done' }], ['session.step.ended'], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [turn], { builtins: true });
    const { sessionId } = await a.sessions.start();
    await a.sessions.send(sessionId, 'run date');
    const state = await waitTurns(a.sessions, sessionId, 1);
    expect(a.errors).toEqual([]);
    expect(seen.init).toMatchObject({ builtins: [...OPENCODE_TOOLS], directory: '/workspace' });
    expect(seen.init!.system).toContain('virtual workspace at /workspace');
    expect(seen.begin).toMatchObject({ ok: true });
    expect(seen.intentBeforeReply).toBe(true);
    expect(seen.eventFirst).toBe(true);
    // On a virtual workspace every built-in is `safe`: a call that never reported changed nothing.
    expect(state.effects.get('tool:call_sh')).toMatchObject({ name: 'tool.shell', replay: 'safe', status: 'completed', output: 'ok' });
    expect(state.effects.get('tool:call_rd')).toMatchObject({ name: 'tool.read', replay: 'safe', status: 'failed', error: { message: 'ENOENT' } });
    // No working directory of this machine: nothing recorded about one.
    expect(journalRecords(state, WORKSPACE_STREAM)).toHaveLength(0);
  });

  it('a crash mid built-in: the next drive resumes with a note that says it was interrupted and is safe to repeat; a re-dispatch of the call runs it again', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let crashed!: () => void;
    const died = new Promise<void>((r) => (crashed = r));
    const first: Script = async (h) => {
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.tool.input.started', { id: 'call_x', name: 'shell' }], ['session.tool.called', { id: 'call_x', input: { command: 'make build' } }]);
      await h.request({ type: 'builtin', phase: 'begin', callId: 'call_x', name: 'shell', input: { command: 'make build' } });
      // The command runs; the crash comes before OpenCode reports it.
      await new Promise(() => {});
    };
    let note = '';
    let again: Extract<ToHost, { type: 'reply' }> | undefined;
    const second: Script = async (h) => {
      open(h);
      const r = await h.take('recover');
      note = r.note;
      h.send({ type: 'reply', id: r.id, ok: true });
      h.commit(['session.tool.failed', { id: 'call_x', error: { type: 'aborted', message: 'Tool execution interrupted: shell' } }]);
      // A dispatch of the same call again runs it: the cut-off attempt changed nothing on the workspace.
      again = await h.request({ type: 'builtin', phase: 'begin', callId: 'call_x', name: 'shell', input: { command: 'make build' } });
      await h.request({ type: 'builtin', phase: 'end', callId: 'call_x', name: 'shell', text: 'built', isError: false });
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started'], ['session.text.ended', { text: 'Built.' }], ['session.step.ended'], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [first], { builtins: true, chaos: true, crash: () => crashed() });
    const { sessionId } = await a.sessions.start();
    await a.sessions.chaos(sessionId, { at: 'tool', afterMs: 300 });
    await a.sessions.send(sessionId, 'build');
    await died;
    await a.world.close?.();
    const b = await session(dataDir, [second], { builtins: true, chaos: true, recover: true });
    const state = await waitTurns(b.sessions, sessionId, 1);
    expect(b.errors).toEqual([]);
    expect(note).toContain('shell({"command":"make build"}), call call_x: interrupted before it reported a result. It is safe to repeat.');
    expect(note).not.toContain('[Environment]');
    expect(again).toMatchObject({ ok: true });
    expect(state.effects.get('tool:call_x')).toMatchObject({ name: 'tool.shell', replay: 'safe', status: 'completed', output: 'built' });
    expect(state.effectOrder.filter((e) => e.key === 'tool:call_x' && !state.superseded.has(e.stepId)).map((e) => e.status)).toEqual(['completed']);
  });

  it('in memory, a turn picked up by a new drive: the first call after it hears its workspace was reset', async () => {
    const dataDir = await mkdtemp(join(tmpdir(), 'oc-fake-'));
    let crashed!: () => void;
    const died = new Promise<void>((r) => (crashed = r));
    const call = async (h: FakeHost, id: string, name: string, input: unknown, text?: string) => {
      h.commit(['session.tool.input.started', { id, name }], ['session.tool.called', { id, input }]);
      await h.request({ type: 'builtin', phase: 'begin', callId: id, name, input });
      return text === undefined ? undefined : h.request({ type: 'builtin', phase: 'end', callId: id, name, text, isError: false });
    };
    const first: Script = async (h) => {
      open(h);
      await admit(h);
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.step.started']);
      expect(await call(h, 'call_a', 'write', { path: 'a.txt', content: 'a' }, 'Created file successfully: a.txt')).toMatchObject({ ok: true });
      await call(h, 'call_b', 'shell', { command: 'sleep 5' });
      await new Promise(() => {});
    };
    let after: Extract<ToHost, { type: 'reply' }> | undefined;
    const second: Script = async (h) => {
      open(h);
      const r = await h.take('recover');
      h.send({ type: 'reply', id: r.id, ok: true });
      h.commit(['session.tool.failed', { id: 'call_b', error: { type: 'aborted', message: 'Tool execution interrupted: shell' } }]);
      after = await call(h, 'call_c', 'read', { path: 'a.txt' }, 'File not found: a.txt');
      await h.request({ type: 'barrier', kind: 'primary' });
      h.commit(['session.text.ended', { text: 'It is gone.' }], ['session.step.ended'], ['session.execution.succeeded']);
      await h.take('close');
    };
    const a = await session(dataDir, [first], { builtins: true, durable: false, chaos: true, crash: () => crashed() });
    const { sessionId } = await a.sessions.start();
    await a.sessions.chaos(sessionId, { at: 'tool', afterMs: 300 });
    await a.sessions.send(sessionId, 'go');
    await died;
    await a.world.close?.();
    const b = await session(dataDir, [second], { builtins: true, durable: false, chaos: true, recover: true });
    const state = await waitTurns(b.sessions, sessionId, 1);
    expect(b.errors).toEqual([]);
    expect(after).toMatchObject({ ok: true, note: RESET_NOTE });
    expect(state.effects.get('tool:call_c')?.output).toBe(`${RESET_NOTE}\n\nFile not found: a.txt`);
    expect(filesFromState(state)).toEqual({});
  });
});

describe('the options', () => {
  const virtual = () => ({ kind: 'virtual' as const, runtime: workspaceRuntime() });
  it("no workspace: tool-less; `builtins` other than `false` is a TypeError, since OpenCode's own tools never run on this machine", () => {
    expect(() => opencodeHarness({})).not.toThrow();
    expect(() => opencodeHarness({ builtins: false })).not.toThrow();
    for (const builtins of [true, ['shell'] as const]) expect(() => opencodeHarness({ builtins })).toThrow(/needs a `workspace`/);
  });
  it('with a workspace: `true` and the default are all seven, a list narrows them, `false` and an unknown tool are TypeErrors', () => {
    expect(() => opencodeHarness({ workspace: virtual() })).not.toThrow();
    expect(() => opencodeHarness({ workspace: virtual(), builtins: true })).not.toThrow();
    expect(() => opencodeHarness({ workspace: virtual(), builtins: ['read', 'glob'] })).not.toThrow();
    expect(() => opencodeHarness({ workspace: virtual(), builtins: false })).toThrow(/`builtins: false` with a `workspace`/);
    expect(() => opencodeHarness({ workspace: virtual(), builtins: ['webfetch'] as never })).toThrow(/not one of OpenCode's own tools/);
  });
  it('a workspace that is not resolved (a bare descriptor) is a TypeError naming durable-harness/opencode; a resolved sandbox is the sandbox tier\'s acquire', () => {
    expect(() => opencodeHarness({ workspace: { kind: 'virtual', durable: true } as never })).toThrow(/durable-harness\/opencode resolves/);
    expect(() => opencodeHarness({ workspace: { kind: 'sandbox', vcpus: 2 } as never })).toThrow(/durable-harness\/opencode resolves virtual\(\) and sandbox\(\)/);
    const acquire = () => Promise.reject(new Error('not in this test'));
    expect(() => opencodeHarness({ workspace: { kind: 'sandbox', acquire } })).not.toThrow();
    expect(() => opencodeHarness({ workspace: { kind: 'sandbox', acquire }, builtins: ['read', 'grep'] })).not.toThrow();
  });
  it('the options that are gone are TypeErrors naming what replaces them', () => {
    for (const [key, replacement] of [
      ['mode', /drop `mode`/],
      ['directory', /workspace: virtual\(\)/],
      ['host', /pass `root`/],
      ['workspaceNote', /drop `workspaceNote`/],
    ] as const)
      expect(() => opencodeHarness({ [key]: 'x' } as never)).toThrow(replacement);
  });
});