opencode-drive 0.1.2 → 0.1.4

package/README.md

@@ -1,100 +1,39 @@
 # opencode-drive
 
-Drive visible, headless, simulated, or real OpenCode instances.
+This project gives your agents control over OpenCode:
 
-# Usage
+* Run it during development and let your agents see and poke at the running instance
+* Allow your agents to run it in headless mode and drive it to test things
 
-**Start the default detached, headless instance:**
+## Skill
 
-```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 "Explain this project in one sentence" \
-  --command.enter \
-  --command.screenshot
-```
-
-**List the full command API for agents:**
-
-```bash
-bunx opencode-drive api
-```
-
-**Run OpenCode visibly in the foreground:**
-
-```bash
-bunx opencode-drive start --visible
-```
-
-**Run a local OpenCode development checkout:**
-
-```bash
-cd ~/projects/opencode
-bunx opencode-drive start --visible --dev .
-```
-
-**Run a custom OpenCode command after `--`:**
-
-```bash
-bunx opencode-drive start --name demo -- opencode2 --standalone
+```sh
+npx skills add jlongster/opencode-drive --agent opencode --skill opencode-drive
 ```
+## OpenCode development
 
-**Stop a detached headless instance:**
+Run this:
 
-```bash
-bunx opencode-drive stop --name demo
+```sh
+OPENCODE_DRIVE=1 bun run dev
 ```
 
-# Use cases
-
-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:
-
-1. You want to develop opencode
+If you installed the skill file, OpenCode will be able to see and interact with the running instance.
 
-You are running a development version of OpenCode to work on it. You have another OpenCode instance making changes to the app.
+## Using with agents
 
-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.
+Install the skill file above and ask the agent to test various flows with the app. You also ask it to make a recording and it will generate a video file for you to watch anything it did.
 
-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):
+## UI development
 
-```sh
-bunx opencode-drive start --dev . --visible
-```
+If you are doing UI development in OpenCode, you might want to run it in a simulated mode. This allows `opencode-drive` to drive it and always put it into a state that you want to see.
 
-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:
+Run it in visible mode:
 
 ```sh
-bunx opencode-drive restart
+opencode-drive start --visible --dev ~/projects/opencode
 ```
 
-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
+While developing, you can run `opencode-drive restart` to restart only the UI (the server will persist as a separate process). Do this with agents, and they will always restart and get the UI where you want it to be automatically.
 
-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.
+View the [skills file](https://github.com/jlongster/opencode-drive/blob/main/skills/opencode-drive/SKILL.md) for more details about the CLI.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-drive",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Drive real and simulated OpenCode instances",
   "license": "MIT",
   "type": "module",

package/src/cli/commands.ts

@@ -1,25 +1,45 @@
-import { Backend, connectBackendSimulation, connectSimulation, Frontend } from "../client/index.js"
-import type { DriveCommand, InstanceManifest } from "./types.js"
+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.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.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" },
+  "ui.end-record": {
+    value: false,
+    description: "Stop recording and return the recording path",
+  },
 } as const
 
 export function commandAcceptsValue(operation: string) {
-  if (operation in commandInfo) return commandInfo[operation as keyof typeof commandInfo].value
+  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}"`)
 }
 
@@ -27,31 +47,33 @@ export function commandNames() {
   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))
@@ -61,62 +83,76 @@ 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 "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)
+      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 "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)
+      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 "ui.enter": return (await ui()).pressEnter()
+    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 (await ui()).pressArrow(request.params.direction)
+      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 "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)
+      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 "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 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 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)
+      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 "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
 }
 

package/src/cli/control.ts

@@ -0,0 +1,143 @@
+import { rm } from "node:fs/promises"
+import { connect, createServer } from "node:net"
+import type {
+  ResponseConfiguration,
+  ResponseUpdate,
+} from "./response-generator.js"
+
+export async function listenControl(
+  path: string,
+  handlers: {
+    readonly restart: () => Promise<void>
+    readonly stop: () => Promise<void>
+    readonly responses: (
+      input: ResponseUpdate,
+    ) => Promise<ResponseConfiguration>
+  },
+) {
+  const server = createServer((socket) => {
+    let buffer = ""
+    socket.setEncoding("utf8")
+    socket.on("data", (data) => {
+      buffer += data
+      if (buffer.length > 64 * 1024) {
+        socket.removeAllListeners("data")
+        socket.end("error: control request exceeds 64 KiB\n")
+        return
+      }
+      if (!buffer.includes("\n")) return
+      socket.removeAllListeners("data")
+      void handle(buffer.slice(0, buffer.indexOf("\n"))).then(
+        (result) =>
+          socket.end(
+            `success${result === undefined ? "" : ` ${JSON.stringify(result)}`}\n`,
+          ),
+        (error) =>
+          socket.end(
+            `error: ${error instanceof Error ? error.message : String(error)}\n`,
+          ),
+      )
+    })
+  })
+  const handle = async (input: string) => {
+    if (input === "restart") return handlers.restart()
+    if (input === "stop") return handlers.stop()
+    if (input === "responses") return handlers.responses({})
+    if (input.startsWith("responses "))
+      return handlers.responses(parseResponseUpdate(input.slice("responses ".length)))
+    throw new Error("unknown control command")
+  }
+  await listen(server, path)
+  return async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+    await rm(path, { force: true })
+  }
+}
+
+export async function request(path: string, command: "restart" | "stop") {
+  const response = await send(path, command)
+  if (response !== "success") throw responseError(response)
+}
+
+export async function requestResponses(path: string, input: ResponseUpdate) {
+  const response = await send(
+    path,
+    Object.keys(input).length === 0
+      ? "responses"
+      : `responses ${JSON.stringify(input)}`,
+  )
+  if (!response.startsWith("success ")) throw responseError(response)
+  const value: unknown = JSON.parse(response.slice("success ".length))
+  if (!isResponseConfiguration(value))
+    throw new Error("instance returned an invalid response configuration")
+  return value
+}
+
+function send(path: string, command: string) {
+  return new Promise<string>((resolve, reject) => {
+    const socket = connect(path)
+    let response = ""
+    const timer = setTimeout(() => {
+      socket.destroy()
+      reject(new Error("instance control request timed out"))
+    }, 10_000)
+    socket.setEncoding("utf8")
+    socket.on("connect", () => socket.write(`${command}\n`))
+    socket.on("data", (data) => {
+      response += data
+    })
+    socket.on("end", () => {
+      clearTimeout(timer)
+      resolve(response.trim())
+    })
+    socket.on("error", () => {
+      clearTimeout(timer)
+      reject(new Error("instance control socket is unavailable"))
+    })
+  })
+}
+
+function parseResponseUpdate(input: string): ResponseUpdate {
+  const value: unknown = JSON.parse(input)
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new Error("invalid responses configuration")
+  const types = "types" in value ? stringArray(value.types) : undefined
+  const tools = "tools" in value ? stringArray(value.tools) : undefined
+  return {
+    ...(types === undefined ? {} : { types }),
+    ...(tools === undefined ? {} : { tools }),
+  }
+}
+
+function stringArray(value: unknown) {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+    throw new Error("response types and tools must be string arrays")
+  return value
+}
+
+function isResponseConfiguration(
+  value: unknown,
+): value is ResponseConfiguration {
+  if (typeof value !== "object" || value === null) return false
+  if (!("types" in value) || !stringArrayValue(value.types)) return false
+  return "tools" in value && stringArrayValue(value.tools)
+}
+
+function stringArrayValue(value: unknown) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string")
+}
+
+function responseError(response: string) {
+  return new Error(response.replace(/^error:\s*/, "") || "empty control response")
+}
+
+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()
+    })
+  })
+}