opencode-drive 0.1.7 → 0.1.9

package/src/cli/start.ts

@@ -1,9 +1,12 @@
 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"
+import { loadScript, runScript } from "./script.js"
+import type { DriveScript } from "./script.js"
 import { listenControl } from "./control.js"
 import {
   controlPath,
@@ -19,14 +22,16 @@ import type { StartOptions } from "./types.js"
 export async function start(options: StartOptions) {
   if (!options.visible && !options.script && !options.daemon)
     return startDetached(options)
+  const script = options.script ? await loadScript(options.script) : undefined
   const responses = createResponseSettings()
   const instance = await launchInstance({
     name: options.name,
     command: options.command,
     dev: options.dev,
-    state: options.state,
     scripted: options.script !== undefined,
     visible: options.visible,
+    record: options.record,
+    setup: script?.setup,
   })
   await register({
     version: 1,
@@ -43,13 +48,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 +97,49 @@ 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, script?.run, (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, script?.run, (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 +152,10 @@ export async function start(options: StartOptions) {
         continue
       }
       if (active !== current) continue
+      if (options.script) {
+        await completeScript()
+        break
+      }
       completed = true
       break
     }
@@ -104,14 +163,45 @@ 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) {
   const existing = await resolveInstance(options.name, { ready: false }).catch(() => undefined)
   if (existing)
@@ -129,7 +219,7 @@ async function startDetached(options: StartOptions) {
       options.name,
       ...(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 +266,8 @@ function run(
   options: StartOptions,
   instance: Awaited<ReturnType<typeof launchInstance>>,
   responses: ReturnType<typeof createResponseSettings>,
+  driveScript: DriveScript | undefined,
+  onScreenshot: (path: string) => void,
 ) {
   const abort = new AbortController()
   const child = instance.child
@@ -188,24 +280,27 @@ function run(
     ready: readiness,
     promise: (async () => {
       await instance.waitForDrive("both")
-      if (options.script) {
+      if (driveScript) {
         const script = runScript(
-          options.script,
+          driveScript,
           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
       }

package/src/cli/stop.ts

@@ -1,10 +1,12 @@
-import { request } from "./control.js"
+import { requestStop } from "./control.js"
 import { manifestPath, resolveInstance } from "./registry.js"
 
 export async function stop(name?: string) {
   const manifest = await resolveInstance(name)
-  await request(manifest.control, "stop")
-  const deadline = Date.now() + 10_000
+  const result = await requestStop(manifest.control, (percent) => {
+    console.error(`Rendering video: ${percent}%`)
+  })
+  const deadline = Date.now() + 5 * 60_000
   while (Date.now() < deadline) {
     const current: unknown = await Bun.file(manifestPath(manifest.name))
       .json()
@@ -15,7 +17,12 @@ export async function stop(name?: string) {
       !("pid" in current) ||
       current.pid !== manifest.pid
     ) {
-      console.log("success")
+      for (const screenshot of result.screenshots) console.log(screenshot)
+      if (result.recording) {
+        console.error(`Video successfully created: ${result.recording}`)
+      } else if (result.screenshots.length === 0) {
+        console.log("success")
+      }
       return
     }
     await Bun.sleep(25)

package/src/cli/types.ts

@@ -9,8 +9,8 @@ export interface StartOptions {
   readonly daemon: boolean
   readonly script?: string
   readonly visible: boolean
+  readonly record: boolean
   readonly dev?: string
-  readonly state?: string
   readonly command: ReadonlyArray<string>
 }
 

package/src/client/client.ts

@@ -4,20 +4,16 @@ const defaultPort = 40900
 
 type Methods = {
   readonly "ui.screenshot": {
-    readonly params: undefined
+    readonly params: Frontend.ScreenshotParams | undefined
     readonly result: Frontend.Screenshot
   }
   readonly "ui.state": {
     readonly params: undefined
     readonly result: Frontend.State
   }
-  readonly "ui.start-record": {
-    readonly params: undefined
-    readonly result: Frontend.StartRecord
-  }
-  readonly "ui.end-record": {
+  readonly "ui.recording.finish": {
     readonly params: undefined
-    readonly result: Frontend.EndRecord
+    readonly result: Frontend.RecordingFinish
   }
   readonly "ui.type": {
     readonly params: Frontend.TypeParams
@@ -69,6 +65,7 @@ export interface SimulationClientOptions {
   readonly portAttempts?: number
   /** Per-call timeout in milliseconds. Defaults to 30_000. */
   readonly timeout?: number
+  readonly onScreenshot?: (path: string) => void
 }
 
 export class SimulationError extends Error {
@@ -93,13 +90,20 @@ export class SimulationClient {
 
   private readonly socket: WebSocket
   private readonly timeout: number
+  private readonly onScreenshot?: (path: string) => void
   private nextId = 1
   private readonly pending = new Map<number, Waiter>()
 
-  private constructor(socket: WebSocket, url: string, timeout: number) {
+  private constructor(
+    socket: WebSocket,
+    url: string,
+    timeout: number,
+    onScreenshot?: (path: string) => void,
+  ) {
     this.socket = socket
     this.url = url
     this.timeout = timeout
+    this.onScreenshot = onScreenshot
     socket.addEventListener("message", (event) =>
       this.onMessage(String(event.data)),
     )
@@ -116,14 +120,24 @@ export class SimulationClient {
   ): Promise<SimulationClient> {
     const timeout = options?.timeout ?? 30_000
     if (options?.url !== undefined) {
-      return new SimulationClient(await open(options.url), options.url, timeout)
+      return new SimulationClient(
+        await open(options.url),
+        options.url,
+        timeout,
+        options.onScreenshot,
+      )
     }
     const first = options?.port ?? defaultPort
     const attempts = options?.portAttempts ?? 10
     for (let offset = 0; offset < attempts; offset++) {
       const url = `ws://127.0.0.1:${first + offset}`
       try {
-        return new SimulationClient(await open(url), url, timeout)
+        return new SimulationClient(
+          await open(url),
+          url,
+          timeout,
+          options?.onScreenshot,
+        )
       } catch {
         // occupied by something else or nothing listening; try the next port
       }
@@ -170,16 +184,17 @@ export class SimulationClient {
     return this.call("ui.state")
   }
 
-  screenshot(): Promise<Frontend.Screenshot> {
-    return this.call("ui.screenshot")
-  }
-
-  startRecord(): Promise<Frontend.StartRecord> {
-    return this.call("ui.start-record")
+  async screenshot(name?: string): Promise<Frontend.Screenshot> {
+    const path = await this.call(
+      "ui.screenshot",
+      name === undefined ? undefined : { name },
+    )
+    this.onScreenshot?.(path)
+    return path
   }
 
-  endRecord(): Promise<Frontend.EndRecord> {
-    return this.call("ui.end-record")
+  finishRecording(): Promise<Frontend.RecordingFinish> {
+    return this.call("ui.recording.finish")
   }
 
   /** Executes one user-level action and returns the post-action state. */

package/src/client/protocol.ts

@@ -111,11 +111,14 @@ export namespace Frontend {
   export const Screenshot = Schema.String
   export type Screenshot = Schema.Schema.Type<typeof Screenshot>
 
-  export const StartRecord = Schema.Struct({ recording: Schema.Literal(true) })
-  export interface StartRecord extends Schema.Schema.Type<typeof StartRecord> {}
+  export const RecordingFinish = Schema.String
+  export type RecordingFinish = Schema.Schema.Type<typeof RecordingFinish>
 
-  export const EndRecord = Schema.String
-  export type EndRecord = Schema.Schema.Type<typeof EndRecord>
+  export const ScreenshotParams = Schema.Struct({
+    name: Schema.optional(Schema.String),
+  })
+  export interface ScreenshotParams
+    extends Schema.Schema.Type<typeof ScreenshotParams> {}
 
   export const TypeParams = Schema.Struct({ text: Schema.String })
   export interface TypeParams extends Schema.Schema.Type<typeof TypeParams> {}
@@ -169,13 +172,12 @@ export namespace Frontend {
     }),
     Schema.Struct({
       ...JsonRpc.RequestFields,
-      method: Schema.Literals([
-        "ui.enter",
-        "ui.screenshot",
-        "ui.state",
-        "ui.start-record",
-        "ui.end-record",
-      ]),
+      method: Schema.Literal("ui.screenshot"),
+      params: Schema.optional(ScreenshotParams),
+    }),
+    Schema.Struct({
+      ...JsonRpc.RequestFields,
+      method: Schema.Literals(["ui.enter", "ui.state", "ui.recording.finish"]),
     }),
   ])
   export type Request = Schema.Schema.Type<typeof Request>

package/src/experimental/reproduce-stale-exploring-empty.ts

@@ -0,0 +1,102 @@
+import { join } from "node:path"
+import { defineScript } from "../index.js"
+
+export default defineScript(async ({ artifacts, backend, ui }) => {
+  const completed = Array.from({ length: 3 }, () => Promise.withResolvers<void>())
+  let turn = 0
+
+  await backend.attach(async (request) => {
+    if (isTitleRequest(request.body)) {
+      await backend.chunk(request.id, [{ type: "textDelta", text: "Stale exploring reproduction" }])
+      await backend.finish(request.id)
+      return
+    }
+    const current = turn++
+    if (current === 0) {
+      await backend.chunk(request.id, [
+        {
+          type: "toolCall",
+          index: 0,
+          id: "call_read",
+          name: "read",
+          input: { filePath: join(artifacts, "files", "src", "garden.js") },
+        },
+      ])
+      await backend.finish(request.id, "tool-calls")
+      return
+    }
+    if (current === 1) {
+      await backend.finish(request.id, "tool-calls")
+      completed[0]?.resolve()
+      return
+    }
+    const response = current === 2 ? "The file exports a small greeting function." : "Confirmed again with no more tools."
+    await backend.chunk(request.id, [{ type: "textDelta", text: response }])
+    await backend.finish(request.id)
+    completed[current - 1]?.resolve()
+  })
+
+  const prompts = [
+    "Read src/garden.js, then tell me what it contains.",
+    "Now inspect that file one more time.",
+    "Finally, verify the same file again.",
+  ]
+  for (const [index, prompt] of prompts.entries()) {
+    if (index === 0) await ui.typeText(prompt)
+    else await typeSlowly(ui, prompt)
+    await ui.pressEnter()
+    await withTimeout(
+      completed[index]!.promise,
+      30_000,
+      `timed out waiting for empty continuation ${index + 1}`,
+    )
+    await waitForEditor(ui)
+    await Bun.sleep(500)
+    await ui.screenshot(`stale-exploring-${index + 1}`)
+  }
+})
+
+async function withTimeout(promise: Promise<void>, timeout: number, message: string) {
+  const expired = Promise.withResolvers<never>()
+  const timer = setTimeout(() => expired.reject(new Error(message)), timeout)
+  try {
+    await Promise.race([promise, expired.promise])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function typeSlowly(
+  ui: Parameters<Parameters<typeof defineScript>[0]>[0]["ui"],
+  text: string,
+) {
+  for (const char of text) {
+    await ui.typeText(char)
+    await Bun.sleep(55)
+  }
+}
+
+async function waitForEditor(
+  ui: Parameters<Parameters<typeof defineScript>[0]>[0]["ui"],
+) {
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    if ((await ui.state()).focused.editor) return
+    await Bun.sleep(50)
+  }
+  throw new Error("timed out waiting for the session to become idle")
+}
+
+function isTitleRequest(body: unknown) {
+  if (typeof body !== "object" || body === null || !("messages" in body)) return false
+  const messages = body.messages
+  if (!Array.isArray(messages)) return false
+  return messages.some(
+    (message) =>
+      typeof message === "object" &&
+      message !== null &&
+      "content" in message &&
+      typeof message.content === "string" &&
+      message.content.includes("You are a title generator"),
+  )
+}

package/src/index.ts

@@ -1,3 +1,8 @@
 export * from "./client/index.js"
 export { defineScript } from "./cli/script.js"
-export type { DriveScript, ScriptContext } from "./cli/script.js"
+export type {
+  DriveScript,
+  DriveScriptSetup,
+  ScriptContext,
+  ScriptSetupContext,
+} from "./cli/script.js"

package/src/recording/decode.ts

@@ -0,0 +1,93 @@
+import { createReadStream } from "node:fs"
+import type { TimelineHeader, TimelineOutput, TimelineRecord } from "./types.js"
+
+function fail(line: number, message: string): never {
+  throw new Error(`Invalid recording timeline at line ${line}: ${message}`)
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: string[]) {
+  const actual = Object.keys(value).sort()
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
+}
+
+function positiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+}
+
+function nonnegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+}
+
+function canonicalBase64(value: string) {
+  if (value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return false
+  }
+  return Buffer.from(value, "base64").toString("base64") === value
+}
+
+function parseRecord(text: string, line: number, first: boolean, previousAt: number): TimelineRecord {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    fail(line, "line is not valid JSON")
+  }
+  if (!isObject(value)) fail(line, "record must be an object")
+
+  if (first) {
+    if (!hasExactKeys(value, ["cols", "encoding", "rows", "type", "version"])) fail(line, "invalid header fields")
+    if (value.type !== "header" || value.version !== 1 || value.encoding !== "base64") {
+      fail(line, "unsupported or missing header")
+    }
+    if (!positiveInteger(value.cols) || !positiveInteger(value.rows)) fail(line, "cols and rows must be positive integers")
+    return { type: "header", version: 1, cols: value.cols, rows: value.rows, encoding: "base64" } satisfies TimelineHeader
+  }
+
+  if (!hasExactKeys(value, ["at_ms", "data", "type"]) || value.type !== "output") fail(line, "invalid output fields")
+  if (!nonnegativeInteger(value.at_ms)) fail(line, "at_ms must be a nonnegative integer")
+  if (value.at_ms < previousAt) fail(line, "output timestamps must be nondecreasing")
+  if (typeof value.data !== "string" || !canonicalBase64(value.data)) fail(line, "data must be canonical base64")
+  return { type: "output", at_ms: value.at_ms, data: value.data } satisfies TimelineOutput
+}
+
+/** Decodes and validates a timeline without loading the complete file into memory. */
+export async function* decodeTimeline(path: string): AsyncGenerator<TimelineRecord> {
+  const decoder = new TextDecoder("utf-8", { fatal: true })
+  let buffered = ""
+  let line = 0
+  let records = 0
+  let previousAt = -1
+
+  const consume = (raw: string) => {
+    line++
+    const text = raw.endsWith("\r") ? raw.slice(0, -1) : raw
+    if (text.length === 0) fail(line, "empty lines are not allowed")
+    const record = parseRecord(text, line, records === 0, previousAt)
+    records++
+    if (record.type === "output") previousAt = record.at_ms
+    return record
+  }
+
+  try {
+    for await (const chunk of createReadStream(path)) {
+      buffered += decoder.decode(chunk, { stream: true })
+      let newline: number
+      while ((newline = buffered.indexOf("\n")) !== -1) {
+        const raw = buffered.slice(0, newline)
+        buffered = buffered.slice(newline + 1)
+        yield consume(raw)
+      }
+    }
+    buffered += decoder.decode()
+  } catch (error) {
+    if (error instanceof TypeError) fail(line + 1, "file is not valid UTF-8")
+    throw error
+  }
+
+  if (buffered.length > 0) yield consume(buffered)
+  if (records === 0) fail(1, "missing header")
+}