opencode-drive 0.1.2 → 0.1.3

package/README.md

@@ -1,59 +1,71 @@
 # opencode-drive
 
-Drive visible, headless, simulated, or real OpenCode instances.
+Drive real and simulated OpenCode instances through fixed local WebSocket ports.
+
+## Skill
+
+```sh
+npx skills add jlongster/opencode-drive --agent opencode --skill opencode-drive
+```
 
 # Usage
 
-**Start the default detached, headless instance:**
+**Start the default headless instance:**
 
 ```bash
 bunx opencode-drive start
 ```
 
-**Start a named instance, then address it with `--name`:**
+There is no "detached" version. If you want to drive an isolated app, use the scripted version below.
 
-```bash
-bunx opencode-drive start --name demo
+Run a local OpenCode checkout:
+
+```sh
+bunx opencode-drive start --dev ~/projects/opencode
 ```
 
-**Type, submit a prompt, and take a screenshot:**
+## Send UI Commands
 
-```bash
-bunx opencode-drive send --name demo \
-  --command.type "Explain this project in one sentence" \
-  --command.enter \
-  --command.screenshot
-```
+`send` always connects to UI port `40900`:
 
-**List the full command API for agents:**
+```sh
+bunx opencode-drive send \
+  --command.ui.type '{"text":"Explain this project"}' \
+  --command.ui.enter
 
-```bash
-bunx opencode-drive api
+bunx opencode-drive send --command.ui.state
+bunx opencode-drive send --command.ui.screenshot
 ```
 
-**Run OpenCode visibly in the foreground:**
+Run `bunx opencode-drive api` for the full UI command contract.
 
-```bash
-bunx opencode-drive start --visible
-```
+## Scripted Mode
 
-**Run a local OpenCode development checkout:**
+Scripted mode launches OpenCode, runs the script, and stops OpenCode when the script exits.
 
-```bash
-cd ~/projects/opencode
-bunx opencode-drive start --visible --dev .
+```sh
+bunx opencode-drive start --script ./drive.ts
 ```
 
-**Run a custom OpenCode command after `--`:**
+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`.
 
-```bash
-bunx opencode-drive start --name demo -- opencode2 --standalone
-```
+Only one visible instance can be controlled this way. Headless runs exit when their script completes and do not support restart.
 
-**Stop a detached headless instance:**
+The module must default-export a function receiving connected clients and the run's artifact directory:
 
-```bash
-bunx opencode-drive stop --name demo
+```ts
+import { defineScript } from "opencode-drive"
+
+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()
+  await ui.screenshot()
+})
 ```
 
 # Use cases
@@ -65,36 +77,43 @@ There are two different modes OpenCode can run in:
 
 You can choose one or the other, or both! This allows the following use cases:
 
-1. You want to develop opencode
+## 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):
+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
+```
+
+#### UI work in simulated mode
+
+If you are doing UI work, you may want to run it in simulated mode. You can do that with this:
+
+```
 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:
+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:
 
 ```sh
 bunx opencode-drive restart
 ```
 
-If you want to restart the backend, use the `/reload` command.
-
-2. You want opencode to develop itself
+## 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
+## 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
+## 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,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-drive",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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,30 @@ 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 +80,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,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"))
 }