opencode-drive 0.1.7 → 0.1.8

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.8",
   "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,6 +38,9 @@ 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"),
@@ -100,32 +103,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 +152,6 @@ const root = Command.make("opencode-drive").pipe(
     startCommand,
     sendCommand,
     screenshotCommand,
-    startRecordingCommand,
-    endRecordingCommand,
     listCommand,
     responsesCommand,
     logsCommand,
@@ -196,6 +171,7 @@ function toStartOptions(
     readonly name: string
     readonly daemon: boolean
     readonly visible: boolean
+    readonly record: boolean
     readonly dev: Option.Option<string>
     readonly state: Option.Option<string>
   },
@@ -210,6 +186,7 @@ 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,

package/src/cli/instance.ts

@@ -1,6 +1,7 @@
 import { mkdir, rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join, resolve } from "node:path"
+import { ensureMediaDirectory } from "./media.js"
 
 export interface LaunchOptions {
   readonly name: string
@@ -9,6 +10,7 @@ export interface LaunchOptions {
   readonly state?: string
   readonly scripted?: boolean
   readonly visible?: boolean
+  readonly record?: boolean
   readonly env?: Readonly<Record<string, string>>
 }
 
@@ -22,6 +24,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,10 +33,20 @@ 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`,
-  )
+  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 state = options.state
     ? resolve(options.state)
     : join(artifacts, "state")
@@ -124,6 +137,9 @@ export async function launchInstance(options: LaunchOptions) {
     artifacts,
     logs,
     endpoints,
+    get recording() {
+      return recording
+    },
     get child() {
       return child
     },
@@ -143,6 +159,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 +195,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

@@ -24,6 +24,7 @@ export async function runScript(
   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
@@ -31,7 +32,7 @@ export async function runScript(
   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) => {

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 ?? "",
     )
   ) {

package/src/cli/start.ts

@@ -1,6 +1,8 @@
 import { launchInstance } from "./instance.js"
 import { mkdir, rm } from "node:fs/promises"
 import { join } from "node:path"
+import { connectSimulation } from "../client/index.js"
+import { exportRecording } from "../recording/index.js"
 import { connectMockBackend } from "./mock-backend.js"
 import { createResponseSettings } from "./response-generator.js"
 import { runScript } from "./script.js"
@@ -27,6 +29,7 @@ export async function start(options: StartOptions) {
     state: options.state,
     scripted: options.script !== undefined,
     visible: options.visible,
+    record: options.record,
   })
   await register({
     version: 1,
@@ -43,13 +46,48 @@ export async function start(options: StartOptions) {
     await instance.stop()
     throw error
   })
-  const interrupt = () => void instance.stop()
   let completed = false
   let current: ReturnType<typeof run> | undefined
-  let restarting: Promise<void> | undefined
+  let restarting: Promise<string | undefined> | undefined
   let stopping = false
+  const screenshots: string[] = []
+  let driveReady = false
+  let recording: Promise<string | undefined> | undefined
+  const finishCurrentRecording = (onProgress?: (percent: number) => void) => {
+    if (!options.record || options.visible || !driveReady)
+      return Promise.resolve(undefined)
+    recording ??= finishRecording(instance, onProgress)
+    return recording
+  }
+  const interrupt = () => {
+    stopping = true
+    current?.abort.abort(new Error("opencode-drive interrupted"))
+    void finishCurrentRecording()
+      .catch((error) =>
+        process.stderr.write(`opencode-drive: failed to export recording: ${error}\n`),
+      )
+      .finally(() => instance.stop())
+  }
   process.once("SIGINT", interrupt)
   process.once("SIGTERM", interrupt)
+  const stopInstance = async (onProgress?: (percent: number) => void) => {
+    try {
+      const output = await finishCurrentRecording(onProgress)
+      return {
+        ...(output ? { recording: output } : {}),
+        screenshots: [...screenshots],
+      }
+    } finally {
+      stopping = true
+      current?.abort.abort(new Error("opencode-drive stopped"))
+      await instance.stop()
+    }
+  }
+  const completeScript = async () => {
+    completed = true
+    const result = await stopInstance()
+    for (const screenshot of result.screenshots) console.log(screenshot)
+  }
   let closeControl: (() => Promise<void>) | undefined
   try {
     closeControl = await listenControl(controlPath(options.name), {
@@ -57,34 +95,45 @@ export async function start(options: StartOptions) {
         if (restarting) return restarting
         restarting = (async () => {
           await markStarting(options.name, process.pid)
+          const output = await finishCurrentRecording()
           const previous = current
           previous?.abort.abort(new Error("script restarted"))
           await previous?.promise.catch(() => undefined)
+          driveReady = false
           await instance.restart()
-          current = run(options, instance, responses)
+          recording = undefined
+          current = run(options, instance, responses, (path) => screenshots.push(path))
           await current.ready
+          driveReady = true
           await markReady(options.name, process.pid)
+          return output
         })().finally(() => {
           restarting = undefined
         })
         return restarting
       },
-      stop: async () => {
-        stopping = true
-        current?.abort.abort(new Error("opencode-drive stopped"))
-        await instance.stop()
-      },
+      stop: stopInstance,
       responses: async (input) => {
         if (options.script)
           throw new Error("responses are unavailable when --script owns the simulation backend")
         return responses.update(input)
       },
     })
-    current = run(options, instance, responses)
+    current = run(options, instance, responses, (path) => screenshots.push(path))
     await current.ready
+    driveReady = true
     await markReady(options.name, process.pid)
     if (options.visible) {
-      const status = await instance.wait()
+      const result = options.script
+        ? await Promise.race([
+            current.promise.then(() => ({ script: true as const })),
+            instance.wait().then((status) => ({ script: false as const, status })),
+          ])
+        : { script: false as const, status: await instance.wait() }
+      if (result.script) {
+        await completeScript()
+      }
+      const status = result.script ? await instance.wait() : result.status
       if (status !== 0 && !stopping) process.exitCode = status
       return
     }
@@ -97,6 +146,10 @@ export async function start(options: StartOptions) {
         continue
       }
       if (active !== current) continue
+      if (options.script) {
+        await completeScript()
+        break
+      }
       completed = true
       break
     }
@@ -104,12 +157,43 @@ export async function start(options: StartOptions) {
     process.off("SIGINT", interrupt)
     process.off("SIGTERM", interrupt)
     current?.abort.abort(new Error("opencode-drive stopped"))
+    const recordingPath = await finishCurrentRecording().catch((error) => {
+      process.stderr.write(`opencode-drive: failed to export recording: ${error}\n`)
+      return undefined
+    })
     await closeControl?.()
     await instance.stop()
     await unregister(options.name, process.pid)
     if (options.script && !options.visible)
       report(instance, completed ? "completed" : undefined)
+    if (options.script && recordingPath)
+      console.error(`opencode-drive: recording ${recordingPath}`)
+  }
+}
+
+async function finishRecording(
+  instance: Awaited<ReturnType<typeof launchInstance>>,
+  onProgress?: (percent: number) => void,
+) {
+  const expected = instance.recording
+  if (!expected) throw new Error("recording was not enabled for this instance")
+  let timeline: string
+  if (instance.child.exitCode !== null) {
+    timeline = expected.timeline
+  } else {
+    const ui = await connectSimulation({ url: instance.endpoints.ui, timeout: 60_000 })
+    try {
+      timeline = await ui.finishRecording()
+    } finally {
+      ui.close()
+    }
   }
+  if (timeline !== expected.timeline)
+    throw new Error(`OpenCode returned an unexpected recording path: ${timeline}`)
+  if (!(await Bun.file(timeline).exists()))
+    throw new Error(`OpenCode recording timeline was not created: ${timeline}`)
+  await exportRecording(timeline, expected.video, { onProgress })
+  return expected.video
 }
 
 async function startDetached(options: StartOptions) {
@@ -130,6 +214,7 @@ async function startDetached(options: StartOptions) {
       ...(options.script ? ["--script", options.script] : []),
       ...(options.dev ? ["--dev", options.dev] : []),
       ...(options.state ? ["--state", options.state] : []),
+      ...(options.record ? ["--record"] : []),
       ...(options.command.length ? ["--", ...options.command] : []),
     ],
     {
@@ -176,6 +261,7 @@ function run(
   options: StartOptions,
   instance: Awaited<ReturnType<typeof launchInstance>>,
   responses: ReturnType<typeof createResponseSettings>,
+  onScreenshot: (path: string) => void,
 ) {
   const abort = new AbortController()
   const child = instance.child
@@ -194,18 +280,21 @@ function run(
           instance.artifacts,
           instance.endpoints,
           abort.signal,
+          onScreenshot,
         )
         ready()
-        await script
         if (options.visible) {
-          await Promise.race([
-            child.exited,
-            new Promise<void>((resolve) =>
-              abort.signal.addEventListener("abort", () => resolve(), {
-                once: true,
-              }),
-            ),
-          ])
+          await script
+          return
+        }
+        const result = await Promise.race([
+          script.then(() => ({ script: true as const })),
+          child.exited.then((status) => ({ script: false as const, status })),
+        ])
+        if (!result.script) {
+          abort.abort(new Error(`OpenCode exited with status ${result.status}`))
+          await script.catch(() => undefined)
+          if (result.status !== 0) process.exitCode = result.status
         }
         return
       }