opencode-drive 0.1.0

package/src/experimental/campaign.ts

@@ -0,0 +1,144 @@
+import path from "node:path"
+import { generateFlow, type FlowResult } from "./flows/index.js"
+import { parseWeightsFromArgs, parseEnabledTools } from "./flows/weights.js"
+
+const config = (seed: number) => {
+  const provider = seed % 2 === 0 ? "openai" : "simulation"
+  return {
+    model: `${provider}/sim-model`,
+    permissions: [{ action: "*", resource: "*", effect: seed % 3 === 0 ? "ask" : "allow" }],
+    skills: [".opencode/skills"],
+    providers: {
+      [provider]: {
+      name: "Simulation",
+      request: { body: { apiKey: "sim-key" } },
+      models: {
+        "sim-model": {
+          name: "Simulated Model",
+          api: { type: "aisdk", package: "@ai-sdk/openai-compatible", url: "https://api.openai.com/v1" },
+          capabilities: { tools: true, input: ["text"], output: ["text"] },
+          limit: { context: 128000, output: 16000 },
+        },
+      },
+      },
+    },
+  }
+}
+
+const options = parseArgs(process.argv.slice(2))
+const weights = parseWeightsFromArgs(process.argv.slice(2))
+const enabledTools = parseEnabledTools(process.argv.slice(2)) ?? undefined
+const root = "/tmp/opencode-drive-campaign"
+await Bun.$`rm -rf ${root}`.quiet()
+await Bun.$`mkdir -p ${root}`.quiet()
+const results: FlowResult[] = []
+const coverage = {
+  responseKinds: { text: 0, chunked: 0, reasoning: 0, markdown: 0, raw: 0, tool: 0 },
+  toolNames: {} as Record<string, number>,
+  interactions: { normal: 0, "double-submit": 0, steer: 0, interrupt: 0, "provider-drop": 0 },
+  streamChunkTypes: new Set<string>(),
+}
+
+for (let index = 0; index < options.count; index++) {
+  const seed = options.seed + index
+  const directory = path.join(root, `flow-${String(index + 1).padStart(2, "0")}-${seed}`)
+  const state = path.join(directory, "state", "files")
+  await Bun.$`mkdir -p ${path.join(state, ".config/opencode")} ${path.join(state, "src")}`.quiet()
+  await Bun.$`mkdir -p ${path.join(state, ".opencode/skills/simulation-demo")}`.quiet()
+  const scenario = generateFlow(seed, { turns: options.turns, weights, enabledTools })
+  coverage.responseKinds.text += scenario.coverage.responseKinds.text
+  coverage.responseKinds.chunked += scenario.coverage.responseKinds.chunked
+  coverage.responseKinds.reasoning += scenario.coverage.responseKinds.reasoning
+  coverage.responseKinds.markdown += scenario.coverage.responseKinds.markdown
+  coverage.responseKinds.raw += scenario.coverage.responseKinds.raw
+  coverage.responseKinds.tool += scenario.coverage.responseKinds.tool
+  for (const [name, count] of Object.entries(scenario.coverage.toolNames)) {
+    coverage.toolNames[name] = (coverage.toolNames[name] ?? 0) + count
+  }
+  coverage.interactions.normal += scenario.coverage.interactions.normal
+  coverage.interactions["double-submit"] += scenario.coverage.interactions["double-submit"]
+  coverage.interactions.steer += scenario.coverage.interactions.steer
+  coverage.interactions.interrupt += scenario.coverage.interactions.interrupt
+  coverage.interactions["provider-drop"] += scenario.coverage.interactions["provider-drop"]
+  for (const type of scenario.coverage.streamChunkTypes) coverage.streamChunkTypes.add(type)
+  await Promise.all([
+    Bun.write(path.join(directory, "scenario.json"), `${JSON.stringify(scenario, undefined, 2)}\n`),
+    Bun.write(path.join(state, "opencode.json"), `${JSON.stringify(config(seed), undefined, 2)}\n`),
+    Bun.write(path.join(state, ".config/opencode/opencode.json"), `${JSON.stringify(config(seed), undefined, 2)}\n`),
+    Bun.write(path.join(state, ".opencode/skills/simulation-demo/SKILL.md"), "---\nname: simulation-demo\ndescription: Simulation fixture skill\n---\nUse this skill to exercise the built-in skill loader.\n"),
+    Bun.write(path.join(state, "src/example.ts"), "export function greet(name: string) {\n  return `hello ${name}`\n}\n"),
+    Bun.write(path.join(state, "src/server.ts"), "export function createServer() {\n  return { close() {} }\n}\n"),
+    Bun.write(path.join(state, "src/cache.ts"), "export const invalidate = (key: string) => key\n"),
+    Bun.write(path.join(state, "src/config.ts"), "export const loadConfig = () => ({})\n"),
+  ])
+  const driverLog = path.join(directory, "driver.log")
+  const simulationLog = path.join(directory, "simulation.log")
+  console.log(`[${index + 1}/${options.count}] seed=${seed} turns=${scenario.turns.length} exchanges=${scenario.coverage.providerExchanges}`)
+  const visible = options.renderer === "visible"
+  const process = Bun.spawn([
+    path.resolve("bin/opencode-sim"),
+    "--state", path.join(directory, "state"),
+    "--anchor", path.join(directory, "anchor"),
+    "--renderer", options.renderer,
+    "--driver", `bun ${path.resolve("src/experimental/flow-driver.ts")} ${path.join(directory, "scenario.json")} ${path.join(directory, "result.json")}`,
+    "--",
+    "bun", "run", "--conditions=browser", "--preload=@opentui/solid/preload",
+    "/root/projects/opencode-latest/packages/cli/src/index.ts", "--standalone",
+  ], {
+    cwd: path.resolve("."),
+    env: {
+      ...processEnv(),
+      OPENCODE_SIMULATION_DRIVER_LOG: driverLog,
+      OPENCODE_SIMULATION_LOG: simulationLog,
+      OPENCODE_PROBE_STEP_DELAY: String(options.stepDelay),
+      OPENCODE_PROBE_CHUNK_DELAY: String(options.chunkDelay),
+    },
+    stdin: visible ? "inherit" : "ignore",
+    stdout: visible ? "inherit" : "pipe",
+    stderr: visible ? "inherit" : "pipe",
+  })
+  const [status, stdout, stderr] = await Promise.all([
+    process.exited,
+    process.stdout instanceof ReadableStream ? new Response(process.stdout).text() : "",
+    process.stderr instanceof ReadableStream ? new Response(process.stderr).text() : "",
+  ])
+  if (status !== 0) {
+    throw new Error(`flow ${index + 1} failed (seed ${seed})\n${stdout}\n${stderr}\n${await Bun.file(driverLog).text()}`)
+  }
+  const result: FlowResult = await Bun.file(path.join(directory, "result.json")).json()
+  results.push(result)
+  console.log(`  passed in ${result.durationMs}ms; trace=${result.traceRecords} title=${result.titleExchanges}`)
+}
+
+const summary = {
+  count: results.length,
+  seed: options.seed,
+  turns: results.reduce((total, result) => total + result.turns, 0),
+  assistantExchanges: results.reduce((total, result) => total + result.assistantExchanges, 0),
+  subagentExchanges: results.reduce((total, result) => total + result.subagentExchanges, 0),
+  titleExchanges: results.reduce((total, result) => total + result.titleExchanges, 0),
+  traceRecords: results.reduce((total, result) => total + result.traceRecords, 0),
+  durationMs: results.reduce((total, result) => total + result.durationMs, 0),
+  coverage: { ...coverage, streamChunkTypes: [...coverage.streamChunkTypes] },
+}
+await Bun.write(path.join(root, "summary.json"), `${JSON.stringify(summary, undefined, 2)}\n`)
+console.log(`Campaign passed: ${JSON.stringify(summary)}`)
+
+function parseArgs(args: string[]) {
+  const value = (name: string, fallback: string) => {
+    const index = args.indexOf(name)
+    return index === -1 ? fallback : (args[index + 1] ?? fallback)
+  }
+  return {
+    count: Number(value("--count", "10")),
+    seed: Number(value("--seed", String(Date.now() % 1_000_000))),
+    turns: Number(value("--turns", "7")),
+    renderer: value("--renderer", "headless") === "visible" ? "visible" as const : "headless" as const,
+    stepDelay: Number(value("--step-delay", "0")),
+    chunkDelay: Number(value("--chunk-delay", "30")),
+  }
+}
+
+function processEnv(): Record<string, string> {
+  return Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined))
+}

package/src/experimental/cli-campaign.ts

@@ -0,0 +1,179 @@
+import { mkdir } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { basename, join, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { DefinedCampaign } from "./campaign-api.js"
+import { connectDrive } from "./drive.js"
+import { launchInstance } from "../cli/instance.js"
+import type { StartOptions } from "../cli/types.js"
+
+interface CaseResult {
+  readonly index: number
+  readonly seed: number
+  readonly status: "passed" | "failed"
+  readonly durationMs: number
+  readonly artifacts: string
+  readonly error?: string
+  readonly result?: unknown
+}
+
+export async function runCampaign(options: StartOptions) {
+  const file = resolve(options.campaign!)
+  const campaign = await loadCampaign(file)
+  const root = resolve(process.env.DRIVE_CAMPAIGN_ROOT ?? join(tmpdir(), `opencode-drive-campaign-${Date.now()}`))
+  const indexes = options.caseIndex === undefined
+    ? Array.from({ length: options.count ?? campaign.count ?? 1 }, (_, index) => index)
+    : [options.caseIndex]
+  if (indexes.length === 0) throw new Error("campaign count must be greater than zero")
+  await mkdir(root, { recursive: true })
+  const results: CaseResult[] = []
+  const cursor = { value: 0 }
+  const controller = new AbortController()
+  const active = new Set<Awaited<ReturnType<typeof launchInstance>>>()
+  const interrupt = () => {
+    controller.abort()
+    void Promise.all([...active].map((instance) => instance.stop(true)))
+  }
+  process.once("SIGINT", interrupt)
+  process.once("SIGTERM", interrupt)
+  try {
+    const workers = Array.from(
+      { length: Math.min(options.visible ? 1 : options.concurrency, indexes.length) },
+      async () => {
+        while (!controller.signal.aborted && cursor.value < indexes.length) {
+          const index = indexes[cursor.value++]!
+          const result = await runCase(campaign, file, root, index, options, controller.signal, active)
+          results.push(result)
+          console.log(`[${results.length}/${indexes.length}] case=${index} seed=${result.seed} ${result.status}`)
+        }
+      },
+    )
+    await Promise.all(workers)
+  } finally {
+    process.off("SIGINT", interrupt)
+    process.off("SIGTERM", interrupt)
+    await Promise.all([...active].map((instance) => instance.stop(true)))
+  }
+  if (controller.signal.aborted) throw new Error("campaign interrupted")
+  results.sort((a, b) => a.index - b.index)
+  const summary = {
+    campaign: file,
+    seed: options.seed,
+    count: results.length,
+    passed: results.filter((result) => result.status === "passed").length,
+    failed: results.filter((result) => result.status === "failed").length,
+    durationMs: results.reduce((total, result) => total + result.durationMs, 0),
+    results,
+  }
+  await Bun.write(resolve(root, "summary.json"), `${JSON.stringify(summary, undefined, 2)}\n`)
+  if (summary.failed > 0) throw new Error(`${summary.failed} campaign case${summary.failed === 1 ? "" : "s"} failed; see ${root}`)
+  console.log(JSON.stringify(summary, undefined, 2))
+}
+
+async function runCase(
+  campaign: DefinedCampaign,
+  campaignFile: string,
+  root: string,
+  index: number,
+  options: StartOptions,
+  signal: AbortSignal,
+  active: Set<Awaited<ReturnType<typeof launchInstance>>>,
+): Promise<CaseResult> {
+  const seed = options.seed + index
+  const artifacts = resolve(root, `case-${String(index).padStart(6, "0")}-${seed}`)
+  const started = Date.now()
+  await mkdir(artifacts, { recursive: true })
+  const generated = { index, seed, artifacts }
+  try {
+    const flow = await campaign.generate(generated)
+    await Bun.write(resolve(artifacts, "flow.json"), `${JSON.stringify(flow, undefined, 2)}\n`)
+    const prepared = await campaign.prepare?.({ ...generated, flow })
+    const instance = await launchInstance({
+      name: `campaign-${process.pid}-${index}`,
+      command: options.command.length > 0 ? options.command : prepared?.command,
+      dev: options.dev,
+      state: prepared?.state ?? options.state,
+      visible: options.visible,
+      env: prepared?.env,
+    })
+    active.add(instance)
+    try {
+      await instance.waitForDrive("both")
+      const session = await connectDrive(instance.manifest.endpoints)
+      try {
+        const result = await campaign.run({
+          ...generated,
+          flow,
+          name: instance.manifest.name,
+          ui: session.ui,
+          backend: session.backend,
+          signal,
+        })
+        const value: CaseResult = {
+          index,
+          seed,
+          status: "passed",
+          durationMs: Date.now() - started,
+          artifacts,
+          result,
+        }
+        await Bun.write(resolve(artifacts, "result.json"), `${JSON.stringify(value, undefined, 2)}\n`)
+        return value
+      } finally {
+        session.close()
+      }
+    } finally {
+      active.delete(instance)
+      await instance.stop(true)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    const result: CaseResult = {
+      index,
+      seed,
+      status: "failed",
+      durationMs: Date.now() - started,
+      artifacts,
+      error: message,
+    }
+    await Bun.write(resolve(artifacts, "failure.json"), `${JSON.stringify({
+      ...result,
+      replay: replayCommand(campaignFile, index, options),
+    }, undefined, 2)}\n`)
+    return result
+  }
+}
+
+function replayCommand(campaignFile: string, index: number, options: StartOptions) {
+  const args = [
+    "opencode-drive",
+    "start",
+    "--campaign",
+    campaignFile,
+    "--seed",
+    String(options.seed),
+    "--case",
+    String(index),
+    "--visible",
+    ...(options.state ? ["--state", options.state] : []),
+    ...(options.anchor ? ["--anchor", options.anchor] : []),
+    ...(options.command.length > 0 ? ["--", ...options.command] : []),
+  ]
+  return args.map((arg) => JSON.stringify(arg)).join(" ")
+}
+
+async function loadCampaign(file: string): Promise<DefinedCampaign> {
+  const module: { readonly default?: unknown } = await import(`${pathToFileURL(file).href}?drive=${Date.now()}`)
+  const value = module.default
+  if (!isCampaign(value)) {
+    throw new Error(`${basename(file)} must default-export defineCampaign(...)`)
+  }
+  return value
+}
+
+function isCampaign(value: unknown): value is DefinedCampaign {
+  if (typeof value !== "object" || value === null) return false
+  if (!("kind" in value) || value.kind !== "opencode-drive/campaign") return false
+  if (!("generate" in value) || typeof value.generate !== "function") return false
+  return "run" in value && typeof value.run === "function"
+}

package/src/experimental/drive.ts

@@ -0,0 +1,37 @@
+import { connectBackendSimulation, connectSimulation } from "../client/index.js"
+import type { BackendSimulationClient, SimulationClient } from "../client/index.js"
+
+export interface DriveEndpoints {
+  readonly ui: string
+  readonly backend: string
+}
+
+export interface DriveContext {
+  readonly name: string
+  readonly ui: SimulationClient
+  readonly backend: BackendSimulationClient
+  readonly artifacts: string
+  readonly signal: AbortSignal
+}
+
+export type Driver = (context: DriveContext) => void | Promise<void>
+
+export function defineDriver(driver: Driver) {
+  return driver
+}
+
+export async function connectDrive(endpoints: DriveEndpoints, timeout = 30_000) {
+  const ui = await connectSimulation({ url: endpoints.ui, timeout })
+  const backend = await connectBackendSimulation({ url: endpoints.backend, timeout }).catch((error) => {
+    ui.close()
+    throw error
+  })
+  return {
+    ui,
+    backend,
+    close() {
+      ui.close()
+      backend.close()
+    },
+  }
+}

package/src/experimental/driver.ts

@@ -0,0 +1,41 @@
+import { connectBackendSimulation, connectSimulation, type OpenedExchange } from "../client/index.js"
+
+const uiUrl = process.env.OPENCODE_SIMULATION_UI_WS
+const backendUrl = process.env.OPENCODE_SIMULATION_BACKEND_WS
+
+const ui = await connectSimulation(uiUrl ? { url: uiUrl } : undefined)
+const backend = await connectBackendSimulation(backendUrl ? { url: backendUrl } : undefined)
+
+console.log("ui:", ui.url)
+console.log("backend:", backend.url)
+
+await backend.attach(async (request: OpenedExchange) => {
+  console.log("llm.request:", JSON.stringify({ id: request.id, model: (request.body as { model?: string }).model }))
+  await backend.chunk(request.id, [{ type: "textDelta", text: "Hello from opencode-probe." }])
+  await backend.finish(request.id, "stop")
+})
+
+for (let attempt = 0; attempt < 60; attempt++) {
+  const state = await ui.state()
+  if (state.focused.editor) break
+  await new Promise((resolve) => setTimeout(resolve, 250))
+  if (attempt === 59) throw new Error("prompt editor did not become ready")
+}
+
+await ui.typeText(process.argv.slice(2).join(" ") || "Hello from opencode-probe")
+await ui.pressEnter()
+
+for (let attempt = 0; attempt < 30; attempt++) {
+  await new Promise((resolve) => setTimeout(resolve, 500))
+  if ((await backend.pendingExchanges()).exchanges.length === 0) {
+    console.log("response complete")
+    ui.close()
+    backend.close()
+    process.exit(0)
+  }
+}
+
+console.log(await ui.state())
+ui.close()
+backend.close()
+throw new Error("assistant reply did not render")

package/src/experimental/flow-driver.ts

@@ -0,0 +1,189 @@
+import { connectBackendSimulation, connectSimulation, type OpenedExchange } from "../client/index.js"
+import { flowProperties, type FlowPropertyContext, type FlowResult, type FlowScenario, type TurnOutcome } from "./flows/index.js"
+
+const scenarioPath = process.argv[2]
+const resultPath = process.argv[3]
+if (scenarioPath === undefined) throw new Error("usage: flow-driver SCENARIO [RESULT]")
+
+const scenario: FlowScenario = await Bun.file(scenarioPath).json()
+const stepDelay = Number(process.env.OPENCODE_PROBE_STEP_DELAY ?? "0")
+const chunkDelay = Number(process.env.OPENCODE_PROBE_CHUNK_DELAY ?? "30")
+const started = Date.now()
+const ui = await connectSimulation({ url: requiredEnv("OPENCODE_SIMULATION_UI_WS") })
+const backend = await connectBackendSimulation({ url: requiredEnv("OPENCODE_SIMULATION_BACKEND_WS") })
+const responses = scenario.turns.flatMap((turn) => turn.responses)
+let assistantExchanges = 0
+let responseCursor = 0
+let subagentExchanges = 0
+let titleExchanges = 0
+let failure: Error | undefined
+const active = new Set<string>()
+const interrupted = new Set<string>()
+let chunksSent = 0
+
+await backend.attach(async (request: OpenedExchange) => {
+  try {
+    if (isTitleRequest(request)) {
+      titleExchanges++
+      await backend.chunk(request.id, [{ type: "textDelta", text: scenario.name }])
+      await backend.finish(request.id, "stop")
+      return
+    }
+    if (isSubagentRequest(request)) {
+      subagentExchanges++
+      await backend.chunk(request.id, [{ type: "textDelta", text: "The nested simulation fixture is consistent." }])
+      await backend.finish(request.id, "stop")
+      return
+    }
+    const response = responses[responseCursor++]
+    assistantExchanges++
+    if (response === undefined) throw new Error(`unexpected assistant exchange ${assistantExchanges}`)
+    active.add(request.id)
+    for (const chunk of response.chunks) {
+      await backend.chunk(request.id, chunk)
+      chunksSent++
+      if (chunkDelay > 0) await Bun.sleep(chunkDelay)
+    }
+    if (chunkDelay > 0) await Bun.sleep(Math.max(chunkDelay * 3, 100))
+    if (response.terminal === "disconnect") await backend.disconnect(request.id)
+    else if (response.terminal !== "invalid-provider-event") await backend.finish(request.id, response.finish)
+  } catch (error) {
+    if (!interrupted.has(request.id)) failure = error instanceof Error ? error : new Error(String(error))
+  } finally {
+    active.delete(request.id)
+  }
+})
+
+try {
+  await waitFor("prompt editor", async () => (await ui.state()).focused.editor)
+  let expectedExchanges = 0
+  for (const turn of scenario.turns) {
+    if (failure !== undefined) throw failure
+    await waitFor("prompt editor before submit", async () => (await ui.state()).focused.editor)
+    expectedExchanges += turn.responses.length
+    const beforeChunks = chunksSent
+    await ui.typeText(turn.prompt)
+    await ui.pressEnter()
+    await runProperties("afterSubmit", { turn, ui, backend, waitFor })
+    if (turn.interaction === "double-submit") await ui.pressEnter()
+    let outcome: TurnOutcome = "completed"
+    const hasTools = turn.responses.some((response) => (response.toolNames?.length ?? 0) > 0)
+    const settleTools = turn.interaction === "interrupt" || !hasTools
+      ? undefined
+      : settleBlockingUi(expectedExchanges)
+    if (turn.interaction === "steer") {
+      await waitFor("active stream", async () => active.size > 0 && chunksSent > beforeChunks)
+      await ui.typeText(turn.steerPrompt ?? "Also inspect the active boundary.")
+      await ui.pressEnter()
+    }
+    if (turn.interaction === "interrupt") {
+      await waitFor("interruptible stream", async () => active.size > 0 && chunksSent > beforeChunks)
+      for (const id of active) interrupted.add(id)
+      await ui.pressKey("escape")
+      await ui.pressKey("escape")
+      await waitFor("interrupted provider drain", async () => active.size === 0 && (await backend.pendingExchanges()).exchanges.length === 0)
+      responseCursor = expectedExchanges
+      outcome = "interrupted"
+    } else if (turn.interaction === "provider-drop") {
+      await waitFor("dropped provider exchange", async () => responseCursor >= expectedExchanges)
+      await waitFor("dropped provider drain", async () => active.size === 0 && (await backend.pendingExchanges()).exchanges.length === 0)
+      outcome = "provider-error"
+    } else {
+      await settleTools
+      await waitFor(turn.marker, async () => {
+        if (failure !== undefined) throw failure
+        await ui.state()
+        return responseCursor >= expectedExchanges
+      })
+    }
+    await runProperties("afterTerminal", { turn, ui, backend, outcome, waitFor })
+    if (stepDelay > 0) await Bun.sleep(stepDelay)
+  }
+  await waitFor("provider idle", async () => (await backend.pendingExchanges()).exchanges.length === 0)
+  const trace = await ui.traceExport()
+  const result: FlowResult = {
+    seed: scenario.seed,
+    name: scenario.name,
+    turns: scenario.turns.length,
+    assistantExchanges,
+    subagentExchanges,
+    titleExchanges,
+    traceRecords: trace.records.length,
+    durationMs: Date.now() - started,
+    finalState: await ui.state(),
+  }
+  if (resultPath !== undefined) await Bun.write(resultPath, `${JSON.stringify(result, undefined, 2)}\n`)
+  console.log(JSON.stringify({ ...result, finalState: undefined }))
+} catch (error) {
+  if (resultPath !== undefined) {
+    await Bun.write(`${resultPath}.failure.json`, `${JSON.stringify({
+      error: error instanceof Error ? error.message : String(error),
+      assistantExchanges,
+      subagentExchanges,
+      titleExchanges,
+      pendingExchanges: (await backend.pendingExchanges()).exchanges,
+      state: await ui.state(),
+    }, undefined, 2)}\n`)
+  }
+  throw error
+} finally {
+  ui.close()
+  backend.close()
+}
+
+function requiredEnv(name: string) {
+  const value = process.env[name]
+  if (value === undefined) throw new Error(`${name} is required`)
+  return value
+}
+
+function isTitleRequest(request: OpenedExchange) {
+  if (typeof request.body !== "object" || request.body === null || !("messages" in request.body)) return false
+  const messages = request.body.messages
+  if (!Array.isArray(messages)) return false
+  const first = messages[0]
+  if (typeof first !== "object" || first === null || !("content" in first)) return false
+  return typeof first.content === "string" && first.content.includes("You are a title generator")
+}
+
+function isSubagentRequest(request: OpenedExchange) {
+  if (typeof request.body !== "object" || request.body === null || !("messages" in request.body)) return false
+  const messages = request.body.messages
+  if (!Array.isArray(messages)) return false
+  return messages.some((message) => {
+    if (typeof message !== "object" || message === null || !("content" in message)) return false
+    return typeof message.content === "string" && message.content.includes("Inspect the simulation fixture.")
+  })
+}
+
+async function waitFor(label: string, check: () => Promise<boolean>, timeout = 30_000) {
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    if (await check()) return
+    await Bun.sleep(50)
+  }
+  throw new Error(`timed out waiting for ${label}`)
+}
+
+async function runProperties(stage: "afterSubmit" | "afterTerminal", context: FlowPropertyContext) {
+  for (const property of flowProperties) {
+    const check = property[stage]
+    if (check === undefined) continue
+    try {
+      await check(context)
+    } catch (error) {
+      throw new Error(`property ${property.name} failed for ${context.turn.marker}: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      })
+    }
+  }
+}
+
+async function settleBlockingUi(expectedExchanges: number) {
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline && responseCursor < expectedExchanges) {
+    await ui.pressEnter()
+    await Bun.sleep(25)
+  }
+  if (responseCursor < expectedExchanges) throw new Error("timed out settling blocking tool UI")
+}