@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/detail.ts

@@ -0,0 +1,65 @@
+import type { AgentEvent, CodeEvent } from "./types.ts"
+
+/**
+ * How much of the browser and coding agents' work the terminal shows. brief: what a person follows (what each browser
+ * step is for and its result, warnings and errors, the coding agent's milestones, files it writes, test results).
+ * full: everything, including the browser agent's whole reasoning, page memory, engine logs, and every file the coding
+ * agent reads or searches.
+ * The session log records everything either way.
+ */
+export type Detail = "brief" | "full"
+
+/** Coding agent tool calls that change files: worth a line even in brief. */
+export const WRITES_FILE = /^(Writing|Editing) /
+
+/** Whether an event gets a line of its own at this level; hidden events still drive the shell's activity line. */
+export function shows(event: AgentEvent | CodeEvent, detail: Detail): boolean {
+  if (detail === "full") return true
+  switch (event.type) {
+    case "log":
+      return event.level !== "info"
+    case "outcome":
+      return true
+    // One line per step in brief: what the browser agent is about to do (stepIntent).
+    case "thought":
+      return true
+    case "step":
+    case "memory":
+      return false
+    case "code":
+      if (event.kind === "info" || event.kind === "test") return true
+      if (event.kind === "tool") return !event.ok || WRITES_FILE.test(event.text)
+      return false
+    default:
+      return false
+  }
+}
+
+/** What a browser step is for: "Step 4 · Fill in the contact form" in brief (its first sentence); whole in full. */
+export function stepIntent(step: number, text: string, detail: Detail): string {
+  if (detail === "full") return text
+  const line = (text.split("\n").find((l) => l.trim()) || "").trim()
+  const sentence = /^(.{20,}?[.!?])\s/.exec(line)?.[1] || line
+  return `Step ${step} · ${sentence.length <= 140 ? sentence : `${sentence.slice(0, 139)}…`}`
+}
+
+/** Reading and searching files: noise in brief. Everything else ForgeQE's agent calls (MCP tools, commands) is shown. */
+const LOOKS_AROUND = /^(Reading|Finding files|Searching for|Listing) /
+
+/** Whether a tool call of ForgeQE's own agent (not Scribe) gets a line: in brief, all but its file reads and searches. */
+export function showsAgentTool(text: string, ok: boolean, detail: Detail): boolean {
+  return detail === "full" || !ok || !LOOKS_AROUND.test(text)
+}
+
+/** A step's result as one short line in brief; whole in full. */
+export function briefText(text: string, detail: Detail, max = 160): string {
+  if (detail === "full") return text
+  const line = text.split("\n").find((l) => l.trim()) || ""
+  const flat = line.trim()
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`
+}
+
+/** --verbose (or FORGEQE_VERBOSE=1) shows everything. */
+export function detailFrom(verbose: boolean | undefined): Detail {
+  return verbose || /^(1|true|yes|on)$/i.test(process.env.FORGEQE_VERBOSE || "") ? "full" : "brief"
+}

package/src/domain.ts

@@ -0,0 +1,19 @@
+import type { AppConfig } from "./config.ts"
+
+/**
+ * The product's domain (domain: in forgeqe.yaml) as the lines every agent that designs or judges tests is given, so
+ * it applies the industry's risks and the declared regulations' obligations; prompts/domain-rule.md says how.
+ * The regulations themselves the model knows; what applies here, with the organisation's control ids, is in the
+ * knowledge folder's compliance file.
+ */
+export function domainNotes(cfg: Pick<AppConfig, "domain" | "knowledge">): string {
+  const d = cfg.domain
+  if (!d) return "Domain: not declared (domain: in forgeqe.yaml). Work out the industry and any regulations from the story, the product knowledge, and the application, and say which you assumed."
+  const controls = cfg.knowledge ? ` The controls that apply, with their ids, are in ${cfg.knowledge.dir}/compliance.md when the team has filled it in.` : ""
+  return [
+    `Domain: ${d.industry || "not named"}.`,
+    d.regulations.length ? ` Regulations and standards in scope: ${d.regulations.join(", ")}.` : "",
+    d.notes ? ` ${d.notes}` : "",
+    controls,
+  ].join("")
+}

package/src/engine/bridge.ts

@@ -0,0 +1,359 @@
+import { spawn } from "node:child_process"
+import { createInterface } from "node:readline"
+
+import type { LlmProfile } from "../llm.ts"
+import type { AgentEvent, CaseReport, MemoryInfo, ReplayMode, RunResult } from "../types.ts"
+import { loginEnvNames } from "../childEnv.ts"
+import { recordUsage } from "../usage.ts"
+import type { LoginConfig } from "../config.ts"
+import { debugLogging, logEvent } from "../sessionLog.ts"
+import { engineEnv } from "./setup.ts"
+import { AZURE_IDENTITY_ENV, entraPayload } from "../entra.ts"
+
+export type EngineRequest = {
+  goal: string
+  outDir: string
+  llm: LlmProfile
+  startUrl?: string
+  headed: boolean
+  maxSteps: number
+  allowedHosts: string[]
+  extendSystemMessage?: string
+  /** Page memory folder and replay mode; omit to run without memory. */
+  memory?: { dir: string; replay: ReplayMode }
+  /** BROWSER_USE_* tuning for the engine process. */
+  env?: Record<string, string>
+  /** Saved logins: the engine reads values from the environment by name, or from `values` (logins remembered for this session). */
+  logins?: (LoginConfig & { values?: { username?: string; password?: string; totp?: string } })[]
+  /** Steps in the test case this goal came from; the agent reports a verdict for each. */
+  caseSteps?: number
+  screenshots?: "all" | "failures" | "off"
+  accessibility?: boolean
+  /** Record the application's API calls (network.json). */
+  network?: boolean
+  /** axe-core for the accessibility checks: the script and the rule tags of the standard. */
+  axe?: { script: string; tags: string[] }
+  /** Core Web Vitals and load timings (performance.json). */
+  vitals?: boolean
+  /** The browser agent's prompts (prompts/browser-*.md, resolved), by name; the engine's own text for any not given. */
+  prompts?: Record<string, string>
+  /** Screenshots of each page for visual comparison (visual.json): masks by path prefix, and full page or not. */
+  visual?: { mask: string[]; pages: Record<string, string[]>; full_page: boolean }
+  overlay?: boolean
+  /** A failed run's resume.json: its steps are replayed first, then the agent carries on. */
+  resume?: Record<string, unknown>
+  /** Browser skills: `given` adds them all to the prompt, `choose` has the model pick the ones the goal needs. */
+  skills?: { name: string; description: string; body: string }[]
+  skillsPick?: "given" | "choose"
+  skillsMaxChars?: number
+}
+
+export function loginPayload(logins: EngineRequest["logins"]): Record<string, unknown>[] {
+  return (logins || []).map((l) => ({
+    name: l.name,
+    domains: l.domains,
+    username_env: l.usernameEnv || null,
+    password_env: l.passwordEnv || null,
+    totp_env: l.totpEnv || null,
+    session_file: l.sessionFile || null,
+    ...(l.values ? { values: l.values } : {}),
+  }))
+}
+
+type EngineMemory = {
+  dir?: string
+  mode?: ReplayMode
+  replayed?: number
+  replay_total?: number
+  replay_stopped?: string
+  llm_steps?: number
+  pages?: number
+  elements?: number
+  new_elements?: number
+  flow?: "saved" | "updated" | null
+  resume?: { steps?: number; failed_at?: number; reason?: string; lines?: string[]; file?: string }
+}
+
+type EngineResult = {
+  success?: boolean
+  summary?: string
+  error?: string
+  final_url?: string
+  usage?: { input?: number; output?: number; cached?: number }
+  files?: string[]
+  cancelled?: boolean
+  memory?: EngineMemory
+  case_report?: CaseReport
+  skills?: string[]
+  /** "synthetic" from the mock engine: no browser ran, so the run cannot become a test. */
+  driver?: "synthetic"
+  outcome?: "passed" | "assertion_failed" | "error"
+  checks?: { expected?: string; text?: string; holds?: boolean }[]
+}
+
+type EngineEvent =
+  | { type: "log"; level?: string; text?: string }
+  | { type: "memory"; text?: string }
+  | {
+      type: "step"
+      source?: "memory"
+      step_number?: number
+      url?: string
+      title?: string
+      next_goal?: string
+      memory?: string
+      evaluation_previous_goal?: string
+      action_lines?: string[]
+    }
+  | { type: "result"; step?: number; items?: { ok?: boolean; done?: boolean; text?: string }[] }
+  | { type: "usage"; input?: number; output?: number; cached?: number }
+  | { type: "done"; result?: EngineResult }
+
+function toMemoryInfo(m: EngineMemory | undefined): MemoryInfo | undefined {
+  if (!m) return undefined
+  return {
+    dir: String(m.dir || ""),
+    mode: m.mode || "verify",
+    replayed: Number(m.replayed || 0),
+    replayTotal: Number(m.replay_total || 0),
+    replayStopped: m.replay_stopped || undefined,
+    llmSteps: Number(m.llm_steps || 0),
+    pages: Number(m.pages || 0),
+    elements: Number(m.elements || 0),
+    newElements: Number(m.new_elements || 0),
+    flow: m.flow || null,
+    ...(m.resume?.steps
+      ? {
+          resume: {
+            steps: Number(m.resume.steps),
+            failedAt: Number(m.resume.failed_at || 0),
+            reason: String(m.resume.reason || ""),
+            lines: (m.resume.lines || []).map(String),
+            file: m.resume.file || undefined,
+          },
+        }
+      : {}),
+  }
+}
+
+function llmPayload(p: LlmProfile): Record<string, unknown> {
+  const out: Record<string, unknown> = { provider: p.provider, model: p.model }
+  if (p.endpoint) out.endpoint = p.endpoint
+  if (p.deployment) out.deployment = p.deployment
+  if (p.apiVersion) out.api_version = p.apiVersion
+  if (p.apiKey && p.auth !== "entra") out.api_key = p.apiKey
+  if (p.auth === "entra") Object.assign(out, entraPayload(p))
+  else if (p.apiKeyEnv) out.api_key_env = p.apiKeyEnv
+  if (typeof p.temperature === "number") out.temperature = p.temperature
+  return out
+}
+
+export function toRunResult(goal: string, startUrl: string, r: EngineResult): RunResult {
+  // The agent's evidence wins over its verdict: a check that does not hold, or a failed case step, fails the run even
+  // when the agent called done with success (engines before this rule did not apply it themselves).
+  const contradicted =
+    Boolean(r.success) && ((r.checks || []).some((c) => c.holds === false) || (r.case_report?.steps || []).some((s) => s.status === "failed"))
+  if (contradicted) r = { ...r, success: false, outcome: "assertion_failed" }
+  return {
+    status: r.success ? "complete" : r.cancelled ? "stopped" : "fail",
+    goal,
+    startUrl,
+    finalUrl: r.final_url || "",
+    summary: String(r.summary || r.error || ""),
+    usage: { input: Number(r.usage?.input || 0), output: Number(r.usage?.output || 0), ...(r.usage?.cached ? { cached: Number(r.usage.cached) } : {}) },
+    driver: r.driver === "synthetic" ? "synthetic" : "engine",
+    memory: toMemoryInfo(r.memory),
+    ...(r.case_report?.steps ? { caseReport: r.case_report } : {}),
+    ...(r.outcome ? { outcome: r.outcome } : {}),
+    ...(r.outcome === "assertion_failed"
+      ? { failedChecks: (r.checks || []).filter((c) => c.holds === false).map((c) => ({ expected: String(c.expected || ""), actual: String(c.text || "") })) }
+      : {}),
+    ...(Array.isArray(r.skills) ? { skills: r.skills.map(String) } : {}),
+  }
+}
+
+/** After "stop", how long the engine gets to write its artifacts before it is terminated, then killed. */
+export const STOP_GRACE_MS = 30_000
+export const KILL_AFTER_MS = 10_000
+
+/**
+ * Run one goal in the Python ForgeQE engine and translate its JSON-line events for the TUI and CLI. A stop (the
+ * signal, or `deadlineMs` passing) asks the engine to stop; one that has not exited `STOP_GRACE_MS` later gets
+ * SIGTERM, then SIGKILL, so a hung engine never hangs the caller.
+ */
+export async function runEngine(opts: {
+  python: string
+  /** The engine command; default `<python> -m forgeqe_engine run`. The mock profile runs mock.ts instead. */
+  command?: string[]
+  request: EngineRequest
+  signal?: AbortSignal
+  onEvent?: (event: AgentEvent) => void
+  /** Hard ceiling for the whole run, setup and replay included; the engine's own timeout covers only the agent. */
+  deadlineMs?: number
+  /** Overrides STOP_GRACE_MS and KILL_AFTER_MS (tests). */
+  graceMs?: { stop: number; kill: number }
+}): Promise<{ result: RunResult; files: string[] }> {
+  const { request: req, onEvent } = opts
+  const [bin, ...args] = opts.command || [opts.python, "-m", "forgeqe_engine", "run"]
+  const child = spawn(bin!, args, {
+    env: engineEnv(debugLogging() ? { ...req.env, BROWSER_USE_LOGGING_LEVEL: "debug" } : req.env, [
+      ...(req.llm.auth === "entra" ? AZURE_IDENTITY_ENV : req.llm.apiKeyEnv ? [req.llm.apiKeyEnv] : []),
+      ...loginEnvNames(req.logins || []),
+    ]),
+    stdio: ["pipe", "pipe", "pipe"],
+  })
+
+  const stderrTail: string[] = []
+  child.stderr.setEncoding("utf8")
+  child.stderr.on("data", (chunk: string) => {
+    for (const line of chunk.split(/\r?\n/)) {
+      if (!line.trim()) continue
+      logEvent("engine.log", line)
+      stderrTail.push(line)
+      if (stderrTail.length > 40) stderrTail.shift()
+    }
+  })
+
+  const payload = {
+    goal: req.goal,
+    out_dir: req.outDir,
+    llm: llmPayload(req.llm),
+    start_url: req.startUrl || null,
+    headed: req.headed,
+    max_steps: req.maxSteps,
+    allowed_hosts: req.allowedHosts,
+    extend_system_message: req.extendSystemMessage || null,
+    memory: req.memory || null,
+    logins: loginPayload(req.logins),
+    case_steps: req.caseSteps || 0,
+    screenshots: req.screenshots || "all",
+    accessibility: req.accessibility !== false,
+    network: req.network !== false,
+    ...(req.axe ? { axe: req.axe } : {}),
+    vitals: req.vitals !== false,
+    ...(req.prompts ? { prompts: req.prompts } : {}),
+    ...(req.visual ? { visual: req.visual } : {}),
+    overlay: req.overlay !== false,
+    resume: req.resume || null,
+    ...(req.skills?.length ? { skills: req.skills, skills_pick: req.skillsPick || "given", skills_max_chars: req.skillsMaxChars || 6000 } : {}),
+  }
+  child.stdin.write(JSON.stringify(payload) + "\n")
+  logEvent("engine.request", payload)
+
+  const grace = opts.graceMs || { stop: STOP_GRACE_MS, kill: KILL_AFTER_MS }
+  const timers: ReturnType<typeof setTimeout>[] = []
+  let stopping: "user" | "deadline" | null = null
+  let killed = false
+  const exited = () => child.exitCode !== null || child.signalCode !== null
+  const stop = (why: "user" | "deadline") => {
+    if (stopping || exited()) return
+    stopping = why
+    if (child.stdin.writable) child.stdin.write("stop\n")
+    timers.push(
+      setTimeout(() => {
+        if (exited()) return
+        killed = true
+        logEvent("engine.kill", { signal: "SIGTERM", why })
+        child.kill("SIGTERM")
+        timers.push(setTimeout(() => !exited() && child.kill("SIGKILL"), grace.kill))
+      }, grace.stop),
+    )
+  }
+  const onAbort = () => stop("user")
+  if (opts.signal?.aborted) onAbort()
+  opts.signal?.addEventListener("abort", onAbort, { once: true })
+  if (opts.deadlineMs) timers.push(setTimeout(() => stop("deadline"), opts.deadlineMs))
+
+  let pendingActions: string[] = []
+  let done: EngineResult | null = null
+
+  const handle = (ev: EngineEvent) => {
+    logEvent("engine.event", ev)
+    switch (ev.type) {
+      case "log": {
+        if (ev.level === "debug") return
+        const level = ev.level === "error" ? "error" : ev.level === "warn" ? "warn" : "info"
+        if (ev.text) onEvent?.({ type: "log", level, text: ev.text })
+        return
+      }
+      case "memory":
+        if (ev.text) onEvent?.({ type: "memory", text: ev.text })
+        return
+      case "step": {
+        const step = Number(ev.step_number || 0)
+        onEvent?.({ type: "step", step, url: ev.url || "", title: ev.title || "", category: "", source: ev.source })
+        const thought = ev.next_goal || ev.memory || ev.evaluation_previous_goal || ""
+        if (thought) onEvent?.({ type: "thought", step, text: thought })
+        pendingActions = ev.action_lines || []
+        return
+      }
+      case "result": {
+        const step = Number(ev.step || 0)
+        const items = ev.items || []
+        items.forEach((item, i) => {
+          if (item.done) return
+          const action = pendingActions[i] || "action"
+          // A check recorded as not holding worked as an action, but it is the test failing: show it as a failure.
+          const notMet = /^Recorded: expected result not met/.test(item.text || "")
+          const ok = Boolean(item.ok) && !notMet
+          const text = ok ? action : notMet ? `${action}: expected result not met` : `${action}: ${item.text || "failed"}`
+          onEvent?.({ type: "outcome", step, ok, text })
+        })
+        pendingActions = []
+        return
+      }
+      case "usage":
+        onEvent?.({ type: "usage", usage: { input: Number(ev.input || 0), output: Number(ev.output || 0), ...(ev.cached ? { cached: Number(ev.cached) } : {}) } })
+        return
+      case "done":
+        done = ev.result || {}
+        setTimeout(() => child.kill(), 10_000).unref()
+        return
+    }
+  }
+
+  const lines = createInterface({ input: child.stdout })
+  lines.on("line", (line) => {
+    if (!line.trim()) return
+    try {
+      handle(JSON.parse(line) as EngineEvent)
+    } catch {
+      onEvent?.({ type: "log", level: "info", text: line })
+    }
+  })
+
+  const code = await new Promise<number>((resolve, reject) => {
+    child.on("error", reject)
+    child.on("close", (c) => resolve(c ?? 1))
+  }).finally(() => {
+    for (const t of timers) clearTimeout(t)
+    opts.signal?.removeEventListener("abort", onAbort)
+  })
+  logEvent("engine.exit", { code, finished: Boolean(done), stopping, killed })
+
+  if (!done && stopping) {
+    const seconds = Math.round(grace.stop / 1000)
+    done = {
+      success: false,
+      cancelled: stopping === "user",
+      error:
+        stopping === "user"
+          ? `Browser task stopped by user; the engine did not finish within ${seconds}s, so it was terminated and its artifacts may be incomplete.`
+          : `Browser task exceeded its ${Math.round((opts.deadlineMs || 0) / 1000)}s limit and was terminated.`,
+    }
+  } else if (done && stopping === "deadline") {
+    // The engine reports any stop as the user's; this one was the deadline.
+    const why = `Browser task exceeded its ${Math.round((opts.deadlineMs || 0) / 1000)}s limit and was stopped.`
+    done = { ...(done as EngineResult), success: false, cancelled: false, error: why, summary: why }
+  }
+  if (!done) {
+    const detail = stderrTail.slice(-12).join("\n")
+    throw new Error(`The ForgeQE engine exited (${code}) without a result.${detail ? `\n${detail}` : ""}`)
+  }
+  const finished: EngineResult = done
+  const result = toRunResult(req.goal, req.startUrl || "", finished)
+  recordUsage("browser agent", result.usage, req.llm.price)
+  onEvent?.({ type: "usage", usage: result.usage })
+  onEvent?.({ type: "done", result })
+  return { result, files: finished.files || [] }
+}

package/src/engine/mock.ts

@@ -0,0 +1,102 @@
+/**
+ * The mock profile's engine: speaks the Python engine's protocol (bridge.ts) without a browser or a model, so offline
+ * runs and tests go through the same bridge, events, and reports as live ones.
+ *
+ *   stdin  line 1  run request JSON; later "stop"
+ *   stdout         one JSON event per line, ending with done
+ *
+ * With a start URL it opens it and finishes; without one it fails, since it cannot choose a website.
+ */
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { createInterface } from "node:readline"
+
+import YAML from "yaml"
+
+export const MOCK_ENGINE = import.meta.path
+
+type Request = { goal?: string; out_dir?: string; start_url?: string | null }
+
+const emit = (event: Record<string, unknown>) => process.stdout.write(`${JSON.stringify(event)}\n`)
+
+function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname
+  } catch {
+    return url
+  }
+}
+
+function writeArtifacts(dir: string, run: Record<string, unknown>, steps: { url: string; goal: string; actions: { text: string; ok: boolean }[] }[]): string[] {
+  mkdirSync(dir, { recursive: true })
+  const trace = [
+    "# ForgeQE run",
+    "",
+    `- Status: ${run.status}`,
+    `- Goal: ${run.goal}`,
+    `- Start URL: ${run.start_url || "(none)"}`,
+    `- Final URL: ${run.final_url || "(none)"}`,
+    "- Driver: mock engine (no browser or model)",
+    "",
+    `## Summary\n\n${run.summary}`,
+    "",
+  ].join("\n")
+  const files: [string, string][] = [
+    ["run.json", JSON.stringify(run, null, 2)],
+    ["workflow.yaml", YAML.stringify({ format: "forgeqe-mock", goal: run.goal, start_url: run.start_url, final_url: run.final_url, status: run.status, steps: steps.map((s, i) => ({ step: i + 1, url: s.url, goal: s.goal })) })],
+    ["trace.md", trace],
+    ["steps.json", JSON.stringify(steps.map((s, i) => ({ n: i + 1, source: "agent", url: s.url, title: hostOf(s.url), goal: s.goal, actions: s.actions })), null, 2)],
+  ]
+  return files.map(([name, body]) => {
+    const file = path.join(dir, name)
+    writeFileSync(file, body.endsWith("\n") ? body : `${body}\n`)
+    return file
+  })
+}
+
+async function main() {
+  const lines = createInterface({ input: process.stdin })[Symbol.asyncIterator]()
+  const first = await lines.next()
+  const req: Request = first.done ? {} : JSON.parse(first.value)
+  let stopped = false
+  void (async () => {
+    for (let l = await lines.next(); !l.done; l = await lines.next()) if (l.value.trim().toLowerCase() === "stop") stopped = true
+    stopped = true
+  })()
+
+  const goal = String(req.goal || "")
+  const startUrl = req.start_url || ""
+  const dir = String(req.out_dir || ".")
+  const steps: { url: string; goal: string; actions: { text: string; ok: boolean }[] }[] = []
+  const finish = (success: boolean, summary: string, finalUrl: string, extra: Record<string, unknown> = {}) => {
+    const usage = success ? { input: 12, output: 8 } : { input: 0, output: 0 }
+    const status = success ? "complete" : extra.cancelled ? "stopped" : "fail"
+    const files = writeArtifacts(dir, { status, goal, start_url: startUrl, final_url: finalUrl, summary, driver: "synthetic", usage }, steps)
+    emit({ type: "usage", ...usage })
+    emit({ type: "done", result: { success, summary, final_url: finalUrl, usage, files, driver: "synthetic", ...extra } })
+  }
+
+  if (!startUrl) {
+    const why = "The mock profile cannot choose a website. Press Tab for a live profile, or pin one with --url or start_url."
+    steps.push({ url: "about:blank", goal: "There is no page to act on.", actions: [{ text: `fail ${why}`, ok: false }] })
+    emit({ type: "step", step_number: 1, url: "about:blank", title: "", next_goal: "There is no page to act on.", action_lines: ["FAIL"] })
+    emit({ type: "result", step: 1, items: [{ ok: false, text: why }] })
+    return finish(false, why, "")
+  }
+
+  steps.push({ url: startUrl, goal: "Opening the start URL.", actions: [{ text: `navigate ${startUrl}`, ok: true }] })
+  emit({ type: "step", step_number: 1, url: "about:blank", title: "", next_goal: "Opening the start URL.", action_lines: [`NAVIGATE ${startUrl}`] })
+  emit({ type: "result", step: 1, items: [{ ok: true }] })
+  if (stopped) return finish(false, "Browser task stopped by user", startUrl, { cancelled: true })
+
+  const thought = `Observed ${hostOf(startUrl)}. Mock provider does not drive a live model.`
+  steps.push({ url: startUrl, goal: thought, actions: [{ text: "complete", ok: true }] })
+  emit({ type: "step", step_number: 2, url: startUrl, title: hostOf(startUrl), next_goal: thought, action_lines: ["COMPLETE"] })
+  emit({ type: "result", step: 2, items: [{ ok: true, done: true }] })
+  finish(true, `Mock run finished on ${startUrl}`, startUrl)
+}
+
+if (import.meta.main) {
+  await main()
+  process.exit(0)
+}