opencode-drive 0.1.3 → 0.1.4

package/README.md

@@ -1,119 +1,39 @@
 # opencode-drive
 
-Drive real and simulated OpenCode instances through fixed local WebSocket ports.
+This project gives your agents control over OpenCode:
+
+* 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
 
 ## Skill
 
 ```sh
 npx skills add jlongster/opencode-drive --agent opencode --skill opencode-drive
 ```
+## OpenCode development
 
-# Usage
-
-**Start the default headless instance:**
-
-```bash
-bunx opencode-drive start
-```
-
-There is no "detached" version. If you want to drive an isolated app, use the scripted version below.
-
-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
-```
-
-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.
+Run this:
 
 ```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 { 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()
-})
+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
+If you installed the skill file, OpenCode will be able to see and interact with the running instance.
 
-You can choose one or the other, or both! This allows the following use cases:
+## Using with agents
 
-## You want to develop opencode
+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.
 
-You are running a development version of OpenCode to work on it. You have another OpenCode instance making changes to the app.
+## UI development
 
-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.
+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.
 
-To do this, all you have to do is pass `OPENCODE_DRIVE=1` when running opencode:
+Run it in visible mode:
 
 ```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:
-
+opencode-drive start --visible --dev ~/projects/opencode
 ```
-bunx opencode-drive start --dev . --visible
-```
-
-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
-```
-
-## 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
+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.3",
+  "version": "0.1.4",
   "description": "Drive real and simulated OpenCode instances",
   "license": "MIT",
   "type": "module",

package/src/cli/commands.ts

@@ -47,7 +47,10 @@ export function commandNames() {
   return Object.keys(commandInfo).sort()
 }
 
-export async function executeCommands(endpoint: string, commands: ReadonlyArray<DriveCommand>) {
+export async function executeCommands(
+  endpoint: string,
+  commands: ReadonlyArray<DriveCommand>,
+) {
   const ui = await connectSimulation({ url: endpoint })
   const results: Array<{ readonly command: string; readonly result: unknown }> =
     []

package/src/cli/control.ts

@@ -1,21 +1,52 @@
 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> },
+  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.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)}`)
-      })
+    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()))
@@ -23,14 +54,83 @@ export async function listenControl(
   }
 }
 
-export function request(path: string, command: "restart" | "stop") {
-  return new Promise<void>((resolve, reject) => {
+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)
-    socket.on("connect", () => socket.end(`${command}\n`, resolve))
-    socket.on("error", () => reject(new Error("instance control socket is unavailable")))
+    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) => {

package/src/cli/index.ts

@@ -4,16 +4,32 @@ import { Effect, Option } from "effect"
 import { Command, Flag } from "effect/unstable/cli"
 import { api } from "./api.js"
 import { extractCommands } from "./parse.js"
+import { list } from "./list.js"
+import { logs } from "./logs.js"
+import { restart } from "./restart.js"
+import { responses } from "./responses.js"
 import { send } from "./send.js"
 import { start } from "./start.js"
-import { restart } from "./restart.js"
+import { stop } from "./stop.js"
 import type { DriveCommand, SendOptions, StartOptions } from "./types.js"
 
 const extracted = extract()
+const startName = Flag.string("name").pipe(
+  Flag.withDefault("default"),
+  Flag.withDescription("Instance name"),
+)
+const name = Flag.string("name").pipe(
+  Flag.optional,
+  Flag.withDescription("Instance name (inferred when exactly one is running)"),
+)
 
 const startCommand = Command.make(
   "start",
   {
+    name: startName,
+    daemon: Flag.boolean("daemon").pipe(
+      Flag.withDescription("Run as detached instance owner"),
+    ),
     script: Flag.string("script").pipe(
       Flag.optional,
       Flag.withDescription("JavaScript or TypeScript automation module"),
@@ -52,8 +68,16 @@ const startCommand = Command.make(
   ]),
 )
 
-const sendCommand = Command.make("send", {}, () =>
-  execute(() => send(toSendOptions(extracted.commands, extracted.app))),
+const sendCommand = Command.make("send", { name }, (config) =>
+  execute(() =>
+    send(
+      toSendOptions(
+        Option.getOrUndefined(config.name),
+        extracted.commands,
+        extracted.app,
+      ),
+    ),
+  ),
 ).pipe(
   Command.withDescription("Send UI commands to OpenCode on the default port"),
   Command.withExamples([
@@ -69,18 +93,59 @@ const apiCommand = Command.make("api", {}, () => execute(api)).pipe(
   Command.withDescription("Print the OpenCode drive UI protocol"),
 )
 
-const restartCommand = Command.make("restart", {}, () => execute(restart)).pipe(
+const restartCommand = Command.make("restart", { name }, (config) =>
+  execute(() => restart(Option.getOrUndefined(config.name))),
+).pipe(
   Command.withDescription(
-    "Restart the active visible OpenCode instance and rerun its script",
+    "Restart a named OpenCode instance and rerun its script",
   ),
 )
 
+const stopCommand = Command.make("stop", { name }, (config) =>
+  execute(() => stop(Option.getOrUndefined(config.name))),
+).pipe(Command.withDescription("Stop a named OpenCode instance"))
+
+const logsCommand = Command.make("logs", { name }, (config) =>
+  execute(() => logs(Option.getOrUndefined(config.name))),
+).pipe(Command.withDescription("List log files for a named OpenCode instance"))
+
+const listCommand = Command.make("list", {}, () => execute(list)).pipe(
+  Command.withDescription("List active OpenCode instances"),
+)
+
+const responsesCommand = Command.make(
+  "responses",
+  {
+    name,
+    types: Flag.string("types").pipe(
+      Flag.optional,
+      Flag.withDescription("Comma-delimited response types"),
+    ),
+    tools: Flag.string("tools").pipe(
+      Flag.optional,
+      Flag.withDescription("Comma-delimited tool names, or * for all tools"),
+    ),
+  },
+  (config) =>
+    execute(() =>
+      responses({
+        name: Option.getOrUndefined(config.name),
+        types: Option.getOrUndefined(config.types),
+        tools: Option.getOrUndefined(config.tools),
+      }),
+    ),
+).pipe(Command.withDescription("Configure simulated LLM response generation"))
+
 const root = Command.make("opencode-drive").pipe(
   Command.withDescription("Drive real and simulated OpenCode instances"),
   Command.withSubcommands([
     startCommand,
     sendCommand,
+    listCommand,
+    responsesCommand,
+    logsCommand,
     restartCommand,
+    stopCommand,
     apiCommand,
   ]),
 )
@@ -93,6 +158,8 @@ Command.runWith(root, { version: "0.1.0" })(extracted.args).pipe(
 function toStartOptions(
   config: {
     readonly script: Option.Option<string>
+    readonly name: string
+    readonly daemon: boolean
     readonly visible: boolean
     readonly dev: Option.Option<string>
     readonly state: Option.Option<string>
@@ -104,6 +171,8 @@ function toStartOptions(
     throw new Error("start does not accept command flags; use send or --script")
   const options = {
     kind: "start" as const,
+    name: config.name,
+    daemon: config.daemon,
     script: Option.getOrUndefined(config.script),
     visible: config.visible,
     dev: Option.getOrUndefined(config.dev),
@@ -116,11 +185,12 @@ function toStartOptions(
 }
 
 function toSendOptions(
+  name: string | undefined,
   commands: ReadonlyArray<DriveCommand>,
   app: ReadonlyArray<string>,
 ): SendOptions {
   if (app.length > 0) throw new Error("send does not accept a command after --")
-  return { kind: "send", commands }
+  return { kind: "send", name, commands }
 }
 
 function execute(task: () => Promise<void>) {

package/src/cli/instance.ts

@@ -1,7 +1,6 @@
 import { mkdir, rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join, resolve } from "node:path"
-import { defaultBackendPort, defaultPort } from "../client/index.js"
 
 export interface LaunchOptions {
   readonly name: string
@@ -13,7 +12,7 @@ export interface LaunchOptions {
   readonly env?: Readonly<Record<string, string>>
 }
 
-export async function launchInstance(options: LaunchOptions = {}) {
+export async function launchInstance(options: LaunchOptions) {
   const artifacts = resolve(
     join(tmpdir(), "opencode-drive", `run-${crypto.randomUUID().slice(0, 6)}`),
   )
@@ -31,7 +30,10 @@ export async function launchInstance(options: LaunchOptions = {}) {
     mkdir(join(artifacts, "home", ".local", "share"), { recursive: true }),
     mkdir(join(artifacts, "home", ".local", "state"), { recursive: true }),
   ])
-  await Bun.write(join(drive, `${options.name}.json`), `${JSON.stringify({ endpoints }, undefined, 2)}\n`)
+  await Bun.write(
+    join(drive, `${options.name}.json`),
+    `${JSON.stringify({ endpoints }, undefined, 2)}\n`,
+  )
   const state = options.state
     ? resolve(options.state)
     : join(artifacts, "state")
@@ -40,37 +42,44 @@ export async function launchInstance(options: LaunchOptions = {}) {
     await Promise.all([
       mkdir(join(state, "files", ".git"), { recursive: true }),
       mkdir(join(state, "files", ".opencode"), { recursive: true }),
+      mkdir(join(state, "files", "src"), { recursive: true }),
     ])
-    await Bun.write(
-      join(state, "files", ".opencode", "opencode.jsonc"),
-      `${JSON.stringify(
-        {
-          model: "simulation/sim-model",
-          permissions: [{ action: "*", resource: "*", effect: "allow" }],
-          providers: {
-            simulation: {
-              name: "Simulation",
-              package: "aisdk:@ai-sdk/openai-compatible",
-              settings: { baseURL: "https://api.openai.com/v1" },
-              request: { body: { apiKey: "sim-key" } },
-              models: {
-                "sim-model": {
-                  name: "Simulated Model",
-                  capabilities: {
-                    tools: true,
-                    input: ["text"],
-                    output: ["text"],
+    await Promise.all([
+      Bun.write(
+        join(state, "files", ".opencode", "opencode.jsonc"),
+        `${JSON.stringify(
+          {
+            model: "simulation/gpt-sim-model",
+            permissions: [{ action: "*", resource: "*", effect: "allow" }],
+            providers: {
+              simulation: {
+                name: "Simulation",
+                package: "aisdk:@ai-sdk/openai-compatible",
+                settings: { baseURL: "https://api.openai.com/v1" },
+                request: { body: { apiKey: "sim-key" } },
+                models: {
+                  "gpt-sim-model": {
+                    name: "Simulated Model",
+                    capabilities: {
+                      tools: true,
+                      input: ["text"],
+                      output: ["text"],
+                    },
+                    limit: { context: 128000, output: 16000 },
                   },
-                  limit: { context: 128000, output: 16000 },
                 },
               },
             },
           },
-        },
-        undefined,
-        2,
-      )}\n`,
-    )
+          undefined,
+          2,
+        )}\n`,
+      ),
+      Bun.write(
+        join(state, "files", "src", "garden.js"),
+        'export function greet(name) {\n  return `Hello, ${name}.`\n}\n',
+      ),
+    ])
   }
   const environment = cleanEnv({
     ...process.env,
@@ -301,7 +310,7 @@ async function waitForWebSocket(
     const connected = await Promise.race([
       open(url)
         .then((socket) => {
-          socket.close()
+          socket.terminate()
           return true
         })
         .catch(() => false),

package/src/cli/list.ts

@@ -0,0 +1,10 @@
+import { listInstances, manifestPath } from "./registry.js"
+
+export async function list() {
+  const instances = await listInstances()
+  console.log(
+    instances
+      .map((instance) => `${instance.name}: ${manifestPath(instance.name)}`)
+      .join("\n"),
+  )
+}

package/src/cli/logs.ts

@@ -0,0 +1,9 @@
+import { join } from "node:path"
+import { resolveInstance } from "./registry.js"
+
+export async function logs(name?: string) {
+  const manifest = await resolveInstance(name)
+  console.log(
+    join(manifest.artifacts, "logs", "opencode", "log", "opencode*.log"),
+  )
+}

package/src/cli/mock-backend.ts

@@ -1,25 +1,37 @@
 import { connectBackendSimulation } from "../client/index.js"
+import { generateResponse } from "./response-generator.js"
+import type { createResponseSettings } from "./response-generator.js"
 
-const response = "This is a sample response from opencode-drive."
-
-export async function connectMockBackend(endpoint: string) {
+export async function connectMockBackend(
+  endpoint: string,
+  responses: ReturnType<typeof createResponseSettings>,
+) {
   const backend = await connectBackendSimulation({ url: endpoint })
-  let closing = false
-  await backend.attach((request) => {
-    void backend
-      .chunk(request.id, [{ type: "textDelta", text: response }])
-      .then(() => backend.finish(request.id))
-      .catch((error) => {
-        if (!closing)
-          console.error(
-            `error: ${error instanceof Error ? error.message : String(error)}`,
-          )
-      })
+  await backend.attach(async (request) => {
+    const response = generateResponse(responses.current(), request)
+    for (const item of response.items) {
+      if (item.type !== "textDelta" && item.type !== "reasoningDelta") {
+        await backend.chunk(request.id, [item])
+        continue
+      }
+      for (const text of splitText(item.text)) {
+        await backend.chunk(request.id, [{ ...item, text }])
+        await Bun.sleep(45 + Math.floor(Math.random() * 35))
+      }
+    }
+    await backend.finish(request.id, response.finish)
   })
   return {
     close() {
-      closing = true
       backend.close()
     },
   }
 }
+
+export function splitText(text: string) {
+  const words = text.match(/\S+\s*/g) ?? [text]
+  return Array.from(
+    { length: Math.ceil(words.length / 3) },
+    (_, index) => words.slice(index * 3, index * 3 + 3).join(""),
+  )
+}