opencode-drive 0.1.0

package/src/client/backend.ts

@@ -0,0 +1,184 @@
+import {
+  Backend,
+  type JsonRpc,
+} from "./protocol.js"
+
+const defaultBackendPort = 40950
+
+type BackendMethods = {
+  readonly "llm.attach": { readonly params: undefined; readonly result: { readonly attached: true } }
+  readonly "llm.chunk": { readonly params: Backend.ChunkParams; readonly result: { readonly ok: true } }
+  readonly "llm.finish": { readonly params: Partial<Backend.FinishParams> & Pick<Backend.FinishParams, "id">; readonly result: { readonly ok: true } }
+  readonly "llm.disconnect": { readonly params: Backend.DisconnectParams; readonly result: { readonly ok: true } }
+  readonly "llm.pending": { readonly params: undefined; readonly result: { readonly exchanges: ReadonlyArray<Backend.OpenedExchange> } }
+  readonly "network.log": { readonly params: undefined; readonly result: { readonly entries: ReadonlyArray<Backend.NetworkLogEntry> } }
+}
+
+type BackendMethodName = keyof BackendMethods
+
+export interface BackendSimulationClientOptions {
+  readonly url?: string
+  readonly port?: number
+  readonly portAttempts?: number
+  readonly timeout?: number
+}
+
+export class BackendSimulationError extends Error {
+  constructor(
+    message: string,
+    readonly method?: string,
+  ) {
+    super(message)
+    this.name = "BackendSimulationError"
+  }
+}
+
+interface Waiter {
+  readonly method: string
+  readonly resolve: (value: unknown) => void
+  readonly reject: (error: Error) => void
+  readonly timer: ReturnType<typeof setTimeout>
+}
+
+export class BackendSimulationClient {
+  readonly url: string
+
+  private readonly socket: WebSocket
+  private readonly timeout: number
+  private nextId = 1
+  private readonly pending = new Map<number, Waiter>()
+  private readonly llmRequests = new Set<(request: Backend.OpenedExchange) => void>()
+
+  private constructor(socket: WebSocket, url: string, timeout: number) {
+    this.socket = socket
+    this.url = url
+    this.timeout = timeout
+    socket.addEventListener("message", (event) => this.onMessage(String(event.data)))
+    socket.addEventListener("close", () => this.rejectAll(new BackendSimulationError("connection closed")))
+    socket.addEventListener("error", () => this.rejectAll(new BackendSimulationError("connection error")))
+  }
+
+  static async connect(options?: BackendSimulationClientOptions): Promise<BackendSimulationClient> {
+    const timeout = options?.timeout ?? 30_000
+    if (options?.url !== undefined) return new BackendSimulationClient(await open(options.url), options.url, timeout)
+    const first = options?.port ?? defaultBackendPort
+    const attempts = options?.portAttempts ?? 10
+    for (let offset = 0; offset < attempts; offset++) {
+      const url = `ws://127.0.0.1:${first + offset}`
+      try {
+        return new BackendSimulationClient(await open(url), url, timeout)
+      } catch {}
+    }
+    throw new BackendSimulationError(`no backend simulation server found on ports ${first}-${first + attempts - 1}`)
+  }
+
+  async call<M extends BackendMethodName>(
+    method: M,
+    params?: BackendMethods[M]["params"],
+  ): Promise<BackendMethods[M]["result"]> {
+    if (this.socket.readyState !== WebSocket.OPEN) throw new BackendSimulationError("connection is not open", method)
+    const id = this.nextId++
+    const promise = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new BackendSimulationError(`timed out after ${this.timeout}ms`, method))
+      }, this.timeout)
+      this.pending.set(id, { method, resolve, reject, timer })
+    })
+    this.socket.send(JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }))
+    return (await promise) as BackendMethods[M]["result"]
+  }
+
+  async attach(onRequest: (request: Backend.OpenedExchange) => void | Promise<void>) {
+    this.llmRequests.add((request) => void onRequest(request))
+    return await this.call("llm.attach")
+  }
+
+  chunk(id: string, items: ReadonlyArray<Backend.Item>) {
+    return this.call("llm.chunk", { id, items: [...items] })
+  }
+
+  finish(id: string, reason?: Backend.FinishReason) {
+    return this.call("llm.finish", { id, ...(reason === undefined ? {} : { reason }) })
+  }
+
+  disconnect(id: string) {
+    return this.call("llm.disconnect", { id })
+  }
+
+  pendingExchanges() {
+    return this.call("llm.pending")
+  }
+
+  networkLog(): Promise<{ readonly entries: ReadonlyArray<Backend.NetworkLogEntry> }> {
+    return this.call("network.log")
+  }
+
+  close() {
+    this.socket.close()
+  }
+
+  private onMessage(data: string) {
+    const message = parseResponse(data)
+    if (message === undefined) return
+    if ("method" in message) {
+      if (message.method === "llm.request") {
+        for (const listener of this.llmRequests) listener(message.params as Backend.OpenedExchange)
+      }
+      return
+    }
+    if (typeof message.id !== "number") return
+    const waiter = this.pending.get(message.id)
+    if (waiter === undefined) return
+    this.pending.delete(message.id)
+    clearTimeout(waiter.timer)
+    if (message.error) waiter.reject(new BackendSimulationError(message.error.message, waiter.method))
+    else waiter.resolve(message.result)
+  }
+
+  private rejectAll(error: BackendSimulationError) {
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer)
+      waiter.reject(error)
+    }
+    this.pending.clear()
+  }
+}
+
+function parseResponse(data: string): JsonRpc.Response | { readonly method: string; readonly params: unknown } | undefined {
+  try {
+    const value = JSON.parse(data) as unknown
+    if (typeof value !== "object" || value === null) return undefined
+    if (!("jsonrpc" in value) || value.jsonrpc !== "2.0") return undefined
+    if ("method" in value && typeof value.method === "string") {
+      return { method: value.method, params: "params" in value ? value.params : undefined }
+    }
+    if (!("id" in value)) return undefined
+    return value as JsonRpc.Response
+  } catch {
+    return undefined
+  }
+}
+
+function open(url: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(url)
+    const onOpen = () => {
+      cleanup()
+      resolve(socket)
+    }
+    const onError = () => {
+      cleanup()
+      reject(new BackendSimulationError(`cannot connect to ${url}`))
+    }
+    const cleanup = () => {
+      socket.removeEventListener("open", onOpen)
+      socket.removeEventListener("error", onError)
+    }
+    socket.addEventListener("open", onOpen)
+    socket.addEventListener("error", onError)
+  })
+}
+
+export const connectBackendSimulation = (options?: BackendSimulationClientOptions): Promise<BackendSimulationClient> =>
+  BackendSimulationClient.connect(options)

package/src/client/client.ts

@@ -0,0 +1,252 @@
+import {
+  Frontend,
+  type JsonRpc,
+} from "./protocol.js"
+
+const defaultPort = 40900
+
+type Methods = {
+  readonly "ui.render": { readonly params: undefined; readonly result: Frontend.Render }
+  readonly "ui.state": { readonly params: undefined; readonly result: Frontend.State }
+  readonly "ui.start-record": { readonly params: undefined; readonly result: Frontend.StartRecord }
+  readonly "ui.end-record": { readonly params: undefined; readonly result: Frontend.EndRecord }
+  readonly "ui.action": { readonly params: Frontend.ActionParams; readonly result: Frontend.State }
+  readonly "trace.list": { readonly params: undefined; readonly result: Frontend.TraceList }
+  readonly "trace.clear": { readonly params: undefined; readonly result: { readonly cleared: true } }
+  readonly "trace.export": { readonly params: undefined; readonly result: Frontend.TraceList }
+}
+
+type MethodName = keyof Methods
+
+/**
+ * WebSocket client for the OpenCode simulation control server.
+ *
+ * Start OpenCode with `OPENCODE_SIMULATION=1` (optionally
+ * `OPENCODE_SIMULATION_RENDERER=headless`), then connect from a probe run:
+ *
+ * ```ts
+ * const client = await connectSimulation()
+ * const state = await client.state()
+ * await client.typeText("hello")
+ * client.close()
+ * ```
+ */
+export interface SimulationClientOptions {
+  /** Explicit server URL; skips port scanning. */
+  readonly url?: string
+  /** First port to try when no URL is given. Defaults to 40900. */
+  readonly port?: number
+  /** Ports to scan upward from `port`. Defaults to 10. */
+  readonly portAttempts?: number
+  /** Per-call timeout in milliseconds. Defaults to 30_000. */
+  readonly timeout?: number
+}
+
+export class SimulationError extends Error {
+  constructor(
+    message: string,
+    readonly method?: string,
+  ) {
+    super(message)
+    this.name = "SimulationError"
+  }
+}
+
+interface Waiter {
+  readonly method: string
+  readonly resolve: (value: unknown) => void
+  readonly reject: (error: Error) => void
+  readonly timer: ReturnType<typeof setTimeout>
+}
+
+export class SimulationClient {
+  readonly url: string
+
+  private readonly socket: WebSocket
+  private readonly timeout: number
+  private nextId = 1
+  private readonly pending = new Map<number, Waiter>()
+
+  private constructor(socket: WebSocket, url: string, timeout: number) {
+    this.socket = socket
+    this.url = url
+    this.timeout = timeout
+    socket.addEventListener("message", (event) => this.onMessage(String(event.data)))
+    socket.addEventListener("close", () => this.rejectAll(new SimulationError("connection closed")))
+    socket.addEventListener("error", () => this.rejectAll(new SimulationError("connection error")))
+  }
+
+  static async connect(options?: SimulationClientOptions): Promise<SimulationClient> {
+    const timeout = options?.timeout ?? 30_000
+    if (options?.url !== undefined) {
+      return new SimulationClient(await open(options.url), options.url, timeout)
+    }
+    const first = options?.port ?? defaultPort
+    const attempts = options?.portAttempts ?? 10
+    for (let offset = 0; offset < attempts; offset++) {
+      const url = `ws://127.0.0.1:${first + offset}`
+      try {
+        return new SimulationClient(await open(url), url, timeout)
+      } catch {
+        // occupied by something else or nothing listening; try the next port
+      }
+    }
+    throw new SimulationError(
+      `no simulation server found on ports ${first}-${first + attempts - 1}; ` +
+        "is OpenCode running with OPENCODE_SIMULATION=1?",
+    )
+  }
+
+  /** Raw JSON-RPC call. Prefer the typed wrappers below. */
+  async call<M extends MethodName>(method: M, params?: Methods[M]["params"]): Promise<Methods[M]["result"]> {
+    if (this.socket.readyState !== WebSocket.OPEN) {
+      throw new SimulationError("connection is not open", method)
+    }
+    const id = this.nextId++
+    const promise = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new SimulationError(`timed out after ${this.timeout}ms`, method))
+      }, this.timeout)
+      this.pending.set(id, { method, resolve, reject, timer })
+    })
+    this.socket.send(JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }))
+    // The server contract types each method's result; the cast happens once
+    // here rather than at every call site.
+    return (await promise) as Methods[M]["result"]
+  }
+
+  // ── ui ────────────────────────────────────────────────────────────────
+
+  /** Current screen, focus, elements, and generated actions. */
+  state(): Promise<Frontend.State> {
+    return this.call("ui.state")
+  }
+
+  render(): Promise<Frontend.Render> {
+    return this.call("ui.render")
+  }
+
+  startRecord(): Promise<Frontend.StartRecord> {
+    return this.call("ui.start-record")
+  }
+
+  endRecord(): Promise<Frontend.EndRecord> {
+    return this.call("ui.end-record")
+  }
+
+  /** Executes one user-level action and returns the post-action state. */
+  action(action: Frontend.Action): Promise<Frontend.State> {
+    return this.call("ui.action", { action })
+  }
+
+  typeText(text: string): Promise<Frontend.State> {
+    return this.action({ type: "typeText", text })
+  }
+
+  pressKey(key: string, modifiers?: Frontend.KeyModifiers): Promise<Frontend.State> {
+    return this.action({ type: "pressKey", key: key === "escape" ? "\u001b" : key, ...(modifiers === undefined ? {} : { modifiers }) })
+  }
+
+  pressEnter(): Promise<Frontend.State> {
+    return this.action({ type: "pressEnter" })
+  }
+
+  pressArrow(direction: "up" | "down" | "left" | "right"): Promise<Frontend.State> {
+    return this.action({ type: "pressArrow", direction })
+  }
+
+  focus(target: number): Promise<Frontend.State> {
+    return this.action({ type: "focus", target })
+  }
+
+  click(target: number, x: number, y: number): Promise<Frontend.State> {
+    return this.action({ type: "click", target, x, y })
+  }
+
+  // ── trace ─────────────────────────────────────────────────────────────
+
+  traceList(): Promise<Frontend.TraceList> {
+    return this.call("trace.list")
+  }
+
+  traceClear(): Promise<{ readonly cleared: true }> {
+    return this.call("trace.clear")
+  }
+
+  traceExport(): Promise<Frontend.TraceList> {
+    return this.call("trace.export")
+  }
+
+  // ── lifecycle ─────────────────────────────────────────────────────────
+
+  close(): void {
+    this.socket.close()
+  }
+
+  private onMessage(data: string) {
+    const message = parseResponse(data)
+    if (message === undefined || typeof message.id !== "number") return
+    const waiter = this.pending.get(message.id)
+    if (waiter === undefined) return
+    this.pending.delete(message.id)
+    clearTimeout(waiter.timer)
+    if (message.error) waiter.reject(new SimulationError(message.error.message, waiter.method))
+    else waiter.resolve(message.result)
+  }
+
+  private rejectAll(error: SimulationError) {
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer)
+      waiter.reject(error)
+    }
+    this.pending.clear()
+  }
+}
+
+function parseResponse(data: string): JsonRpc.Response | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(data)
+  } catch {
+    return undefined
+  }
+  if (typeof value !== "object" || value === null) return undefined
+  if (!("jsonrpc" in value) || value.jsonrpc !== "2.0") return undefined
+  if (!("id" in value)) return undefined
+  const id = value.id
+  if (typeof id !== "number" && typeof id !== "string" && id !== null) return undefined
+  const result = "result" in value ? value.result : undefined
+  const error = "error" in value ? value.error : undefined
+  if (error !== undefined) {
+    if (typeof error !== "object" || error === null) return undefined
+    const code = "code" in error ? error.code : undefined
+    const message = "message" in error ? error.message : undefined
+    if (typeof code !== "number" || typeof message !== "string") return undefined
+    return { jsonrpc: "2.0", id, error: { code, message } }
+  }
+  return { jsonrpc: "2.0", id, result: result as JsonRpc.Response["result"] }
+}
+
+function open(url: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(url)
+    const onOpen = () => {
+      cleanup()
+      resolve(socket)
+    }
+    const onError = () => {
+      cleanup()
+      reject(new SimulationError(`cannot connect to ${url}`))
+    }
+    const cleanup = () => {
+      socket.removeEventListener("open", onOpen)
+      socket.removeEventListener("error", onError)
+    }
+    socket.addEventListener("open", onOpen)
+    socket.addEventListener("error", onError)
+  })
+}
+
+export const connectSimulation = (options?: SimulationClientOptions): Promise<SimulationClient> =>
+  SimulationClient.connect(options)

package/src/client/index.ts

@@ -0,0 +1,17 @@
+export { SimulationClient, SimulationError, connectSimulation } from "./client.js"
+export { BackendSimulationClient, BackendSimulationError, connectBackendSimulation } from "./backend.js"
+export type { BackendSimulationClientOptions } from "./backend.js"
+export type { SimulationClientOptions } from "./client.js"
+export const defaultPort = 40900
+export const defaultBackendPort = 40950
+export { Backend, Frontend, JsonRpc, SimulationProtocol } from "./protocol.js"
+export type BackendFinishReason = import("./protocol.js").Backend.FinishReason
+export type BackendItem = import("./protocol.js").Backend.Item
+export type NetworkLogEntry = import("./protocol.js").Backend.NetworkLogEntry
+export type OpenedExchange = import("./protocol.js").Backend.OpenedExchange
+export type KeyModifiers = import("./protocol.js").Frontend.KeyModifiers
+export type TraceList = import("./protocol.js").Frontend.TraceList
+export type TraceRecord = import("./protocol.js").Frontend.TraceRecord
+export type UiAction = import("./protocol.js").Frontend.Action
+export type UiElement = import("./protocol.js").Frontend.Element
+export type UiState = import("./protocol.js").Frontend.State

package/src/client/protocol.ts

@@ -0,0 +1,186 @@
+import { Effect, Schema } from "effect"
+
+const JsonRpcID = Schema.Union([Schema.String, Schema.Number, Schema.Null])
+type Json = Schema.Schema.Type<typeof Schema.Json>
+
+export namespace JsonRpc {
+  export const RequestFields = {
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.optional(JsonRpcID),
+  }
+  export const Request = Schema.Struct({
+    ...RequestFields,
+    method: Schema.String,
+    params: Schema.optional(Schema.Json),
+  })
+  export interface Request extends Schema.Schema.Type<typeof Request> {}
+
+  export const ErrorObject = Schema.Struct({
+    code: Schema.Number,
+    message: Schema.String,
+    data: Schema.optional(Schema.Json),
+  })
+
+  export const Response = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: JsonRpcID,
+    result: Schema.optional(Schema.Json),
+    error: Schema.optional(ErrorObject),
+  })
+  export interface Response extends Schema.Schema.Type<typeof Response> {}
+
+  export const decodeRequest = Schema.decodeUnknownSync(Request)
+
+  export function success(id: Request["id"], result: unknown): Response | undefined {
+    if (id === undefined) return undefined
+    return { jsonrpc: "2.0", id, result: result as Json }
+  }
+
+  export function failure(id: Request["id"], error: unknown): Response {
+    return {
+      jsonrpc: "2.0",
+      id: id ?? null,
+      error: {
+        code: -32000,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    }
+  }
+}
+
+export namespace Frontend {
+  export const KeyModifiers = Schema.Struct({
+    ctrl: Schema.optional(Schema.Boolean),
+    shift: Schema.optional(Schema.Boolean),
+    meta: Schema.optional(Schema.Boolean),
+    super: Schema.optional(Schema.Boolean),
+    hyper: Schema.optional(Schema.Boolean),
+  })
+  export interface KeyModifiers extends Schema.Schema.Type<typeof KeyModifiers> {}
+
+  export const Action = Schema.Union([
+    Schema.Struct({ type: Schema.Literal("typeText"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("pressKey"), key: Schema.String, modifiers: Schema.optional(KeyModifiers) }),
+    Schema.Struct({ type: Schema.Literal("pressEnter") }),
+    Schema.Struct({ type: Schema.Literal("pressArrow"), direction: Schema.Literals(["up", "down", "left", "right"]) }),
+    Schema.Struct({ type: Schema.Literal("focus"), target: Schema.Number }),
+    Schema.Struct({ type: Schema.Literal("click"), target: Schema.Number, x: Schema.Number, y: Schema.Number }),
+  ])
+  export type Action = Schema.Schema.Type<typeof Action>
+
+  export const Element = Schema.Struct({
+    id: Schema.String,
+    num: Schema.Number,
+    x: Schema.Number,
+    y: Schema.Number,
+    width: Schema.Number,
+    height: Schema.Number,
+    focusable: Schema.Boolean,
+    focused: Schema.Boolean,
+    clickable: Schema.Boolean,
+    editor: Schema.Boolean,
+  })
+  export interface Element extends Schema.Schema.Type<typeof Element> {}
+
+  export const State = Schema.Struct({
+    focused: Schema.Struct({
+      renderable: Schema.optional(Schema.Number),
+      editor: Schema.Boolean,
+    }),
+    elements: Schema.Array(Element),
+    actions: Schema.Array(Action),
+  })
+  export interface State extends Schema.Schema.Type<typeof State> {}
+
+  export const Render = Schema.String
+  export type Render = Schema.Schema.Type<typeof Render>
+
+  export const StartRecord = Schema.Struct({ recording: Schema.Literal(true) })
+  export interface StartRecord extends Schema.Schema.Type<typeof StartRecord> {}
+
+  export const EndRecord = Schema.String
+  export type EndRecord = Schema.Schema.Type<typeof EndRecord>
+
+  export const ActionParams = Schema.Struct({ action: Action })
+  export interface ActionParams extends Schema.Schema.Type<typeof ActionParams> {}
+
+  export const Request = Schema.Union([
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.action"), params: ActionParams }),
+    Schema.Struct({
+      ...JsonRpc.RequestFields,
+      method: Schema.Literals([
+        "ui.render",
+        "ui.state",
+        "ui.start-record",
+        "ui.end-record",
+        "trace.list",
+        "trace.clear",
+        "trace.export",
+      ]),
+    }),
+  ])
+  export type Request = Schema.Schema.Type<typeof Request>
+  export const decodeRequest = Schema.decodeUnknownSync(Request)
+
+  export const TraceRecord = Schema.Struct({
+    id: Schema.Number,
+    time: Schema.String,
+    type: Schema.String,
+    data: Schema.optional(Schema.Json),
+  })
+  export interface TraceRecord extends Schema.Schema.Type<typeof TraceRecord> {}
+
+  export const TraceList = Schema.Struct({ records: Schema.Array(TraceRecord) })
+  export interface TraceList extends Schema.Schema.Type<typeof TraceList> {}
+}
+
+export namespace Backend {
+  export const Item = Schema.Union([
+    Schema.Struct({ type: Schema.Literal("textDelta"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("reasoningDelta"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("toolCall"), id: Schema.String, name: Schema.String, input: Schema.Json }),
+    Schema.Struct({ type: Schema.Literal("raw"), chunk: Schema.Json }),
+  ])
+  export type Item = Schema.Schema.Type<typeof Item>
+
+  export const FinishReason = Schema.Literals(["stop", "tool-calls", "length", "content-filter"])
+  export type FinishReason = Schema.Schema.Type<typeof FinishReason>
+
+  export const ChunkParams = Schema.Struct({ id: Schema.String, items: Schema.Array(Item) })
+  export interface ChunkParams extends Schema.Schema.Type<typeof ChunkParams> {}
+
+  export const FinishParams = Schema.Struct({
+    id: Schema.String,
+    reason: FinishReason.pipe(Schema.withDecodingDefault(Effect.succeed("stop" as const))),
+  })
+  export interface FinishParams extends Schema.Schema.Type<typeof FinishParams> {}
+
+  export const DisconnectParams = Schema.Struct({ id: Schema.String })
+  export interface DisconnectParams extends Schema.Schema.Type<typeof DisconnectParams> {}
+
+  export const Request = Schema.Union([
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("llm.chunk"), params: ChunkParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("llm.finish"), params: FinishParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("llm.disconnect"), params: DisconnectParams }),
+    Schema.Struct({
+      ...JsonRpc.RequestFields,
+      method: Schema.Literals(["llm.attach", "llm.pending", "network.log"]),
+    }),
+  ])
+  export type Request = Schema.Schema.Type<typeof Request>
+  export const decodeRequest = Schema.decodeUnknownSync(Request)
+
+  export const OpenedExchange = Schema.Struct({ id: Schema.String, url: Schema.String, body: Schema.Json })
+  export interface OpenedExchange extends Schema.Schema.Type<typeof OpenedExchange> {}
+
+  export const NetworkLogEntry = Schema.Struct({
+    time: Schema.Number,
+    method: Schema.String,
+    url: Schema.String,
+    matched: Schema.Boolean,
+  })
+  export interface NetworkLogEntry extends Schema.Schema.Type<typeof NetworkLogEntry> {}
+
+}
+
+export * as SimulationProtocol from "./index"

package/src/experimental/campaign-api.ts

@@ -0,0 +1,34 @@
+import type { DriveContext } from "./drive.js"
+
+export interface CampaignGenerateContext {
+  readonly index: number
+  readonly seed: number
+  readonly artifacts: string
+}
+
+export interface CampaignPrepareContext<Flow> extends CampaignGenerateContext {
+  readonly flow: Flow
+}
+
+export interface CampaignRunContext<Flow> extends CampaignPrepareContext<Flow>, DriveContext {}
+
+export interface CampaignInstanceOptions {
+  readonly state?: string
+  readonly env?: Readonly<Record<string, string>>
+  readonly command?: ReadonlyArray<string>
+}
+
+export interface CampaignDefinition<Flow = unknown, Result = unknown> {
+  readonly count?: number
+  readonly generate: (context: CampaignGenerateContext) => Flow | Promise<Flow>
+  readonly prepare?: (context: CampaignPrepareContext<Flow>) => CampaignInstanceOptions | Promise<CampaignInstanceOptions>
+  readonly run: (context: CampaignRunContext<Flow>) => Result | Promise<Result>
+}
+
+export interface DefinedCampaign<Flow = unknown, Result = unknown> extends CampaignDefinition<Flow, Result> {
+  readonly kind: "opencode-drive/campaign"
+}
+
+export function defineCampaign<Flow, Result>(campaign: CampaignDefinition<Flow, Result>): DefinedCampaign<Flow, Result> {
+  return { kind: "opencode-drive/campaign", ...campaign }
+}