opencode-drive 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# opencode-drive
+
+Drive visible, headless, simulated, or real OpenCode instances.
+
+```bash
+bunx opencode-drive start --name demo
+
+bunx opencode-drive send --name demo \
+  --command.type "hello" \
+  --command.press enter \
+  --command.render \
+  --command.state
+```
+
+`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
+`--`:
+
+```bash
+bunx opencode-drive start --name local --visible -- \
+  opencode2 --standalone
+```
+
+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:
+
+```bash
+bunx opencode-drive start --visible --dev ~/projects/opencode-latest
+```
+
+Both `start` and `send` accept `--driver ./driver.ts`. Drivers may default
+export a function created with `defineDriver`:
+
+```ts
+import { defineDriver } from "opencode-drive/experimental"
+
+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")
+})
+```
+
+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:
+
+```bash
+bunx opencode-drive start --campaign ./campaign.ts --seed 42000
+bunx opencode-drive start --campaign ./campaign.ts --seed 42000 --case 17 --visible
+```
+
+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"
+  }
+}
+```
+
+## Probe Experiments
+
+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.
+
+The opencode checkout is expected at `~/projects/opencode-latest`.
+
+## Setup
+
+```bash
+cd ~/projects/opencode-drive
+bun install
+bun run check
+```

package/bin/opencode-drive

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli/index.js"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-drive",
+  "version": "0.1.0",
+  "description": "Drive real and simulated OpenCode instances",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "bun@1.3.14",
+  "bin": {
+    "opencode-drive": "./bin/opencode-drive"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./experimental": "./src/experimental/index.ts"
+  },
+  "files": [
+    "bin/opencode-drive",
+    "src/cli",
+    "src/client",
+    "src/experimental",
+    "src/index.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "drive": "bun run src/cli/index.ts",
+    "lint": "oxlint src",
+    "test": "bun test test/cli/parse.test.ts test/cli/integration.test.ts",
+    "typecheck": "tsgo --noEmit",
+    "check": "bun run lint && bun run typecheck"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.93",
+    "@effect/platform-node-shared": "4.0.0-beta.93",
+    "effect": "4.0.0-beta.93"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.3.13",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1",
+    "oxlint": "1.60.0",
+    "oxlint-tsgolint": "0.21.0",
+    "typescript": "5.8.2"
+  }
+}

package/src/cli/commands.ts

@@ -0,0 +1,175 @@
+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",
+])
+
+export function commandAcceptsValue(operation: string) {
+  if (noValue.has(operation)) return false
+  if (withValue.has(operation)) return true
+  throw new Error(`unknown drive command "${operation}"`)
+}
+
+export function commandNames() {
+  return [...noValue, ...withValue].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 }> = []
+  try {
+    for (const command of commands) {
+      results.push({ command: command.operation, result: await execute(command, ui, backend) })
+    }
+    return { name: manifest.name, results }
+  } catch (error) {
+    throw new CommandBatchError(manifest.name, results, error)
+  } finally {
+    clients.ui?.close()
+    clients.backend?.close()
+  }
+}
+
+export class CommandBatchError extends Error {
+  constructor(
+    readonly instance: string,
+    readonly results: ReadonlyArray<{ readonly command: string; readonly result: unknown }>,
+    readonly reason: unknown,
+  ) {
+    super(reason instanceof Error ? reason.message : String(reason))
+    this.name = "CommandBatchError"
+  }
+}
+
+async function execute(
+  command: DriveCommand,
+  ui: () => Promise<Awaited<ReturnType<typeof connectSimulation>>>,
+  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 "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 "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 "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 "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 "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()
+  }
+  throw new Error(`unknown drive command "${command.operation}"`)
+}
+
+function required(command: DriveCommand) {
+  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
+}

package/src/cli/describe.ts

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

package/src/cli/driver-runner.ts

@@ -0,0 +1,39 @@
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { connectDrive } from "../experimental/drive.js"
+import type { Driver } from "../experimental/drive.js"
+
+const driver = process.argv[2]
+if (!driver) throw new Error("driver file is required")
+const name = requiredArgument(3, "instance name")
+const ui = requiredArgument(4, "frontend WebSocket URL")
+const backend = requiredArgument(5, "backend WebSocket URL")
+const artifacts = requiredArgument(6, "artifacts directory")
+
+const module: { readonly default?: unknown } = await import(pathToFileURL(resolve(driver)).href)
+if (!isDriver(module.default)) throw new Error("driver must default-export defineDriver(...)")
+const controller = new AbortController()
+process.once("SIGINT", () => controller.abort())
+process.once("SIGTERM", () => controller.abort())
+const session = await connectDrive({ ui, backend })
+try {
+  await module.default({
+    name,
+    ui: session.ui,
+    backend: session.backend,
+    artifacts,
+    signal: controller.signal,
+  })
+} finally {
+  session.close()
+}
+
+function isDriver(value: unknown): value is Driver {
+  return typeof value === "function"
+}
+
+function requiredArgument(index: number, name: string) {
+  const value = process.argv[index]
+  if (!value) throw new Error(`${name} is required`)
+  return value
+}

package/src/cli/driver.ts

@@ -0,0 +1,28 @@
+import { mkdir } from "node:fs/promises"
+import { resolve } from "node:path"
+import type { InstanceManifest } from "./types.js"
+
+export async function runDriver(driver: string, manifest: InstanceManifest) {
+  await mkdir(manifest.artifacts, { recursive: true })
+  const child = Bun.spawn([
+    process.execPath,
+    resolve(import.meta.dir, "driver-runner.ts"),
+    resolve(driver),
+    manifest.name,
+    manifest.endpoints.ui,
+    manifest.endpoints.backend,
+    manifest.artifacts,
+  ], {
+    cwd: process.cwd(),
+    env: cleanEnv(process.env),
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const status = await child.exited
+  if (status !== 0) throw new Error(`driver exited with status ${status}`)
+}
+
+function cleanEnv(env: Readonly<Record<string, string | undefined>>) {
+  return Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined))
+}

package/src/cli/index.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+import { NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Effect, Option } from "effect"
+import { Command, Flag } from "effect/unstable/cli"
+import { send } from "./send.js"
+import { describe } from "./describe.js"
+import { extractCommands } from "./parse.js"
+import { start } from "./start.js"
+import type { DriveCommand, SendOptions, StartOptions } from "./types.js"
+
+const extracted = extract()
+const name = Flag.string("name").pipe(Flag.optional, Flag.withDescription("Instance name"))
+const driver = Flag.string("driver").pipe(Flag.optional, Flag.withDescription("TypeScript driver module"))
+
+const startCommand = Command.make("start", {
+  name,
+  driver,
+  campaign: Flag.string("campaign").pipe(Flag.optional, Flag.withDescription("Campaign module")),
+  seed: Flag.integer("seed").pipe(Flag.withDefault(Date.now() % 1_000_000)),
+  caseIndex: Flag.integer("case").pipe(
+    Flag.filter((value) => value >= 0, () => "Case must be non-negative"),
+    Flag.optional,
+  ),
+  count: Flag.integer("count").pipe(
+    Flag.filter((value) => value > 0, () => "Count must be greater than zero"),
+    Flag.optional,
+  ),
+  concurrency: Flag.integer("concurrency").pipe(
+    Flag.filter((value) => value > 0, () => "Concurrency must be greater than zero"),
+    Flag.withDefault(1),
+  ),
+  visible: Flag.boolean("visible").pipe(Flag.withDescription("Show OpenCode in the terminal")),
+  detach: Flag.boolean("detach").pipe(Flag.withDescription("Keep OpenCode running in the background (default)")),
+  dev: Flag.string("dev").pipe(Flag.optional, Flag.withDescription("Path to an OpenCode development checkout")),
+  state: Flag.string("state").pipe(Flag.optional, Flag.withDescription("Simulation snapshot containing files/")),
+  anchor: Flag.string("anchor").pipe(Flag.optional),
+}, (config) => execute(() => start(toStartOptions(config, extracted.commands, extracted.app)))).pipe(
+  Command.withDescription("Launch and own a local simulated OpenCode instance"),
+  Command.withExamples([
+    { command: "opencode-drive start --name demo --visible", description: "Launch a visible simulated instance" },
+    { command: "opencode-drive start --name demo --detach", description: "Launch a background simulated instance" },
+  ]),
+)
+
+const sendCommand = Command.make("send", { name, driver }, (config) =>
+  execute(() => send(toSendOptions(config, extracted.commands, extracted.app)))).pipe(
+    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",
+        description: "Execute an ordered command batch",
+      },
+    ]),
+  )
+
+const describeCommand = Command.make("describe", { name }, (config) =>
+  execute(() => describe(Option.getOrUndefined(config.name)))).pipe(
+    Command.withDescription("Describe a registered OpenCode instance"),
+  )
+
+const root = Command.make("opencode-drive").pipe(
+  Command.withDescription("Drive real and simulated OpenCode instances"),
+  Command.withSubcommands([startCommand, sendCommand, describeCommand]),
+)
+
+Command.runWith(root, { version: "0.1.0" })(extracted.args).pipe(
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain,
+)
+
+function toStartOptions(
+  config: {
+    readonly name: Option.Option<string>
+    readonly driver: Option.Option<string>
+    readonly campaign: Option.Option<string>
+    readonly seed: number
+    readonly caseIndex: Option.Option<number>
+    readonly count: Option.Option<number>
+    readonly concurrency: number
+    readonly visible: boolean
+    readonly detach: boolean
+    readonly dev: Option.Option<string>
+    readonly state: Option.Option<string>
+    readonly anchor: Option.Option<string>
+  },
+  commands: ReadonlyArray<DriveCommand>,
+  app: ReadonlyArray<string>,
+): StartOptions {
+  const driver = Option.getOrUndefined(config.driver)
+  const campaign = Option.getOrUndefined(config.campaign)
+  const visible = config.visible
+  const options = {
+    kind: "start" as const,
+    name: Option.getOrUndefined(config.name),
+    driver,
+    campaign,
+    seed: config.seed,
+    caseIndex: Option.getOrUndefined(config.caseIndex),
+    count: Option.getOrUndefined(config.count),
+    concurrency: config.concurrency,
+    visible,
+    detach: !visible && (config.detach || (driver === undefined && campaign === undefined && commands.length === 0)),
+    dev: Option.getOrUndefined(config.dev),
+    state: Option.getOrUndefined(config.state),
+    anchor: Option.getOrUndefined(config.anchor),
+    command: app,
+    commands,
+  }
+  assertExecutionMode(options.driver, options.campaign, commands)
+  if (options.dev !== undefined && app.length > 0) throw new Error("--dev cannot be combined with a command after --")
+  if (options.caseIndex !== undefined && options.campaign === undefined) throw new Error("--case requires --campaign")
+  if (options.visible && options.campaign !== undefined && options.caseIndex === undefined) {
+    throw new Error("visible campaign runs require --case")
+  }
+  if (config.detach && (options.driver !== undefined || options.campaign !== undefined || commands.length > 0)) {
+    throw new Error("--detach cannot be combined with --driver, --campaign, or command flags")
+  }
+  return options
+}
+
+function toSendOptions(
+  config: { readonly name: Option.Option<string>; readonly driver: Option.Option<string> },
+  commands: ReadonlyArray<DriveCommand>,
+  app: ReadonlyArray<string>,
+): SendOptions {
+  if (app.length > 0) throw new Error("send does not accept a command after --")
+  const options = {
+    kind: "send" as const,
+    name: Option.getOrUndefined(config.name),
+    driver: Option.getOrUndefined(config.driver),
+    commands,
+  }
+  assertExecutionMode(options.driver, undefined, commands)
+  return options
+}
+
+function assertExecutionMode(driver: string | undefined, campaign: string | undefined, commands: ReadonlyArray<DriveCommand>) {
+  const count = Number(driver !== undefined) + Number(campaign !== undefined) + Number(commands.length > 0)
+  if (count > 1) throw new Error("command flags, --driver, and --campaign are mutually exclusive")
+}
+
+function execute(task: () => Promise<void>) {
+  return Effect.tryPromise({ try: task, catch: (error) => error }).pipe(
+    Effect.catch((error) => Effect.sync(() => {
+      console.error(`error: ${error instanceof Error ? error.message : String(error)}`)
+      process.exitCode = 1
+    })),
+  )
+}
+
+function extract() {
+  try {
+    return extractCommands(process.argv.slice(2))
+  } catch (error) {
+    console.error(`opencode-drive: ${error instanceof Error ? error.message : String(error)}`)
+    return process.exit(1)
+  }
+}