opencode-drive 0.1.1 → 0.1.3

package/README.md

@@ -1,90 +1,119 @@
 # opencode-drive
 
-Drive visible, headless, simulated, or real OpenCode instances.
+Drive real and simulated OpenCode instances through fixed local WebSocket ports.
 
-```bash
-bunx opencode-drive start --name demo
+## Skill
 
-bunx opencode-drive send --name demo \
-  --command.type "hello" \
-  --command.press enter \
-  --command.render \
-  --command.state
+```sh
+npx skills add jlongster/opencode-drive --agent opencode --skill opencode-drive
 ```
 
-`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
-`--`:
+# Usage
+
+**Start the default headless instance:**
 
 ```bash
-bunx opencode-drive start --name local --visible -- \
-  opencode2 --standalone
+bunx opencode-drive start
 ```
 
-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:
+There is no "detached" version. If you want to drive an isolated app, use the scripted version below.
 
-```bash
-bunx opencode-drive start --visible --dev ~/projects/opencode-latest
+Run a local OpenCode checkout:
+
+```sh
+bunx opencode-drive start --dev ~/projects/opencode
+```
+
+## Send UI Commands
+
+`send` always connects to UI port `40900`:
+
+```sh
+bunx opencode-drive send \
+  --command.ui.type '{"text":"Explain this project"}' \
+  --command.ui.enter
+
+bunx opencode-drive send --command.ui.state
+bunx opencode-drive send --command.ui.screenshot
 ```
 
-Both `start` and `send` accept `--driver ./driver.ts`. Drivers may default
-export a function created with `defineDriver`:
+Run `bunx opencode-drive api` for the full UI command contract.
+
+## Scripted Mode
+
+Scripted mode launches OpenCode, runs the script, and stops OpenCode when the script exits.
+
+```sh
+bunx opencode-drive start --script ./drive.ts
+```
+
+Add `--visible` to watch the TUI while the script runs. Visible starts remain active after a script finishes. Restart the visible OpenCode child and rerun its script with `bunx opencode-drive restart`.
+
+Only one visible instance can be controlled this way. Headless runs exit when their script completes and do not support restart.
+
+The module must default-export a function receiving connected clients and the run's artifact directory:
 
 ```ts
-import { defineDriver } from "opencode-drive/experimental"
+import { defineScript } from "opencode-drive"
 
-export default defineDriver(async ({ ui }) => {
-  await ui.typeText("hello")
+export default defineScript(async ({ ui, backend }) => {
+  await backend.attach(async (request) => {
+    await backend.chunk(request.id, [{ type: "textDelta", text: "Hello" }])
+    await backend.finish(request.id)
+  })
+
+  await ui.typeText("Say hello")
   await ui.pressEnter()
-  const state = await ui.state()
-  if (!state.focused.editor) throw new Error("prompt editor is not focused")
+  await ui.screenshot()
 })
 ```
 
-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:
+# Use cases
 
-```bash
-bunx opencode-drive start --campaign ./campaign.ts --seed 42000
-bunx opencode-drive start --campaign ./campaign.ts --seed 42000 --case 17 --visible
-```
+There are two different modes OpenCode can run in:
+
+* 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
+
+You can choose one or the other, or both! This allows the following use cases:
+
+## 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.
 
-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"
-  }
-}
+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, all you have to do is pass `OPENCODE_DRIVE=1` when running opencode:
+
+```sh
+# In the opencode repo
+OPENCODE_DRIVE=1 bun run dev
 ```
 
-## Probe Experiments
+#### UI work in simulated mode
 
-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.
+If you are doing UI work, you may want to run it in simulated mode. You can do that with this:
 
-The opencode checkout is expected at `~/projects/opencode-latest`.
+```
+bunx opencode-drive start --dev . --visible
+```
 
-## Setup
+The nice thing about this is OpenCode can drive it into the states you are interested in. Additionally, its able to restart the UI itself. The server will still be running in the background so this only restarts the UI:
 
-```bash
-cd ~/projects/opencode-drive
-bun install
-bun run check
+```sh
+bunx opencode-drive restart
 ```
+
+## 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.
+
+## 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)
+
+## 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.3",
   "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,64 +1,76 @@
-import type { BackendFinishReason, BackendItem, KeyModifiers } from "../client/index.js"
-import { connectBackendSimulation, connectSimulation } 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",
-])
+import { connectSimulation, Frontend } from "../client/index.js"
+import type { DriveCommand } from "./types.js"
+
+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",
+  },
+} as const
 
 export function commandAcceptsValue(operation: string) {
-  if (noValue.has(operation)) return false
-  if (withValue.has(operation)) return true
+  if (operation === "ui.type") return commandInfo[operation].value
+  if (operation === "ui.press") return commandInfo[operation].value
+  if (operation === "ui.enter") return commandInfo[operation].value
+  if (operation === "ui.arrow") return commandInfo[operation].value
+  if (operation === "ui.focus") return commandInfo[operation].value
+  if (operation === "ui.click") return commandInfo[operation].value
+  if (operation === "ui.screenshot") return commandInfo[operation].value
+  if (operation === "ui.state") return commandInfo[operation].value
+  if (operation === "ui.start-record") return commandInfo[operation].value
+  if (operation === "ui.end-record") return commandInfo[operation].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>) {
-  const clients: {
-    ui?: Awaited<ReturnType<typeof connectSimulation>>
-    backend?: Awaited<ReturnType<typeof connectBackendSimulation>>
-  } = {}
-  const ui = async () => (clients.ui ??= await connectSimulation({ url: manifest.endpoints.ui }))
-  const backend = async () => (clients.backend ??= await connectBackendSimulation({ url: manifest.endpoints.backend }))
-  const results: Array<{ readonly command: string; readonly result: unknown }> = []
+export async function executeCommands(endpoint: string, commands: ReadonlyArray<DriveCommand>) {
+  const ui = await connectSimulation({ url: endpoint })
+  const results: Array<{ readonly command: string; readonly result: unknown }> =
+    []
   try {
-    for (const command of commands) {
-      results.push({ command: command.operation, result: await execute(command, ui, backend) })
-    }
-    return { name: manifest.name, results }
+    for (const command of commands)
+      results.push({
+        command: command.operation,
+        result: await execute(command, ui),
+      })
+    return { results }
   } catch (error) {
-    throw new CommandBatchError(manifest.name, results, error)
+    throw new CommandBatchError(results, error)
   } finally {
-    clients.ui?.close()
-    clients.backend?.close()
+    ui.close()
   }
 }
 
 export class CommandBatchError extends Error {
   constructor(
-    readonly instance: string,
-    readonly results: ReadonlyArray<{ readonly command: string; readonly result: unknown }>,
+    readonly results: ReadonlyArray<{
+      readonly command: string
+      readonly result: unknown
+    }>,
     readonly reason: unknown,
   ) {
     super(reason instanceof Error ? reason.message : String(reason))
@@ -68,108 +80,79 @@ export class CommandBatchError extends Error {
 
 async function execute(
   command: DriveCommand,
-  ui: () => Promise<Awaited<ReturnType<typeof connectSimulation>>>,
-  backend: () => Promise<Awaited<ReturnType<typeof connectBackendSimulation>>>,
+  ui: Awaited<ReturnType<typeof connectSimulation>>,
 ) {
   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 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 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 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 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 ui.focus(request.params.target)
     }
-    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>)
+    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 ui.click(request.params.target, request.params.x, request.params.y)
     }
-    case "llm.finish": {
-      const input = scalarOrObject(required(command), "id")
-      return (await backend()).finish(string(input, "id"), finishReason(input.reason))
-    }
-    case "llm.disconnect": return (await backend()).disconnect(required(command))
-    case "network.log": return (await backend()).networkLog()
+    case "ui.screenshot":
+      return ui.screenshot()
+    case "ui.state":
+      return ui.state()
+    case "ui.start-record":
+      return ui.startRecord()
+    case "ui.end-record":
+      return ui.endRecord()
   }
   throw new Error(`unknown drive command "${command.operation}"`)
 }
 
 function required(command: DriveCommand) {
-  if (command.value === undefined) throw new Error(`${command.operation} requires a value`)
+  if (command.value === undefined)
+    throw new Error(`${command.operation} requires a value`)
   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/control.ts

@@ -0,0 +1,43 @@
+import { rm } from "node:fs/promises"
+import { connect, createServer } from "node:net"
+
+export async function listenControl(
+  path: string,
+  handlers: { readonly restart: () => Promise<void>; readonly stop: () => Promise<void> },
+) {
+  const server = createServer((socket) => {
+    socket.setEncoding("utf8")
+    socket.once("data", (data) => {
+      const handler = handlers[String(data).trim() as keyof typeof handlers]
+      socket.destroy()
+      if (!handler) return
+      void handler().catch((error) => {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`)
+      })
+    })
+  })
+  await listen(server, path)
+  return async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+    await rm(path, { force: true })
+  }
+}
+
+export function request(path: string, command: "restart" | "stop") {
+  return new Promise<void>((resolve, reject) => {
+    const socket = connect(path)
+    socket.on("connect", () => socket.end(`${command}\n`, resolve))
+    socket.on("error", () => reject(new Error("instance control socket is unavailable")))
+  })
+}
+
+async function listen(server: ReturnType<typeof createServer>, path: string) {
+  await rm(path, { force: true })
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(path, () => {
+      server.off("error", reject)
+      resolve()
+    })
+  })
+}

package/src/cli/describe.ts

@@ -1,14 +1,13 @@
-import { join } from "node:path"
 import { resolveInstance } from "./registry.js"
 
-export async function describe(name?: string) {
-  const manifest = await resolveInstance(name ?? "default")
+export async function describe(name: string) {
+  const manifest = await resolveInstance(name)
   console.log([
     `PID: ${manifest.pid}`,
-    `Headless: ${manifest.headless}`,
+    `Visible: ${manifest.visible}`,
     `Artifacts: ${manifest.artifacts}`,
     `UI: ${manifest.endpoints.ui}`,
     `Backend: ${manifest.endpoints.backend}`,
-    `Logs: ${join(manifest.artifacts, "home", ".local", "share", "opencode", "log", "opencode*.log")}`,
+    `Logs: ${manifest.artifacts}/logs`,
   ].join("\n"))
 }