Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
/**
* The messages between the drive (the kernel `Harness`, in the app's
* process) and the OpenCode host (OpenCode's embedded server plus our
* plugin, in the same process).
*
* The drive owns everything durable: the journal, the tools, the inbox. The
* host owns OpenCode. So the host sends what OpenCode committed (`events`),
* asks before every model request (`barrier`) and runs every tool call
* through the drive (`tool`); the drive answers each request with a `reply`
* and tells the host what to do (`prompt`, `recover`, `close`).
*
* The host runs in the drive's process (OpenCode's embedded server), and
* the two talk over an in-process pipe (`pipePair`) that copies every
* message as JSON would: neither side shares objects with the other. The
* one thing that crosses by reference is the session's workspace, which the
* host gets as an argument of `runHost` (environment.ts), not as a message.
* No Node or OpenCode imports here.
*/
/** One committed OpenCode event, as OpenCode's `event` table stores it and `Bus.replay` takes it. */
export interface OpenCodeEvent {
/** OpenCode's event id (`evt_…`). */
id: string;
/** The event's position in its session (0-based, contiguous). */
seq: number;
/** Milliseconds since the epoch. */
created: number;
/** The versioned type, e.g. `session.tool.called.1`. */
type: string;
/** The event's data, encoded. */
data: Record<string, any>;
}
/**
* An instruction blob: state OpenCode writes in a commit hook of
* `session.instructions.updated` (whose event holds only the hash). It
* carries the date and the working directory, so it cannot be recomputed on
* another machine; the drive journals it next to the events.
*/
export interface InstructionBlob {
hash: string;
value: unknown;
}
/** A tool as the host registers it with OpenCode. */
export interface HostToolSpec {
name: string;
description: string;
inputSchema: Record<string, unknown>;
}
/** Everything the host needs to rebuild the session and run it. */
export interface HostInit {
/** OpenCode's session id (`ses_<runId>`). */
sessionId: string;
/**
* OpenCode's working directory for a new session: `/workspace`, a path of
* the session's workspace (never a directory of this machine; a rebuilt
* session keeps the one it was created with).
*/
directory: string;
/** The SQLite file. Absolute. Rebuilt by every drive. */
dbPath: string;
/** OpenCode's global config directory (empty: no user config, plugins or credentials). */
configDir: string;
/**
* The session's own directory on this machine for OpenCode's global paths
* (its home, data, cache, config, state, tmp): this drive's, empty, and
* removed with it. Nothing OpenCode reads on this machine is outside it,
* the database and the config directory.
*/
global: string;
/** `vercel/<gateway model id>`. */
model: string;
/** The AI Gateway base URL for OpenCode's `vercel` provider: the drive's loopback proxy. */
gatewayBaseURL: string;
/** A placeholder for the provider's key: the proxy replaces it with the real credential. */
gatewayKey: string;
/** The drive's tools (next to OpenCode's own `builtins`, else the session's only tools). */
tools: HostToolSpec[];
/**
* OpenCode's own tools that are on, on the session's workspace (empty: the
* drive's tools are the only ones). Each call asks the drive before it
* runs and reports after (`builtin`), and runs on the workspace the drive
* opened for it.
*/
builtins: string[];
/**
* What each built-in's description gets after OpenCode's own, saying where
* it runs (`shell`) and how long its files last (both). Empty strings: nothing.
*/
notes?: { shell: string; file: string };
/** Added to every model request's system prompt. */
system: string;
/** The session's title (OpenCode's own title request is skipped). */
title: string;
/** The session's committed events, in order: the log's copy, replayed into an empty database. */
events: OpenCodeEvent[];
/** The instruction blobs those events reference. */
blobs: InstructionBlob[];
/** The events leave OpenCode's execution claim held (see `OpenCodeStatus.claimHeld`). */
claim: boolean;
/** Restart notices since the turn began (OpenCode's resume budget counts them). */
restarts: number;
}
/** Host → drive. */
export type FromHost =
/** The session is rebuilt up to `seq` (-1: a new session) and the plugin is active. */
| { type: 'ready'; seq: number }
/** Events OpenCode committed, in order, with the blobs they reference that were not sent yet. */
| { type: 'events'; events: OpenCodeEvent[]; blobs: InstructionBlob[] }
/** OpenCode is about to make a model request: reply once everything sent so far is durable. */
| { type: 'barrier'; id: number; kind: string }
/** OpenCode called a tool: reply with its result. */
| { type: 'tool'; id: number; callId: string; name: string; input: unknown }
/**
* OpenCode is about to run one of its own tools (`begin`: reply `ok` once
* its intent is in the log, or refuse it), or ran it (`end`: its outcome).
*/
| { type: 'builtin'; id: number; phase: 'begin'; callId: string; name: string; input: unknown }
| { type: 'builtin'; id: number; phase: 'end'; callId: string; name: string; text: string; isError: boolean }
/** A live text delta (ephemeral: never in the log). */
| { type: 'text'; delta: string }
/** The answer to a `prompt` or `recover`. */
| { type: 'reply'; id: number; ok: boolean; error?: string }
/** The host failed and is exiting. */
| { type: 'error'; message: string };
/** Drive → host. */
export type ToHost =
/**
* The answer to a `barrier`, `tool` or `builtin`. To a built-in's `end`:
* `note`, a line the model sees before the call's result (its workspace
* was reset), and `failed`, the failure the log recorded for a call
* OpenCode reported as done (what it changed could not be kept): the
* model sees that instead.
*/
| { type: 'reply'; id: number; ok: true; text?: string; isError?: boolean; note?: string; failed?: string }
| { type: 'reply'; id: number; ok: false; error: string }
/** Admit a user message (idempotent by `id`, OpenCode's `msg_…` id). */
| { type: 'prompt'; id: number; messageId: string; text: string; delivery: 'queue' | 'steer' }
/**
* Resume a turn a crash cut off: add `note` as a synthetic message without
* starting a drain, hold the execution claim, and run OpenCode's own
* restart sweep (which continues the turn).
*/
| { type: 'recover'; id: number; note: string }
/** Dispose OpenCode and exit. */
| { type: 'close' };
/** A two-way message channel (an in-process pipe). */
export interface Channel<In, Out> {
send(message: Out): void;
/** Messages in order; ends when the other side closes or exits. */
messages: AsyncIterable<In>;
}
/**
* An in-process channel pair (the embedded host): what one side sends, the
* other receives, asynchronously, in order.
*/
export function pipePair<A, B>(): { left: Channel<A, B> & { close(): void }; right: Channel<B, A> & { close(): void } } {
const a = queue<A>();
const b = queue<B>();
return {
// left sends B (to right), receives A
left: { send: (m) => b.push(m), messages: a.iterable, close: () => b.end() },
right: { send: (m) => a.push(m), messages: b.iterable, close: () => a.end() },
};
}
function queue<T>() {
const items: T[] = [];
let ended = false;
let wake: (() => void) | undefined;
const iterable: AsyncIterable<T> = {
async *[Symbol.asyncIterator]() {
for (;;) {
if (items.length) {
yield items.shift()!;
continue;
}
if (ended) return;
await new Promise<void>((r) => (wake = r));
wake = undefined;
}
},
};
return {
iterable,
push(item: T) {
if (ended) return;
// Copy, as a pipe would: neither side shares objects with the other.
items.push(JSON.parse(JSON.stringify(item)) as T);
wake?.();
},
end() {
ended = true;
wake?.();
},
};
}