opencode-drive 0.1.7 → 0.1.9

package/README.md

@@ -22,7 +22,9 @@ If you installed the skill file, OpenCode will be able to see and interact with
 
 ## Using with agents
 
-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.
+Install the skill file above and ask the agent to test various flows with the app. Start with `--record` when you want a video; `opencode-drive stop` then exports the complete session and prints its path.
+
+Screenshots and videos are written to `<system temp>/opencode-drive/output` with unique filenames. Set `OPENCODE_DRIVE_MEDIA_DIR` to use a different directory.
 
 ## UI development
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-drive",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Drive real and simulated OpenCode instances",
   "license": "MIT",
   "type": "module",
@@ -12,26 +12,32 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
-    "./experimental": "./src/experimental/index.ts"
+    "./experimental": "./src/experimental/index.ts",
+    "./recording": "./src/recording/index.ts"
   },
   "files": [
     "bin/opencode-drive",
     "src/cli",
     "src/client",
     "src/experimental",
+    "src/recording",
     "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",
+    "test": "bun test test",
     "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",
+    "@fontsource/adwaita-mono": "5.2.1",
+    "@napi-rs/canvas": "1.0.2",
+    "@wterm/core": "0.3.0",
+    "@wterm/ghostty": "0.3.0",
     "effect": "4.0.0-beta.93"
   },
   "devDependencies": {

package/src/cli/commands.ts

@@ -22,10 +22,9 @@ export const commandInfo = {
     value: false,
     description: "Return focus, elements, and available UI actions",
   },
-  "ui.start-record": { value: false, description: "Start recording the UI" },
-  "ui.end-record": {
+  "ui.recording.finish": {
     value: false,
-    description: "Stop recording and return the recording path",
+    description: "Finish recording and return the timeline path",
   },
 } as const
 
@@ -38,8 +37,7 @@ export function commandAcceptsValue(operation: string) {
   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
+  if (operation === "ui.recording.finish") return commandInfo[operation].value
   throw new Error(`unknown drive command "${operation}"`)
 }
 
@@ -142,10 +140,8 @@ async function execute(
       return ui.screenshot()
     case "ui.state":
       return ui.state()
-    case "ui.start-record":
-      return ui.startRecord()
-    case "ui.end-record":
-      return ui.endRecord()
+    case "ui.recording.finish":
+      return ui.finishRecording()
   }
   throw new Error(`unknown drive command "${command.operation}"`)
 }

package/src/cli/control.ts

@@ -5,11 +5,16 @@ import type {
   ResponseUpdate,
 } from "./response-generator.js"
 
+export interface StopResult {
+  readonly recording?: string
+  readonly screenshots: ReadonlyArray<string>
+}
+
 export async function listenControl(
   path: string,
   handlers: {
-    readonly restart: () => Promise<void>
-    readonly stop: () => Promise<void>
+    readonly restart: () => Promise<string | undefined>
+    readonly stop: (onProgress: (percent: number) => void) => Promise<StopResult>
     readonly responses: (
       input: ResponseUpdate,
     ) => Promise<ResponseConfiguration>
@@ -27,7 +32,8 @@ export async function listenControl(
       }
       if (!buffer.includes("\n")) return
       socket.removeAllListeners("data")
-      void handle(buffer.slice(0, buffer.indexOf("\n"))).then(
+      const progress = (percent: number) => socket.write(`progress ${percent}\n`)
+      void handle(buffer.slice(0, buffer.indexOf("\n")), progress).then(
         (result) =>
           socket.end(
             `success${result === undefined ? "" : ` ${JSON.stringify(result)}`}\n`,
@@ -39,9 +45,9 @@ export async function listenControl(
       )
     })
   })
-  const handle = async (input: string) => {
+  const handle = async (input: string, onProgress: (percent: number) => void) => {
     if (input === "restart") return handlers.restart()
-    if (input === "stop") return handlers.stop()
+    if (input === "stop") return handlers.stop(onProgress)
     if (input === "responses") return handlers.responses({})
     if (input.startsWith("responses "))
       return handlers.responses(parseResponseUpdate(input.slice("responses ".length)))
@@ -54,9 +60,28 @@ export async function listenControl(
   }
 }
 
-export async function request(path: string, command: "restart" | "stop") {
+export async function request(
+  path: string,
+  command: "restart",
+) {
   const response = await send(path, command)
-  if (response !== "success") throw responseError(response)
+  if (response === "success") return undefined
+  if (!response.startsWith("success ")) throw responseError(response)
+  const value: unknown = JSON.parse(response.slice("success ".length))
+  if (typeof value !== "string")
+    throw new Error("instance returned an invalid recording path")
+  return value
+}
+
+export async function requestStop(
+  path: string,
+  onProgress?: (percent: number) => void,
+) {
+  const response = await send(path, "stop", onProgress)
+  if (!response.startsWith("success ")) throw responseError(response)
+  const value: unknown = JSON.parse(response.slice("success ".length))
+  if (!isStopResult(value)) throw new Error("instance returned an invalid stop result")
+  return value
 }
 
 export async function requestResponses(path: string, input: ResponseUpdate) {
@@ -73,22 +98,34 @@ export async function requestResponses(path: string, input: ResponseUpdate) {
   return value
 }
 
-function send(path: string, command: string) {
+function send(path: string, command: string, onProgress?: (percent: number) => void) {
   return new Promise<string>((resolve, reject) => {
     const socket = connect(path)
     let response = ""
+    let buffer = ""
     const timer = setTimeout(() => {
       socket.destroy()
       reject(new Error("instance control request timed out"))
-    }, 10_000)
+    }, 5 * 60_000)
     socket.setEncoding("utf8")
     socket.on("connect", () => socket.write(`${command}\n`))
     socket.on("data", (data) => {
-      response += data
+      buffer += data
+      while (buffer.includes("\n")) {
+        const index = buffer.indexOf("\n")
+        const line = buffer.slice(0, index)
+        buffer = buffer.slice(index + 1)
+        if (line.startsWith("progress ")) {
+          const percent = Number(line.slice("progress ".length))
+          if (Number.isInteger(percent)) onProgress?.(percent)
+          continue
+        }
+        response += `${line}\n`
+      }
     })
     socket.on("end", () => {
       clearTimeout(timer)
-      resolve(response.trim())
+      resolve(`${response}${buffer}`.trim())
     })
     socket.on("error", () => {
       clearTimeout(timer)
@@ -123,6 +160,13 @@ function isResponseConfiguration(
   return "tools" in value && stringArrayValue(value.tools)
 }
 
+function isStopResult(value: unknown): value is StopResult {
+  if (typeof value !== "object" || value === null) return false
+  if (!("screenshots" in value) || !stringArrayValue(value.screenshots))
+    return false
+  return !("recording" in value) || typeof value.recording === "string"
+}
+
 function stringArrayValue(value: unknown) {
   return Array.isArray(value) && value.every((item) => typeof item === "string")
 }

package/src/cli/index.ts

@@ -38,14 +38,13 @@ const startCommand = Command.make(
     visible: Flag.boolean("visible").pipe(
       Flag.withDescription("Show OpenCode in the terminal"),
     ),
+    record: Flag.boolean("record").pipe(
+      Flag.withDescription("Record the complete headless session and export it on stop"),
+    ),
     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/"),
-    ),
   },
   (config) =>
     execute(() =>
@@ -100,32 +99,6 @@ const screenshotCommand = Command.make("screenshot", { name }, (config) =>
   ),
 ).pipe(Command.withDescription("Take a screenshot and print its path"))
 
-const startRecordingCommand = Command.make(
-  "record-start",
-  { name },
-  (config) =>
-    execute(() =>
-      send({
-        kind: "send",
-        name: Option.getOrUndefined(config.name),
-        commands: [{ operation: "ui.start-record" }],
-      }),
-    ),
-).pipe(Command.withDescription("Start recording the UI"))
-
-const endRecordingCommand = Command.make(
-  "record-end",
-  { name },
-  (config) =>
-    execute(() =>
-      send({
-        kind: "send",
-        name: Option.getOrUndefined(config.name),
-        commands: [{ operation: "ui.end-record" }],
-      }),
-    ),
-).pipe(Command.withDescription("Stop recording and print its path"))
-
 const restartCommand = Command.make("restart", { name }, (config) =>
   execute(() => restart(Option.getOrUndefined(config.name))),
 ).pipe(
@@ -175,8 +148,6 @@ const root = Command.make("opencode-drive").pipe(
     startCommand,
     sendCommand,
     screenshotCommand,
-    startRecordingCommand,
-    endRecordingCommand,
     listCommand,
     responsesCommand,
     logsCommand,
@@ -196,8 +167,8 @@ function toStartOptions(
     readonly name: string
     readonly daemon: boolean
     readonly visible: boolean
+    readonly record: boolean
     readonly dev: Option.Option<string>
-    readonly state: Option.Option<string>
   },
   commands: ReadonlyArray<DriveCommand>,
   app: ReadonlyArray<string>,
@@ -210,8 +181,8 @@ function toStartOptions(
     daemon: config.daemon,
     script: Option.getOrUndefined(config.script),
     visible: config.visible,
+    record: config.record,
     dev: Option.getOrUndefined(config.dev),
-    state: Option.getOrUndefined(config.state),
     command: app,
   }
   if (options.dev !== undefined && app.length > 0)

package/src/cli/instance.ts

@@ -1,15 +1,18 @@
-import { mkdir, rm } from "node:fs/promises"
+import { mkdir } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join, resolve } from "node:path"
+import { ensureMediaDirectory } from "./media.js"
+import type { DriveScriptSetup } from "./script.js"
 
 export interface LaunchOptions {
   readonly name: string
   readonly command?: ReadonlyArray<string>
   readonly dev?: string
-  readonly state?: string
   readonly scripted?: boolean
   readonly visible?: boolean
+  readonly record?: boolean
   readonly env?: Readonly<Record<string, string>>
+  readonly setup?: DriveScriptSetup
 }
 
 export async function launchInstance(options: LaunchOptions) {
@@ -22,6 +25,7 @@ export async function launchInstance(options: LaunchOptions) {
     backend: `ws://127.0.0.1:${await freePort()}`,
   }
   const drive = join(artifacts, "drive")
+  const media = await ensureMediaDirectory()
   await Promise.all([
     mkdir(logs, { recursive: true }),
     mkdir(drive, { recursive: true }),
@@ -30,66 +34,71 @@ 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`,
-  )
-  const state = options.state
-    ? resolve(options.state)
-    : join(artifacts, "state")
-  if (!options.state) {
-    await rm(state, { recursive: true, force: true })
-    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 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 },
+  let recording = options.record ? recordingPaths(media) : undefined
+  const writeDriveManifest = () =>
+    Bun.write(
+      join(drive, `${options.name}.json`),
+      `${JSON.stringify(
+        {
+          endpoints,
+          ...(recording ? { recording: { timeline: recording.timeline } } : {}),
+        },
+        undefined,
+        2,
+      )}\n`,
+    )
+  await writeDriveManifest()
+  const files = join(artifacts, "files")
+  await Promise.all([
+    mkdir(join(files, ".git"), { recursive: true }),
+    mkdir(join(files, ".opencode"), { recursive: true }),
+    mkdir(join(files, "src"), { recursive: true }),
+  ])
+  await Promise.all([
+    Bun.write(
+      join(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 },
                 },
               },
             },
           },
-          undefined,
-          2,
-        )}\n`,
-      ),
-      Bun.write(
-        join(state, "files", "src", "garden.js"),
-        'export function greet(name) {\n  return `Hello, ${name}.`\n}\n',
-      ),
-    ])
-  }
+        },
+        undefined,
+        2,
+      )}\n`,
+    ),
+    Bun.write(
+      join(files, "src", "garden.js"),
+      'export function greet(name) {\n  return `Hello, ${name}.`\n}\n',
+    ),
+  ])
+  await options.setup?.({ directory: files })
   const environment = cleanEnv({
     ...process.env,
     ...options.env,
     OPENCODE_SIMULATE: "1",
-    OPENCODE_SIMULATE_STATE: state,
     DRIVE_REGISTRY_DIR: drive,
     OPENCODE_DRIVE: options.name,
     OPENCODE_DRIVE_RENDERER: options.visible ? "visible" : "headless",
-    OPENCODE_CONFIG_DIR: join(artifacts, ".opencode"),
+    OPENCODE_CONFIG_DIR: join(files, ".opencode"),
     OPENCODE_DB: ":memory:",
     OPENCODE_LOG_LEVEL: !options.visible
       ? "INFO"
@@ -101,13 +110,13 @@ export async function launchInstance(options: LaunchOptions) {
     XDG_STATE_HOME: join(artifacts, "home", ".local", "state"),
   })
   const command = options.dev
-    ? await prepareDev(artifacts, options.dev)
+    ? await prepareDev(files, options.dev)
     : options.command?.length
       ? [...options.command]
       : ["opencode2"]
   const spawn = () =>
     Bun.spawn(command, {
-      cwd: artifacts,
+      cwd: files,
       env: environment,
       stdin: options.visible ? "inherit" : "ignore",
       stdout: !options.visible
@@ -124,6 +133,9 @@ export async function launchInstance(options: LaunchOptions) {
     artifacts,
     logs,
     endpoints,
+    get recording() {
+      return recording
+    },
     get child() {
       return child
     },
@@ -143,6 +155,8 @@ export async function launchInstance(options: LaunchOptions) {
       if (restarting) return restarting
       restarting = (async () => {
         await terminate(child)
+        recording = options.record ? recordingPaths(media) : undefined
+        await writeDriveManifest()
         child = spawn()
         await Promise.all([
           waitForWebSocket(endpoints.ui, child.exited, 60_000),
@@ -177,6 +191,14 @@ export async function launchInstance(options: LaunchOptions) {
   }
 }
 
+function recordingPaths(directory: string) {
+  const id = crypto.randomUUID()
+  return {
+    timeline: join(directory, `recording-${id}.jsonl`),
+    video: join(directory, `recording-${id}.mp4`),
+  }
+}
+
 async function terminate(child: Bun.Subprocess) {
   if (child.exitCode !== null) return
   child.kill("SIGTERM")

package/src/cli/media.ts

@@ -0,0 +1,16 @@
+import { mkdir } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+
+export function mediaDirectory() {
+  return resolve(
+    process.env.OPENCODE_DRIVE_MEDIA_DIR ??
+      join(tmpdir(), "opencode-drive", "output"),
+  )
+}
+
+export async function ensureMediaDirectory() {
+  const directory = mediaDirectory()
+  await mkdir(directory, { recursive: true })
+  return directory
+}

package/src/cli/restart.ts

@@ -2,6 +2,6 @@ import { request } from "./control.js"
 import { resolveInstance } from "./registry.js"
 
 export async function restart(name?: string) {
-  await request((await resolveInstance(name)).control, "restart")
-  console.log("success")
+  const recording = await request((await resolveInstance(name)).control, "restart")
+  console.log(recording ?? "success")
 }

package/src/cli/script.ts

@@ -15,23 +15,44 @@ export interface ScriptContext {
 
 export type DriveScript = (context: ScriptContext) => void | Promise<void>
 
+export interface ScriptSetupContext {
+  readonly directory: string
+}
+
+export type DriveScriptSetup = (
+  context: ScriptSetupContext,
+) => void | Promise<void>
+
+export interface LoadedDriveScript {
+  readonly run: DriveScript
+  readonly setup?: DriveScriptSetup
+}
+
 export function defineScript(script: DriveScript) {
   return script
 }
 
+export async function loadScript(file: string): Promise<LoadedDriveScript> {
+  const module: { readonly default?: unknown; readonly setup?: unknown } =
+    await import(pathToFileURL(resolve(file)).href)
+  if (!isDriveScript(module.default))
+    throw new Error("script must default-export a function")
+  if (module.setup !== undefined && !isDriveScriptSetup(module.setup))
+    throw new Error("script setup export must be a function")
+  return {
+    run: module.default,
+    ...(module.setup === undefined ? {} : { setup: module.setup }),
+  }
+}
+
 export async function runScript(
-  file: string,
+  script: DriveScript,
   artifacts: string,
   endpoints: { readonly ui: string; readonly backend: string },
   signal: AbortSignal,
+  onScreenshot?: (path: string) => void,
 ) {
-  const module: { readonly default?: unknown } = await import(
-    pathToFileURL(resolve(file)).href
-  )
-  const script = module.default
-  if (!isDriveScript(script))
-    throw new Error("script must default-export a function")
-  const ui = await connectSimulation({ url: endpoints.ui })
+  const ui = await connectSimulation({ url: endpoints.ui, onScreenshot })
   const backend = await connectBackendSimulation({
     url: endpoints.backend,
   }).catch((error) => {
@@ -75,3 +96,7 @@ async function waitForEditor(ui: SimulationClient, signal: AbortSignal) {
 function isDriveScript(value: unknown): value is DriveScript {
   return typeof value === "function"
 }
+
+function isDriveScriptSetup(value: unknown): value is DriveScriptSetup {
+  return typeof value === "function"
+}

package/src/cli/send.ts

@@ -5,13 +5,11 @@ import { resolveInstance } from "./registry.js"
 export async function send(options: SendOptions) {
   if (options.commands.length === 0)
     throw new Error("send requires at least one --command.ui.* flag")
-  const result = await executeCommands(
-    (await resolveInstance(options.name)).endpoints.ui,
-    options.commands,
-  )
+  const instance = await resolveInstance(options.name)
+  const result = await executeCommands(instance.endpoints.ui, options.commands)
   if (
     options.commands.length === 1 &&
-    ["ui.screenshot", "ui.end-record"].includes(
+    ["ui.screenshot", "ui.recording.finish"].includes(
       options.commands[0]?.operation ?? "",
     )
   ) {
@@ -20,7 +18,7 @@ export async function send(options: SendOptions) {
   }
   if (
     options.commands.length === 1 &&
-    ["ui.state", "ui.start-record"].includes(
+    ["ui.state"].includes(
       options.commands[0]?.operation ?? "",
     )
   ) {