opencode-drive 0.1.1 → 0.1.2

package/README.md

@@ -2,89 +2,99 @@
 
 Drive visible, headless, simulated, or real OpenCode instances.
 
+# Usage
+
+**Start the default detached, headless instance:**
+
+```bash
+bunx opencode-drive start
+```
+
+**Start a named instance, then address it with `--name`:**
+
 ```bash
 bunx opencode-drive start --name demo
+```
+
+**Type, submit a prompt, and take a screenshot:**
 
+```bash
 bunx opencode-drive send --name demo \
-  --command.type "hello" \
-  --command.press enter \
-  --command.render \
-  --command.state
+  --command.type "Explain this project in one sentence" \
+  --command.enter \
+  --command.screenshot
 ```
 
-`start` launches a detached headless simulated OpenCode process. Add
-`--visible` to keep it in the foreground and show it in the terminal. Pass a custom OpenCode command after
-`--`:
+**List the full command API for agents:**
 
 ```bash
-bunx opencode-drive start --name local --visible -- \
-  opencode2 --standalone
+bunx opencode-drive api
 ```
 
-Use `--dev` to run an OpenCode development checkout. The launcher installs the
-checkout's `@opentui/solid` runtime in its isolated working directory and configures
-Bun automatically:
+**Run OpenCode visibly in the foreground:**
 
 ```bash
-bunx opencode-drive start --visible --dev ~/projects/opencode-latest
+bunx opencode-drive start --visible
 ```
 
-Both `start` and `send` accept `--driver ./driver.ts`. Drivers may default
-export a function created with `defineDriver`:
-
-```ts
-import { defineDriver } from "opencode-drive/experimental"
+**Run a local OpenCode development checkout:**
 
-export default defineDriver(async ({ ui }) => {
-  await ui.typeText("hello")
-  await ui.pressEnter()
-  const state = await ui.state()
-  if (!state.focused.editor) throw new Error("prompt editor is not focused")
-})
+```bash
+cd ~/projects/opencode
+bunx opencode-drive start --visible --dev .
 ```
 
-Experimental campaign modules use `defineCampaign` from `opencode-drive/experimental`. Every case gets a fresh isolated,
-headless OpenCode process. One deterministic case can use the same runner in a
-visible terminal:
+**Run a custom OpenCode command after `--`:**
 
 ```bash
-bunx opencode-drive start --campaign ./campaign.ts --seed 42000
-bunx opencode-drive start --campaign ./campaign.ts --seed 42000 --case 17 --visible
+bunx opencode-drive start --name demo -- opencode2 --standalone
 ```
 
-OpenCode starts its drive interfaces when `OPENCODE_DRIVE` contains an instance
-name and its simulated services when `OPENCODE_SIMULATE=1`. `run` creates the
-named registry manifest, then sets both variables. OpenCode resolves the
-manifest by name to obtain its drive ports. The manifest has this contract:
-
-```json
-{
-  "version": 1,
-  "name": "demo",
-  "pid": 1234,
-  "startedAt": "2026-07-06T00:00:00.000Z",
-  "mode": "simulated",
-  "cwd": "/workspace",
-  "artifacts": "/tmp/opencode-drive/demo",
-  "endpoints": {
-    "ui": "ws://127.0.0.1:41000",
-    "backend": "ws://127.0.0.1:41001"
-  }
-}
+**Stop a detached headless instance:**
+
+```bash
+bunx opencode-drive stop --name demo
 ```
 
-## Probe Experiments
+# Use cases
 
-Model-based and deterministic simulation drivers for the local opencode V2 TUI
-and server. The probe controls the real application through simulation-only
-WebSocket interfaces while external model and filesystem state remain isolated.
+There are two different modes OpenCode can run in:
 
-The opencode checkout is expected at `~/projects/opencode-latest`.
+* Simulated: core layers like networking are swapped out in the backend so you can control them
+* Driven: starts websocket servers internally to expose commands to drive the app
 
-## Setup
+You can choose one or the other, or both! This allows the following use cases:
 
-```bash
-cd ~/projects/opencode-drive
-bun install
-bun run check
+1. You want to develop opencode
+
+You are running a development version of OpenCode to work on it. You have another OpenCode instance making changes to the app.
+
+In this case, you don't care about simulation. But you still want OpenCode to see and drive your development version! This _closes the loop_ and gives direct feedback to AI.
+
+To do this, run it with a development version of OpenCode with `--dev` (takes the path to the code) and `--visible` (so you can see it):
+
+```sh
+bunx opencode-drive start --dev . --visible
 ```
+
+If you are doing UI work, you can use the `restart` command to refresh the UI. The server will still be running in the background so this only restarts the UI:
+
+```sh
+bunx opencode-drive restart
+```
+
+If you want to restart the backend, use the `/reload` command.
+
+2. You want opencode to develop itself
+
+OpenCode can spawn it's own instances of OpenCode in headless mode. Use the skill in this repo to teach it about it.
+
+It will spawn it in both drive and simulated mode, allowing it explore the app. It will use the `screenshot` command to capture screenshots to see what's happening, providing a full feedback loop.
+
+3. You want to share reproducible steps
+
+Ask opencode to find a bug, and list the commands it used to get there. You can then share this list with someone else who can use `opencode-drive` in visible mode to visually inspect it and develop a fix. (Or just share the steps with your own local OpenCode to find a fix)
+
+4. You want to run it a billion times and assert properties
+
+This isn't fully implemented right now, but in the future `opencode-drive` will provide a way to specify properties that you want to assert, and run the app a billion times in many different states to make sure those properties hold. This will work with a new CLI command that takes different flags.

package/package.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-drive",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drive real and simulated OpenCode instances",
   "license": "MIT",
   "type": "module",
   "packageManager": "bun@1.3.14",
   "bin": {
-    "opencode-drive": "./bin/opencode-drive"
+    "opencode-drive": "bin/opencode-drive"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli/api.ts

@@ -0,0 +1,5 @@
+import { resolve } from "node:path"
+
+export async function api() {
+  process.stdout.write(await Bun.file(resolve(import.meta.dir, "..", "client", "protocol.types.ts")).text())
+}

package/src/cli/commands.ts

@@ -1,37 +1,30 @@
-import type { BackendFinishReason, BackendItem, KeyModifiers } from "../client/index.js"
-import { connectBackendSimulation, connectSimulation } from "../client/index.js"
+import { Backend, connectBackendSimulation, connectSimulation, Frontend } from "../client/index.js"
 import type { DriveCommand, InstanceManifest } from "./types.js"
 
-const noValue = new Set([
-  "render",
-  "state",
-  "start-record",
-  "end-record",
-  "enter",
-  "llm.pending",
-  "network.log",
-])
-
-const withValue = new Set([
-  "type",
-  "press",
-  "arrow",
-  "focus",
-  "click",
-  "llm.respond",
-  "llm.chunk",
-  "llm.finish",
-  "llm.disconnect",
-])
+export const commandInfo = {
+  "ui.type": { value: true, description: "Type text using JSON params" },
+  "ui.press": { value: true, description: "Press a key using JSON params" },
+  "ui.enter": { value: false, description: "Press Enter" },
+  "ui.arrow": { value: true, description: "Press an arrow key using JSON params" },
+  "ui.focus": { value: true, description: "Focus an element using JSON params" },
+  "ui.click": { value: true, description: "Click using JSON params" },
+  "ui.screenshot": { value: false, description: "Take a screenshot and return its path" },
+  "ui.state": { value: false, description: "Return focus, elements, and available UI actions" },
+  "ui.start-record": { value: false, description: "Start recording the UI" },
+  "ui.end-record": { value: false, description: "Stop recording and return the recording path" },
+  "llm.pending": { value: false, description: "List pending simulated LLM exchanges" },
+  "llm.chunk": { value: true, description: "Send response items to a simulated LLM exchange" },
+  "llm.finish": { value: true, description: "Finish a simulated LLM exchange" },
+  "llm.disconnect": { value: true, description: "Disconnect a simulated LLM exchange" },
+} as const
 
 export function commandAcceptsValue(operation: string) {
-  if (noValue.has(operation)) return false
-  if (withValue.has(operation)) return true
+  if (operation in commandInfo) return commandInfo[operation as keyof typeof commandInfo].value
   throw new Error(`unknown drive command "${operation}"`)
 }
 
 export function commandNames() {
-  return [...noValue, ...withValue].sort()
+  return Object.keys(commandInfo).sort()
 }
 
 export async function executeCommands(manifest: InstanceManifest, commands: ReadonlyArray<DriveCommand>) {
@@ -72,49 +65,52 @@ async function execute(
   backend: () => Promise<Awaited<ReturnType<typeof connectBackendSimulation>>>,
 ) {
   switch (command.operation) {
-    case "render": return (await ui()).render()
-    case "state": return (await ui()).state()
-    case "start-record": return (await ui()).startRecord()
-    case "end-record": return (await ui()).endRecord()
-    case "type": return (await ui()).typeText(required(command))
-    case "press": {
-      const value = required(command)
-      if (!value.trim().startsWith("{")) return value === "enter" ? (await ui()).pressEnter() : (await ui()).pressKey(value)
-      const input = object(value)
-      return (await ui()).pressKey(string(input, "key"), modifiers(input.modifiers))
+    case "ui.type": {
+      const request = Frontend.decodeRequest({ jsonrpc: "2.0", method: "ui.type", params: json(required(command)) })
+      if (request.method !== "ui.type") throw new Error("invalid ui.type params")
+      return (await ui()).typeText(request.params.text)
     }
-    case "enter": return (await ui()).pressEnter()
-    case "arrow": {
-      const direction = required(command)
-      if (direction !== "up" && direction !== "down" && direction !== "left" && direction !== "right") {
-        throw new Error("arrow must be up, down, left, or right")
-      }
-      return (await ui()).pressArrow(direction)
+    case "ui.press": {
+      const request = Frontend.decodeRequest({ jsonrpc: "2.0", method: "ui.press", params: json(required(command)) })
+      if (request.method !== "ui.press") throw new Error("invalid ui.press params")
+      return (await ui()).pressKey(request.params.key, request.params.modifiers)
     }
-    case "focus": return (await ui()).focus(number(required(command), "target"))
-    case "click": {
-      const input = object(required(command))
-      return (await ui()).click(number(input.target, "target"), number(input.x, "x"), number(input.y, "y"))
+    case "ui.enter": return (await ui()).pressEnter()
+    case "ui.arrow": {
+      const request = Frontend.decodeRequest({ jsonrpc: "2.0", method: "ui.arrow", params: json(required(command)) })
+      if (request.method !== "ui.arrow") throw new Error("invalid ui.arrow params")
+      return (await ui()).pressArrow(request.params.direction)
     }
-    case "llm.pending": return (await backend()).pendingExchanges()
-    case "llm.respond": {
-      const input = object(required(command))
-      const client = await backend()
-      const chunk = await client.chunk(string(input, "id"), [{ type: "textDelta", text: string(input, "text") }])
-      const finish = await client.finish(string(input, "id"), finishReason(input.reason))
-      return { chunk, finish }
+    case "ui.focus": {
+      const request = Frontend.decodeRequest({ jsonrpc: "2.0", method: "ui.focus", params: json(required(command)) })
+      if (request.method !== "ui.focus") throw new Error("invalid ui.focus params")
+      return (await ui()).focus(request.params.target)
+    }
+    case "ui.click": {
+      const request = Frontend.decodeRequest({ jsonrpc: "2.0", method: "ui.click", params: json(required(command)) })
+      if (request.method !== "ui.click") throw new Error("invalid ui.click params")
+      return (await ui()).click(request.params.target, request.params.x, request.params.y)
     }
+    case "ui.screenshot": return (await ui()).screenshot()
+    case "ui.state": return (await ui()).state()
+    case "ui.start-record": return (await ui()).startRecord()
+    case "ui.end-record": return (await ui()).endRecord()
+    case "llm.pending": return (await backend()).pendingExchanges()
     case "llm.chunk": {
-      const input = object(required(command))
-      if (!Array.isArray(input.items)) throw new Error("llm.chunk items must be an array")
-      return (await backend()).chunk(string(input, "id"), input.items as ReadonlyArray<BackendItem>)
+      const request = Backend.decodeRequest({ jsonrpc: "2.0", method: "llm.chunk", params: json(required(command)) })
+      if (request.method !== "llm.chunk") throw new Error("invalid llm.chunk params")
+      return (await backend()).chunk(request.params.id, request.params.items)
     }
     case "llm.finish": {
-      const input = scalarOrObject(required(command), "id")
-      return (await backend()).finish(string(input, "id"), finishReason(input.reason))
+      const request = Backend.decodeRequest({ jsonrpc: "2.0", method: "llm.finish", params: json(required(command)) })
+      if (request.method !== "llm.finish") throw new Error("invalid llm.finish params")
+      return (await backend()).finish(request.params.id, request.params.reason)
+    }
+    case "llm.disconnect": {
+      const request = Backend.decodeRequest({ jsonrpc: "2.0", method: "llm.disconnect", params: json(required(command)) })
+      if (request.method !== "llm.disconnect") throw new Error("invalid llm.disconnect params")
+      return (await backend()).disconnect(request.params.id)
     }
-    case "llm.disconnect": return (await backend()).disconnect(required(command))
-    case "network.log": return (await backend()).networkLog()
   }
   throw new Error(`unknown drive command "${command.operation}"`)
 }
@@ -124,52 +120,6 @@ function required(command: DriveCommand) {
   return command.value
 }
 
-function object(value: string) {
-  const parsed: unknown = JSON.parse(value)
-  if (!isRecord(parsed)) throw new Error("command value must be a JSON object")
-  return parsed
-}
-
-function scalarOrObject(value: string, key: string) {
-  return value.trim().startsWith("{") ? object(value) : { [key]: value }
-}
-
-function string(input: Record<string, unknown>, key: string) {
-  const value = input[key]
-  if (typeof value !== "string") throw new Error(`${key} must be a string`)
-  return value
-}
-
-function number(value: unknown, name: string) {
-  const parsed = typeof value === "number" ? value : Number(value)
-  if (!Number.isFinite(parsed)) throw new Error(`${name} must be a number`)
-  return parsed
-}
-
-function modifiers(value: unknown): KeyModifiers | undefined {
-  if (value === undefined) return undefined
-  if (!isRecord(value)) throw new Error("modifiers must be an object")
-  return {
-    ctrl: optionalBoolean(value.ctrl, "ctrl"),
-    shift: optionalBoolean(value.shift, "shift"),
-    meta: optionalBoolean(value.meta, "meta"),
-    super: optionalBoolean(value.super, "super"),
-    hyper: optionalBoolean(value.hyper, "hyper"),
-  }
-}
-
-function finishReason(value: unknown): BackendFinishReason | undefined {
-  if (value === undefined) return undefined
-  if (value === "stop" || value === "tool-calls" || value === "length" || value === "content-filter") return value
-  throw new Error("reason must be stop, tool-calls, length, or content-filter")
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-function optionalBoolean(value: unknown, name: string) {
-  if (value === undefined) return undefined
-  if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`)
-  return value
+function json(value: string): unknown {
+  return JSON.parse(value)
 }

package/src/cli/index.ts

@@ -7,6 +7,8 @@ import { describe } from "./describe.js"
 import { extractCommands } from "./parse.js"
 import { start } from "./start.js"
 import { stop } from "./stop.js"
+import { api } from "./api.js"
+import { restart } from "./restart.js"
 import type { DriveCommand, SendOptions, StartOptions } from "./types.js"
 
 const extracted = extract()
@@ -48,7 +50,7 @@ const sendCommand = Command.make("send", { name, driver }, (config) =>
     Command.withDescription("Connect to an existing drive-enabled OpenCode instance"),
     Command.withExamples([
       {
-        command: "opencode-drive send --name demo --command.type hello --command.press enter --command.render --command.state",
+        command: "opencode-drive send --name demo --command.ui.type '{\"text\":\"hello\"}' --command.ui.state",
         description: "Execute an ordered command batch",
       },
     ]),
@@ -64,9 +66,18 @@ const stopCommand = Command.make("stop", { name }, (config) =>
     Command.withDescription("Stop a registered headless OpenCode instance"),
   )
 
+const restartCommand = Command.make("restart", { name }, (config) =>
+  execute(() => restart(Option.getOrUndefined(config.name)))).pipe(
+    Command.withDescription("Restart a registered OpenCode client"),
+  )
+
+const apiCommand = Command.make("api", {}, () => execute(api)).pipe(
+  Command.withDescription("Print the OpenCode drive protocol"),
+)
+
 const root = Command.make("opencode-drive").pipe(
   Command.withDescription("Drive real and simulated OpenCode instances"),
-  Command.withSubcommands([startCommand, sendCommand, describeCommand, stopCommand]),
+  Command.withSubcommands([startCommand, sendCommand, describeCommand, stopCommand, restartCommand, apiCommand]),
 )
 
 Command.runWith(root, { version: "0.1.0" })(extracted.args).pipe(

package/src/cli/instance.ts

@@ -1,4 +1,4 @@
-import { mkdir, rm } from "node:fs/promises"
+import { chmod, mkdir, rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join, resolve } from "node:path"
 import { registerInstance, registryDirectory, transferInstance, unregisterInstance } from "./registry.js"
@@ -89,6 +89,7 @@ export async function launchInstance(options: LaunchOptions = {}) {
     OPENCODE_DRIVE_RENDERER: options.visible ? "visible" : "headless",
     OPENCODE_CONFIG_DIR: join(cwd, ".opencode"),
     OPENCODE_DB: ":memory:",
+    OPENCODE_TEST_HOME: artifacts,
     XDG_CACHE_HOME: join(artifacts, "home", ".cache"),
     XDG_CONFIG_HOME: join(artifacts, "home", ".config"),
     XDG_DATA_HOME: join(artifacts, "home", ".local", "share"),
@@ -98,19 +99,22 @@ export async function launchInstance(options: LaunchOptions = {}) {
     ? await prepareDev(cwd, options.dev)
     : options.command?.length
       ? [...options.command]
-      : ["opencode2", "--standalone"]
+      : ["opencode2"]
+  const launch = join(artifacts, "launch.json")
+  await Bun.write(launch, `${JSON.stringify({ command, environment }, undefined, 2)}\n`)
+  await chmod(launch, 0o600)
   const visible = options.visible === true
-  const child = Bun.spawn(command, {
-    cwd,
-    env: environment,
-    stdin: visible ? "inherit" : "ignore",
-    stdout: visible ? "inherit" : Bun.file(join(artifacts, "opencode.stdout.log")),
-    stderr: visible ? "inherit" : Bun.file(join(artifacts, "opencode.stderr.log")),
-  })
-  const lifecycle = { detached: false, stopping: undefined as Promise<void> | undefined }
+  let child = spawn(command, environment, manifest)
+  const lifecycle = {
+    detached: false,
+    stopping: undefined as Promise<void> | undefined,
+    restarting: undefined as Promise<void> | undefined,
+  }
   return {
     manifest,
-    child,
+    get child() {
+      return child
+    },
     async waitForDrive(requirement: "ui" | "backend" | "both" = "both", timeout = 60_000) {
       const urls = requirement === "both"
         ? [endpoints.ui, endpoints.backend]
@@ -122,10 +126,37 @@ export async function launchInstance(options: LaunchOptions = {}) {
       child.unref()
       lifecycle.detached = true
     },
+    restart() {
+      if (lifecycle.restarting) return lifecycle.restarting
+      lifecycle.restarting = (async () => {
+        await terminate(child)
+        child = spawn(command, environment, manifest)
+        await Promise.all([
+          waitForWebSocket(endpoints.ui, child.exited, 60_000),
+          waitForWebSocket(endpoints.backend, child.exited, 60_000),
+        ])
+      })().finally(() => {
+        lifecycle.restarting = undefined
+      })
+      return lifecycle.restarting
+    },
+    async wait() {
+      while (true) {
+        const current = child
+        const status = await current.exited
+        if (lifecycle.restarting) {
+          await lifecycle.restarting
+          continue
+        }
+        if (child !== current) continue
+        return status
+      }
+    },
     stop(force = false) {
       if (lifecycle.detached) return Promise.resolve()
       if (lifecycle.stopping) return lifecycle.stopping
       lifecycle.stopping = (async () => {
+        if (lifecycle.restarting) await lifecycle.restarting.catch(() => undefined)
         if (force) {
           if (child.exitCode === null) child.kill("SIGKILL")
         } else if (child.exitCode === null) {
@@ -141,6 +172,53 @@ export async function launchInstance(options: LaunchOptions = {}) {
   }
 }
 
+async function terminate(child: Bun.Subprocess) {
+  if (child.exitCode !== null) return
+  child.kill("SIGTERM")
+  await Promise.race([child.exited, Bun.sleep(1_000)])
+  if (child.exitCode === null) child.kill("SIGKILL")
+  await child.exited
+}
+
+export async function restartInstance(manifest: InstanceManifest) {
+  const value: unknown = await Bun.file(join(manifest.artifacts, "launch.json")).json()
+  if (!isLaunchInfo(value)) throw new Error(`drive instance "${manifest.name}" has no valid restart metadata`)
+  const child = spawn(value.command, value.environment, manifest)
+  await transferInstance(manifest, child.pid)
+  try {
+    await Promise.all([
+      waitForWebSocket(manifest.endpoints.ui, child.exited, 60_000),
+      waitForWebSocket(manifest.endpoints.backend, child.exited, 60_000),
+    ])
+    child.unref()
+    return child.pid
+  } catch (error) {
+    if (child.exitCode === null) child.kill("SIGKILL")
+    await child.exited
+    throw error
+  }
+}
+
+function spawn(command: ReadonlyArray<string>, environment: Readonly<Record<string, string>>, manifest: InstanceManifest) {
+  return Bun.spawn([...command], {
+    cwd: manifest.cwd,
+    env: environment,
+    stdin: manifest.headless ? "ignore" : "inherit",
+    stdout: manifest.headless ? Bun.file(join(manifest.artifacts, "opencode.stdout.log")) : "inherit",
+    stderr: manifest.headless ? Bun.file(join(manifest.artifacts, "opencode.stderr.log")) : "inherit",
+  })
+}
+
+function isLaunchInfo(value: unknown): value is {
+  readonly command: ReadonlyArray<string>
+  readonly environment: Readonly<Record<string, string>>
+} {
+  if (typeof value !== "object" || value === null) return false
+  if (!("command" in value) || !Array.isArray(value.command) || !value.command.every((item) => typeof item === "string")) return false
+  if (!("environment" in value) || typeof value.environment !== "object" || value.environment === null || Array.isArray(value.environment)) return false
+  return Object.values(value.environment).every((item) => typeof item === "string")
+}
+
 async function prepareDev(cwd: string, directory: string) {
   const root = resolve(directory)
   const entrypoint = join(root, "packages", "cli", "src", "index.ts")
@@ -168,7 +246,6 @@ async function prepareDev(cwd: string, directory: string) {
     "--conditions=browser",
     "--preload=@opentui/solid/preload",
     entrypoint,
-    "--standalone",
   ]
 }
 

package/src/cli/restart.ts

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto"
+import { join } from "node:path"
+import { restartInstance } from "./instance.js"
+import { resolveInstance } from "./registry.js"
+
+export async function restart(name?: string) {
+  const manifest = await resolveInstance(name ?? "default")
+  if (!manifest.headless) {
+    await restartVisible(manifest)
+    console.log("success")
+    return
+  }
+  process.kill(manifest.pid, "SIGTERM")
+  await Promise.race([waitForExit(manifest.pid), Bun.sleep(1_000)])
+  if (alive(manifest.pid)) process.kill(manifest.pid, "SIGKILL")
+  await waitForExit(manifest.pid)
+  await restartInstance(manifest)
+  console.log("success")
+}
+
+async function restartVisible(manifest: Awaited<ReturnType<typeof resolveInstance>>) {
+  if (!(await Bun.file(join(manifest.artifacts, "launch.json")).exists())) {
+    throw new Error(`drive instance "${manifest.name}" was started by a version that does not support restart`)
+  }
+  const token = randomUUID()
+  const request = join(manifest.artifacts, "restart-request.json")
+  const response = join(manifest.artifacts, "restart-response.json")
+  await Bun.file(response).delete().catch(() => undefined)
+  await Bun.write(request, `${JSON.stringify({ token })}\n`)
+  const deadline = Date.now() + 60_000
+  while (Date.now() < deadline) {
+    const value = await Bun.file(response).json().catch(() => undefined)
+    if (isRestartResponse(value) && value.token === token) {
+      if (!value.success) throw new Error(value.error ?? "visible restart failed")
+      return
+    }
+    if (!alive(manifest.pid)) throw new Error(`drive instance "${manifest.name}" exited while restarting`)
+    await Bun.sleep(25)
+  }
+  throw new Error(`timed out restarting drive instance "${manifest.name}"`)
+}
+
+function isRestartResponse(value: unknown): value is {
+  readonly token: string
+  readonly success: boolean
+  readonly error?: string
+} {
+  if (typeof value !== "object" || value === null) return false
+  if (!("token" in value) || typeof value.token !== "string") return false
+  return "success" in value && typeof value.success === "boolean"
+}
+
+function waitForExit(pid: number) {
+  return new Promise<void>((resolve) => {
+    const check = () => {
+      if (!alive(pid)) return resolve()
+      setTimeout(check, 25)
+    }
+    check()
+  })
+}
+
+function alive(pid: number) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/cli/send.ts

@@ -12,11 +12,11 @@ export async function send(options: SendOptions) {
     : await resolveInstance("default").catch(() => defaultManifest())
   if (options.commands.length > 0) {
     const result = await executeCommands(manifest, options.commands)
-    if (options.commands.length === 1 && ["render", "end-record"].includes(options.commands[0]?.operation ?? "")) {
+    if (options.commands.length === 1 && ["ui.screenshot", "ui.end-record"].includes(options.commands[0]?.operation ?? "")) {
       console.log(result.results[0]?.result)
       return
     }
-    if (options.commands.length === 1 && ["llm.pending", "state", "start-record"].includes(options.commands[0]?.operation ?? "")) {
+    if (options.commands.length === 1 && ["llm.pending", "ui.state", "ui.start-record"].includes(options.commands[0]?.operation ?? "")) {
       console.log(JSON.stringify(result.results[0]?.result, undefined, 2))
       return
     }

package/src/cli/start.ts

@@ -4,6 +4,7 @@ import { runCampaign } from "../experimental/cli-campaign.js"
 import { runDriver } from "./driver.js"
 import { launchInstance } from "./instance.js"
 import type { StartOptions } from "./types.js"
+import { join } from "node:path"
 
 export async function start(options: StartOptions) {
   if (options.campaign) return runCampaign(options)
@@ -23,6 +24,7 @@ export async function start(options: StartOptions) {
     return
   }
   const interrupt = () => void instance.stop()
+  const stopRestart = options.visible ? watchVisibleRestarts(instance) : () => {}
   process.once("SIGINT", interrupt)
   process.once("SIGTERM", interrupt)
   try {
@@ -30,11 +32,11 @@ export async function start(options: StartOptions) {
       await instance.waitForDrive("both")
       const result = await executeCommands(instance.manifest, options.commands)
       await instance.stop()
-      if (options.commands.length === 1 && ["render", "end-record"].includes(options.commands[0]?.operation ?? "")) {
+      if (options.commands.length === 1 && ["ui.screenshot", "ui.end-record"].includes(options.commands[0]?.operation ?? "")) {
         console.log(result.results[0]?.result)
         return
       }
-      if (options.commands.length === 1 && ["llm.pending", "state", "start-record"].includes(options.commands[0]?.operation ?? "")) {
+      if (options.commands.length === 1 && ["llm.pending", "ui.state", "ui.start-record"].includes(options.commands[0]?.operation ?? "")) {
         console.log(JSON.stringify(result.results[0]?.result, undefined, 2))
         return
       }
@@ -46,11 +48,51 @@ export async function start(options: StartOptions) {
       await runDriver(resolve(options.driver), instance.manifest)
       return
     }
-    const status = await instance.child.exited
+    const status = await instance.wait()
     if (status !== 0) process.exitCode = status
   } finally {
     process.off("SIGINT", interrupt)
     process.off("SIGTERM", interrupt)
+    stopRestart()
     await instance.stop()
   }
 }
+
+function watchVisibleRestarts(instance: Awaited<ReturnType<typeof launchInstance>>) {
+  const request = join(instance.manifest.artifacts, "restart-request.json")
+  const response = join(instance.manifest.artifacts, "restart-response.json")
+  const state = { token: undefined as string | undefined, busy: false }
+  const timer = setInterval(() => {
+    if (state.busy) return
+    state.busy = true
+    void handleVisibleRestart(instance, request, response, state).finally(() => {
+      state.busy = false
+    })
+  }, 50)
+  return () => clearInterval(timer)
+}
+
+async function handleVisibleRestart(
+  instance: Awaited<ReturnType<typeof launchInstance>>,
+  request: string,
+  response: string,
+  state: { token: string | undefined },
+) {
+  const value: unknown = await Bun.file(request).json().catch(() => undefined)
+  if (!isRestartRequest(value) || value.token === state.token) return
+  state.token = value.token
+  try {
+    await instance.restart()
+    await Bun.write(response, `${JSON.stringify({ token: value.token, success: true })}\n`)
+  } catch (error) {
+    await Bun.write(response, `${JSON.stringify({
+      token: value.token,
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    })}\n`)
+  }
+}
+
+function isRestartRequest(value: unknown): value is { readonly token: string } {
+  return typeof value === "object" && value !== null && "token" in value && typeof value.token === "string"
+}

package/src/client/backend.ts

@@ -11,7 +11,6 @@ type BackendMethods = {
   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
@@ -110,10 +109,6 @@ export class BackendSimulationClient {
     return this.call("llm.pending")
   }
 
-  networkLog(): Promise<{ readonly entries: ReadonlyArray<Backend.NetworkLogEntry> }> {
-    return this.call("network.log")
-  }
-
   close() {
     this.socket.close()
   }

package/src/client/client.ts

@@ -6,14 +6,16 @@ import {
 const defaultPort = 40900
 
 type Methods = {
-  readonly "ui.render": { readonly params: undefined; readonly result: Frontend.Render }
+  readonly "ui.screenshot": { readonly params: undefined; readonly result: Frontend.Screenshot }
   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 }
+  readonly "ui.type": { readonly params: Frontend.TypeParams; readonly result: Frontend.State }
+  readonly "ui.press": { readonly params: Frontend.PressParams; readonly result: Frontend.State }
+  readonly "ui.enter": { readonly params: undefined; readonly result: Frontend.State }
+  readonly "ui.arrow": { readonly params: Frontend.ArrowParams; readonly result: Frontend.State }
+  readonly "ui.focus": { readonly params: Frontend.FocusParams; readonly result: Frontend.State }
+  readonly "ui.click": { readonly params: Frontend.ClickParams; readonly result: Frontend.State }
 }
 
 type MethodName = keyof Methods
@@ -123,8 +125,8 @@ export class SimulationClient {
     return this.call("ui.state")
   }
 
-  render(): Promise<Frontend.Render> {
-    return this.call("ui.render")
+  screenshot(): Promise<Frontend.Screenshot> {
+    return this.call("ui.screenshot")
   }
 
   startRecord(): Promise<Frontend.StartRecord> {
@@ -136,46 +138,28 @@ export class SimulationClient {
   }
 
   /** 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 })
+    return this.call("ui.type", { text })
   }
 
   pressKey(key: string, modifiers?: Frontend.KeyModifiers): Promise<Frontend.State> {
-    return this.action({ type: "pressKey", key: key === "escape" ? "\u001b" : key, ...(modifiers === undefined ? {} : { modifiers }) })
+    return this.call("ui.press", { key: key === "escape" ? "\u001b" : key, ...(modifiers === undefined ? {} : { modifiers }) })
   }
 
   pressEnter(): Promise<Frontend.State> {
-    return this.action({ type: "pressEnter" })
+    return this.call("ui.enter")
   }
 
   pressArrow(direction: "up" | "down" | "left" | "right"): Promise<Frontend.State> {
-    return this.action({ type: "pressArrow", direction })
+    return this.call("ui.arrow", { direction })
   }
 
   focus(target: number): Promise<Frontend.State> {
-    return this.action({ type: "focus", target })
+    return this.call("ui.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")
+    return this.call("ui.click", { target, x, y })
   }
 
   // ── lifecycle ─────────────────────────────────────────────────────────

package/src/client/index.ts

@@ -7,11 +7,8 @@ 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

@@ -59,12 +59,12 @@ export namespace Frontend {
   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 }),
+    Schema.Struct({ type: Schema.Literal("ui.type"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("ui.press"), key: Schema.String, modifiers: Schema.optional(KeyModifiers) }),
+    Schema.Struct({ type: Schema.Literal("ui.enter") }),
+    Schema.Struct({ type: Schema.Literal("ui.arrow"), direction: Schema.Literals(["up", "down", "left", "right"]) }),
+    Schema.Struct({ type: Schema.Literal("ui.focus"), target: Schema.Number }),
+    Schema.Struct({ type: Schema.Literal("ui.click"), target: Schema.Number, x: Schema.Number, y: Schema.Number }),
   ])
   export type Action = Schema.Schema.Type<typeof Action>
 
@@ -88,12 +88,11 @@ export namespace Frontend {
       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 Screenshot = Schema.String
+  export type Screenshot = Schema.Schema.Type<typeof Screenshot>
 
   export const StartRecord = Schema.Struct({ recording: Schema.Literal(true) })
   export interface StartRecord extends Schema.Schema.Type<typeof StartRecord> {}
@@ -101,37 +100,41 @@ export namespace Frontend {
   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 TypeParams = Schema.Struct({ text: Schema.String })
+  export interface TypeParams extends Schema.Schema.Type<typeof TypeParams> {}
+
+  export const PressParams = Schema.Struct({ key: Schema.String, modifiers: Schema.optional(KeyModifiers) })
+  export interface PressParams extends Schema.Schema.Type<typeof PressParams> {}
+
+  export const ArrowParams = Schema.Struct({ direction: Schema.Literals(["up", "down", "left", "right"]) })
+  export interface ArrowParams extends Schema.Schema.Type<typeof ArrowParams> {}
+
+  export const FocusParams = Schema.Struct({ target: Schema.Number })
+  export interface FocusParams extends Schema.Schema.Type<typeof FocusParams> {}
+
+  export const ClickParams = Schema.Struct({ target: Schema.Number, x: Schema.Number, y: Schema.Number })
+  export interface ClickParams extends Schema.Schema.Type<typeof ClickParams> {}
 
   export const Request = Schema.Union([
-    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.action"), params: ActionParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.type"), params: TypeParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.press"), params: PressParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.arrow"), params: ArrowParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.focus"), params: FocusParams }),
+    Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("ui.click"), params: ClickParams }),
     Schema.Struct({
       ...JsonRpc.RequestFields,
       method: Schema.Literals([
-        "ui.render",
+        "ui.enter",
+        "ui.screenshot",
         "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 {
@@ -164,7 +167,7 @@ export namespace Backend {
     Schema.Struct({ ...JsonRpc.RequestFields, method: Schema.Literal("llm.disconnect"), params: DisconnectParams }),
     Schema.Struct({
       ...JsonRpc.RequestFields,
-      method: Schema.Literals(["llm.attach", "llm.pending", "network.log"]),
+      method: Schema.Literals(["llm.attach", "llm.pending"]),
     }),
   ])
   export type Request = Schema.Schema.Type<typeof Request>

package/src/client/protocol.types.ts

@@ -0,0 +1,68 @@
+// CLI command contract for `opencode-drive send`.
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json }
+
+export type KeyModifiers = {
+  ctrl?: boolean
+  shift?: boolean
+  meta?: boolean
+  super?: boolean
+  hyper?: boolean
+}
+
+export type Element = {
+  id: string
+  num: number
+  x: number
+  y: number
+  width: number
+  height: number
+  focusable: boolean
+  focused: boolean
+  clickable: boolean
+  editor: boolean
+}
+
+export type State = {
+  focused: {
+    renderable?: number
+    editor: boolean
+  }
+  elements: Element[]
+}
+
+export type LlmItem =
+  | { type: "textDelta"; text: string }
+  | { type: "reasoningDelta"; text: string }
+  | { type: "toolCall"; id: string; name: string; input: Json }
+  | { type: "raw"; chunk: Json }
+
+export type FinishReason = "stop" | "tool-calls" | "length" | "content-filter"
+
+export type OpenedExchange = {
+  id: string
+  url: string
+  body: Json
+}
+
+export type Command =
+  | { name: "ui.type"; params: { text: string }; result: State }
+  | { name: "ui.press"; params: { key: string; modifiers?: KeyModifiers }; result: State }
+  | { name: "ui.enter"; result: State }
+  | { name: "ui.arrow"; params: { direction: "up" | "down" | "left" | "right" }; result: State }
+  | { name: "ui.focus"; params: { target: number }; result: State }
+  | { name: "ui.click"; params: { target: number; x: number; y: number }; result: State }
+  | { name: "ui.screenshot"; result: string }
+  | { name: "ui.state"; result: State }
+  | { name: "ui.start-record"; result: { recording: true } }
+  | { name: "ui.end-record"; result: string }
+  | { name: "llm.chunk"; params: { id: string; items: LlmItem[] }; result: { ok: true } }
+  | { name: "llm.finish"; params: { id: string; reason?: FinishReason }; result: { ok: true } }
+  | { name: "llm.disconnect"; params: { id: string }; result: { ok: true } }
+  | { name: "llm.attach"; result: { attached: true } }
+  | { name: "llm.pending"; result: { exchanges: OpenedExchange[] } }
+
+// Commands with `params` take one JSON argument:
+//   --command.ui.type '{"text":"hello"}'
+// Commands without `params` are flags:
+//   --command.ui.enter

package/src/experimental/campaign.ts

@@ -83,7 +83,7 @@ for (let index = 0; index < options.count; index++) {
     "--driver", `bun ${path.resolve("src/experimental/flow-driver.ts")} ${path.join(directory, "scenario.json")} ${path.join(directory, "result.json")}`,
     "--",
     "bun", "run", "--conditions=browser", "--preload=@opentui/solid/preload",
-    "/root/projects/opencode-latest/packages/cli/src/index.ts", "--standalone",
+    "/root/projects/opencode-latest/packages/cli/src/index.ts",
   ], {
     cwd: path.resolve("."),
     env: {
@@ -107,7 +107,7 @@ for (let index = 0; index < options.count; index++) {
   }
   const result: FlowResult = await Bun.file(path.join(directory, "result.json")).json()
   results.push(result)
-  console.log(`  passed in ${result.durationMs}ms; trace=${result.traceRecords} title=${result.titleExchanges}`)
+  console.log(`  passed in ${result.durationMs}ms; title=${result.titleExchanges}`)
 }
 
 const summary = {
@@ -117,7 +117,6 @@ const summary = {
   assistantExchanges: results.reduce((total, result) => total + result.assistantExchanges, 0),
   subagentExchanges: results.reduce((total, result) => total + result.subagentExchanges, 0),
   titleExchanges: results.reduce((total, result) => total + result.titleExchanges, 0),
-  traceRecords: results.reduce((total, result) => total + result.traceRecords, 0),
   durationMs: results.reduce((total, result) => total + result.durationMs, 0),
   coverage: { ...coverage, streamChunkTypes: [...coverage.streamChunkTypes] },
 }

package/src/experimental/flow-driver.ts

@@ -100,7 +100,6 @@ try {
     if (stepDelay > 0) await Bun.sleep(stepDelay)
   }
   await waitFor("provider idle", async () => (await backend.pendingExchanges()).exchanges.length === 0)
-  const trace = await ui.traceExport()
   const result: FlowResult = {
     seed: scenario.seed,
     name: scenario.name,
@@ -108,7 +107,6 @@ try {
     assistantExchanges,
     subagentExchanges,
     titleExchanges,
-    traceRecords: trace.records.length,
     durationMs: Date.now() - started,
     finalState: await ui.state(),
   }

package/src/experimental/flows/types.ts

@@ -41,7 +41,6 @@ export interface FlowResult {
   readonly assistantExchanges: number
   readonly subagentExchanges: number
   readonly titleExchanges: number
-  readonly traceRecords: number
   readonly durationMs: number
   readonly finalState: UiState
 }

package/src/experimental/reproduce-stale-running-visible.ts

@@ -38,7 +38,7 @@ const child = Bun.spawn([
   "--driver", `bun ${path.resolve("src/experimental/stale-running-driver.ts")}`,
   "--",
   "bun", "run", "--conditions=browser", "--preload=@opentui/solid/preload",
-  "/root/projects/opencode-latest/packages/cli/src/index.ts", "--standalone",
+  "/root/projects/opencode-latest/packages/cli/src/index.ts",
 ], {
   cwd: path.resolve("."),
   env: {